docs: adds a tutorial on how to integrate ecma scripts modules through a CDN

README.md

@@ -19,13 +19,14 @@ npm install --save @srgssr/pillarbox-web video.js@8.21.0
 > [!NOTE]
 > `video.js` is now a peer dependency and must be installed by the project that bundles Pillarbox.
 > Version 8.21.0 is the version we use to test the player and is the one we recommend.
-> 
-> This approach is more flexible and consistent with the fact that integrators are responsible for 
+>
+> This approach is more flexible and consistent with the fact that integrators are responsible for
 > providing their own UI components.
 
 In your HTML file, add the following code to initialize Pillarbox:
 
 ```html
+
 <video-js id="my-player" class="pillarbox-js" controls></video-js>
 ```
 
@@ -44,6 +45,9 @@ const player = pillarbox('my-player', {/* options... */ });
 player.src({ src: 'urn:swi:video:48115940', type: 'srgssr/urn' });
 ```
 
+For examples of integrating Pillarbox with popular frameworks, check out this collection of
+[samples][pillarbox-samples].
+
 ## CDN Integration
 
 Pillarbox is an open-source project published as a public NPM package. You can easily include it in
@@ -67,6 +71,8 @@ To integrate Pillarbox Web via CDN, you can include it in your HTML like this:
 </script>
 ```
 
+Try the sample live on StackBlitz: [Open in StackBlitz][stackblitz-umd]
+
 You can also use a different CDN or host the file yourself.
 
 > [!NOTE]
@@ -75,6 +81,11 @@ You can also use a different CDN or host the file yourself.
 > The UMD bundle also exposes `video.js` as a global variable, allowing you to use both and internal
 > extensions as needed.
 
+### ESM integration from a CDN
+
+If you’d like to load Pillarbox from a CDN while taking advantage of modern ES module packages,
+check out this tutorial: [ESM and import maps][esm-tutorial]
+
 ## Documentation
 
 For detailed information on how to use the Pillarbox Web Player, checkout
@@ -150,8 +161,7 @@ To contribute to the theme editor go to: https://github.com/SRGSSR/pillarbox-web
 
 See the [LICENSE](LICENSE) file for more information.
 
-[token-settings]: https://github.com/settings/tokens
-
-[token-guide]: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-with-a-personal-access-token
-
 [js-deliver]: https://www.jsdelivr.com/package/npm/@srgssr/pillarbox-web
+[stackblitz-umd]: https://stackblitz.com/github/srgssr/pillarbox-web-demo/tree/main/samples/umd
+[esm-tutorial]: https://web.pillarbox.ch/api/tutorial-ESM%20and%20import%20maps.html
+[pillarbox-samples]: https://github.com/SRGSSR/pillarbox-web-demo/tree/main/samples

docs/api/tutorials/ESM and import maps.md

@@ -0,0 +1,57 @@
+In this tutorial, we’ll walk through how to integrate **@srgssr/pillarbox-web** using 
+**import maps** and the [esm.sh](https://esm.sh) CDN. This approach ensures that all dependencies 
+(like `video.js` and `videojs-contrib-eme`) resolve to a single shared instance, preventing runtime
+inconsistencies.
+
+## Setting Up Pillarbox with esm.sh
+
+[esm.sh](https://esm.sh) makes this easy by allowing us to declare **external dependencies**. This
+way, both Pillarbox and its plugins share the same `video.js` instance.
+
+Here’s a minimal working example:
+
+```html
+
+<script type="importmap">
+  {
+    "imports": {
+      "video.js": "https://esm.sh/video.js@8.23.3",
+      "videojs-contrib-eme": "https://esm.sh/videojs-contrib-eme@5.5.1?external=video.js",
+      "@srgssr/pillarbox-web": "https://esm.sh/@srgssr/pillarbox-web@1.23.1?external=video.js,videojs-contrib-eme"
+    }
+  }
+</script>
+
+<script type="module">
+  import pillarbox from "@srgssr/pillarbox-web";
+
+  console.log("Pillarbox loaded", pillarbox.VERSION);
+</script>
+```
+
+### Explanation:
+
+* `video.js` is pinned to version **8.23.3**.
+* `videojs-contrib-eme` declares `video.js` as **external**, so it won’t load its own copy.
+* `@srgssr/pillarbox-web` declares both `video.js` and `videojs-contrib-eme` as **external**,
+  reusing the same instances defined above.
+
+This ensures all dependencies are aligned and avoids duplication.
+
+## Alternative: Using JSPM’s Import Map Generator
+
+If you’d rather not manage dependencies manually, you can generate a ready-to-use import map
+with [JSPM Generator](https://generator.jspm.io/).
+
+Simply enter `@srgssr/pillarbox-web` and the plugins you want to use and JSPM will output a verbose 
+but working import map that resolves all transitive dependencies.
+
+## Why Import Maps?
+
+When importing modules from a CDN, you risk ending up with **duplicate instances** of shared
+dependencies. For example, Pillarbox and `videojs-contrib-eme` both depend on `video.js`. If loaded
+separately, you may face issues like plugins not attaching properly because they’re referencing
+different `video.js` instances.
+
+**Import maps** solve this by explicitly telling the browser which CDN URLs to use for specific
+package names, ensuring consistency.

docs/api/tutorials/Player Tips and Tricks.md

@@ -22,7 +22,7 @@ const player = pillarbox('player');
 // overrides the URL and adds a blocking reason
 player.src({
   src: 'urn:bu:media:id',
-  type:'srgssr/urn'
+  type: 'srgssr/urn',
   mediaData: {
     // override the media URL
     url: 'https://fake-url.com/new-media.m3u8',