feat(docs): update README and index.html for ESM module usage and paths

Author: kalwalt

README.md

@@ -4,9 +4,8 @@ ARToolKit marker detection plugin for AR.js core with WebAssembly support.
 
 ## Features
 
-- Web Worker-based detection — marker detection runs off the main thread
+- Web Worker-based detection — marker detection runs off the main thread (Browser Module Worker)
 - ImageBitmap support — zero-copy frame transfer (browser)
-- Cross-platform — browser Workers and Node.js worker_threads (stub path)
 - ARToolKit integration — square pattern markers
 - Event-driven API — marker found/updated/lost + raw getMarker forwarding
 - Filtering — only forwards PATTERN_MARKER events above a minimum confidence
@@ -17,26 +16,53 @@ ARToolKit marker detection plugin for AR.js core with WebAssembly support.
 npm install @ar-js-org/arjs-plugin-artoolkit
 ```
 
-## Configuration (module + assets)
+## Using the ESM build (recommended)
 
-To ensure the Worker can import ARToolKit in the browser, pass an explicit ESM URL (recommended):
+When you import the built ESM bundle from `dist/`, the worker and ARToolKit are already bundled and referenced correctly. You do NOT need to pass `artoolkitModuleUrl`.
+
+Example:
+
+```html
+<script type="module">
+  import { ArtoolkitPlugin } from '/dist/arjs-plugin-artoolkit.esm.js';
+
+  const engine = { eventBus: /* your event bus */ };
+
+  const plugin = new ArtoolkitPlugin({
+    worker: true,
+    cameraParametersUrl: '/path/to/camera_para.dat',
+    minConfidence: 0.6
+  });
+
+  await plugin.init(engine);
+  await plugin.enable();
+</script>
+```
+
+Serving notes:
+- Serve from a web server so `/dist` assets resolve. The build is configured with `base: './'`, so the worker asset is referenced relative to the ESM file (e.g., `/dist/assets/worker-*.js`).
+- In your own apps, place `dist/` where you serve static assets and import the ESM with the appropriate path (absolute or relative).
+
+## Using source (development mode)
+
+If you develop against `src/` (not the built `dist/`), the worker will attempt to dynamically import ARToolKit. In that case you should provide `artoolkitModuleUrl` or ensure your dev server can resolve `@ar-js-org/artoolkit5-js`.
 
 ```js
 const plugin = new ArtoolkitPlugin({
   worker: true,
-  artoolkitModuleUrl: '/node_modules/@ar-js-org/artoolkit5-js/dist/ARToolkit.js', // explicit ESM
-  cameraParametersUrl: '/path/to/camera_para.dat',                                // optional override
-  wasmBaseUrl: '/node_modules/@ar-js-org/artoolkit5-js/dist/',                    // optional; if your build needs it
-  minConfidence: 0.6                                                              // forward only confident detections
+  artoolkitModuleUrl: '/node_modules/@ar-js-org/artoolkit5-js/dist/ARToolkit.js', // provide when using src/
+  cameraParametersUrl: '/path/to/camera_para.dat',
+  wasmBaseUrl: '/node_modules/@ar-js-org/artoolkit5-js/dist/', // optional; if your build requires it
+  minConfidence: 0.6
 });
 ```
 
-CDN fallback (if you don’t serve node_modules):
-- Set `artoolkitModuleUrl` to a CDN ESM endpoint, e.g. a jsDelivr/UNPKG URL for the package’s ESM bundle.
+CDN fallback (for source/dev):
+- Set `artoolkitModuleUrl` to a CDN ESM endpoint (e.g., jsDelivr/UNPKG) for `@ar-js-org/artoolkit5-js`.
 
 Notes:
 - The previous “loader.js” and manual WASM placement flow is no longer used.
-- If your ARToolKit build fetches auxiliary assets (WASM, data), set `wasmBaseUrl` accordingly.
+- In the `dist/` build, ARToolKit is bundled and `artoolkitModuleUrl` is NOT needed.
 
 ## Usage
 
@@ -49,7 +75,7 @@ const plugin = new ArtoolkitPlugin({
   worker: true,
   lostThreshold: 5,       // frames before a marker is considered lost
   frameDurationMs: 100,   // expected ms per frame (affects lost timing)
-  artoolkitModuleUrl: '/node_modules/@ar-js-org/artoolkit5-js/dist/ARToolkit.js',
+  // artoolkitModuleUrl: '/node_modules/@ar-js-org/artoolkit5-js/dist/ARToolkit.js', // Only for src/dev
   cameraParametersUrl: '/data/camera_para.dat',
   minConfidence: 0.6
 });
@@ -114,7 +140,7 @@ const { markerId, size } = await plugin.loadMarker('/examples/simple-marker/data
 
 A complete webcam-based example is available under `examples/simple-marker/`.
 
-Serve from the repository root so that ES modules and node_modules paths resolve:
+Serve from the repository root so that `dist/` and example paths resolve:
 
 ```bash
 # From repository root
@@ -142,9 +168,9 @@ The example demonstrates:
   lostThreshold?: number;      // Frames before 'lost' (default: 5)
   frameDurationMs?: number;    // ms per frame (default: 200)
   sweepIntervalMs?: number;    // Lost-sweep interval (default: 100)
-  artoolkitModuleUrl?: string; // ESM URL for ARToolKit (recommended)
+  artoolkitModuleUrl?: string; // Only needed when using source/dev; NOT needed for dist build
   cameraParametersUrl?: string;// Camera params file URL
-  wasmBaseUrl?: string;        // Base URL for ARToolKit assets (if required)
+  wasmBaseUrl?: string;        // Base URL for ARToolKit assets (if required by your build)
   minConfidence?: number;      // Minimum confidence to forward getMarker (default: 0.6)
 }
 ```
@@ -160,7 +186,10 @@ The example demonstrates:
 
 ## Troubleshooting
 
-- “Failed to resolve module specifier” in the Worker:
+- Worker asset 404:
+    - Ensure you import the ESM from `/dist/arjs-plugin-artoolkit.esm.js` and that `/dist/assets/worker-*.js` is served.
+    - The build uses `base: './'`, so worker URLs are relative to the ESM file location.
+- “Failed to resolve module specifier” in the Worker (source/dev only):
     - Provide `artoolkitModuleUrl` or serve `/node_modules` from your dev server
 - Worker not starting:
     - Serve via HTTP/HTTPS; ensure ES modules and Workers are supported

examples/simple-marker/README.md

@@ -15,8 +15,8 @@ npm install
 ### 2. Serve the Example
 
 You must serve from the repository root so that:
-- ES modules resolve (../../src/plugin.js)
-- The worker module URL (../../node_modules/...) is reachable
+- The built ESM (`/dist/arjs-plugin-artoolkit.esm.js`) and worker asset (`/dist/assets/worker-*.js`) resolve
+- Example paths under `/examples/simple-marker/` resolve
 
 You can use any static file server. Examples:
 
@@ -56,19 +56,26 @@ If you're using VS Code with the Live Server extension:
 
 ## Module resolution
 
-The example config (in `index.html`) passes explicit URLs so the worker can import ARToolKit and camera params:
+When importing the built ESM from `dist/`, ARToolKit is bundled and no extra configuration is required:
 
 ```js
+import { ArtoolkitPlugin } from '/dist/arjs-plugin-artoolkit.esm.js';
+
 const plugin = new ArtoolkitPlugin({
   worker: true,
-  artoolkitModuleUrl: '/node_modules/@ar-js-org/artoolkit5-js/dist/ARToolkit.js',
   cameraParametersUrl: '/examples/simple-marker/data/camera_para.dat'
 });
 ```
 
-If your server can’t serve `/node_modules`, either:
-- Adjust `artoolkitModuleUrl` to a path your server exposes, or
-- Use a CDN ESM URL as a fallback (see project README for details)
+If you develop against `src/` instead, provide an explicit ARToolKit module URL:
+
+```js
+const plugin = new ArtoolkitPlugin({
+  worker: true,
+  artoolkitModuleUrl: '/node_modules/@ar-js-org/artoolkit5-js/dist/ARToolkit.js',
+  cameraParametersUrl: '/examples/simple-marker/data/camera_para.dat'
+});
+```
 
 ## What’s Happening
 
@@ -93,10 +100,9 @@ The `data/patt.hiro` file is a standard ARToolKit pattern. You can replace it wi
 Key parts of the example:
 
 ```javascript
-// Create plugin instance with worker enabled and explicit module/params URLs
+// Create plugin instance with worker enabled (no artoolkitModuleUrl needed with dist)
 const plugin = new ArtoolkitPlugin({
   worker: true,
-  artoolkitModuleUrl: '/node_modules/@ar-js-org/artoolkit5-js/dist/ARToolkit.js',
   cameraParametersUrl: '/examples/simple-marker/data/camera_para.dat'
 });
 
@@ -113,9 +119,7 @@ console.log(`Marker loaded with ID: ${result.markerId}`);
 
 - Worker not loading?
     - Ensure you’re serving via HTTP/HTTPS from the repository root (not `file://`)
-    - Check console for module resolution/CORS errors
-- Module import errors?
-    - Make sure `/node_modules/@ar-js-org/artoolkit5-js/dist/ARToolkit.js` is reachable, or use a CDN URL
+    - Confirm `/dist/arjs-plugin-artoolkit.esm.js` and `/dist/assets/worker-*.js` are reachable
 - Marker not loading?
     - Verify the pattern file path is correct and accessible
     - Ensure the worker is ready before calling `loadMarker()`

examples/simple-marker/index.html

@@ -33,7 +33,7 @@ <h3>Event Log:</h3>
 
 <!-- Only showing the <script type="module"> block; keep the rest unchanged -->
 <script type="module">
-    import { ArtoolkitPlugin } from '../../dist/arjs-plugin-artoolkit.es.js';
+    import { ArtoolkitPlugin } from '../../dist/arjs-plugin-artoolkit.esm.js';
 
     const statusEl = document.getElementById('status');
     const logEl = document.getElementById('log');

vite.config.ts

@@ -8,7 +8,7 @@ export default defineConfig({
             entry: 'src/index.js',
             name: 'ARjsPluginARtoolkit',
             fileName: (format) => `arjs-plugin-artoolkit.${format}.js`,
-            formats: ['es'], // ESM-only build
+            formats: ['esm'], // ESM-only build
         },
         rollupOptions: {
             output: {