InsightSoftwareConsortium · thewtex · May 22, 2025 · Apr 10, 2025 · Apr 10, 2025 · Apr 11, 2025
diff --git a/.github/workflows/playwright.yml b/.github/workflows/playwright.yml
@@ -0,0 +1,30 @@
+name: Playwright Tests
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+jobs:
+  test:
+    defaults:
+      run:
+        working-directory: ./examples/esm
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: lts/*
+    - name: Install dependencies
+      run: npm install
+    - name: Install Playwright Browsers
+      run: npx playwright install --with-deps
+    - name: Run Playwright tests
+      run: npm run test
+    - uses: actions/upload-artifact@v4
+      if: ${{ !cancelled() }}
+      with:
+        name: playwright-report
+        path: playwright-report/
+        retention-days: 30
diff --git a/docs/index.md b/docs/index.md
@@ -13,6 +13,7 @@ ITK-Wasm
 [![itkwasm version](https://badge.fury.io/py/itkwasm.svg)](https://pypi.org/project/itkwasm/)
 
 [![DOI](https://zenodo.org/badge/45812381.svg)](https://zenodo.org/badge/latestdoi/45812381)
+[![Give it a star!](https://img.shields.io/github/stars/InsightSoftwareConsortium/ITK-Wasm?style=social)](https://github.com/InsightSoftwareConsortium/ITK-Wasm)
 
 ![License](https://img.shields.io/github/license/InsightSoftwareConsortium/ITK-Wasm) ![GitHub commit activity](https://img.shields.io/github/commit-activity/y/InsightSoftwareConsortium/ITK-Wasm)
 </div>

diff --git a/docs/typescript/distribution/index.md b/docs/typescript/distribution/index.md
@@ -1,6 +1,7 @@
 # Distribution
 
-This sections walks through examples on how to distribution applications for deployment that depend on itk-wasm packages.
+This section provides examples of how to distribute applications
+for deployment that rely on [ITK-Wasm packages](../../introduction/packages.md).
 
 ```{toctree}
 :maxdepth: 1
@@ -10,4 +11,4 @@ umd.md
 vite.md
 webpack.md
 node.md
-```
+```
diff --git a/examples/esm/.gitignore b/examples/esm/.gitignore
@@ -0,0 +1,7 @@
+
+# Playwright
+node_modules/
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
diff --git a/examples/esm/README.md b/examples/esm/README.md
@@ -0,0 +1,27 @@
+ITK-Wasm ESM Example
+====================
+
+This example demonstrates how to use the
+[ITK-Wasm](https://wasm.itk.org/) ESM module from
+a an HTML script tag for access to the image and mesh IO module that are
+distributed on the [jsDelivr](https://www.jsdelivr.com/) [content delivery
+network](https://en.wikipedia.org/wiki/Content_delivery_network).
+
+More information can be found in the [example
+documentation](https://docs.itk.org/projects/wasm/en/latest/typescript/distribution/esm.html).
+
+## Run Locally
+
+```
+npm install
+npm run start
+```
+
+And visit [http://localhost:8080/](http://localhost:8080/).
+
+## Development
+
+```
+npm install
+npm test
+```
diff --git a/examples/esm/dist/index.html b/examples/esm/dist/index.html
@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>ITK-Wasm ESM Example</title>
+    <meta charset="UTF-8" />
+    <link rel="stylesheet" href="styles.css">
+  </head>
+
+  <body>
+    <!-- Selector -->
+    <div>
+      <label>Select image:</label>
+      <input name="input-file" type="file">
+    </div>
+
+    <!-- Image visualization -->
+    <div id="viewer">
+      <canvas height="600"></canvas>
+    </div>
+
+    <!-- Image information -->
+    <textarea readonly name="image-information">Image information...</textarea>
+
+    <!-- Javascript -->
+    <script type="module">
+      // Example ITK-Wasm package, @itk-wasm/image-io
+      import { readImage } from "https://cdn.jsdelivr.net/npm/@itk-wasm/image-io@1.6.0/dist/bundle/index-worker-embedded.min.js";
+
+      // Visualization
+      import { Niivue, MULTIPLANAR_TYPE } from "https://cdn.jsdelivr.net/npm/@niivue/niivue@0.56.0/dist/index.js";
+      // Convert ITK-Wasm Image to Niivue Image
+      import { iwi2niiCore } from "https://cdn.jsdelivr.net/npm/@niivue/cbor-loader@1.2.1/+esm";
+
+      async function processImage(event) {
+        const outputTextArea = document.querySelector("textarea");
+        outputTextArea.textContent = "Loading...";
+
+        const dataTransfer = event.dataTransfer;
+        const files = event.target.files || dataTransfer.files;
+
+        const { image } = await readImage(files[0]);
+
+        function replacer(key, value) {
+          if (!!value && value.byteLength !== undefined) {
+            return String(value.slice(0, 6)) + "...";
+          }
+          return value;
+        }
+        outputTextArea.textContent = JSON.stringify(image, replacer, 4);
+
+        const canvas = document.querySelector('#viewer > canvas');
+        const nv = new Niivue({ multiplanarLayout: MULTIPLANAR_TYPE.GRID });
+        await nv.attachToCanvas(canvas);
+        const niiImage = iwi2niiCore(image);
+        await nv.loadVolumes([{ url: niiImage, name: 'image.nii' }])
+      }
+
+      const imageInput = document.querySelector("input[name='input-file']");
+      imageInput.addEventListener("change", processImage);
+    </script>
+
+  </body>
+</html>
+
diff --git a/examples/esm/dist/styles.css b/examples/esm/dist/styles.css
@@ -0,0 +1,11 @@
+html, body {
+  height: 90%;
+}
+
+textarea {
+  resize: none;
+  overflow-y: scroll;
+  box-sizing: border-box;
+  width: 600px;
+  height: 400px;
+}
diff --git a/examples/esm/package.json b/examples/esm/package.json
@@ -0,0 +1,36 @@
+{
+  "name": "itk-wasm-esm-example",
+  "version": "1.0.0",
+  "private": true,
+  "description": "This example demonstrates how to use an ITK-Wasm package ESM module from an HTML script tag.",
+  "scripts": {
+    "start": "http-server -c-1 ./dist/",
+    "test:browser": "npx playwright test",
+    "test:browser:ui": "npx playwright test --ui",
+    "test:browser:debug": "npx playwright test --debug",
+    "test:browser:report": "npx playwright show-report",
+    "test:debug": "start-server-and-test start http://localhost:8080 test:browser:debug",
+    "test:ui": "start-server-and-test start http://localhost:8080 test:browser:ui",
+    "test": "start-server-and-test start http://localhost:8080 test:browser"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/InsightSoftwareConsortium/ITK-Wasm.git"
+  },
+  "keywords": [
+    "itk",
+    "esm"
+  ],
+  "author": "Matt McCormick <matt@fideus.io>",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/InsightSoftwareConsortium/ITK-Wasm/issues"
+  },
+  "homepage": "https://github.com/InsightSoftwareConsortium/ITK-Wasm#readme",
+  "devDependencies": {
+    "@playwright/test": "^1.52.0",
+    "@types/node": "^22.13.13",
+    "http-server": "^14.1.1",
+    "start-server-and-test": "^2.0.11"
+  }
+}
diff --git a/examples/esm/playwright.config.js b/examples/esm/playwright.config.js
@@ -0,0 +1,81 @@
+// @ts-check
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+// import dotenv from 'dotenv';
+// import path from 'path';
+// dotenv.config({ path: path.resolve(__dirname, '.env') });
+
+/**
+ * @see https://playwright.dev/docs/test-configuration
+ */
+export default defineConfig({
+  testDir: './tests',
+  /* Run tests in files in parallel */
+  fullyParallel: true,
+  /* Fail the build on CI if you accidentally left test.only in the source code. */
+  forbidOnly: !!process.env.CI,
+  /* Retry on CI only */
+  retries: process.env.CI ? 2 : 0,
+  /* Opt out of parallel tests on CI. */
+  workers: process.env.CI ? 1 : undefined,
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: 'html',
+  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    /* Base URL to use in actions like `await page.goto('/')`. */
+    // baseURL: 'http://127.0.0.1:3000',
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: 'on-first-retry',
+  },
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+
+    /* Test against mobile viewports. */
+    // {
+    //   name: 'Mobile Chrome',
+    //   use: { ...devices['Pixel 5'] },
+    // },
+    // {
+    //   name: 'Mobile Safari',
+    //   use: { ...devices['iPhone 12'] },
+    // },
+
+    /* Test against branded browsers. */
+    // {
+    //   name: 'Microsoft Edge',
+    //   use: { ...devices['Desktop Edge'], channel: 'msedge' },
+    // },
+    // {
+    //   name: 'Google Chrome',
+    //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
+    // },
+  ],
+
+  /* Run your local dev server before starting the tests */
+  // webServer: {
+  //   command: 'npm run start',
+  //   url: 'http://127.0.0.1:3000',
+  //   reuseExistingServer: !process.env.CI,
+  // },
+});
+
diff --git a/examples/esm/tests/read-image.spec.js b/examples/esm/tests/read-image.spec.js
@@ -0,0 +1,14 @@
+// @ts-check
+import { test, expect } from "@playwright/test";
+
+test("loads an image", async ({ page }) => {
+  await page.goto("http://localhost:8080/");
+
+  await expect(page).toHaveTitle(/ITK-Wasm ESM/);
+
+  const fileInput = page.locator("input[type='file']");
+  await fileInput.setInputFiles("tests/tooth.nrrd");
+
+  const textarea = page.locator("textarea");
+  await expect(textarea).toHaveText(/imageType/);
+});
diff --git a/examples/esm/tests/tooth.nrrd b/examples/esm/tests/tooth.nrrd
diff --git a/package.json b/package.json
@@ -42,9 +42,9 @@
       "@shoelace-style/shoelace": "^2.12.0",
       "@types/node": "^22.13.13",
       "esbuild": "^0.25.1",
-      "start-server-and-test": "^2.0.4",
+      "start-server-and-test": "^2.0.12",
       "ava": "^6.1.3",
-      "cypress": "^14.3.0",
+      "cypress": "^14.4.0",
       "shx": "^0.4.0",
       "vite": "^6.2.3"
     }