diff --git a/.distignore b/.distignore
index fdc801e..b5e982c 100644
--- a/.distignore
+++ b/.distignore
@@ -13,11 +13,15 @@
 # --- Frontend sources -------------------------------------------------
 # All TypeScript / Vue under src/ is compiled into js/ at build time
 # and not needed at runtime, EXCEPT src/sw/ which `SwController.php`
-# reads to serve /apps/exelearning/sw.js. Whitelist that subtree
-# before excluding the rest of src/.
+# reads to serve /apps/exelearning/sw.js, and
+# src/embed/exe_external_media/ which `ContentController.php` inlines into every
+# served package. Whitelist those subtrees before excluding the rest of src/.
 + src/
 + src/sw/
 + src/sw/**
++ src/embed/
++ src/embed/exe_external_media/
++ src/embed/exe_external_media/**
 - src/**
 
 # --- Version control & developer metadata --------------------------------
diff --git a/.eslintrc.cjs b/.eslintrc.cjs
index c41d06b..5305279 100644
--- a/.eslintrc.cjs
+++ b/.eslintrc.cjs
@@ -18,6 +18,11 @@ module.exports = {
 		'js/',
 		'node_modules/',
 		'vendor/',
+		// The vendored eXe-core external-media bundle: built artifacts owned by
+		// upstream (eXe ADR-0021), verified byte for byte against the manifest core
+		// published. They are minified output, not source, so our lint rules do not
+		// apply — and a local "fix" here would be overwritten on the next re-vendor.
+		'src/embed/exe_external_media/',
 	],
 	rules: {
 		// `void promise` is the canonical TypeScript way of marking a
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a5b69e0..c90de45 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -41,6 +41,19 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Verify the vendored external-media artifact
+        # eXeLearning core is canonical (eXe ADR-0021): this repo holds the BYTES and
+        # verifies them against the manifest core published, rather than a copy of the
+        # logic that could drift. --build-hash makes it a PROVENANCE check and not merely
+        # an integrity one: without it a locally rebuilt-and-resigned copy would pass.
+        #
+        # The expected hash is PINNED HERE, deliberately, and not read from the vendored
+        # manifest. A hash taken from the copy under test cannot say anything about that
+        # copy: file, digest and buildHash can all be rewritten together, and a check that
+        # trusted them would pass a consistent forgery. Bump it in the same commit that
+        # re-vendors the artifact.
+        run: node src/embed/exe_external_media/verify.mjs src/embed/exe_external_media --build-hash "43c776daa551fd770b6dade520629362e5a8ca8745e4245c359447c4689b34d6"
+
       # Biome lints .ts/.js under src/. Vue single-file components stay
       # with ESLint (better Vue support); see biome.json for scope.
       - name: Biome lint
@@ -177,3 +190,94 @@ jobs:
           # that the file actually got staged into the app tree.
           test -f apps/exelearning/src/sw/exelearning-sw.js \
             || test -f custom_apps/exelearning/src/sw/exelearning-sw.js
+
+  preview-e2e:
+    name: Editor-preview API E2E (real Nextcloud)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: pdo_sqlite, gd, zip, intl, mbstring, ctype, curl, dom, fileinfo, simplexml, xml, xmlreader, xmlwriter
+          coverage: none
+
+      - name: Install Composer dependencies
+        run: composer install --prefer-dist --no-progress
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install JS dependencies
+        run: npm ci
+
+      - name: Build frontend
+        run: npm run build
+
+      - name: Set up Nextcloud server
+        uses: SMillerDev/nextcloud-actions/setup-nextcloud@main
+        with:
+          version: stable33
+          database-type: sqlite
+          cron: false
+
+      - name: Install eXeLearning app into the running Nextcloud
+        uses: SMillerDev/nextcloud-actions/setup-nextcloud-app@main
+        with:
+          app: exelearning
+          check-code: false
+
+      # Serve the installed Nextcloud over HTTP (the built-in PHP server routes
+      # everything through the front controller, `/index.php/...`), enable the
+      # app, create the owner + a second user, then drive the real management
+      # and serving routes end to end. Cookie/session auth is used on purpose so
+      # the CSRF middleware is genuinely exercised.
+      - name: Preview API end-to-end against the running Nextcloud
+        working-directory: ../server
+        env:
+          WORKSPACE: ${{ github.workspace }}
+        run: |
+          set -euo pipefail
+          php occ app:enable exelearning
+          php occ config:system:set trusted_domains 1 --value=127.0.0.1
+          # Treat the origin as plain HTTP end-to-end so the login session cookie
+          # and the SameSite cookies are NOT marked Secure — curl over http never
+          # sends a Secure cookie back, which silently breaks the login POST's
+          # own CSRF/strict-cookie check and leaves every request unauthenticated.
+          # Use a webroot WITHOUT /index.php so cookies get Path=/ (routing still
+          # goes through the /index.php front controller under php -S).
+          php occ config:system:set overwrite.cli.url --value="http://127.0.0.1:8080"
+          php occ config:system:set overwriteprotocol --value=http
+          php occ config:system:delete forcessl 2>/dev/null || true
+          php occ config:system:delete overwritehost 2>/dev/null || true
+
+          export OC_PASS='Preview-e2e-owner-1!'
+          php occ user:add --password-from-env previewe2e1
+          export OC_PASS='Preview-e2e-other-2!'
+          php occ user:add --password-from-env previewe2e2
+
+          # The built-in server's document root is the Nextcloud tree, so the
+          # top-level status.php is served directly (routed app URLs go through
+          # /index.php/... instead).
+          php -S 127.0.0.1:8080 >"${RUNNER_TEMP}/nc-server.log" 2>&1 &
+          echo $! > "${RUNNER_TEMP}/nc-server.pid"
+          ready=
+          for _ in $(seq 1 30); do
+            if curl -sf "http://127.0.0.1:8080/status.php" | grep -q '"installed":true'; then ready=1; break; fi
+            sleep 1
+          done
+          [ "$ready" = "1" ] || { echo "Nextcloud did not come up"; curl -s "http://127.0.0.1:8080/status.php" || true; cat "${RUNNER_TEMP}/nc-server.log"; exit 1; }
+
+          EXE_E2E_BASE="http://127.0.0.1:8080/index.php" \
+          EXE_E2E_USER1=previewe2e1 EXE_E2E_PASS1='Preview-e2e-owner-1!' \
+          EXE_E2E_USER2=previewe2e2 EXE_E2E_PASS2='Preview-e2e-other-2!' \
+            bash "${WORKSPACE}/tests/e2e/preview-api-e2e.sh" \
+            || { echo '--- nextcloud.log (tail) ---'; tail -n 80 data/nextcloud.log 2>/dev/null || true; exit 1; }
+
+          kill "$(cat "${RUNNER_TEMP}/nc-server.pid")" 2>/dev/null || true
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 41a9aaa..08e9f6e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,7 +33,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - CI matrix (`.github/workflows/ci.yml`) covering NC 31/32/33 × PHP
   8.2/8.3/8.4 with rotated databases (sqlite/mysql/pgsql), plus an
   experimental PHP 8.5 cell. Each cell installs the app into a real
-  Nextcloud server and verifies the Service Worker route responds.
+  Nextcloud server and verifies it enables cleanly, and an API-level
+  end-to-end job exercises the editor-preview management and serving routes
+  against a live Nextcloud (CSRF enforcement, ownership, revision publish,
+  sandbox CSP, session deletion).
 - `make ci-matrix` reproduces the matrix locally with Docker.
 - README "Compatibility" table backed by the CI matrix and a CI badge.
 - Initial Nextcloud app scaffold (`appinfo/info.xml`, routes, bootstrap).
diff --git a/Makefile b/Makefile
index 907f9c5..1f8a1d5 100644
--- a/Makefile
+++ b/Makefile
@@ -346,7 +346,12 @@ appstore: package
 # sidesteps that.
 #
 # Override host port with `make up DOCKER_PORT=9000`.
-APP_RUNTIME_DIRS := appinfo lib js templates img src/sw
+# src/embed carries the vendored external-media child bundle, which
+# ContentController inlines into every served package AT RUNTIME — like src/sw,
+# it is shipped source, not build input. Leaving it out made shimSource() return
+# null inside the container: no shim injected, no embed ever promoted, and no
+# error anywhere to say so.
+APP_RUNTIME_DIRS := appinfo lib js templates img src/sw src/embed
 
 # Verify both that the docker CLI exists and that its daemon is
 # reachable. `docker version` talks to the daemon, so it fails with a
diff --git a/README.md b/README.md
index 9e5c180..13d3f5d 100644
--- a/README.md
+++ b/README.md
@@ -33,12 +33,24 @@ playground link (posted as a PR comment) built from that branch — see
 When a user clicks a `.elpx` file in Nextcloud Files:
 
 1. A Nextcloud Viewer modal opens.
-2. The package is downloaded for the current user.
-3. The browser extracts the ZIP archive in memory.
-4. The internal `index.html` renders inside a **sandboxed iframe**.
-5. Relative assets (`html/`, `content/`, `libs/`, `theme/`, `idevices/`,
-   images, CSS, JS, audio, video, …) are served by a scoped Service Worker
-   from the in-memory extraction — no second request to the server.
+2. The package is downloaded and validated for the current user.
+3. The internal `index.html` and its relative assets (`html/`, `content/`,
+   `libs/`, `theme/`, `idevices/`, images, CSS, JS, audio, video, …) render
+   inside an **opaque-origin sandboxed iframe** — a sandbox **without**
+   `allow-same-origin`, so the untrusted author scripts cannot reach the
+   Nextcloud session. The bytes are served over real HTTP from a cookieless,
+   capability-token route (`/content/{token}/{path}`), because a Service Worker
+   cannot back an opaque origin. External media (YouTube/Vimeo/PDF/…) is relayed
+   to the trusted parent page. See [docs/secure-iframe-viewer.md](docs/secure-iframe-viewer.md).
+
+The bundled static editor ("Edit with eXeLearning") renders its live **editor
+preview** the same way — an opaque-origin iframe served over the HTTP preview
+transport (serving contract v2), never the Service Worker. See
+[docs/preview-serving-contract.md](docs/preview-serving-contract.md).
+
+> The legacy Service Worker viewer remains only as an explicit, dev-only opt-in
+> (a trusted-content compatibility mode, **not** a security boundary); the opaque
+> HTTP path is the default.
 
 Optional features:
 
@@ -84,8 +96,9 @@ maintenance ends mid-2026; NC 32 and 33 are the reference targets.
 | npm             | 10 or 11                               |
 | Bun (optional)  | latest stable, only for `build-editor` |
 
-Browsers must support Service Workers in the Nextcloud origin. The viewer
-will refuse to start otherwise.
+The default opaque-origin viewer and the HTTP editor preview are served over
+plain HTTP and do **not** require Service Workers. Only the legacy, opt-in
+Service Worker viewer needs Service Worker support in the Nextcloud origin.
 
 ## Quick start with Docker
 
diff --git a/appinfo/info.xml b/appinfo/info.xml
index 791c955..d5c65f8 100644
--- a/appinfo/info.xml
+++ b/appinfo/info.xml
@@ -6,11 +6,18 @@
     <summary>Preview and edit eXeLearning .elpx packages in Nextcloud</summary>
     <description><![CDATA[
 Provides a Nextcloud Files viewer for eXeLearning `.elpx` packages by
-rendering the internal `index.html` inside a sandboxed iframe.
+rendering the internal `index.html` inside an opaque-origin sandboxed iframe.
 
 The app registers a Nextcloud Viewer handler so `.elpx` files open in a modal
 with the package fully navigable: HTML pages, CSS, JavaScript, images, audio
-and video resolve from the package contents through a scoped Service Worker.
+and video resolve from the package contents. Because the rendered author
+content is untrusted, it is served from a cookieless, capability-token HTTP
+route into a sandbox without `allow-same-origin` — a browser-enforced opaque
+origin isolated from the Nextcloud session — rather than same-origin. External
+media (YouTube, Vimeo, PDF, …) is relayed to the trusted parent page. The
+bundled static editor renders its live preview the same way, over the HTTP
+editor-preview transport (serving contract v2). A legacy Service Worker viewer
+survives only as an explicit, dev-only opt-in.
 
 Optional features:
 
@@ -37,4 +44,8 @@ This app is Nextcloud-native and does not depend on Google Drive.
         <php min-version="8.2" max-version="8.5"/>
         <nextcloud min-version="31" max-version="33"/>
     </dependencies>
+
+    <background-jobs>
+        <job>OCA\ExeLearning\BackgroundJob\PreviewCleanupJob</job>
+    </background-jobs>
 </info>
diff --git a/appinfo/routes.php b/appinfo/routes.php
index ded2661..00032f7 100644
--- a/appinfo/routes.php
+++ b/appinfo/routes.php
@@ -21,6 +21,42 @@
 			'verb' => 'GET',
 			'requirements' => ['path' => '.+'],
 		],
+		[
+			'name' => 'content#serve',
+			'url' => '/content/{token}/{path}',
+			'verb' => 'GET',
+			'requirements' => ['token' => '[A-Za-z0-9._~-]+', 'path' => '.+'],
+			'defaults' => ['path' => 'index.html'],
+		],
+		// Opaque editor preview. The serving route is an authless, cookieless
+		// capability URL gated solely on the unguessable previewId UUID; the
+		// management routes are authenticated + owner-scoped (CSRF on).
+		[
+			'name' => 'preview#serve',
+			'url' => '/preview/{previewId}/{path}',
+			'verb' => 'GET',
+			'requirements' => [
+				'previewId' => '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}',
+				'path' => '.+',
+			],
+		],
+		[
+			'name' => 'preview#serveRoot',
+			'url' => '/preview/{previewId}',
+			'verb' => 'GET',
+			'requirements' => ['previewId' => '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'],
+		],
+		[
+			'name' => 'previewSession#create',
+			'url' => '/api/preview-session',
+			'verb' => 'POST',
+		],
+		[
+			'name' => 'previewSession#delete',
+			'url' => '/api/preview-session/{previewId}',
+			'verb' => 'DELETE',
+			'requirements' => ['previewId' => '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'],
+		],
 		[
 			'name' => 'thumbnail#byFileId',
 			'url' => '/thumbnail/by-file-id/{fileId}',
diff --git a/biome.json b/biome.json
index 48e4ede..09f3bef 100644
--- a/biome.json
+++ b/biome.json
@@ -16,7 +16,8 @@
 			"!**/coverage/**",
 			"!**/js/**",
 			"!**/exelearning/**",
-			"!**/*.vue"
+			"!**/*.vue",
+			"!**/src/embed/exe_external_media/**"
 		]
 	},
 	"formatter": {
diff --git a/blueprint.json b/blueprint.json
index c7c8346..7798b25 100644
--- a/blueprint.json
+++ b/blueprint.json
@@ -30,6 +30,13 @@
       "url": "https://github-proxy.exelearning.dev/?repo=exelearning/exelearning&release=v4.0.2&asset=exelearning-static-v4.0.2.zip",
       "destination": "apps/exelearning/js/editor"
     },
+    {
+      "step": "setConfig",
+      "comment": "DEV-ONLY Playground demo hatch — NEVER production. The viewer defaults to the secure opaque-origin /content/{token} route, which a Service Worker CANNOT serve (it 404s in the php-wasm Playground). This app-config value is read by the envReader wired in lib/AppInfo/Application.php and flips lib/Service/IframeSandbox::resolveMode() to 'legacy', so ViewController hands the viewer the same-origin Service-Worker/AssetController path that DOES render in the browser. Mirrors the wp-exelearning mu-plugin / mod_exelearning phpConstants demo hatch. Maps to `occ config:app:set exelearning unsafe_legacy_iframe --value 1`; re-introduces allow-same-origin and drops opaque-origin isolation, so it must never be set on a real deployment.",
+      "app": "exelearning",
+      "key": "unsafe_legacy_iframe",
+      "value": "1"
+    },
     {
       "step": "writeFile",
       "path": "config/mimetypemapping.json",
diff --git a/docs/preview-serving-contract.md b/docs/preview-serving-contract.md
new file mode 100644
index 0000000..3502d8b
--- /dev/null
+++ b/docs/preview-serving-contract.md
@@ -0,0 +1,162 @@
+# Opaque editor preview — Nextcloud adapter
+
+The embedded editor renders its preview **filtered** by default: sanitised, with
+no author JavaScript running. When the author opts in to running their own code,
+the editor needs somewhere to put the real project bytes that is **not** the
+Nextcloud page — a browser-enforced **opaque origin** the content cannot reach
+out of.
+
+This app is that somewhere. The editor POSTs the whole project as one ZIP and
+gets back an unguessable capability id; the app serves that tree from an authless
+route under a sandbox CSP. There is no authored-content `srcdoc` transport and no
+Service Worker fallback here: missing or invalid configuration **fails closed**
+and the filtered preview stays.
+
+The sandbox CSP string must stay **byte-identical** to eXe core's
+`previewCspHeader()`; core is authoritative.
+
+## Why not the Service Worker
+
+For *published* `.elpx` content this app serves package bytes same-origin (the
+Service Worker `src/sw/exelearning-sw.js` and the authenticated
+`AssetController::fetch`) — fine for content the owner has committed.
+
+The **editor preview** is different: it renders *untrusted, unsaved* author HTML
+and SVG that can contain arbitrary scripts. Rendering that same-origin — or via a
+Service Worker in our scope — would let it read the Nextcloud session, call our
+APIs and pivot. A Service Worker **cannot** back an opaque origin (its
+subresources bypass the SW), so the preview is served from an authless,
+cookieless route and never through the Service Worker.
+
+## The two endpoints
+
+| | Request | Result |
+|---|---|---|
+| Management | `POST {basePath}/api/preview-session` | multipart `snapshot=<zip>`, optional `previewId` → `{previewId}` |
+| Management | `DELETE {basePath}/api/preview-session/{previewId}` | drops the snapshot |
+| Serving | `GET {basePath}/preview/{previewId}/{path}` | the snapshot, authless |
+
+Management is the only authenticated surface: a logged-in `IUserSession` user
+plus Nextcloud's ordinary CSRF check (the actions are deliberately **not**
+`#[NoCSRFRequired]`, mirroring `editor#save`), and the store scopes every
+snapshot to its owner (403/404).
+
+Serving carries no authentication at all. The unguessable id plus the idle TTL is
+the whole credential, which is what makes the origin opaque — an iframe pointed
+at this URL carries no Nextcloud session, so author code inside it has nothing to
+steal.
+
+## Why one whole snapshot
+
+An earlier revision implemented a layered protocol (contract v2): immutable asset
+keys uploaded once, incremental document revisions, and a manifest of fixed
+installation resources resolved out of the editor distribution — all to avoid
+re-uploading unchanged bytes. The editor no longer speaks it; it was handed a
+contract nothing read while the one it does read (`previewSnapshot`) was
+withheld, which left the opaque preview unreachable here. One ZIP per refresh
+replaced the store, the fixed-resource layer and the four-operation management
+API.
+
+## Storage
+
+    {datadirectory}/exelearning/preview-snapshots/{previewId}/
+      meta.json    ownerUserId, createdAt, bytes
+      .accessed    empty marker; its mtime is the idle-TTL / LRU clock
+      content/     the extracted snapshot
+
+Outside the web root, so no direct web-server path can bypass the serving route
+and its sandbox CSP. The root comes from `datadirectory` rather than `IAppData`
+because the store needs a POSIX-local directory for atomic renames, and
+`IAppData` may be object storage. Content sits in its own subdirectory so no
+author path can collide with the store's own files — there are no reserved names
+to police. A write is staged beside the live tree and swapped in, so a reader
+sees the previous snapshot or the new one, never a half-written one.
+
+## What an archive must survive before extraction
+
+`SnapshotArchive` vets every entry **before** anything is written, then extracts
+under a byte budget:
+
+- Unsafe entries (absolute paths, backslashes, `.`/`..` segments, NUL bytes) and
+  symbolic links reject the **whole** archive in the first pass.
+- The zip-bomb cap is enforced on the **real decompressed bytes** as they stream
+  out, not on the sizes declared in the central directory — those are supplied by
+  whoever built the archive. The declared total is only an early reject.
+- An `index.html` must be present, or it is not a preview.
+
+## Bounds
+
+Nextcloud is the one adapter where these matter beyond a single author, because
+one shared instance hosts many users against one filesystem:
+
+| Bound | Default |
+|---|---|
+| Idle TTL | 30 min |
+| Snapshots per user | 4 (LRU-evicted) |
+| Files per snapshot | 5000 |
+| Bytes per snapshot | 200 MiB |
+| Global | 2 GiB (LRU-evicted, then 507) |
+
+Serving a snapshot pushes its idle clock back, so a preview in use never expires
+under the author. Every publish sweeps, and `PreviewCleanupJob` sweeps every
+10 minutes, so the store never depends on cron alone to bound its size.
+
+## Response headers
+
+Every response, 404s included, carries `X-Content-Type-Options: nosniff`,
+`Referrer-Policy: no-referrer`, the preview `Permissions-Policy` and
+`Access-Control-Allow-Origin: *` — safe here precisely because the route is
+authless and cookieless, and never to be paired with credentials. There is
+deliberately no `X-Frame-Options`: framing is governed by the CSP
+`frame-ancestors` directive.
+
+Every **scriptable** type — `text/html`, `image/svg+xml`, XML, XHTML — also gets
+the sandbox CSP, so a capability URL stays opaque even when opened directly. Not
+just HTML: an author-supplied SVG runs its inline `<script>` top-level, and
+`nosniff` does not help — SVG is already a scriptable type.
+
+Caching is tiered: a scriptable document is `no-store` (it is rewritten on every
+refresh), everything else revalidates with an `ETag` and supports single-range
+206/416, which is what makes a video inside the snapshot seek without a full
+re-download.
+
+The bare capability URL (`…/{previewId}`) never serves `index.html` bytes: it
+302s to `…/{previewId}/index.html`, so the opaque iframe's base URL is the
+snapshot directory. The `Location` is relative, so it stays correct under any
+Nextcloud webroot.
+
+## Client wiring
+
+`EditorController::previewSnapshotConfig()` injects into
+`window.__EXE_EMBEDDING_CONFIG__`:
+
+```jsonc
+"previewSnapshot": {
+  "managementUrl":     "{basePath}/api/preview-session",
+  "servingBaseUrl":    "{basePath}/preview",
+  "deleteUrlTemplate": "{basePath}/api/preview-session/{previewId}",
+  "managementHeaders": { "requesttoken": "…" }
+}
+```
+
+Every URL is generated server-side through the router, so it carries the correct
+webroot and front-controller prefix under a sub-path install. `requesttoken` is
+the current Nextcloud CSRF token: it stays valid for the whole editing session,
+because a token is bound to a per-session secret that only rotates when the
+session id does — and that invalidates the parent page hosting the iframe, which
+reloads and injects a fresh one.
+
+## External video inside the opaque iframe
+
+An opaque origin fails YouTube's and Vimeo's embedder check (Error 153), so the
+players cannot run inside the sandbox. `exe-external-media-child.min.js` — inlined into the
+served package by `ContentController` — demotes provider iframes to geometry
+placeholders, and `exe-external-media-host.min.js` on the trusted parent (driven by
+`src/embed/relay-host.ts`) overlays the real player over each one.
+
+## Tests
+
+`PreviewSnapshotStoreTest` covers the capability lifecycle, owner scoping, the
+archive guards and the DoS bounds; `PreviewServerTest` covers the serving
+response contract; `PreviewPolicyTest` covers MIME/scriptable classification and
+path normalization.
diff --git a/docs/secure-iframe-viewer.md b/docs/secure-iframe-viewer.md
new file mode 100644
index 0000000..07f6e86
--- /dev/null
+++ b/docs/secure-iframe-viewer.md
@@ -0,0 +1,62 @@
+# Secure (opaque-origin) published-content viewer
+
+The Nextcloud Viewer renders **published `.elpx` content** — untrusted, author-authored
+HTML/JS — in a browser-enforced **opaque origin**, and relays external media
+(YouTube/Vimeo/Dailymotion/EducaMadrid/PDF + the interactive-video iDevice) to the
+trusted parent page. This matches the secure-iframe mode already shipped by the
+Moodle, WordPress and Omeka S plugins.
+
+## Why
+
+Rendered author content runs scripts. Same-origin, those scripts can read the
+Nextcloud DOM, the session/cookie surface, IndexedDB and app pages. The fix is an
+**opaque origin**: a sandboxed iframe **without `allow-same-origin`**, whose
+document is served with a response-level `Content-Security-Policy: … sandbox …`.
+A Service Worker **cannot** back an opaque origin (its subresources bypass it), so
+the opaque path is served over real HTTP, not the SW.
+
+## How it works
+
+| Piece | File |
+|---|---|
+| Opaque sandbox tokens + published CSP + provider whitelist + embed mode | `lib/Service/IframeSandbox.php` |
+| Capability token (fileId-bound, HMAC, short-lived) | `lib/Service/ContentTokenService.php` |
+| Cookieless serving route `/content/{token}/{path}` | `lib/Controller/ContentController.php` |
+| Token minted at view-open (read permission checked here) | `lib/Controller/ViewController.php` |
+| Opaque iframe (`allow-scripts allow-popups allow-forms`) | `src/elpx/iframe-renderer.ts` |
+| Relay + media host in the parent page | `src/embed/relay-host.ts` + `src/viewer/ElpxViewer.vue` |
+| eXe-core external-media bundle (vendored) | `src/embed/exe_external_media/exe-external-media-child.min.js`, `exe-external-media-host.min.js` |
+
+Flow: the Viewer downloads + validates the package (legacy `.elp` → migration
+prompt), then loads the opaque iframe from `/content/{token}/index.html`. The PHP
+`ContentController` verifies the token, resolves the file, serves each entry with
+the sandbox CSP, and **inlines the embed shim** into HTML. Inside the opaque iframe
+the shim promotes each cross-origin/PDF sub-iframe to a geometry placeholder; the
+parent's relay (`exe-external-media-host.min.js`) overlays a real player over it, and the media
+host (`exe_media_host.js`) drives the interactive-video iDevice.
+
+## Capability model (cookieless)
+
+The opaque origin sends no Nextcloud cookie, so the serving route is a
+`#[PublicPage]` gated purely by an unguessable, short-lived, fileId-bound HMAC
+token minted in `ViewController` — where the user's read permission is checked.
+This mirrors Moodle's `tokenpluginfile` model. The response carries
+`Access-Control-Allow-Origin: *` (sound only because the origin is cookieless) and
+`Referrer-Policy: no-referrer` / `X-Content-Type-Options: nosniff` on every
+response including 404s.
+
+## Modes / escape hatches
+
+- **Secure (default).** Opaque `/content` route. No setting required.
+- **Legacy same-origin (dev only).** Set `EXELEARNING_UNSAFE_LEGACY_IFRAME=1` to
+  fall back to the same-origin Service-Worker `/runtime` path. Never a UI setting.
+- **Embed relay mode.** `strict` (default) overlays only the maintained provider
+  hosts; set `EXELEARNING_EMBED_OPEN=1` for `open` mode (any cross-origin https
+  player the shim reports).
+
+## Keeping the bridge in sync
+
+`src/embed/exe_*.js` are byte-synced mirrors of eXe core
+`public/app/common/exe_embed_bridge/` + `exe_media_bridge/`. Verify with the core
+drift checker: `node scripts/check-embed-sync.mjs --nextcloud <this-repo>`. They are
+excluded from ESLint/Biome (they keep upstream's code style).
diff --git a/lib/AppInfo/Application.php b/lib/AppInfo/Application.php
index d7a6019..b2d79a3 100644
--- a/lib/AppInfo/Application.php
+++ b/lib/AppInfo/Application.php
@@ -5,11 +5,17 @@
 namespace OCA\ExeLearning\AppInfo;
 
 use OCA\ExeLearning\Preview\ElpxPreviewProvider;
+use OCA\ExeLearning\Service\ContentTokenService;
+use OCA\ExeLearning\Service\IframeSandbox;
+use OCA\ExeLearning\Service\Preview\PreviewSnapshotLimits;
+use OCA\ExeLearning\Service\Preview\PreviewSnapshotStore;
 use OCP\AppFramework\App;
 use OCP\AppFramework\Bootstrap\IBootContext;
 use OCP\AppFramework\Bootstrap\IBootstrap;
 use OCP\AppFramework\Bootstrap\IRegistrationContext;
+use OCP\IConfig;
 use OCP\Util;
+use Psr\Container\ContainerInterface;
 
 class Application extends App implements IBootstrap {
 	public const APP_ID = 'exelearning';
@@ -57,6 +63,86 @@ public function register(IRegistrationContext $context): void {
 		// the legacy `IPreview::registerProviderV2()` call in boot() only
 		// covered some of those code paths.
 		$context->registerPreviewProvider(ElpxPreviewProvider::class, ElpxPreviewProvider::MIME_REGEX);
+
+		// The capability-token service needs the instance secret as a plain
+		// string (it is kept OCP-free for unit testing), so it cannot be
+		// auto-wired — provide a factory that reads it from IConfig.
+		$context->registerService(ContentTokenService::class, static function (ContainerInterface $c): ContentTokenService {
+			return new ContentTokenService((string)$c->get(IConfig::class)->getSystemValue('secret', ''));
+		});
+
+		// IframeSandbox is OCP-free (so it stays unit-testable) and by default
+		// reads its dev-only escape hatches straight from the process env. We
+		// override the default wiring with a reader that ALSO consults a
+		// Nextcloud app-config value — the ONLY way to flip the hatch inside the
+		// php-wasm Playground, which cannot set process env vars. See
+		// {@see self::iframeSandboxEnvReader()} for the (unit-tested) precedence
+		// rules. IConfig lives here in the factory, never inside IframeSandbox.
+		$context->registerService(IframeSandbox::class, static function (ContainerInterface $c): IframeSandbox {
+			$config = $c->get(IConfig::class);
+			return new IframeSandbox(self::iframeSandboxEnvReader(
+				getenv(...),
+				static fn (string $key): string => $config->getAppValue(self::APP_ID, $key, ''),
+			));
+		});
+
+		// Opaque editor preview (docs/preview-serving-contract.md). The
+		// file-backed snapshot store needs a POSIX-local directory (atomic
+		// rename), so its root is resolved from the Nextcloud data directory
+		// rather than IAppData (which may be object storage). The store itself
+		// stays OCP-free; this factory is the only OCP seam. PreviewServer and
+		// the controllers auto-wire from it.
+		$context->registerService(PreviewSnapshotStore::class, static function (ContainerInterface $c): PreviewSnapshotStore {
+			$config = $c->get(IConfig::class);
+			$dataDir = (string)$config->getSystemValue('datadirectory', '');
+			$base = $dataDir !== '' ? $dataDir : sys_get_temp_dir();
+			$root = rtrim($base, '/') . '/' . self::APP_ID . '/preview-snapshots';
+			return new PreviewSnapshotStore($root, new PreviewSnapshotLimits());
+		});
+	}
+
+	/**
+	 * Build the environment reader {@see IframeSandbox} uses to resolve its
+	 * dev-only escape hatches (`EXELEARNING_UNSAFE_LEGACY_IFRAME`,
+	 * `EXELEARNING_EMBED_OPEN`).
+	 *
+	 * Precedence:
+	 *   1. The process environment wins — the real-host mechanism (a systemd
+	 *      `Environment=`, an Apache `SetEnv`, the wp-exelearning mu-plugin
+	 *      `putenv`, or Moodle `$CFG` phpconstants). An explicitly-empty env
+	 *      var still wins and therefore disables the hatch.
+	 *   2. Otherwise fall back to a Nextcloud app-config value under this app
+	 *      (`EXELEARNING_UNSAFE_LEGACY_IFRAME` -> `unsafe_legacy_iframe`,
+	 *      `EXELEARNING_EMBED_OPEN` -> `embed_open`). This exists ONLY because
+	 *      the php-wasm Nextcloud Playground cannot set process env vars, yet
+	 *      the browser-only demo still needs to flip the hatch so the
+	 *      same-origin viewer — the one a Service Worker can actually serve —
+	 *      renders. The blueprint sets it with a `setConfig`/`config:app:set`
+	 *      step.
+	 *
+	 * DEV-ONLY: enabling the legacy hatch re-introduces `allow-same-origin` and
+	 * drops the opaque-origin isolation that protects against the published
+	 * package's untrusted scripts. NEVER set it on a real deployment.
+	 *
+	 * The reader is a pure function of the two injected lookups so it stays
+	 * unit-testable without a Nextcloud server; it is the only seam that knows
+	 * app-config exists, keeping IframeSandbox itself OCP-free.
+	 *
+	 * @param callable(string):(string|false) $getenv Process-env lookup (getenv()).
+	 * @param callable(string):string $getAppValue App-config lookup, already
+	 *                                             bound to this app id; '' means unset.
+	 * @return callable(string):?string
+	 */
+	public static function iframeSandboxEnvReader(callable $getenv, callable $getAppValue): callable {
+		return static function (string $name) use ($getenv, $getAppValue): ?string {
+			$env = $getenv($name);
+			if ($env !== false) {
+				return (string)$env;
+			}
+			$key = str_starts_with($name, 'EXELEARNING_') ? substr($name, 12) : $name;
+			$value = $getAppValue(strtolower($key));
+			return $value === '' ? null : $value;
+		};
 	}
 
 	public function boot(IBootContext $context): void {
diff --git a/lib/BackgroundJob/PreviewCleanupJob.php b/lib/BackgroundJob/PreviewCleanupJob.php
new file mode 100644
index 0000000..ab0ee94
--- /dev/null
+++ b/lib/BackgroundJob/PreviewCleanupJob.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\BackgroundJob;
+
+use OCA\ExeLearning\Service\Preview\PreviewSnapshotStore;
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\BackgroundJob\TimedJob;
+
+/**
+ * Periodically sweeps idle-expired preview snapshots from disk. Registered in
+ * appinfo/info.xml `<background-jobs>`. A belt-and-braces measure: the serving
+ * route also drops an expired snapshot opportunistically on access, so preview
+ * URLs stop resolving at the TTL even if cron is starved.
+ */
+class PreviewCleanupJob extends TimedJob {
+	public function __construct(
+		ITimeFactory $time,
+		private readonly PreviewSnapshotStore $store,
+	) {
+		parent::__construct($time);
+		// Snapshots have a 30-min idle TTL; sweeping every 10 min bounds the
+		// window in which an expired session's files linger on disk.
+		$this->setInterval(10 * 60);
+		$this->setTimeSensitivity(self::TIME_INSENSITIVE);
+	}
+
+	protected function run($argument): void {
+		$this->store->sweepExpired();
+	}
+}
diff --git a/lib/Controller/AssetController.php b/lib/Controller/AssetController.php
index 2d6e22a..8ec1f8f 100644
--- a/lib/Controller/AssetController.php
+++ b/lib/Controller/AssetController.php
@@ -5,6 +5,7 @@
 namespace OCA\ExeLearning\Controller;
 
 use OCA\ExeLearning\Service\ElpxPackageService;
+use OCA\ExeLearning\Service\PackageMimeService;
 use OCA\ExeLearning\Service\ZipEntryService;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
@@ -27,37 +28,13 @@
  * the current user can read the underlying file before serving any bytes.
  */
 class AssetController extends Controller {
-	private const MIME_MAP = [
-		'html' => 'text/html; charset=utf-8',
-		'htm' => 'text/html; charset=utf-8',
-		'css' => 'text/css; charset=utf-8',
-		'js' => 'text/javascript; charset=utf-8',
-		'mjs' => 'text/javascript; charset=utf-8',
-		'json' => 'application/json; charset=utf-8',
-		'svg' => 'image/svg+xml',
-		'png' => 'image/png',
-		'jpg' => 'image/jpeg',
-		'jpeg' => 'image/jpeg',
-		'gif' => 'image/gif',
-		'webp' => 'image/webp',
-		'mp3' => 'audio/mpeg',
-		'mp4' => 'video/mp4',
-		'ogg' => 'audio/ogg',
-		'wav' => 'audio/wav',
-		'webm' => 'video/webm',
-		'vtt' => 'text/vtt',
-		'woff' => 'font/woff',
-		'woff2' => 'font/woff2',
-		'ttf' => 'font/ttf',
-		'eot' => 'application/vnd.ms-fontobject',
-	];
-
 	public function __construct(
 		string $appName,
 		IRequest $request,
 		private readonly IUserSession $userSession,
 		private readonly ElpxPackageService $packageService,
 		private readonly ZipEntryService $zipEntries,
+		private readonly PackageMimeService $mime,
 	) {
 		parent::__construct($appName, $request);
 	}
@@ -90,16 +67,11 @@ public function fetch(string $sessionId, string $path): DataDisplayResponse|Data
 			return new DataResponse(['error' => 'Entry not found'], Http::STATUS_NOT_FOUND);
 		}
 
-		$mime = $this->detectMime($entry);
+		$mime = $this->mime->detect($entry);
 		$response = new DataDisplayResponse($contents, Http::STATUS_OK, ['Content-Type' => $mime]);
 		$response->addHeader('X-Content-Type-Options', 'nosniff');
 		$response->addHeader('Content-Security-Policy', "default-src 'self' 'unsafe-inline' 'unsafe-eval' data: blob:; frame-ancestors 'self'");
 		$response->addHeader('Cache-Control', 'private, max-age=300');
 		return $response;
 	}
-
-	private function detectMime(string $entry): string {
-		$extension = strtolower(pathinfo($entry, PATHINFO_EXTENSION));
-		return self::MIME_MAP[$extension] ?? 'application/octet-stream';
-	}
 }
diff --git a/lib/Controller/ContentController.php b/lib/Controller/ContentController.php
new file mode 100644
index 0000000..4d7cc2a
--- /dev/null
+++ b/lib/Controller/ContentController.php
@@ -0,0 +1,127 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Controller;
+
+use OCA\ExeLearning\Service\ContentTokenService;
+use OCA\ExeLearning\Service\ElpxPackageService;
+use OCA\ExeLearning\Service\EmbedShimInjector;
+use OCA\ExeLearning\Service\EmbedShimSource;
+use OCA\ExeLearning\Service\IframeSandbox;
+use OCA\ExeLearning\Service\PackageMimeService;
+use OCA\ExeLearning\Service\ZipEntryService;
+use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\PublicPage;
+use OCP\AppFramework\Http\DataDisplayResponse;
+use OCP\Files\NotFoundException;
+use OCP\Files\NotPermittedException;
+use OCP\IRequest;
+
+/**
+ * Serves PUBLISHED .elpx content into an **opaque-origin** iframe over a real
+ * HTTP capability URL.
+ *
+ * Unlike {@see AssetController} (authenticated, same-origin, Service-Worker
+ * fallback), this route is a cookieless `#[PublicPage]`: the caller presents a
+ * short-lived {@see ContentTokenService} token minted by {@see ViewController}
+ * at view-open (where the user's read permission was checked). The response
+ * carries a response-level sandbox CSP ({@see IframeSandbox}) that makes the
+ * document opaque, and HTML documents get the eXe-core embed shim inlined so
+ * external media (YouTube/Vimeo/PDF) can be relayed to the trusted parent.
+ *
+ * A Service Worker cannot back an opaque origin, so this path never uses one.
+ */
+class ContentController extends Controller {
+	public function __construct(
+		string $appName,
+		IRequest $request,
+		private readonly ContentTokenService $tokens,
+		private readonly ElpxPackageService $packageService,
+		private readonly ZipEntryService $zipEntries,
+		private readonly PackageMimeService $mime,
+		private readonly IframeSandbox $sandbox,
+		private readonly EmbedShimInjector $shimInjector,
+	) {
+		parent::__construct($appName, $request);
+	}
+
+	/**
+	 * GET /apps/exelearning/content/{token}/{path}
+	 *
+	 * The frontend always builds a full entry path (defaulting to index.html),
+	 * so a single `{path}` route with a `.+` requirement covers the package
+	 * index and every subresource/subpage.
+	 */
+	#[PublicPage]
+	#[NoCSRFRequired]
+	public function serve(string $token, string $path = 'index.html'): DataDisplayResponse {
+		$capability = $this->tokens->verify($token);
+		if ($capability === null) {
+			return $this->notFound();
+		}
+		[$fileId, $userId] = $capability;
+		$entry = $this->zipEntries->normalizeEntry($path);
+		if ($entry === null) {
+			return $this->notFound();
+		}
+		try {
+			// Resolve via the token's user so the user's storage is mounted and
+			// the read permission is re-checked (the token proves a past grant).
+			$file = $this->packageService->getForUserById($userId, $fileId);
+		} catch (NotFoundException|NotPermittedException) {
+			return $this->notFound();
+		}
+		$bytes = $this->zipEntries->readEntry($file, $entry);
+		if ($bytes === null) {
+			return $this->notFound();
+		}
+
+		$mime = $this->mime->detect($entry);
+		if ($this->mime->isHtmlDocument($mime)) {
+			$shim = $this->shimSource();
+			if ($shim !== null) {
+				$bytes = $this->shimInjector->injectIntoHead($bytes, $shim);
+			}
+		}
+
+		$response = new DataDisplayResponse($bytes, Http::STATUS_OK, ['Content-Type' => $mime]);
+		$this->harden($response);
+		if ($this->mime->isHtmlDocument($mime)) {
+			$response->addHeader('Content-Security-Policy', $this->sandbox->contentSecurityPolicy());
+		} elseif ($this->mime->isLockedXml($mime)) {
+			$response->addHeader('Content-Security-Policy', $this->sandbox->svgCsp());
+		}
+		return $response;
+	}
+
+	/**
+	 * Inline shim source, or null when the vendored artifact is not present. Read from
+	 * src/embed/ at runtime, the same way {@see SwController} reads
+	 * src/sw/exelearning-sw.js — the app ships its src/ tree.
+	 *
+	 * The bytes are the CANONICAL child bundle from eXeLearning core, not a copy kept
+	 * here; {@see EmbedShimSource} owns that decision and is unit-tested for it.
+	 */
+	private function shimSource(): ?string {
+		return (new EmbedShimSource())->read();
+	}
+
+	/** 404 with the mandatory hardening headers (present on every response). */
+	private function notFound(): DataDisplayResponse {
+		$response = new DataDisplayResponse('Not Found', Http::STATUS_NOT_FOUND, ['Content-Type' => 'text/plain; charset=utf-8']);
+		$this->harden($response);
+		return $response;
+	}
+
+	private function harden(DataDisplayResponse $response): void {
+		$response->addHeader('X-Content-Type-Options', 'nosniff');
+		$response->addHeader('Referrer-Policy', 'no-referrer');
+		$response->addHeader('Cache-Control', 'no-store');
+		$response->addHeader('Permissions-Policy', $this->sandbox->permissionsPolicy());
+		// Cookieless capability origin — safe to allow any reader, never with credentials.
+		$response->addHeader('Access-Control-Allow-Origin', '*');
+	}
+}
diff --git a/lib/Controller/EditorController.php b/lib/Controller/EditorController.php
index 30e4879..e1baf31 100644
--- a/lib/Controller/EditorController.php
+++ b/lib/Controller/EditorController.php
@@ -4,6 +4,7 @@
 
 namespace OCA\ExeLearning\Controller;
 
+use OC\Security\CSRF\CsrfTokenManager;
 use OCA\ExeLearning\AppInfo\Application;
 use OCA\ExeLearning\Service\ElpxPackageService;
 use OCP\AppFramework\Controller;
@@ -39,6 +40,7 @@ public function __construct(
 		private readonly ElpxPackageService $packageService,
 		private readonly IInitialState $initialState,
 		private readonly IURLGenerator $urlGenerator,
+		private readonly CsrfTokenManager $csrfTokenManager,
 	) {
 		parent::__construct($appName, $request);
 	}
@@ -205,7 +207,9 @@ private function migrateLegacyExtensionIfNeeded(
 	 *    asset paths (`./libs/...`, `./style/...`) resolve correctly even
 	 *    when the app is mounted under `/custom_apps/`.
 	 *  - `window.__EXE_EMBEDDING_CONFIG__` populated before any editor
-	 *    script runs (the editor's RuntimeConfig reads it during bootstrap).
+	 *    script runs (the editor's RuntimeConfig reads it during bootstrap),
+	 *    including the `previewSnapshot` block that wires the opaque preview —
+	 *    see {@see previewSnapshotConfig()}.
 	 *  - A small bridge that forwards Ctrl/Cmd+S to the parent and patches
 	 *    `EmbeddingBridge.handleSaveRequest` for the v4.0.0 export quirk.
 	 *  - A permissive CSP — eXeLearning has many inline scripts and styles;
@@ -249,11 +253,13 @@ public function iframe(): DataDisplayResponse|DataResponse {
 			],
 		], JSON_UNESCAPED_SLASHES);
 
+		$previewSnapshot = json_encode($this->previewSnapshotConfig(), JSON_HEX_TAG);
+
 		$configScript = '<script>(function(){'
 			. 'var base=new URL(".",document.baseURI).href.replace(/\\/+$/,"");'
 			. 'var origin=window.location.origin;'
 			. 'window.__EXE_EMBEDDING_CONFIG__=Object.assign(' . $staticConfig . ','
-			. '{basePath:base,parentOrigin:origin,trustedOrigins:[origin]});'
+			. '{basePath:base,parentOrigin:origin,trustedOrigins:[origin],previewSnapshot:' . $previewSnapshot . '});'
 			. '})();</script>';
 
 		// The resilience shim must be installed before any editor script
@@ -292,6 +298,74 @@ public function iframe(): DataDisplayResponse|DataResponse {
 		return $response;
 	}
 
+	/**
+	 * The `previewSnapshot` block handed to the embedded editor so it can publish
+	 * opaque previews: `{ managementUrl, servingBaseUrl, deleteUrlTemplate,
+	 * managementHeaders }`.
+	 *
+	 *  - Both URLs are generated server-side through the router so they carry the
+	 *    correct webroot and front-controller prefix under a sub-path install,
+	 *    mirroring the client's `@nextcloud/router` `generateUrl`. The serving
+	 *    routes are parameterised, so the base is derived by generating the bare
+	 *    capability-root URL for a placeholder id and stripping that id segment.
+	 *  - `managementHeaders.requesttoken` is the current Nextcloud CSRF token —
+	 *    the same encrypted value the standard template layer exposes as
+	 *    `data-requesttoken`. It is required because the management routes keep
+	 *    CSRF ON (they are NOT `#[NoCSRFRequired]`); the editor replays it on every
+	 *    management request.
+	 *
+	 * Token lifetime (audited — the injected-token approach is durable, no
+	 * refresh path needed now): a Nextcloud CSRF token is bound to a per-session
+	 * secret. `getEncryptedValue()` returns a per-call randomized encoding, but
+	 * every value minted from the same session validates against that one secret
+	 * (`isTokenValid()` decrypts and compares), so the injected value stays valid
+	 * for the whole editing session — hours — not just one request. The secret is
+	 * regenerated only when the session id itself is regenerated (login / logout /
+	 * re-auth), never on ordinary navigation; and whenever that happens the parent
+	 * Nextcloud page hosting this iframe is itself invalidated and reloads, which
+	 * re-runs iframe() and injects a fresh token. The parent page also keeps the
+	 * session (and `OC.requestToken`) alive with its keepalive heartbeat. The only
+	 * residual staleness — the parent's token rotating without a reload — cannot
+	 * happen in practice, so a postMessage CONFIGURE refresh into the iframe is a
+	 * future nicety, not a correctness requirement.
+	 *
+	 * @return array{managementUrl:string,servingBaseUrl:string,deleteUrlTemplate:string,managementHeaders:object}
+	 */
+	private function previewSnapshotConfig(): array {
+		$sampleId = '00000000-0000-4000-8000-000000000000';
+
+		// The serving routes take a `previewId` (and `path`); generate the bare
+		// capability-root URL for a placeholder id, then strip the trailing
+		// `/{id}` so the client can append `/{previewId}/index.html` itself.
+		$sampleUrl = $this->urlGenerator->linkToRoute(
+			Application::APP_ID . '.preview.serveRoot',
+			['previewId' => $sampleId],
+		);
+		$servingBaseUrl = str_ends_with($sampleUrl, '/' . $sampleId)
+			? substr($sampleUrl, 0, -(strlen($sampleId) + 1))
+			: $sampleUrl;
+
+		// The delete route is templated rather than derived by concatenation, so
+		// the client never has to know how this app spells a capability URL.
+		$deleteUrlTemplate = str_replace(
+			$sampleId,
+			'{previewId}',
+			$this->urlGenerator->linkToRoute(
+				Application::APP_ID . '.previewSession.delete',
+				['previewId' => $sampleId],
+			),
+		);
+
+		return [
+			'managementUrl' => $this->urlGenerator->linkToRoute(Application::APP_ID . '.previewSession.create'),
+			'servingBaseUrl' => $servingBaseUrl,
+			'deleteUrlTemplate' => $deleteUrlTemplate,
+			'managementHeaders' => (object)[
+				'requesttoken' => $this->csrfTokenManager->getToken()->getEncryptedValue(),
+			],
+		];
+	}
+
 	/**
 	 * Resilience shim injected into the editor <head> before any editor
 	 * script runs. The static eXeLearning editor's ResourceFetcher rejects
diff --git a/lib/Controller/PreviewController.php b/lib/Controller/PreviewController.php
new file mode 100644
index 0000000..bb43ff4
--- /dev/null
+++ b/lib/Controller/PreviewController.php
@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Controller;
+
+use OCA\ExeLearning\Service\Preview\PreviewResponse;
+use OCA\ExeLearning\Service\Preview\PreviewServer;
+use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\PublicPage;
+use OCP\AppFramework\Http\DataDisplayResponse;
+use OCP\IRequest;
+
+/**
+ * AUTHLESS, cookieless serving endpoint for the eXeLearning **editor preview**
+ * of untrusted, unsaved author content, served from an opaque origin
+ * (docs/preview-serving-contract.md, canonical spec in eXe core
+ * `doc/development/preview-serving-contract.md`).
+ *
+ * Unlike {@see AssetController} (authenticated, same-origin, published content),
+ * this route is a `#[PublicPage]` capability URL: knowledge of the `previewId`
+ * UUID is the only bearer of access. It never emits a session cookie and always
+ * responds `Access-Control-Allow-Origin: *` (sound only because the origin is
+ * cookieless). The editor preview must be served from here and never same-origin
+ * or through the Service Worker (a Service Worker cannot back an opaque origin).
+ *
+ * All protocol and header policy lives in {@see PreviewServer} (OCP-free and
+ * vector-replayable); this controller is a thin adapter that copies the
+ * resulting {@see PreviewResponse} onto a `DataDisplayResponse`. Nextcloud
+ * serves unknown extensions as `text/plain`, so Content-Type is always set
+ * explicitly.
+ */
+class PreviewController extends Controller {
+	public function __construct(
+		string $appName,
+		IRequest $request,
+		private readonly PreviewServer $server,
+	) {
+		parent::__construct($appName, $request);
+	}
+
+	/**
+	 * GET /apps/exelearning/preview/{previewId}/{path}
+	 */
+	#[PublicPage]
+	#[NoCSRFRequired]
+	public function serve(string $previewId, string $path = 'index.html'): DataDisplayResponse {
+		$response = $this->server->serve(
+			$previewId,
+			$path,
+			$this->headerOrNull('If-None-Match'),
+			$this->headerOrNull('Range'),
+		);
+		return $this->toDataDisplay($response);
+	}
+
+	/**
+	 * GET /apps/exelearning/preview/{previewId}
+	 *
+	 * The bare capability root 302-redirects to `{previewId}/index.html` rather
+	 * than serving index.html bytes inline — otherwise the document's relative
+	 * subresource references resolve against `preview/` (dropping the id segment)
+	 * and every asset 404s. See {@see PreviewServer::serveRoot()}.
+	 */
+	#[PublicPage]
+	#[NoCSRFRequired]
+	public function serveRoot(string $previewId): DataDisplayResponse {
+		return $this->toDataDisplay($this->server->serveRoot($previewId));
+	}
+
+	/** Map the framework-agnostic response onto a DataDisplayResponse. */
+	private function toDataDisplay(PreviewResponse $response): DataDisplayResponse {
+		$headers = $response->headers;
+		$contentType = $headers['Content-Type'] ?? 'application/octet-stream';
+		unset($headers['Content-Type']);
+		$result = new DataDisplayResponse($response->body, $response->status, ['Content-Type' => $contentType]);
+		foreach ($headers as $name => $value) {
+			$result->addHeader($name, $value);
+		}
+		return $result;
+	}
+
+	/** A request header value, or null when it is absent/empty. */
+	private function headerOrNull(string $name): ?string {
+		$value = (string)$this->request->getHeader($name);
+		return $value === '' ? null : $value;
+	}
+}
diff --git a/lib/Controller/PreviewSessionController.php b/lib/Controller/PreviewSessionController.php
new file mode 100644
index 0000000..c275ff9
--- /dev/null
+++ b/lib/Controller/PreviewSessionController.php
@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Controller;
+
+use OCA\ExeLearning\Service\Preview\PreviewSnapshotStore;
+use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+use OCP\AppFramework\Http\DataResponse;
+use OCP\IRequest;
+use OCP\IUserSession;
+
+/**
+ * AUTHENTICATED, owner-scoped management API for the opaque editor preview.
+ *
+ * This is the ONLY authenticated surface of the preview feature; the bytes are
+ * served separately by the authless {@see PreviewController}. Called by the
+ * embedded editor same-origin, so — unlike the public serving route — normal
+ * Nextcloud CSRF protection stays ON (these actions are NOT `#[NoCSRFRequired]`),
+ * mirroring `editor#save`. Ownership is scoped to the authenticated
+ * {@see IUserSession} user id.
+ *
+ * Two endpoints, because the editor sends the whole project each time rather
+ * than patching it:
+ *
+ *   POST   {basePath}/api/preview-session              multipart: snapshot=<zip>,
+ *                                                      previewId? -> { previewId }
+ *   DELETE {basePath}/api/preview-session/{previewId}
+ *
+ * This replaces the four-operation protocol v2 (create / assets / revisions /
+ * delete) that the current editor build no longer speaks.
+ */
+class PreviewSessionController extends Controller {
+	public function __construct(
+		string $appName,
+		IRequest $request,
+		private readonly IUserSession $userSession,
+		private readonly PreviewSnapshotStore $store,
+	) {
+		parent::__construct($appName, $request);
+	}
+
+	/**
+	 * POST {basePath}/api/preview-session — publish a whole-project snapshot.
+	 *
+	 * `previewId` is absent on the first refresh (mint a capability) and present
+	 * afterwards (replace in place). The store refuses an id that is unknown or
+	 * owned by somebody else, so it cannot be used to claim another author's
+	 * capability.
+	 */
+	#[NoAdminRequired]
+	public function create(): DataResponse {
+		$userId = $this->currentUserId();
+		if ($userId === null) {
+			return $this->unauthenticated();
+		}
+		$upload = $this->request->getUploadedFile('snapshot');
+		if (!is_array($upload)
+			|| (int)($upload['error'] ?? UPLOAD_ERR_NO_FILE) !== UPLOAD_ERR_OK
+			|| !is_string($upload['tmp_name'] ?? null)
+			|| $upload['tmp_name'] === ''
+			|| !is_uploaded_file($upload['tmp_name'])) {
+			return new DataResponse(['error' => 'Missing snapshot upload'], Http::STATUS_BAD_REQUEST);
+		}
+
+		$previewId = $this->request->getParam('previewId');
+		$previewId = is_string($previewId) && $previewId !== '' ? $previewId : null;
+
+		$result = $this->store->replace($userId, $upload['tmp_name'], $previewId);
+		if (isset($result['error'])) {
+			return new DataResponse(['error' => $result['error']], (int)$result['status']);
+		}
+		// No previewUrl: the client derives it from servingBaseUrl +
+		// /{previewId}/index.html, which keeps one source of truth for how a
+		// capability URL is shaped.
+		return new DataResponse(['previewId' => $result['previewId']], Http::STATUS_OK);
+	}
+
+	/**
+	 * DELETE {basePath}/api/preview-session/{previewId}
+	 *
+	 * Owner scoping comes from the same store verdict the publish path uses, so
+	 * the two verbs cannot drift: a malformed id is a 400, an unknown capability
+	 * a 404 and somebody else's a 403.
+	 */
+	#[NoAdminRequired]
+	public function delete(string $previewId): DataResponse {
+		$userId = $this->currentUserId();
+		if ($userId === null) {
+			return $this->unauthenticated();
+		}
+		$refused = $this->store->deleteOwned($previewId, $userId);
+		if ($refused !== null) {
+			return new DataResponse(['error' => $refused['error']], (int)$refused['status']);
+		}
+		return new DataResponse([], Http::STATUS_OK);
+	}
+
+	private function currentUserId(): ?string {
+		$user = $this->userSession->getUser();
+		return $user === null ? null : $user->getUID();
+	}
+
+	private function unauthenticated(): DataResponse {
+		return new DataResponse(['error' => 'Not authenticated'], Http::STATUS_UNAUTHORIZED);
+	}
+}
diff --git a/lib/Controller/ViewController.php b/lib/Controller/ViewController.php
index 87ac8a1..ec2f2f1 100644
--- a/lib/Controller/ViewController.php
+++ b/lib/Controller/ViewController.php
@@ -5,7 +5,9 @@
 namespace OCA\ExeLearning\Controller;
 
 use OCA\ExeLearning\AppInfo\Application;
+use OCA\ExeLearning\Service\ContentTokenService;
 use OCA\ExeLearning\Service\ElpxPackageService;
+use OCA\ExeLearning\Service\IframeSandbox;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
@@ -39,6 +41,8 @@ public function __construct(
 		private readonly ElpxPackageService $packageService,
 		private readonly IInitialState $initialState,
 		private readonly IURLGenerator $urlGenerator,
+		private readonly ContentTokenService $contentTokens,
+		private readonly IframeSandbox $sandbox,
 	) {
 		parent::__construct($appName, $request);
 	}
@@ -66,6 +70,7 @@ public function index(?int $fileId = null, ?string $path = null, ?string $mode =
 			}
 		}
 
+		$secureIframe = $this->sandbox->resolveMode() === IframeSandbox::MODE_SECURE;
 		if ($file !== null) {
 			$this->initialState->provideInitialState('file', [
 				'id' => $file->getId(),
@@ -75,7 +80,25 @@ public function index(?int $fileId = null, ?string $path = null, ?string $mode =
 				'etag' => $file->getEtag(),
 				'writable' => $file->isUpdateable(),
 			]);
+			// In secure mode the package is served into an opaque-origin iframe
+			// over the cookieless /content/{token}/… capability route. The user's
+			// read permission was just checked above (getForUser*), so mint the
+			// bearer token here. Legacy (same-origin Service Worker) mode leaves
+			// this null and the viewer keeps its /runtime SW path.
+			$this->initialState->provideInitialState(
+				'contentToken',
+				$secureIframe ? $this->contentTokens->mint((int)$file->getId(), $user->getUID()) : null,
+			);
 		}
+		$this->initialState->provideInitialState('secureIframe', $secureIframe);
+		// External-media relay config for the trusted parent (see relay-host.ts):
+		// 'strict' mode overlays only the maintained provider hosts.
+		$this->initialState->provideInitialState(
+			'embedRelay',
+			$secureIframe
+				? ['mode' => $this->sandbox->embedMode(), 'whitelist' => $this->sandbox->providerWhitelist()]
+				: null,
+		);
 		$this->initialState->provideInitialState(
 			'editorAvailable',
 			is_file(__DIR__ . '/../../js/editor/index.html'),
@@ -101,6 +124,12 @@ public function index(?int $fileId = null, ?string $path = null, ?string $mode =
 		$csp->addAllowedScriptDomain("'self'");
 		$csp->addAllowedConnectDomain("'self'");
 		$csp->addAllowedFrameDomain("'self'");
+		// Promoted players are cross-origin frames mounted on THIS page by the relay, so
+		// 'self' alone blocks every one of them. Allowed hosts come from the same list the
+		// relay is given, never a copy.
+		foreach ($this->sandbox->playerFrameDomains() as $host) {
+			$csp->addAllowedFrameDomain('https://' . $host);
+		}
 		$response->setContentSecurityPolicy($csp);
 		return $response;
 	}
diff --git a/lib/Service/ContentTokenService.php b/lib/Service/ContentTokenService.php
new file mode 100644
index 0000000..47ec09a
--- /dev/null
+++ b/lib/Service/ContentTokenService.php
@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service;
+
+/**
+ * Mints and verifies short-lived, fileId-bound capability tokens for the
+ * cookieless opaque content-serving route ({@see \OCA\ExeLearning\Controller\ContentController}).
+ *
+ * The opaque published-content iframe sends no session cookie, so the route
+ * cannot rely on the Nextcloud session. Instead {@see ViewController} — where
+ * the user IS authenticated and the read permission IS checked — mints a token
+ * that binds the file id, the user id and an expiry under an HMAC keyed by the
+ * instance secret. The user id lets the serving route mount that user's storage
+ * (getUserFolder) and re-check the read permission. The token is the bearer
+ * capability: unforgeable, self-describing, stateless (no server-side store).
+ * This mirrors Moodle's tokenpluginfile model.
+ */
+class ContentTokenService {
+	/** @var callable():int */
+	private $clock;
+
+	/**
+	 * @param string $secret The Nextcloud instance secret (wired from IConfig in
+	 *                       Application.php); kept as a plain string so this service stays free of
+	 *                       OCP dependencies and unit-testable without a server.
+	 * @param (callable():int)|null $clock Injectable unix-time source (tests stub it).
+	 */
+	public function __construct(
+		private readonly string $secret,
+		?callable $clock = null,
+	) {
+		$this->clock = $clock ?? static fn (): int => time();
+	}
+
+	/**
+	 * Mint a capability token binding $fileId + $userId valid for $ttlSeconds.
+	 * The user id is carried so the cookieless serving route can mount that
+	 * user's storage (getUserFolder) — IRootFolder::getById alone resolves
+	 * nothing without a filesystem context on a #[PublicPage].
+	 */
+	public function mint(int $fileId, string $userId, int $ttlSeconds = 3600): string {
+		$expiry = ($this->clock)() + $ttlSeconds;
+		$payload = $fileId . '.' . $expiry . '.' . $this->b64($userId);
+		return $this->b64($payload) . '.' . $this->b64($this->sign($payload));
+	}
+
+	/**
+	 * Verify a token: returns `[fileId, userId]` when the signature is valid and
+	 * the token has not expired, otherwise null.
+	 *
+	 * @return array{0: int, 1: string}|null
+	 */
+	public function verify(string $token): ?array {
+		$parts = explode('.', $token);
+		if (count($parts) !== 2) {
+			return null;
+		}
+		$payload = $this->unb64($parts[0]);
+		$signature = $this->unb64($parts[1]);
+		if ($payload === null || $signature === null) {
+			return null;
+		}
+		if (!hash_equals($this->sign($payload), $signature)) {
+			return null;
+		}
+		$segments = explode('.', $payload);
+		if (count($segments) !== 3) {
+			return null;
+		}
+		[$fileId, $expiry, $encodedUser] = $segments;
+		if (!ctype_digit($fileId) || !ctype_digit($expiry)) {
+			return null;
+		}
+		if ((int)$expiry <= ($this->clock)()) {
+			return null;
+		}
+		$userId = $this->unb64($encodedUser);
+		if ($userId === null || $userId === '') {
+			return null;
+		}
+		return [(int)$fileId, $userId];
+	}
+
+	private function sign(string $payload): string {
+		return hash_hmac('sha256', $payload, $this->secret(), true);
+	}
+
+	private function secret(): string {
+		return $this->secret . '|exelearning-content-v1';
+	}
+
+	private function b64(string $raw): string {
+		return rtrim(strtr(base64_encode($raw), '+/', '-_'), '=');
+	}
+
+	private function unb64(string $encoded): ?string {
+		$decoded = base64_decode(strtr($encoded, '-_', '+/'), true);
+		return $decoded === false ? null : $decoded;
+	}
+}
diff --git a/lib/Service/EmbedShimInjector.php b/lib/Service/EmbedShimInjector.php
new file mode 100644
index 0000000..847c6e0
--- /dev/null
+++ b/lib/Service/EmbedShimInjector.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service;
+
+/**
+ * Inlines the eXe-core external-media child (exe-external-media-child.min.js) into a served
+ * HTML package document, so that inside the opaque iframe every cross-origin /
+ * PDF sub-iframe is promoted to a geometry placeholder the parent relay can
+ * overlay. Mirrors the inject-at-serve approach of wp-exelearning
+ * (ExeLearning_Content_Proxy::inject_embed_shim) and omeka-s-exelearning
+ * (ContentController::injectEmbedShim).
+ *
+ * Pure string transformation (no OCP dependencies) so it is unit-testable.
+ */
+class EmbedShimInjector {
+	private const MARKER = 'data-injected-by="eXeLearning-Viewer"';
+
+	/**
+	 * Insert the shim as an inline <script> as early as possible: before
+	 * </head> when present (it must run before the package's own media bridge),
+	 * otherwise right after <body>, otherwise prepended.
+	 */
+	public function injectIntoHead(string $html, string $scriptSource): string {
+		$tag = '<script ' . self::MARKER . '>' . $scriptSource . '</script>';
+
+		$headClose = stripos($html, '</head>');
+		if ($headClose !== false) {
+			return substr($html, 0, $headClose) . $tag . substr($html, $headClose);
+		}
+
+		if (preg_match('~<body[^>]*>~i', $html, $matches, PREG_OFFSET_CAPTURE) === 1) {
+			$at = $matches[0][1] + strlen($matches[0][0]);
+			return substr($html, 0, $at) . $tag . substr($html, $at);
+		}
+
+		return $tag . $html;
+	}
+}
diff --git a/lib/Service/EmbedShimSource.php b/lib/Service/EmbedShimSource.php
new file mode 100644
index 0000000..e24f7f1
--- /dev/null
+++ b/lib/Service/EmbedShimSource.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service;
+
+/**
+ * Reads the child half of the shared eXeLearning external-media bundle — the script
+ * inlined into every served package so that, inside the opaque iframe, each cross-origin
+ * or PDF sub-iframe is replaced by a geometry placeholder the parent host can overlay.
+ *
+ * eXeLearning core is canonical (eXe ADR-0021): this app holds the BYTES and verifies them
+ * against the manifest core published, rather than a copy of the logic that could drift.
+ * Do not patch the artifact here — a local edit is invisible upstream, is overwritten on
+ * the next re-vendor, and fails `verify.mjs` in CI in the meantime.
+ *
+ * Free of OCP dependencies on purpose, like {@see EmbedShimInjector}, so the question
+ * "which bytes do we serve?" can be asserted in a plain unit test.
+ */
+class EmbedShimSource {
+	private const CHILD_BUNDLE = 'exe-external-media-child.min.js';
+
+	public function __construct(
+		private readonly string $vendoredDir = __DIR__ . '/../../src/embed/exe_external_media',
+	) {
+	}
+
+	/** The bundle source, or null when the vendored artifact is not present. */
+	public function read(): ?string {
+		$path = $this->vendoredDir . '/' . self::CHILD_BUNDLE;
+		if (!is_file($path)) {
+			return null;
+		}
+		$source = file_get_contents($path);
+		return $source === false ? null : $source;
+	}
+}
diff --git a/lib/Service/IframeSandbox.php b/lib/Service/IframeSandbox.php
new file mode 100644
index 0000000..0936a23
--- /dev/null
+++ b/lib/Service/IframeSandbox.php
@@ -0,0 +1,164 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service;
+
+/**
+ * Single source of truth for the secure (opaque-origin) iframe policy used to
+ * render published .elpx content: the sandbox token set, the published
+ * Content-Security-Policy, the SVG/XML locked policy, the Permissions-Policy,
+ * and the external-media provider whitelist.
+ *
+ * Mirrors the ecosystem contract shared with mod_exelearning
+ * (\mod_exelearning\local\ui\player_iframe), wp-exelearning
+ * (ExeLearning_Iframe_Sandbox) and omeka-s-exelearning (IframeSandbox). The
+ * secure token set MUST stay 'allow-scripts allow-popups allow-forms' with NO
+ * 'allow-same-origin' — its absence is what makes the document opaque. The only
+ * path back to a same-origin iframe is the dev-only escape hatch
+ * EXELEARNING_UNSAFE_LEGACY_IFRAME (off by default, never a UI setting).
+ */
+class IframeSandbox {
+	public const MODE_SECURE = 'secure';
+	public const MODE_LEGACY = 'legacy';
+
+	private const SECURE_TOKENS = 'allow-scripts allow-popups allow-forms';
+	private const LEGACY_TOKENS = 'allow-same-origin allow-scripts allow-popups allow-forms allow-popups-to-escape-sandbox';
+
+	private const LEGACY_ENV = 'EXELEARNING_UNSAFE_LEGACY_IFRAME';
+	private const EMBED_OPEN_ENV = 'EXELEARNING_EMBED_OPEN';
+
+	public const EMBED_STRICT = 'strict';
+	public const EMBED_OPEN = 'open';
+
+	/** Hosts whose embedded players the relay may overlay (see exe-external-media-host.min.js). */
+	private const PROVIDER_WHITELIST = [
+		'www.youtube.com',
+		'youtube.com',
+		'www.youtube-nocookie.com',
+		'youtube-nocookie.com',
+		'player.vimeo.com',
+		'vimeo.com',
+		'www.dailymotion.com',
+		'dailymotion.com',
+		'geo.dailymotion.com',
+		'mediateca.educa.madrid.org',
+	];
+
+	/** @var callable(string):?string */
+	private $envReader;
+
+	/**
+	 * @param (callable(string):?string)|null $envReader Injectable environment
+	 *                                                   reader (tests pass a stub); defaults to getenv().
+	 */
+	public function __construct(?callable $envReader = null) {
+		$this->envReader = $envReader ?? static function (string $name): ?string {
+			$value = getenv($name);
+			return $value === false ? null : $value;
+		};
+	}
+
+	/**
+	 * Always 'secure' unless the dev escape hatch is explicitly on.
+	 */
+	public function resolveMode(): string {
+		$raw = ($this->envReader)(self::LEGACY_ENV);
+		$on = $raw !== null && in_array(strtolower(trim($raw)), ['1', 'true', 'yes', 'on'], true);
+		return $on ? self::MODE_LEGACY : self::MODE_SECURE;
+	}
+
+	/**
+	 * External-media relay mode. 'strict' (default, fail-safe) overlays only the
+	 * maintained provider hosts; 'open' (opt-in via EXELEARNING_EMBED_OPEN)
+	 * overlays any cross-origin https player the shim reports.
+	 */
+	public function embedMode(): string {
+		$raw = ($this->envReader)(self::EMBED_OPEN_ENV);
+		$on = $raw !== null && in_array(strtolower(trim($raw)), ['1', 'true', 'yes', 'on'], true);
+		return $on ? self::EMBED_OPEN : self::EMBED_STRICT;
+	}
+
+	/**
+	 * The iframe `sandbox` attribute token list for the given (or resolved) mode.
+	 */
+	public function sandboxTokens(?string $mode = null): string {
+		$mode ??= $this->resolveMode();
+		return $mode === self::MODE_LEGACY ? self::LEGACY_TOKENS : self::SECURE_TOKENS;
+	}
+
+	/**
+	 * Response-level CSP for served HTML package documents.
+	 *
+	 * 'strict' (default) keeps script/img/media/frame-src pinned to 'self' + the
+	 * maintained providers so a URL-borne capability token can never be
+	 * exfiltrated to an arbitrary host; the trailing `sandbox` directive keeps
+	 * the document opaque even if opened top-level. 'compatible' re-opens https:
+	 * for deployments that need arbitrary external assets.
+	 */
+	public function contentSecurityPolicy(string $profile = 'strict'): string {
+		$scriptSrc = "script-src 'self' 'unsafe-inline' 'unsafe-eval'";
+		$imgSrc = "img-src 'self' data: blob:";
+		$mediaSrc = "media-src 'self' data: blob:";
+		$frameSrc = "frame-src 'self' https://www.youtube-nocookie.com https://player.vimeo.com "
+			. 'https://www.dailymotion.com https://mediateca.educa.madrid.org';
+		if ($profile === 'compatible') {
+			$scriptSrc = "script-src 'self' 'unsafe-inline' 'unsafe-eval' https:";
+			$imgSrc = "img-src 'self' data: blob: https:";
+			$mediaSrc = "media-src 'self' data: blob: https:";
+			$frameSrc = "frame-src 'self' https:";
+		}
+		return implode('; ', [
+			"default-src 'self'",
+			$scriptSrc,
+			"style-src 'self' 'unsafe-inline'",
+			$imgSrc,
+			$mediaSrc,
+			"font-src 'self' data:",
+			"connect-src 'self'",
+			$frameSrc,
+			"frame-ancestors 'self'",
+			"form-action 'self'",
+			"base-uri 'self'",
+			"object-src 'none'",
+			'sandbox ' . self::SECURE_TOKENS,
+		]);
+	}
+
+	/**
+	 * Locked, script-free CSP for SVG/XML documents opened top-level.
+	 */
+	public function svgCsp(): string {
+		return "default-src 'none'; style-src 'unsafe-inline'; img-src data:; script-src 'none'; sandbox";
+	}
+
+	/**
+	 * Deny hardware access; deliberately does NOT deny fullscreen (video needs it).
+	 */
+	public function permissionsPolicy(): string {
+		return 'camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), '
+			. 'bluetooth=(), hid=(), magnetometer=(), accelerometer=(), gyroscope=(), '
+			. 'midi=(), display-capture=()';
+	}
+
+	/**
+	 * @return string[]
+	 */
+	public function providerWhitelist(): array {
+		return self::PROVIDER_WHITELIST;
+	}
+
+	/**
+	 * Hosts the page CSP must allow as frame sources.
+	 *
+	 * The relay overlays real players for exactly these hosts, on the trusted page. If the
+	 * CSP is narrower the browser blocks the frame and the learner gets a black rectangle
+	 * with nothing in the console to explain it, so this deliberately returns the same
+	 * list rather than a second one that could drift from it.
+	 *
+	 * @return string[]
+	 */
+	public function playerFrameDomains(): array {
+		return $this->providerWhitelist();
+	}
+}
diff --git a/lib/Service/PackageMimeService.php b/lib/Service/PackageMimeService.php
new file mode 100644
index 0000000..06fd84e
--- /dev/null
+++ b/lib/Service/PackageMimeService.php
@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service;
+
+/**
+ * Maps package entry extensions to MIME types and classifies which served
+ * documents need which Content-Security-Policy. Shared by {@see \OCA\ExeLearning\Controller\AssetController}
+ * (same-origin fallback) and {@see \OCA\ExeLearning\Controller\ContentController}
+ * (opaque serving) so the mapping never drifts between the two.
+ *
+ * Pure logic (no OCP dependencies) so it is unit-testable.
+ */
+class PackageMimeService {
+	private const MIME_MAP = [
+		'html' => 'text/html; charset=utf-8',
+		'htm' => 'text/html; charset=utf-8',
+		'xhtml' => 'application/xhtml+xml; charset=utf-8',
+		'xml' => 'application/xml; charset=utf-8',
+		'css' => 'text/css; charset=utf-8',
+		'js' => 'text/javascript; charset=utf-8',
+		'mjs' => 'text/javascript; charset=utf-8',
+		'json' => 'application/json; charset=utf-8',
+		'svg' => 'image/svg+xml',
+		'png' => 'image/png',
+		'jpg' => 'image/jpeg',
+		'jpeg' => 'image/jpeg',
+		'gif' => 'image/gif',
+		'webp' => 'image/webp',
+		'mp3' => 'audio/mpeg',
+		'mp4' => 'video/mp4',
+		'ogg' => 'audio/ogg',
+		'wav' => 'audio/wav',
+		'webm' => 'video/webm',
+		'vtt' => 'text/vtt',
+		'woff' => 'font/woff',
+		'woff2' => 'font/woff2',
+		'ttf' => 'font/ttf',
+		'eot' => 'application/vnd.ms-fontobject',
+	];
+
+	public function detect(string $entry): string {
+		$extension = strtolower(pathinfo($entry, PATHINFO_EXTENSION));
+		return self::MIME_MAP[$extension] ?? 'application/octet-stream';
+	}
+
+	/**
+	 * A "page" document that runs the eXe engine — gets the full published CSP
+	 * and the injected media shim.
+	 */
+	public function isHtmlDocument(string $mime): bool {
+		$type = $this->baseType($mime);
+		return $type === 'text/html' || $type === 'application/xhtml+xml';
+	}
+
+	/**
+	 * A data document (SVG/XML) that must be locked script-free when opened
+	 * top-level (an author SVG runs inline <script> without it).
+	 */
+	public function isLockedXml(string $mime): bool {
+		$type = $this->baseType($mime);
+		return $type === 'image/svg+xml' || $type === 'application/xml';
+	}
+
+	private function baseType(string $mime): string {
+		return strtolower(trim(explode(';', $mime, 2)[0]));
+	}
+}
diff --git a/lib/Service/Preview/PreviewPolicy.php b/lib/Service/Preview/PreviewPolicy.php
new file mode 100644
index 0000000..394d6ab
--- /dev/null
+++ b/lib/Service/Preview/PreviewPolicy.php
@@ -0,0 +1,206 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service\Preview;
+
+/**
+ * Single source of truth for the eXeLearning **editor-preview** isolation
+ * policy: the sandbox-first Content-Security-Policy, the scriptable-document
+ * classification, the Permissions-Policy, the served MIME resolution, and the
+ * traversal-safe path normalization.
+ *
+ * This mirrors eXe core (repo `exelearning/exelearning`), which is authoritative:
+ *
+ *  - CSP / scriptable set / Permissions-Policy → `src/shared/security/previewSandbox.ts`
+ *  - MIME + path normalization                 → `src/utils/content-path.util.ts`
+ *
+ * The class is intentionally OCP-free (pure static logic, no Nextcloud
+ * dependencies) so every protocol rule is unit-testable without a server and
+ * the {@see \OCA\ExeLearning\Controller\PreviewController} stays a thin adapter.
+ *
+ * WARNING: {@see self::CSP} MUST stay **byte-identical** to `previewCspHeader()`
+ * in eXe core. Do not re-order, re-quote, reformat, or add a trailing `;`. This
+ * is enforced ecosystem-wide by the `serving-contract` drift-check in core's
+ * `scripts/check-embed-sync.mjs`.
+ *
+ * Note: this is a DIFFERENT string from {@see \OCA\ExeLearning\Service\IframeSandbox}
+ * used for *published* content. Published content pins `frame-src`/`img-src` to
+ * the maintained provider hosts (token-exfiltration hardening for a longer-lived
+ * capability URL); the editor preview is a short-lived, ephemeral capability and
+ * matches core's preview CSP verbatim. The two are deliberately not unified — see
+ * docs/preview-serving-contract.md.
+ */
+final class PreviewPolicy {
+	/**
+	 * Byte-identical to `previewCspHeader()` in eXe core
+	 * `src/shared/security/previewSandbox.ts`. The leading `sandbox` directive
+	 * drops the document into an opaque, unique origin even when the capability
+	 * URL is opened top-level (new tab / popup / raw URL); the rest is
+	 * defence-in-depth. Emitted verbatim on every scriptable document type.
+	 */
+	public const CSP = 'sandbox allow-scripts allow-popups allow-forms; '
+		. "default-src 'self'; "
+		. "script-src 'self' 'unsafe-inline' 'unsafe-eval'; "
+		. "style-src 'self' 'unsafe-inline'; "
+		. "img-src 'self' data: blob: https:; "
+		. "media-src 'self' data: blob: https:; "
+		. "font-src 'self' data:; "
+		. "connect-src 'self'; "
+		. "frame-src 'self' https://www.youtube-nocookie.com https://player.vimeo.com; "
+		. "child-src 'self' https://www.youtube-nocookie.com https://player.vimeo.com; "
+		. "object-src 'none'; "
+		. "base-uri 'none'; "
+		. "form-action 'self'; "
+		. "frame-ancestors 'self'";
+
+	/** Permissions-Policy emitted on every preview response. */
+	public const PERMISSIONS_POLICY = 'camera=(), microphone=(), geolocation=(), payment=()';
+
+	/**
+	 * Capability id shape (a server-minted v4 UUID). Anything else is a hard 404
+	 * on the serving route and a 404 on the management route.
+	 */
+	public const PREVIEW_ID_RE = '/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/';
+
+	/**
+	 * Scriptable document types that MUST carry the sandbox-first CSP so they
+	 * stay opaque even when opened top-level. Not just `text/html`: an
+	 * author-supplied `image/svg+xml` served without the sandbox CSP runs its
+	 * inline `<script>` same-origin when opened in a new tab (`nosniff` does not
+	 * help — SVG is already a scriptable document type).
+	 *
+	 * Matches the contract's `isScriptableDocument(mime)` set (eXe core
+	 * `isScriptableDocumentType()`): text/html, image/svg+xml, application/xml,
+	 * text/xml and application/xhtml+xml.
+	 */
+	private const SCRIPTABLE_TYPES = [
+		'text/html',
+		'image/svg+xml',
+		'application/xml',
+		'text/xml',
+		'application/xhtml+xml',
+	];
+
+	/**
+	 * Extension → base MIME type. Mirrors the shared eXe map; textual types get
+	 * a `; charset=utf-8` appended by {@see self::mimeForPath()} so responses
+	 * paired with `nosniff` stay both strict and readable.
+	 */
+	private const MIME_MAP = [
+		'html' => 'text/html',
+		'htm' => 'text/html',
+		'xhtml' => 'application/xhtml+xml',
+		'xml' => 'application/xml',
+		'css' => 'text/css',
+		'js' => 'text/javascript',
+		'mjs' => 'text/javascript',
+		'json' => 'application/json',
+		'svg' => 'image/svg+xml',
+		'png' => 'image/png',
+		'jpg' => 'image/jpeg',
+		'jpeg' => 'image/jpeg',
+		'gif' => 'image/gif',
+		'webp' => 'image/webp',
+		'avif' => 'image/avif',
+		'ico' => 'image/x-icon',
+		'bmp' => 'image/bmp',
+		'mp3' => 'audio/mpeg',
+		'wav' => 'audio/wav',
+		'ogg' => 'audio/ogg',
+		'oga' => 'audio/ogg',
+		'm4a' => 'audio/mp4',
+		'mp4' => 'video/mp4',
+		'm4v' => 'video/mp4',
+		'webm' => 'video/webm',
+		'ogv' => 'video/ogg',
+		'mov' => 'video/quicktime',
+		'vtt' => 'text/vtt',
+		'srt' => 'application/x-subrip',
+		'pdf' => 'application/pdf',
+		'wasm' => 'application/wasm',
+		'woff' => 'font/woff',
+		'woff2' => 'font/woff2',
+		'ttf' => 'font/ttf',
+		'otf' => 'font/otf',
+		'eot' => 'application/vnd.ms-fontobject',
+		'txt' => 'text/plain',
+	];
+
+	/** Extensions that are textual and therefore get a UTF-8 charset appended. */
+	private const CHARSET_EXTENSIONS = ['js', 'mjs', 'json', 'svg', 'xml', 'xhtml'];
+
+	/** No instances — pure static policy. */
+	private function __construct() {
+	}
+
+	/** Whether $previewId is a well-formed capability id. */
+	public static function isValidPreviewId(string $previewId): bool {
+		return preg_match(self::PREVIEW_ID_RE, $previewId) === 1;
+	}
+
+	/**
+	 * True when the given MIME (with any `; charset=…` stripped) is a scriptable
+	 * document type and therefore needs the sandbox CSP.
+	 */
+	public static function isScriptable(string $mime): bool {
+		$base = strtolower(trim(explode(';', $mime, 2)[0]));
+		return in_array($base, self::SCRIPTABLE_TYPES, true);
+	}
+
+	/**
+	 * Resolve the Content-Type for a served path from its extension, appending a
+	 * UTF-8 charset to textual types. Mirrors `contentTypeFor()` in eXe core.
+	 */
+	public static function mimeForPath(string $path): string {
+		$ext = strtolower(pathinfo($path, PATHINFO_EXTENSION));
+		$base = self::MIME_MAP[$ext] ?? 'application/octet-stream';
+		$textual = str_starts_with($base, 'text/') || in_array($ext, self::CHARSET_EXTENSIONS, true);
+		if ($textual && !str_contains($base, 'charset')) {
+			$base .= '; charset=utf-8';
+		}
+		return $base;
+	}
+
+	/**
+	 * Normalize a requested/served relative path against a content-map root.
+	 *
+	 * Returns a safe, root-relative POSIX path, or null when the request escapes
+	 * the root (traversal, literal or percent-encoded), contains a NUL byte, or
+	 * collapses to nothing. The SAME normalization is applied to stored paths
+	 * (revision writes/deletes and both ref-map key sets) and to served paths,
+	 * so a lookup can only ever name a stored entry — never a filesystem
+	 * location. Mirrors `normalizeContentPath()` in eXe core, plus backslash
+	 * folding (a served key is always POSIX, so treating `\` as a separator can
+	 * only turn a would-be traversal into a 404, never a false hit).
+	 */
+	public static function normalizePath(string $raw): ?string {
+		// Drop any query/fragment the caller left attached.
+		$p = preg_split('/[?#]/', $raw, 2)[0];
+		// Percent-decode so encoded traversal (`%2e%2e%2f`) becomes literal `../`
+		// and is rejected below, exactly like core's decodeURIComponent step.
+		$p = rawurldecode($p);
+		if (str_contains($p, "\0")) {
+			return null;
+		}
+		$p = str_replace('\\', '/', $p);
+		$p = ltrim($p, '/');
+		if ($p === '') {
+			$p = 'index.html';
+		}
+		$out = [];
+		foreach (explode('/', $p) as $segment) {
+			if ($segment === '' || $segment === '.') {
+				continue;
+			}
+			if ($segment === '..') {
+				return null;
+			}
+			$out[] = $segment;
+		}
+		if (count($out) === 0) {
+			return null;
+		}
+		return implode('/', $out);
+	}
+}
diff --git a/lib/Service/Preview/PreviewResponse.php b/lib/Service/Preview/PreviewResponse.php
new file mode 100644
index 0000000..b3fa4e5
--- /dev/null
+++ b/lib/Service/Preview/PreviewResponse.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service\Preview;
+
+/**
+ * Framework-agnostic description of a serving-route response.
+ *
+ * {@see PreviewServer} produces these from pure logic (fully unit-testable and
+ * vector-replayable without a Nextcloud server); {@see \OCA\ExeLearning\Controller\PreviewController}
+ * is the thin adapter that copies the status, headers and body onto a
+ * `DataDisplayResponse`. Keeping the HTTP policy in a value object is what lets
+ * the header set, CSP byte-identity, ETag/304 and Range behaviour be asserted
+ * directly against the contract vectors.
+ */
+final class PreviewResponse {
+	/**
+	 * @param int $status HTTP status code.
+	 * @param array<string,string> $headers Response headers (verbatim; the
+	 *                                      adapter emits each with addHeader()).
+	 * @param string $body Response body (empty for 304/416).
+	 */
+	public function __construct(
+		public readonly int $status,
+		public readonly array $headers,
+		public readonly string $body,
+	) {
+	}
+}
diff --git a/lib/Service/Preview/PreviewServer.php b/lib/Service/Preview/PreviewServer.php
new file mode 100644
index 0000000..5b3d766
--- /dev/null
+++ b/lib/Service/Preview/PreviewServer.php
@@ -0,0 +1,218 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service\Preview;
+
+/**
+ * HTTP serving policy for the authless preview capability URL
+ * (`GET {basePath}/preview/{previewId}/{path}`).
+ *
+ * Pure logic over {@see PreviewSnapshotStore}: it validates the capability id,
+ * resolves the path inside the snapshot, and applies the contract's response
+ * policy — the hardening header set on EVERY response (404s included), the
+ * tiered `Cache-Control`, `ETag`/`If-None-Match` → 304 and single-range 206/416
+ * on assets, and the sandbox-first CSP on every scriptable document type. It
+ * returns a {@see PreviewResponse} value object so the whole policy is
+ * unit-testable without a Nextcloud server;
+ * {@see \OCA\ExeLearning\Controller\PreviewController} is the thin adapter onto
+ * `DataDisplayResponse`.
+ */
+final class PreviewServer {
+	public function __construct(
+		private readonly PreviewSnapshotStore $store,
+	) {
+	}
+
+	/**
+	 * Serve a preview file.
+	 *
+	 * @param string|null $ifNoneMatch The request `If-None-Match` header, if any.
+	 * @param string|null $range The request `Range` header, if any.
+	 */
+	public function serve(string $previewId, string $rawPath, ?string $ifNoneMatch = null, ?string $range = null): PreviewResponse {
+		if (!PreviewPolicy::isValidPreviewId($previewId)) {
+			return $this->notFound();
+		}
+		$file = $this->store->resolve($previewId, $rawPath);
+		if ($file === null) {
+			return $this->notFound();
+		}
+
+		return match ($file['kind']) {
+			'asset' => $this->serveAsset($file, $ifNoneMatch, $range),
+			default => $this->serveDocument($file),
+		};
+	}
+
+	/**
+	 * Bare capability root (`GET {servingBase}/{previewId}`) → 302 redirect to
+	 * `{previewId}/index.html`.
+	 *
+	 * The bare root must NEVER emit index.html bytes: a document served from the
+	 * bare URL resolves its relative subresource references against
+	 * `{servingBase}/` — dropping the `{previewId}` segment — so every asset,
+	 * script and stylesheet 404s. Redirecting to `{previewId}/index.html` rebases
+	 * them onto the correct directory. The `Location` is relative so it stays
+	 * correct under any Nextcloud webroot (it resolves against the request URI,
+	 * `{servingBase}/{previewId}`) without the store needing a URL generator, and
+	 * the whole decision stays OCP-free.
+	 */
+	public function serveRoot(string $previewId): PreviewResponse {
+		if (!PreviewPolicy::isValidPreviewId($previewId)) {
+			return $this->notFound();
+		}
+		$headers = $this->baseHeaders();
+		$headers['Content-Type'] = 'text/plain; charset=utf-8';
+		$headers['Cache-Control'] = 'no-store';
+		$headers['Location'] = $previewId . '/index.html';
+		return new PreviewResponse(302, $headers, '');
+	}
+
+	/**
+	 * A scriptable document. It is rewritten on every refresh, so `no-store`, and
+	 * it ALWAYS carries the sandbox CSP: `resolve()` only labels a file a
+	 * document when its type is scriptable, so there is no case here that should
+	 * go out without it.
+	 *
+	 * @param array{contentType:string,bytes?:string} $file
+	 */
+	private function serveDocument(array $file): PreviewResponse {
+		$headers = $this->baseHeaders();
+		$headers['Content-Type'] = $file['contentType'];
+		$headers['Cache-Control'] = 'no-store';
+		$headers['Content-Security-Policy'] = PreviewPolicy::CSP;
+		return new PreviewResponse(200, $headers, $file['bytes'] ?? '');
+	}
+
+	/**
+	 * A non-scriptable asset: revalidated (`no-cache`) with an ETag,
+	 * `Accept-Ranges: bytes`, `If-None-Match` → 304 and single-range 206/416.
+	 *
+	 * No sandbox CSP here, and that is not an omission: `resolve()` labels a file
+	 * an asset precisely when its type is NOT scriptable, so a CSP branch on this
+	 * path could never fire.
+	 *
+	 * @param array{contentType:string,filePath:string,size:int,etag:string} $file
+	 */
+	private function serveAsset(array $file, ?string $ifNoneMatch, ?string $range): PreviewResponse {
+		$etag = '"' . $file['etag'] . '"';
+		$size = $file['size'];
+
+		$headers = $this->baseHeaders();
+		$headers['Content-Type'] = $file['contentType'];
+		$headers['Cache-Control'] = 'no-cache';
+		$headers['ETag'] = $etag;
+		$headers['Accept-Ranges'] = 'bytes';
+
+		if ($ifNoneMatch !== null && trim($ifNoneMatch) === $etag) {
+			return new PreviewResponse(304, $headers, '');
+		}
+
+		$parsed = ($range !== null && trim($range) !== '') ? $this->parseRange($range, $size) : null;
+		if ($parsed !== null && $parsed['satisfiable'] === false) {
+			// A syntactically valid single range wholly outside the entity (e.g.
+			// `bytes=99-` on a 10-byte body) is unsatisfiable → 416. A malformed,
+			// multi-range or non-bytes header is IGNORED by parseRange (null) and
+			// falls through to the normal 200 full body below.
+			$headers['Content-Range'] = 'bytes */' . $size;
+			return new PreviewResponse(416, $headers, '');
+		}
+		if ($parsed !== null) {
+			[$start, $end] = [$parsed['start'], $parsed['end']];
+			$length = $end - $start + 1;
+			$headers['Content-Range'] = 'bytes ' . $start . '-' . $end . '/' . $size;
+			$headers['Content-Length'] = (string)$length;
+			return new PreviewResponse(206, $headers, $this->readSlice($file['filePath'], $start, $length));
+		}
+
+		return new PreviewResponse(200, $headers, (string)@file_get_contents($file['filePath']));
+	}
+
+	/** 404 body carrying the full hardening header set (contract: headers on 404 too). */
+	private function notFound(): PreviewResponse {
+		$headers = $this->baseHeaders();
+		$headers['Content-Type'] = 'text/plain; charset=utf-8';
+		$headers['Cache-Control'] = 'no-store';
+		return new PreviewResponse(404, $headers, 'Not Found');
+	}
+
+	/**
+	 * The hardening headers emitted on every serving response. ACAO `*` is sound
+	 * only because the route is authless and cookieless; never pair it with
+	 * credentials.
+	 *
+	 * @return array<string,string>
+	 */
+	private function baseHeaders(): array {
+		return [
+			'X-Content-Type-Options' => 'nosniff',
+			'Referrer-Policy' => 'no-referrer',
+			'Permissions-Policy' => PreviewPolicy::PERMISSIONS_POLICY,
+			'Access-Control-Allow-Origin' => '*',
+		];
+	}
+
+	/**
+	 * Parse a single HTTP byte range against a known size, per the contract's
+	 * canonical classification (RFC 9110 §14.1.2). Three outcomes:
+	 *
+	 *  - `null` — IGNORE the header, serve a normal 200 full body. This covers a
+	 *    non-`bytes` unit, a multi-range set, any malformed value, AND a valid
+	 *    syntax whose last-byte-pos is less than its first-byte-pos (`bytes=5-2`)
+	 *    — an *invalid* spec, which RFC 9110 says to ignore, not 416.
+	 *  - `['satisfiable' => false]` — a valid single range that is *unsatisfiable*:
+	 *    first-byte-pos at/after EOF (`bytes=99-`) or a zero-length suffix
+	 *    (`bytes=-0`). The caller emits 416.
+	 *  - `['satisfiable' => true, 'start' => int, 'end' => int]` — a satisfiable
+	 *    single range (inclusive). The caller emits 206.
+	 *
+	 * @return array{satisfiable:bool,start?:int,end?:int}|null
+	 */
+	private function parseRange(string $range, int $size): ?array {
+		if (preg_match('/^bytes=(\d*)-(\d*)$/', trim($range), $m) !== 1) {
+			return null; // non-bytes unit / multi-range / garbage → ignore (200)
+		}
+		[$rawStart, $rawEnd] = [$m[1], $m[2]];
+		if ($rawStart === '' && $rawEnd === '') {
+			return null; // `bytes=-` carries no range → ignore (200)
+		}
+		if ($rawStart === '') {
+			// Suffix range `bytes=-N`: the last N bytes. A zero-length suffix or
+			// an empty entity is unsatisfiable (416); otherwise it clamps in.
+			$suffix = (int)$rawEnd;
+			if ($suffix === 0 || $size === 0) {
+				return ['satisfiable' => false];
+			}
+			return ['satisfiable' => true, 'start' => max(0, $size - $suffix), 'end' => $size - 1];
+		}
+		$start = (int)$rawStart;
+		if ($rawEnd !== '' && (int)$rawEnd < $start) {
+			// last-byte-pos < first-byte-pos is an INVALID spec, not an
+			// unsatisfiable one → ignore the header and serve 200.
+			return null;
+		}
+		if ($start >= $size) {
+			return ['satisfiable' => false]; // first-byte-pos at/after EOF → 416
+		}
+		$end = $rawEnd === '' ? $size - 1 : min((int)$rawEnd, $size - 1);
+		return ['satisfiable' => true, 'start' => $start, 'end' => $end];
+	}
+
+	/** Read $length bytes from $filePath starting at $start. */
+	private function readSlice(string $filePath, int $start, int $length): string {
+		$handle = @fopen($filePath, 'rb');
+		if ($handle === false) {
+			return '';
+		}
+		try {
+			if (@fseek($handle, $start) !== 0) {
+				return '';
+			}
+			$data = @fread($handle, $length);
+			return $data === false ? '' : $data;
+		} finally {
+			@fclose($handle);
+		}
+	}
+}
diff --git a/lib/Service/Preview/PreviewSnapshotLimits.php b/lib/Service/Preview/PreviewSnapshotLimits.php
new file mode 100644
index 0000000..522b415
--- /dev/null
+++ b/lib/Service/Preview/PreviewSnapshotLimits.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service\Preview;
+
+/**
+ * DoS bounds for the preview snapshot store.
+ *
+ * Nextcloud is the one adapter where these matter beyond a single author: a
+ * shared instance hosts many users against one temp filesystem, so the store
+ * caps what a single user can hold (`maxSnapshotsPerUser`) as well as what the
+ * whole feature can occupy (`globalMaxBytes`).
+ *
+ * The per-asset and batch-size bounds of the retired layered protocol are gone:
+ * a snapshot arrives as ONE archive, so a single entry can no longer be sized
+ * independently of the archive that carries it.
+ */
+final class PreviewSnapshotLimits {
+	public function __construct(
+		public readonly int $ttlSeconds = 30 * 60,
+		public readonly int $maxSnapshotsPerUser = 4,
+		public readonly int $maxFilesPerSnapshot = 5000,
+		public readonly int $maxBytesPerSnapshot = 200 * 1024 * 1024,
+		public readonly int $globalMaxBytes = 2048 * 1024 * 1024,
+	) {
+	}
+}
diff --git a/lib/Service/Preview/PreviewSnapshotStore.php b/lib/Service/Preview/PreviewSnapshotStore.php
new file mode 100644
index 0000000..45a4c9e
--- /dev/null
+++ b/lib/Service/Preview/PreviewSnapshotStore.php
@@ -0,0 +1,523 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service\Preview;
+
+use RuntimeException;
+use ZipArchive;
+
+/**
+ * File-backed store for opaque editor-preview snapshots.
+ *
+ * The editor sends the WHOLE project as one ZIP on every opaque refresh and gets
+ * back an unguessable capability id; the authless serving route then hands that
+ * tree out without a session. PHP is request-scoped and those GETs carry no
+ * session, so the capability must live on disk:
+ *
+ * ```
+ * {root}/{previewId}/
+ *   meta.json    { ownerUserId, createdAt, bytes }
+ *   .accessed    touch-marker; its mtime is the idle-TTL / LRU clock
+ *   content/     the extracted snapshot
+ * ```
+ *
+ * This replaces the layered protocol-v2 store (immutable asset keys, incremental
+ * revisions, a fixed-resource layer, per-revision manifests and their publish
+ * critical section) — machinery whose whole purpose was to avoid re-uploading
+ * unchanged bytes, for a protocol the editor no longer speaks.
+ *
+ * What survives the simplification, because Nextcloud is multi-user and the
+ * others are not: the per-user snapshot cap and the global byte budget, both
+ * with LRU eviction, plus the idle TTL. One author cannot fill a shared
+ * instance's disk, and the feature as a whole stays bounded.
+ *
+ * Design invariants:
+ *
+ *  - **Atomic publication.** A snapshot is extracted into a staging directory
+ *    beside the live one and swapped in with `rename()`. A concurrent GET sees
+ *    the previous snapshot or the new one, never a half-written tree, and a
+ *    failure anywhere leaves the live snapshot untouched.
+ *  - **Content isolation.** Author bytes live under `content/`, so no path in
+ *    the archive can collide with the store's own metadata — there are no
+ *    reserved names to police.
+ *  - **Traversal safety.** Archive entries are vetted by {@see SnapshotArchive}
+ *    before extraction; served paths go through
+ *    {@see PreviewPolicy::normalizePath()} and are then confirmed with `realpath()`
+ *    to sit inside the content directory.
+ *
+ * OCP-free: the root is an injected plain directory and time comes from an
+ * injected clock, so the whole store is unit-testable against a temp dir.
+ */
+final class PreviewSnapshotStore {
+	/** @var callable():int */
+	private $clock;
+
+	/**
+	 * @param string $root Absolute path to the snapshots root directory.
+	 * @param PreviewSnapshotLimits $limits DoS bounds.
+	 * @param (callable():int)|null $clock Unix-time source (tests stub it).
+	 */
+	public function __construct(
+		private readonly string $root,
+		private readonly PreviewSnapshotLimits $limits,
+		?callable $clock = null,
+	) {
+		$this->clock = $clock ?? static fn (): int => time();
+	}
+
+	// =========================================================================
+	// Publication
+	// =========================================================================
+
+	/**
+	 * Create or atomically replace a snapshot.
+	 *
+	 * $previewId is absent on the first refresh (mint a capability) and present
+	 * afterwards (replace in place). An id that is unknown or owned by somebody
+	 * else is refused, so a capability cannot be claimed from another author.
+	 *
+	 * @return array{previewId:string}|array{error:string,status:int}
+	 */
+	public function replace(string $ownerUserId, string $zipPath, ?string $previewId = null): array {
+		$this->ensureDir($this->root);
+		$this->sweepExpired();
+
+		$replacing = $previewId !== null && $previewId !== '';
+		if ($replacing) {
+			$guard = $this->authorize((string)$previewId, $ownerUserId);
+			if ($guard !== null) {
+				return $guard;
+			}
+		} else {
+			$this->enforceUserSnapshotCap($ownerUserId);
+		}
+		$id = $replacing ? (string)$previewId : $this->generateUuidV4();
+
+		$staging = $this->root . '/.staging-' . bin2hex(random_bytes(12));
+		if (!@mkdir($staging . '/content', 0770, true) && !is_dir($staging . '/content')) {
+			return ['error' => 'Could not create the preview staging directory.', 'status' => 500];
+		}
+
+		$extracted = $this->extractInto($zipPath, $staging . '/content');
+		if (isset($extracted['error'])) {
+			$this->removeTree($staging);
+			return $extracted;
+		}
+
+		$budget = $this->reserveBudget($id, $extracted['bytes']);
+		if ($budget !== null) {
+			$this->removeTree($staging);
+			return $budget;
+		}
+
+		$this->writeFileAtomic($staging . '/meta.json', (string)json_encode([
+			'ownerUserId' => $ownerUserId,
+			'createdAt' => ($this->clock)(),
+			'bytes' => $extracted['bytes'],
+		], JSON_UNESCAPED_SLASHES));
+		@touch($staging . '/.accessed', ($this->clock)());
+
+		return $this->publish($staging, $id);
+	}
+
+	/**
+	 * The authorization verdict for a capability this user is claiming.
+	 *
+	 * Both management verbs run through here, so publish and delete can never
+	 * disagree about what owner scoping means: a malformed id is a 400, one
+	 * nobody holds a 404 and somebody else's a 403. Keeping the rule in the
+	 * store — rather than letting each caller assemble it from `exists()` and
+	 * `ownerOf()` — is what makes that guarantee structural instead of a
+	 * convention two controllers have to remember.
+	 *
+	 * @return array{error:string,status:int}|null Null when the caller may proceed.
+	 */
+	public function authorize(string $previewId, string $ownerUserId): ?array {
+		if (!PreviewPolicy::isValidPreviewId($previewId)) {
+			return ['error' => 'Invalid preview capability.', 'status' => 400];
+		}
+		$owner = $this->ownerOf($previewId);
+		if ($owner === null) {
+			return ['error' => 'Preview snapshot not found.', 'status' => 404];
+		}
+		if ($owner !== $ownerUserId) {
+			return ['error' => 'Preview snapshot belongs to another user.', 'status' => 403];
+		}
+		return null;
+	}
+
+	/**
+	 * Vet and extract the uploaded archive into $contentDir.
+	 *
+	 * @return array{bytes:int}|array{error:string,status:int}
+	 */
+	private function extractInto(string $zipPath, string $contentDir): array {
+		$zip = new ZipArchive();
+		if ($zip->open($zipPath) !== true) {
+			return ['error' => 'Invalid preview archive.', 'status' => 400];
+		}
+		try {
+			SnapshotArchive::inspect($zip, $this->limits);
+			$bytes = SnapshotArchive::extract($zip, $contentDir, $this->limits);
+		} catch (RuntimeException $e) {
+			return ['error' => $e->getMessage(), 'status' => 400];
+		} finally {
+			$zip->close();
+		}
+		return ['bytes' => $bytes];
+	}
+
+	/**
+	 * Make room for $incoming bytes in the global budget, evicting other
+	 * snapshots LRU-first.
+	 *
+	 * @return array{error:string,status:int}|null Null when the budget allows it.
+	 */
+	private function reserveBudget(string $currentId, int $incoming): ?array {
+		$global = $this->globalBytes() - $this->snapshotBytes($currentId);
+		if ($this->evictOthersForBudget($currentId, $incoming, $global) === null) {
+			return ['error' => 'Preview storage budget exhausted.', 'status' => 507];
+		}
+		return null;
+	}
+
+	/**
+	 * Swap the staged tree in for $id, keeping the previous one until the new one
+	 * is live so a failure never destroys a working snapshot.
+	 *
+	 * @return array{previewId:string}|array{error:string,status:int}
+	 */
+	private function publish(string $staging, string $id): array {
+		$target = $this->root . '/' . $id;
+		$backup = $target . '.old-' . bin2hex(random_bytes(6));
+		if (is_dir($target) && !@rename($target, $backup)) {
+			$this->removeTree($staging);
+			return ['error' => 'Could not replace the preview snapshot.', 'status' => 500];
+		}
+		if (!@rename($staging, $target)) {
+			if (is_dir($backup)) {
+				@rename($backup, $target);
+			}
+			$this->removeTree($staging);
+			return ['error' => 'Could not publish the preview snapshot.', 'status' => 500];
+		}
+		if (is_dir($backup)) {
+			$this->removeTree($backup);
+		}
+		return ['previewId' => $id];
+	}
+
+	// =========================================================================
+	// Serving
+	// =========================================================================
+
+	/**
+	 * Resolve a served path inside a snapshot and refresh its idle clock, so a
+	 * preview in use never expires under the author.
+	 *
+	 * A scriptable type is a `document` (rewritten on every refresh, so served
+	 * whole and uncached); everything else is an `asset` (revalidated with an
+	 * ETag and range-capable). The kind IS the scriptability — there is no second
+	 * flag to disagree with it.
+	 *
+	 * @return array{kind:string,contentType:string,bytes?:string,filePath?:string,size?:int,etag?:string}|null
+	 */
+	public function resolve(string $previewId, string $rawPath): ?array {
+		if (!PreviewPolicy::isValidPreviewId($previewId) || $this->isExpired($previewId)) {
+			return null;
+		}
+		$path = PreviewPolicy::normalizePath($rawPath);
+		if ($path === null) {
+			return null;
+		}
+		$file = $this->resolveInsideContent($previewId, $path);
+		if ($file === null) {
+			return null;
+		}
+		$this->touch($previewId);
+
+		$contentType = PreviewPolicy::mimeForPath($path);
+		if (PreviewPolicy::isScriptable($contentType)) {
+			$bytes = @file_get_contents($file);
+			if ($bytes === false) {
+				return null;
+			}
+			return [
+				'kind' => 'document',
+				'contentType' => $contentType,
+				'bytes' => $bytes,
+			];
+		}
+		$size = (int)@filesize($file);
+		// The content directory's inode is part of the identity on purpose: mtime
+		// has one-second granularity, so an author refreshing twice within the
+		// same second with an edit that keeps a file the same length would
+		// otherwise produce the same tag and be handed a 304 for the previous
+		// bytes. Every publish extracts into a fresh directory and renames it in,
+		// so the inode always turns over.
+		$generation = (string)@fileinode($this->snapshotDir($previewId) . '/content');
+		return [
+			'kind' => 'asset',
+			'contentType' => $contentType,
+			'filePath' => $file,
+			'size' => $size,
+			'etag' => sha1($path . '|' . $generation . '|' . (string)@filemtime($file) . '|' . $size),
+		];
+	}
+
+	/**
+	 * Map a normalized relative path onto a real file inside the snapshot's
+	 * content directory.
+	 *
+	 * `normalizePath()` has already rejected traversal, but the tree is author
+	 * controlled, so the resolved path is confirmed with `realpath()` as well: a
+	 * symlink that survived extraction could otherwise point outside.
+	 */
+	private function resolveInsideContent(string $previewId, string $path): ?string {
+		$contentDir = @realpath($this->snapshotDir($previewId) . '/content');
+		if ($contentDir === false) {
+			return null;
+		}
+		$file = @realpath($contentDir . '/' . $path);
+		if ($file === false || !is_file($file) || !str_starts_with($file, $contentDir . '/')) {
+			return null;
+		}
+		return $file;
+	}
+
+	// =========================================================================
+	// Lifecycle
+	// =========================================================================
+
+	/** The owner user id of a snapshot, or null when it does not exist. */
+	public function ownerOf(string $previewId): ?string {
+		$meta = $this->readMeta($previewId);
+		$owner = $meta['ownerUserId'] ?? null;
+		return is_string($owner) ? $owner : null;
+	}
+
+	/**
+	 * Delete a snapshot after {@see authorize()} has cleared the caller.
+	 *
+	 * @return array{error:string,status:int}|null Null once it is gone.
+	 */
+	public function deleteOwned(string $previewId, string $ownerUserId): ?array {
+		$guard = $this->authorize($previewId, $ownerUserId);
+		if ($guard !== null) {
+			return $guard;
+		}
+		$this->removeTree($this->snapshotDir($previewId));
+		return null;
+	}
+
+	/** Whether a snapshot has been idle longer than the TTL. */
+	public function isExpired(string $previewId): bool {
+		$marker = $this->snapshotDir($previewId) . '/.accessed';
+		clearstatcache(true, $marker);
+		$accessed = @filemtime($marker);
+		if ($accessed !== false) {
+			return (($this->clock)() - $accessed) > $this->limits->ttlSeconds;
+		}
+		// A missing/unreadable `.accessed` marker must NOT make a snapshot
+		// immortal — that would keep it counting against the global byte budget
+		// forever and never let sweepExpired reclaim it. Fall back to meta.json
+		// createdAt as the age clock; if meta.json is missing/corrupt too, the
+		// directory is unusable (it can neither be owned nor served), so treat it
+		// as expired and let sweepExpired reclaim it.
+		$meta = $this->readMeta($previewId);
+		$createdAt = isset($meta['createdAt']) ? (int)$meta['createdAt'] : null;
+		if ($createdAt === null) {
+			return true;
+		}
+		return (($this->clock)() - $createdAt) > $this->limits->ttlSeconds;
+	}
+
+	/**
+	 * Remove every snapshot idle longer than the TTL. Returns the count swept.
+	 * Called by the background cleanup job and opportunistically on publish.
+	 */
+	public function sweepExpired(): int {
+		$swept = 0;
+		foreach ($this->listSnapshotIds() as $previewId) {
+			if ($this->isExpired($previewId)) {
+				$this->removeTree($this->snapshotDir($previewId));
+				$swept++;
+			}
+		}
+		return $swept;
+	}
+
+	// =========================================================================
+	// Budgets
+	// =========================================================================
+
+	/** Evict this user's LRU snapshots until they are under the per-user cap. */
+	private function enforceUserSnapshotCap(string $ownerUserId): void {
+		$owned = [];
+		foreach ($this->listSnapshotIds() as $previewId) {
+			if ($this->ownerOf($previewId) === $ownerUserId) {
+				$owned[$previewId] = $this->lastAccess($previewId);
+			}
+		}
+		while (count($owned) >= $this->limits->maxSnapshotsPerUser && $owned !== []) {
+			$lru = array_keys($owned, min($owned))[0];
+			$this->removeTree($this->snapshotDir($lru));
+			unset($owned[$lru]);
+		}
+	}
+
+	/**
+	 * Evict OTHER snapshots (never $currentId) in LRU order until $incoming fits
+	 * the global budget. Returns the updated total, or null when it cannot fit
+	 * even after evicting every other snapshot.
+	 */
+	private function evictOthersForBudget(string $currentId, int $incoming, int $globalBytes): ?int {
+		while ($globalBytes + $incoming > $this->limits->globalMaxBytes) {
+			$candidates = [];
+			foreach ($this->listSnapshotIds() as $previewId) {
+				if ($previewId !== $currentId) {
+					$candidates[$previewId] = $this->lastAccess($previewId);
+				}
+			}
+			if ($candidates === []) {
+				return null;
+			}
+			$lru = array_keys($candidates, min($candidates))[0];
+			$globalBytes -= $this->snapshotBytes($lru);
+			$this->removeTree($this->snapshotDir($lru));
+		}
+		return $globalBytes;
+	}
+
+	/** Sum of logical bytes across every snapshot. */
+	private function globalBytes(): int {
+		$total = 0;
+		foreach ($this->listSnapshotIds() as $previewId) {
+			$total += $this->snapshotBytes($previewId);
+		}
+		return $total;
+	}
+
+	/**
+	 * The byte total a snapshot holds, recorded at publish time.
+	 *
+	 * Read from meta.json rather than walked: the extraction already counted
+	 * every byte it wrote, so re-walking the tree on each budget check would be
+	 * the same answer at a much higher cost.
+	 */
+	private function snapshotBytes(string $previewId): int {
+		$meta = $this->readMeta($previewId);
+		return isset($meta['bytes']) ? (int)$meta['bytes'] : 0;
+	}
+
+	// =========================================================================
+	// Helpers
+	// =========================================================================
+
+	private function snapshotDir(string $previewId): string {
+		return $this->root . '/' . $previewId;
+	}
+
+	/** @return array<string,mixed>|null */
+	private function readMeta(string $previewId): ?array {
+		if (!PreviewPolicy::isValidPreviewId($previewId)) {
+			return null;
+		}
+		$raw = @file_get_contents($this->snapshotDir($previewId) . '/meta.json');
+		if ($raw === false) {
+			return null;
+		}
+		$decoded = json_decode($raw, true);
+		return is_array($decoded) ? $decoded : null;
+	}
+
+	/** Refresh the idle-TTL / LRU clock. */
+	private function touch(string $previewId): void {
+		$marker = $this->snapshotDir($previewId) . '/.accessed';
+		$now = ($this->clock)();
+		if (!@touch($marker, $now)) {
+			@file_put_contents($marker, '');
+			@touch($marker, $now);
+		}
+		clearstatcache(true, $marker);
+	}
+
+	/** The last-access unix time of a snapshot (0 when unknown). */
+	private function lastAccess(string $previewId): int {
+		$marker = $this->snapshotDir($previewId) . '/.accessed';
+		clearstatcache(true, $marker);
+		$mtime = @filemtime($marker);
+		return $mtime === false ? 0 : $mtime;
+	}
+
+	/** @return list<string> */
+	private function listSnapshotIds(): array {
+		$ids = [];
+		if (!is_dir($this->root)) {
+			return $ids;
+		}
+		foreach (scandir($this->root) ?: [] as $entry) {
+			if (PreviewPolicy::isValidPreviewId($entry) && is_dir($this->root . '/' . $entry)) {
+				$ids[] = $entry;
+			}
+		}
+		return $ids;
+	}
+
+	/** Write a small file atomically via temp + rename. */
+	private function writeFileAtomic(string $path, string $contents): void {
+		$tmp = $path . '.tmp.' . bin2hex(random_bytes(8));
+		if (@file_put_contents($tmp, $contents) === false) {
+			@unlink($tmp);
+			return;
+		}
+		if (!@rename($tmp, $path)) {
+			@unlink($tmp);
+		}
+	}
+
+	private function ensureDir(string $dir): void {
+		if (!is_dir($dir)) {
+			@mkdir($dir, 0770, true);
+		}
+	}
+
+	private function removeTree(string $dir): void {
+		if (!is_dir($dir)) {
+			@unlink($dir);
+			return;
+		}
+		$items = scandir($dir);
+		if ($items === false) {
+			return;
+		}
+		foreach ($items as $item) {
+			if ($item === '.' || $item === '..') {
+				continue;
+			}
+			$path = $dir . '/' . $item;
+			if (is_dir($path) && !is_link($path)) {
+				$this->removeTree($path);
+			} else {
+				@unlink($path);
+			}
+		}
+		@rmdir($dir);
+	}
+
+	private function generateUuidV4(): string {
+		$bytes = random_bytes(16);
+		$bytes[6] = chr((ord($bytes[6]) & 0x0f) | 0x40);
+		$bytes[8] = chr((ord($bytes[8]) & 0x3f) | 0x80);
+		$hex = bin2hex($bytes);
+		return sprintf(
+			'%s-%s-%s-%s-%s',
+			substr($hex, 0, 8),
+			substr($hex, 8, 4),
+			substr($hex, 12, 4),
+			substr($hex, 16, 4),
+			substr($hex, 20, 12),
+		);
+	}
+}
diff --git a/lib/Service/Preview/SnapshotArchive.php b/lib/Service/Preview/SnapshotArchive.php
new file mode 100644
index 0000000..3752717
--- /dev/null
+++ b/lib/Service/Preview/SnapshotArchive.php
@@ -0,0 +1,180 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service\Preview;
+
+use RuntimeException;
+use ZipArchive;
+
+/**
+ * The trust boundary for an uploaded preview archive: decides whether a ZIP may
+ * be extracted at all, then extracts it under a real-byte budget.
+ *
+ * Kept apart from {@see PreviewSnapshotStore} on purpose — the store's job is to
+ * publish a tree atomically, this one's is to refuse an archive before a single
+ * byte reaches the disk. These rules are what stands between untrusted author
+ * content and the server filesystem, so they are worth reading in one place.
+ *
+ * Two passes, and the order matters:
+ *
+ *  1. {@see inspect()} vets EVERY entry up front. A limit noticed halfway
+ *     through would leave a partially written tree behind, so nothing is written
+ *     until the whole archive has passed.
+ *  2. {@see extract()} streams each entry out and counts the bytes it ACTUALLY
+ *     writes. The uncompressed sizes in a ZIP's central directory are supplied
+ *     by whoever built the archive, so pass 1's byte total is an early reject,
+ *     never the enforcement — a zip bomb that under-declares its sizes is caught
+ *     here instead.
+ */
+final class SnapshotArchive {
+	/**
+	 * Vet every entry of an open archive.
+	 *
+	 * @throws RuntimeException When the archive must not be extracted.
+	 */
+	public static function inspect(ZipArchive $zip, PreviewSnapshotLimits $limits): void {
+		if ($zip->numFiles > $limits->maxFilesPerSnapshot) {
+			throw new RuntimeException('Preview archive contains too many files.');
+		}
+		$declared = 0;
+		$hasIndex = false;
+		for ($index = 0; $index < $zip->numFiles; $index++) {
+			$entry = self::inspectEntry($zip, $index);
+			if ($entry === null) {
+				continue; // directory
+			}
+			$declared += $entry['size'];
+			if ($declared > $limits->maxBytesPerSnapshot) {
+				throw new RuntimeException('Preview archive is too large.');
+			}
+			$hasIndex = $hasIndex || $entry['name'] === 'index.html';
+		}
+		if (!$hasIndex) {
+			throw new RuntimeException('Preview archive must contain index.html.');
+		}
+	}
+
+	/**
+	 * Extract a vetted archive into $targetDir, enforcing the byte budget on the
+	 * bytes actually written.
+	 *
+	 * Entries are streamed rather than handed to `extractTo()` so the budget can
+	 * be enforced mid-file: an entry that inflates past the cap is abandoned
+	 * as soon as the cap is crossed, not after it has filled the disk.
+	 *
+	 * @return int Bytes written — the caller needs the total and this already
+	 *             counted every one of them.
+	 * @throws RuntimeException When extraction fails or exceeds the budget.
+	 */
+	public static function extract(ZipArchive $zip, string $targetDir, PreviewSnapshotLimits $limits): int {
+		$written = 0;
+		for ($index = 0; $index < $zip->numFiles; $index++) {
+			$name = (string)$zip->getNameIndex($index);
+			if (str_ends_with($name, '/')) {
+				continue;
+			}
+			$destination = $targetDir . '/' . $name;
+			$parent = dirname($destination);
+			if (!is_dir($parent) && !@mkdir($parent, 0700, true) && !is_dir($parent)) {
+				throw new RuntimeException('Could not create a preview directory.');
+			}
+			$written += self::extractEntry($zip, $index, $destination, $limits->maxBytesPerSnapshot - $written);
+		}
+		return $written;
+	}
+
+	/**
+	 * Stream one entry to disk, stopping if it would exceed $remaining bytes.
+	 *
+	 * @return int Bytes written for this entry.
+	 * @throws RuntimeException
+	 */
+	private static function extractEntry(ZipArchive $zip, int $index, string $destination, int $remaining): int {
+		$source = $zip->getStream((string)$zip->getNameIndex($index));
+		if (!is_resource($source)) {
+			throw new RuntimeException('Could not read the preview archive.');
+		}
+		$target = @fopen($destination, 'wb');
+		if (!is_resource($target)) {
+			fclose($source);
+			throw new RuntimeException('Could not write the preview snapshot.');
+		}
+		$written = 0;
+		try {
+			while (!feof($source)) {
+				$chunk = fread($source, 131072);
+				if ($chunk === false) {
+					throw new RuntimeException('Could not read the preview archive.');
+				}
+				$written += strlen($chunk);
+				if ($written > $remaining) {
+					throw new RuntimeException('Preview archive is too large.');
+				}
+				if ($chunk !== '' && fwrite($target, $chunk) === false) {
+					throw new RuntimeException('Could not write the preview snapshot.');
+				}
+			}
+		} finally {
+			fclose($source);
+			fclose($target);
+		}
+		return $written;
+	}
+
+	/**
+	 * Vet a single entry.
+	 *
+	 * @return array{name:string,size:int}|null Null for a directory.
+	 * @throws RuntimeException When the entry is unsafe.
+	 */
+	private static function inspectEntry(ZipArchive $zip, int $index): ?array {
+		$name = $zip->getNameIndex($index);
+		$stat = $zip->statIndex($index);
+		$isDirectory = is_string($name) && str_ends_with($name, '/');
+		$validated = $isDirectory ? rtrim((string)$name, '/') : (string)$name;
+		if (!is_string($name) || !is_array($stat) || !self::isSafePath($validated)) {
+			throw new RuntimeException('Unsafe path in the preview archive.');
+		}
+		if ($isDirectory) {
+			return null;
+		}
+		if (self::isSymlink($zip, $index)) {
+			throw new RuntimeException('The preview archive contains a symbolic link.');
+		}
+		return ['name' => $name, 'size' => (int)($stat['size'] ?? 0)];
+	}
+
+	/**
+	 * Whether an entry is a Unix symbolic link.
+	 *
+	 * A link is stored as a tiny entry whose contents are the target path, so it
+	 * passes every size and path check while pointing anywhere on the filesystem.
+	 */
+	private static function isSymlink(ZipArchive $zip, int $index): bool {
+		$opsys = 0;
+		$attributes = 0;
+		return $zip->getExternalAttributesIndex($index, $opsys, $attributes)
+			&& $opsys === ZipArchive::OPSYS_UNIX
+			&& (($attributes >> 16) & 0xf000) === 0xa000;
+	}
+
+	/**
+	 * Whether a relative path is canonical and safe.
+	 *
+	 * There is deliberately no reserved-name list: the store keeps its own
+	 * metadata OUTSIDE the extracted tree, so no author path can collide with it.
+	 */
+	private static function isSafePath(string $path): bool {
+		if ($path === '' || str_contains($path, "\0") || str_contains($path, '\\')
+			|| $path[0] === '/') {
+			return false;
+		}
+		foreach (explode('/', $path) as $part) {
+			if ($part === '' || $part === '.' || $part === '..') {
+				return false;
+			}
+		}
+		return true;
+	}
+}
diff --git a/src/elpx/iframe-renderer.ts b/src/elpx/iframe-renderer.ts
index 6b18f6b..9da2e61 100644
--- a/src/elpx/iframe-renderer.ts
+++ b/src/elpx/iframe-renderer.ts
@@ -1,15 +1,29 @@
 /**
- * Builds the sandboxed iframe that displays a session. The iframe is the only
- * point where package HTML executes, and the sandbox flags are tuned to the
- * minimum that still lets eXeLearning's iDevices run.
+ * Builds the sandboxed iframe that displays a package.
  *
- * External links inside the iframe are forced to open in a new tab so the
- * parent Nextcloud window never navigates away from the Viewer.
+ * The default (secure) path serves the package from the opaque `/content`
+ * route: the iframe drops `allow-same-origin`, so the document runs in a
+ * browser-enforced **opaque origin** and cannot reach the Nextcloud DOM,
+ * cookies or storage. External media is handled by the eXe embed relay running
+ * in the parent (see relay-host.ts), not by reaching into the iframe document.
+ *
+ * The legacy path (Service-Worker `/runtime` route, only via the
+ * EXELEARNING_UNSAFE_LEGACY_IFRAME escape hatch) keeps `allow-same-origin` —
+ * the SW can only control a same-origin document — and rewires external links
+ * by touching the same-origin iframe document.
  */
 
-import { buildRuntimeUrl } from './paths'
+import { buildAssetUrl, buildContentUrl, buildRuntimeUrl } from './paths'
+
+/** Opaque, secure sandbox: no allow-same-origin (that absence is the isolation). */
+const SECURE_SANDBOX_FLAGS = [
+	'allow-scripts',
+	'allow-popups',
+	'allow-forms',
+] as const
 
-const SANDBOX_FLAGS = [
+/** Legacy same-origin sandbox for the Service-Worker path only. */
+const LEGACY_SANDBOX_FLAGS = [
 	'allow-scripts',
 	'allow-same-origin',
 	'allow-forms',
@@ -57,55 +71,98 @@ export interface IframeOptions {
 	title: string
 }
 
+export interface ContentIframeOptions {
+	contentBase: string
+	token: string
+	indexEntry: string
+	title: string
+}
+
+export interface AssetIframeOptions {
+	assetBase: string
+	fileId: number
+	indexEntry: string
+	title: string
+}
+
 /**
- * Builds a sandboxed iframe pointed at an already-resolved `src`. Shared by the
- * Service Worker path ({@link createPackageIframe}) and the server-side asset
- * fallback so both get identical sandbox flags and external-link rewiring.
+ * Builds a sandboxed iframe pointed at an already-resolved `src`.
  * @param src Fully-resolved URL the iframe should load.
  * @param title Accessible title for the iframe.
+ * @param opaque When true (default) use the secure opaque sandbox and do not
+ *   touch the iframe document; when false use the legacy same-origin sandbox
+ *   (Service-Worker path) and rewire external links.
  */
-export function buildSandboxedIframe(src: string, title: string): HTMLIFrameElement {
+export function buildSandboxedIframe(src: string, title: string, opaque = true): HTMLIFrameElement {
 	const iframe = document.createElement('iframe')
 	iframe.className = 'exelearning-viewer__iframe'
 	iframe.title = title
-	iframe.setAttribute('sandbox', SANDBOX_FLAGS.join(' '))
+	iframe.setAttribute('sandbox', (opaque ? SECURE_SANDBOX_FLAGS : LEGACY_SANDBOX_FLAGS).join(' '))
 	iframe.setAttribute('allow', IFRAME_ALLOW)
 	iframe.setAttribute('referrerpolicy', 'no-referrer')
-	// `src` is always the package *index* entry — both the Service Worker path
-	// ({@link createPackageIframe}) and the server-side asset fallback funnel
-	// the top-level page here, never a subresource. Adding the teacher-mode
-	// param only to this top-level document is enough: the package's own JS
-	// propagates it across in-package navigation, and the SW/AssetController
-	// match requests on the pathname only, so the extra query is harmless.
+	// `src` is always the package *index* entry. Adding the teacher-mode param
+	// only to this top-level document is enough: the package's own JS propagates
+	// it across in-package navigation, and the content/SW route matches requests
+	// on the pathname only, so the extra query is harmless.
 	iframe.src = withTeacherMode(src)
-	iframe.addEventListener('load', () => {
-		try {
-			rewireExternalLinks(iframe)
-		} catch {
-			// Cross-origin error: we lose the same-origin invariant when the
-			// SW is bypassed. We swallow the error rather than break the view.
-		}
-	})
+	if (!opaque) {
+		iframe.addEventListener('load', () => {
+			try {
+				rewireExternalLinks(iframe)
+			} catch {
+				// Same-origin access can still fail; swallow rather than break the view.
+			}
+		})
+	}
 	return iframe
 }
 
 /**
- * Builds the sandboxed iframe that renders a registered package session.
- * The `src` is built from the runtime base + sessionId + index entry; the
- * Service Worker fulfils requests under that scope from in-memory bytes.
+ * Builds the opaque-origin iframe that renders a published package over the
+ * `/content/{token}/…` capability route. This is the default (secure) path.
+ * @param options Content base URL, capability token, index entry and title.
+ */
+export function createContentIframe(options: ContentIframeOptions): HTMLIFrameElement {
+	return buildSandboxedIframe(
+		buildContentUrl(options.contentBase, options.token, options.indexEntry),
+		options.title,
+		true,
+	)
+}
+
+/**
+ * Builds the legacy same-origin iframe that renders a registered package
+ * session over the Service-Worker `/runtime` route. Only used when the
+ * EXELEARNING_UNSAFE_LEGACY_IFRAME escape hatch is on.
  * @param options Runtime base, sessionId, index entry and accessible title.
  */
 export function createPackageIframe(options: IframeOptions): HTMLIFrameElement {
 	return buildSandboxedIframe(
 		buildRuntimeUrl(options.runtimeBase, options.sessionId, options.indexEntry),
 		options.title,
+		false,
+	)
+}
+
+/**
+ * Builds the authenticated same-origin iframe used when Service Worker
+ * registration is unavailable. AssetController checks the Nextcloud session,
+ * so this path must retain `allow-same-origin`; the secure capability-backed
+ * `/content` route remains the only opaque variant.
+ * @param options Asset base URL, file id, index entry and accessible title.
+ */
+export function createAssetIframe(options: AssetIframeOptions): HTMLIFrameElement {
+	return buildSandboxedIframe(
+		buildAssetUrl(options.assetBase, options.fileId, options.indexEntry),
+		options.title,
+		false,
 	)
 }
 
 /**
  * Forces every external (`scheme:` or `//host`) link inside the iframe to
- * open in a new tab with `noopener noreferrer`, so the Viewer modal never
- * navigates away from Nextcloud.
+ * open in a new tab with `noopener noreferrer`, so the Viewer never navigates
+ * away from Nextcloud. Only usable on the same-origin (legacy) path.
  * @param iframe Iframe whose document should be augmented.
  */
 function rewireExternalLinks(iframe: HTMLIFrameElement): void {
diff --git a/src/elpx/paths.ts b/src/elpx/paths.ts
index fd6efe4..f97c8d7 100644
--- a/src/elpx/paths.ts
+++ b/src/elpx/paths.ts
@@ -7,6 +7,7 @@
 
 export const RUNTIME_PREFIX = '/apps/exelearning/runtime'
 export const ASSET_PREFIX = '/apps/exelearning/asset'
+export const CONTENT_PREFIX = '/apps/exelearning/content'
 
 const PROTOCOL_LIKE = /^[a-zA-Z][a-zA-Z0-9+.-]*:/
 
@@ -131,6 +132,28 @@ export function buildAssetUrl(base: string, fileId: number, entry: string): stri
 		.join('/')}`
 }
 
+/**
+ * Builds an iframe-loadable URL for an entry served by the **opaque** content
+ * route ({@link CONTENT_PREFIX}). Unlike {@link buildAssetUrl}, the file is
+ * addressed by a short-lived capability `token` (minted server-side, bound to
+ * the file id) rather than the raw file id, because the opaque origin sends no
+ * session cookie — the token is the only credential.
+ * @param base Content base URL (typically `generateUrl(CONTENT_PREFIX)`).
+ * @param token Capability token from initial state (`contentToken`).
+ * @param entry Normalised entry path inside the package.
+ */
+export function buildContentUrl(base: string, token: string, entry: string): string {
+	const normalized = normalizeEntryPath(entry)
+	if (normalized === null) {
+		throw new Error(`Refusing to build content URL for unsafe entry: ${entry}`)
+	}
+	const cleanBase = base.replace(/\/+$/, '')
+	return `${cleanBase}/${encodeURIComponent(token)}/${normalized
+		.split('/')
+		.map(encodeURIComponent)
+		.join('/')}`
+}
+
 /**
  * Parses a runtime URL produced by {@link buildRuntimeUrl} back into its
  * session and entry components. The base path must match RUNTIME_PREFIX.
diff --git a/src/embed/exe_external_media/exe-external-media-child.min.js b/src/embed/exe_external_media/exe-external-media-child.min.js
new file mode 100644
index 0000000..79bd060
--- /dev/null
+++ b/src/embed/exe_external_media/exe-external-media-child.min.js
@@ -0,0 +1,13 @@
+/*!
+ * eXeLearning external-media child bundle — https://github.com/exelearning/exelearning
+ *
+ * Copyright (C) 2026 eXeLearning Team
+ *
+ * Dual-licensed so these bytes can ship inside eXeLearning (AGPL-3.0-or-later)
+ * and inside the GPL-3.0-or-later host plugins without either project
+ * relicensing them. Combining is already permitted by GPLv3 s13 and AGPLv3 s13;
+ * combining never relicenses, so this grant is what makes vendoring lawful.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later OR GPL-3.0-or-later
+ */
+(()=>{var le=Object.defineProperty,ue=Object.defineProperties,ce=Object.getOwnPropertyDescriptors,B=Object.getOwnPropertyNames,z=Object.getOwnPropertySymbols,de=Object.prototype.hasOwnProperty,fe=Object.prototype.propertyIsEnumerable,Y=(e,t,r)=>t in e?le(e,t,{enumerable:!0,configurable:!0,writable:!0,value:r}):e[t]=r,I=(e,t)=>{for(var r in t||(t={}))de.call(t,r)&&Y(e,r,t[r]);if(z)for(var r of z(t))fe.call(t,r)&&Y(e,r,t[r]);return e},me=(e,t)=>ue(e,ce(t)),_=(e,t)=>function(){return e&&(t=(0,e[B(e)[0]])(e=0)),t},pe=(e,t)=>function(){return t||(0,e[B(e)[0]])((t={exports:{}}).exports,t),t.exports};function ve({warn:e}={}){const t=new Set,r=[],n=e!=null?e:(o=>console.warn(o));return{notice(o,a){t.has(o)||(t.add(o),r.push(o),n(`[exe] window.${o} is deprecated and will be removed in a future major. Use ${a}. It still works for now; nothing needs changing today.`))},announced(){return[...r]}}}function j(e,t,r,n){return typeof Proxy=="undefined"?e:new Proxy(e,{get(o,a,i){return n.notice(t,r),Reflect.get(o,a,i)}})}var he=_({"src/shared/external-media/compatibility/legacy-globals.ts"(){}});function _e(e){return typeof e=="string"&&V.includes(e)}function ye(e){return typeof e=="string"&&F.includes(e)}var g,O,b,V,F,w=_({"src/shared/external-media/protocol/messages.ts"(){g=1,O="exe-embed",b="exe-media",V=["open","play","pause","seek","getCurrentTime","getDuration","hide","show","close"],F=["ready","play","pause","ended","timeupdate","seeked","state","error","closed"]}});function Z(e,t){const r=e.toLowerCase().replace(/\.$/,"");return r===t||r.endsWith(`.${t}`)}var W,H,J,ge=_({"src/shared/external-media/providers/types.ts"(){W="allow-scripts allow-same-origin allow-popups allow-forms allow-presentation",H="autoplay; encrypted-media; fullscreen; picture-in-picture; clipboard-write",J="strict-origin-when-cross-origin"}});function be(e){var t;return(t=ee.get(e))!=null?t:null}function Ee(e){var t;const r=e.hostname.toLowerCase().replace(/\.$/,"");return(t=D.find(n=>n.hosts.some(o=>Z(r,o))))!=null?t:null}function Ie(e){var t,r;let n;try{n=new URL(e)}catch(o){return null}return n.protocol!=="https:"||n.username||n.password?null:(r=(t=Ee(n))==null?void 0:t.parse(n))!=null?r:null}var M,x,X,P,G,R,K,C,Q,D,ee,te=_({"src/shared/external-media/providers/registry.ts"(){ge(),M={passive:{supported:!0,sandbox:W,allow:H,referrerPolicy:J},controlled:{supported:!1},facade:{posterStrategy:"none"}},x=/^[A-Za-z0-9_-]{11}$/,X=I({id:"youtube",hosts:["youtube.com","youtu.be","youtube-nocookie.com"],resourceIdPattern:x,kind:"video",parse(e){var t,r,n,o;const a=e.hostname.toLowerCase().replace(/\.$/,"");let i="";return Z(a,"youtu.be")?i=(t=e.pathname.split("/").filter(Boolean)[0])!=null?t:"":i=(o=(n=e.searchParams.get("v"))!=null?n:(r=e.pathname.match(/^\/(?:embed|v|shorts)\/([^/?#]+)/))==null?void 0:r[1])!=null?o:"",x.test(i)?{provider:"youtube",resourceId:i,kind:"video"}:null},buildCanonicalEmbedUrl(e){return x.test(e)?`https://www.youtube-nocookie.com/embed/${e}`:null}},M),P=/^[0-9]{6,12}$/,G=I({id:"vimeo",hosts:["vimeo.com"],resourceIdPattern:P,kind:"video",parse(e){var t,r,n;const o=(n=(r=(t=e.pathname.match(/^\/video\/([0-9]+)/))==null?void 0:t[1])!=null?r:e.pathname.split("/").filter(Boolean)[0])!=null?n:"";return P.test(o)?{provider:"vimeo",resourceId:o,kind:"video"}:null},buildCanonicalEmbedUrl(e){return P.test(e)?`https://player.vimeo.com/video/${e}`:null}},M),R=/^[A-Za-z0-9]{5,}$/,K=I({id:"dailymotion",hosts:["dailymotion.com","dai.ly"],resourceIdPattern:R,kind:"video",parse(e){var t,r,n,o;const a=(o=(n=(t=e.pathname.match(/^\/embed\/video\/([A-Za-z0-9]+)/))==null?void 0:t[1])!=null?n:(r=e.pathname.match(/^\/video\/([A-Za-z0-9]+)/))==null?void 0:r[1])!=null?o:"";return R.test(a)?{provider:"dailymotion",resourceId:a,kind:"video"}:null},buildCanonicalEmbedUrl(e){return R.test(e)?`https://www.dailymotion.com/embed/video/${e}`:null}},M),C=/^[A-Za-z0-9]{8,}$/,Q=I({id:"mediateca-madrid",hosts:["mediateca.educa.madrid.org"],resourceIdPattern:C,kind:"video",parse(e){var t,r;const n=(r=(t=e.pathname.match(/^\/video\/([A-Za-z0-9]+)(?:\/fs)?\/?$/))==null?void 0:t[1])!=null?r:"";return C.test(n)?{provider:"mediateca-madrid",resourceId:n,kind:"video"}:null},buildCanonicalEmbedUrl(e){return C.test(e)?`https://mediateca.educa.madrid.org/video/${e}/fs`:null}},M),D=[X,G,K,Q],ee=new Map(D.map(e=>[e.id,e]))}});function Me(e){return typeof e=="object"&&e!==null}function Ae(e,t,r){return typeof e=="number"&&Number.isFinite(e)&&e>=t&&e<=r}function E(e){return Ae(e,0,ne)}function re(e,t){return Me(e)&&e.type===t}function Oe(e){if(!re(e,b)||e.v!==g||!_e(e.action))return!1;switch(e.action){case"open":{if(!Number.isInteger(e.reqId)||!(e.start===void 0||e.start===null||E(e.start))||typeof e.provider!="string"||typeof e.videoId!="string")return!1;const t=be(e.provider);return!!t&&t.resourceIdPattern.test(e.videoId)}case"seek":return E(e.t);case"getCurrentTime":case"getDuration":return Number.isInteger(e.reqId);default:return!0}}function we(e){if(!re(e,b)||e.v!==g||!ye(e.action))return!1;switch(e.action){case"timeupdate":return E(e.currentTime)&&E(e.duration);case"seeked":return E(e.currentTime);case"state":return Number.isInteger(e.reqId);case"ready":return e.duration===void 0||e.duration===null||E(e.duration);case"error":return typeof e.code=="string"&&typeof e.fatal=="boolean";default:return!0}}var ne,xe=_({"src/shared/external-media/protocol/schemas.ts"(){te(),w(),ne=1e6}});function Pe(){let e=null;const t=new WeakSet;function r(n){const o=new Map;let a=new Map,i=0,u=!1;function h(s,p){var d;for(const y of(d=o.get(s))!=null?d:[])try{y(p)}catch(je){}}function f(s){if(u)return;const p=me(I({},s),{type:b,v:g});Oe(p)&&n.postMessage(p)}function m(s,p){return new Promise(d=>{if(u){d(null);return}i+=1;const y=i;a.set(y,{resolve:d,field:p}),f({action:s,reqId:y})})}const v={on(s,p){var d;return o.set(s,[...(d=o.get(s))!=null?d:[],p]),v},off(s,p){var d;return o.set(s,((d=o.get(s))!=null?d:[]).filter(y=>y!==p)),v},open(s){i+=1,f({action:"open",reqId:i,provider:s.provider,videoId:s.videoId,start:s.start,autoplay:s.autoplay})},play:()=>f({action:"play"}),pause:()=>f({action:"pause"}),seek:s=>f({action:"seek",t:s}),hide:()=>f({action:"hide"}),show:()=>f({action:"show"}),close:()=>f({action:"close"}),getCurrentTime:()=>m("getCurrentTime","currentTime"),getDuration:()=>m("getDuration","duration"),isRetired:()=>u};function c(s){var p;if(u||!we(s))return;const d=s;if(d.action==="state"){const y=a.get(d.reqId);if(!y)return;a.delete(d.reqId),y.resolve((p=d[y.field])!=null?p:null);return}h(d.action,d)}function l(){if(!u){for(const s of a.values())s.resolve(null);a=new Map,h("closed",{type:b,v:g,action:"closed",superseded:!0}),u=!0,o.clear()}}return{controller:v,deliver:c,retire:l}}return{create(n){var o;const a=r(n);return e&&e.controller!==a.controller&&e.retire(),e=a,t.has(n)||(t.add(n),n.onmessage=i=>e==null?void 0:e.deliver(i==null?void 0:i.data),(o=n.start)==null||o.call(n)),a.controller}}}var Re=_({"src/shared/external-media/media/controller.ts"(){w(),xe()}});function Ce({win:e,createHelloId:t}){const r=Pe();let n=null;function o(){const a=e.parent;return a?new Promise(i=>{const u=t();let h=!1;function f(m){var v;if(h)return;const c=m;if((c==null?void 0:c.source)!==a)return;const l=c.data;if(!l||l.type!==b||l.v!==g||l.action!=="welcome"||l.helloId!==u)return;const s=(v=c.ports)==null?void 0:v[0];s&&(h=!0,e.removeEventListener("message",f),i(s))}e.addEventListener("message",f);try{a.postMessage({type:b,v:g,action:"hello",helloId:u},"*")}catch(m){}}):Promise.resolve(null)}return{session(){return n!=null||(n=o()),n},async openMedia(a){const i=await this.session();if(!i)return null;const u=r.create(i);return u.open(a),u}}}var De=_({"src/shared/external-media/media/media-child.ts"(){w(),Re()}});function L(e){var t;try{return(t=e.document)==null||t.cookie,e.origin==="null"}catch(r){return!0}}function S(e){try{return!!e&&e.parent!==e}catch(t){return!0}}function oe(e){var t;return(t=e.location)==null?void 0:t.href}function Le(e,t){try{const r=new URL(e,t);if(r.protocol!=="https:")return!1;const n=r.hostname.toLowerCase().replace(/\.$/,""),o=new URL(t!=null?t:"").hostname.toLowerCase().replace(/\.$/,"");return n!==o}catch(r){return!1}}function Se(e,t){try{return/\.pdf$/i.test(new URL(e,t).pathname)}catch(r){return!1}}function ie(e,t){return Le(e,t)||Se(e,t)}var T=_({"src/shared/external-media/child/environment.ts"(){}});function Te(e,t,r={}){let n=!1,o="";function a(c){try{e.parent.postMessage(c,"*")}catch(l){}}function i(c){const l=t.collect(),s=JSON.stringify(l);!c&&s===o||(o=s,a({type:O,action:"sync",embeds:l}))}function u(){t.promote(),i(!0)}function h(){var c;n||(n=!0,(c=r.onActivate)==null||c.call(r),u())}function f(c){n||(a({type:O,action:"hello"}),c<$.length&&e.setTimeout(()=>f(c+1),$[c]))}function m(c){if(!c||c.source!==e.parent)return;const l=c.data;if(!(!l||l.type!==O)){if(l.action==="welcome"){n?u():h();return}l.action==="request"&&(n?i(!0):f(0))}}function v(){return!S(e)||!L(e)?!1:(e.addEventListener("message",m),f(0),!0)}return{start:v,isActivated:()=>n,handleHostMessage:m,refresh(){n&&i(!1)},rescan(){n&&(t.promote(),i(!1))},resync(){n&&i(!0)}}}var $,$e=_({"src/shared/external-media/child/child-runtime.ts"(){w(),T(),$=[250,750,1500,3e3]}});function ae(e,t){return e?/^[0-9]+$/.test(e)?`${e}px`:e:t}function Ne(e,t,r){var n,o,a,i;const u=oe(r),h=(n=e.ownerDocument)!=null?n:e,f=[];for(const m of Array.from(e.querySelectorAll("iframe[src]"))){if(m.getAttribute(A))continue;const v=m.getAttribute("src");if(!v||!ie(v,u))continue;const c=(a=(o=m.getBoundingClientRect)==null?void 0:o.call(m))!=null?a:{width:0,height:0},l=h.createElement("div");t.n+=1,l.setAttribute(A,`exe-embed-${t.n}`);let s=v;try{s=new URL(v,u).href}catch(y){s=v}l.setAttribute(N,s);const p=Ie(s);p&&(l.setAttribute(k,p.provider),l.setAttribute(U,p.resourceId)),l.className=m.className;const d=l.style;d.display="block",d.maxWidth="100%",d.width=ae(m.getAttribute("width"),`${c.width||0}px`),d.height=ae(m.getAttribute("height"),`${c.height||0}px`),d.background="#000",(i=m.parentNode)==null||i.replaceChild(l,m),f.push(l)}return f}function ke(e){return Array.from(e.querySelectorAll(`[${A}]`)).map(t=>{var r,n;const o=t.getBoundingClientRect(),a={id:(r=t.getAttribute(A))!=null?r:"",url:(n=t.getAttribute(N))!=null?n:"",x:o.left,y:o.top,w:o.width,h:o.height},i=t.getAttribute(k),u=t.getAttribute(U);return i&&u&&(a.provider=i,a.objectId=u),a})}var A,N,k,U,Ue=_({"src/shared/external-media/child/embed-scanner.ts"(){te(),T(),A="data-exe-embed-id",N="data-exe-embed-url",k="data-exe-embed-provider",U="data-exe-embed-object-id"}});function se(e){const t={n:0},r=()=>{var o;return(o=e.document.body)!=null?o:e.document};let n=!1;return{promote:()=>{if(!n){n=!0;try{Ne(r(),t,e)}finally{n=!1}}},collect:()=>ke(r())}}function q(e){const t=se(e),r=Te(e,t,{onActivate:n});function n(){if(e.MutationObserver&&e.document.documentElement&&new e.MutationObserver(()=>r.rescan()).observe(e.document.documentElement,{childList:!0,subtree:!0,attributes:!0}),e.addEventListener("scroll",()=>r.refresh(),!0),e.addEventListener("resize",()=>r.refresh()),e.addEventListener("transitionend",()=>r.refresh(),!0),e.addEventListener("animationend",()=>r.refresh(),!0),e.ResizeObserver){const o=new e.ResizeObserver(()=>r.refresh());e.document.documentElement&&o.observe(e.document.documentElement),e.document.body&&o.observe(e.document.body)}e.addEventListener("load",()=>r.resync())}return{started:r.start(),runtime:r}}function qe(e,t){e.readyState==="loading"?e.addEventListener("DOMContentLoaded",t):t()}function Be(e,t={}){const r=ve(t),n=Ce({win:e,createHelloId:()=>{var i,u;const h=e.crypto;return(u=(i=h==null?void 0:h.randomUUID)==null?void 0:i.call(h))!=null?u:`h-${Math.random().toString(36).slice(2)}`}});e.exeExternalMediaChild={start:()=>q(e),createDomScanner:se,media:n};const o={openMedia:i=>n.openMedia(i),ensureSession:()=>n.session(),inIframe:()=>S(e),isSandboxedOpaque:()=>L(e)};e.exeMediaBridge=j(o,"exeMediaBridge","window.exeExternalMediaChild.media.openMedia()",r);const a={createRuntime:(i=e)=>q(i).runtime,isOpaqueOrigin:L,isFramed:S,isPromotable:ie,contentBase:oe};e.exeEmbedShim=j(a,"exeEmbedShim","window.exeExternalMediaChild.start()",r)}var ze=_({"src/shared/external-media/child-entry.ts"(){he(),De(),$e(),Ue(),T()}}),Ye=pe({"src/shared/external-media/child-bundle.ts"(){ze(),typeof window!="undefined"&&(Be(window),qe(window.document,()=>q(window)))}});Ye()})();
diff --git a/src/embed/exe_external_media/exe-external-media-host.min.js b/src/embed/exe_external_media/exe-external-media-host.min.js
new file mode 100644
index 0000000..cd1d07d
--- /dev/null
+++ b/src/embed/exe_external_media/exe-external-media-host.min.js
@@ -0,0 +1,13 @@
+/*!
+ * eXeLearning external-media host bundle — https://github.com/exelearning/exelearning
+ *
+ * Copyright (C) 2026 eXeLearning Team
+ *
+ * Dual-licensed so these bytes can ship inside eXeLearning (AGPL-3.0-or-later)
+ * and inside the GPL-3.0-or-later host plugins without either project
+ * relicensing them. Combining is already permitted by GPLv3 s13 and AGPLv3 s13;
+ * combining never relicenses, so this grant is what makes vendoring lawful.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later OR GPL-3.0-or-later
+ */
+(()=>{var Ae=Object.defineProperty,G=Object.getOwnPropertyNames,R=Object.getOwnPropertySymbols,J=Object.prototype.hasOwnProperty,K=Object.prototype.propertyIsEnumerable,Q=(e,t,o)=>t in e?Ae(e,t,{enumerable:!0,configurable:!0,writable:!0,value:o}):e[t]=o,C=(e,t)=>{for(var o in t||(t={}))J.call(t,o)&&Q(e,o,t[o]);if(R)for(var o of R(t))K.call(t,o)&&Q(e,o,t[o]);return e},Le=(e,t)=>{var o={};for(var n in e)J.call(e,n)&&t.indexOf(n)<0&&(o[n]=e[n]);if(e!=null&&R)for(var n of R(e))t.indexOf(n)<0&&K.call(e,n)&&(o[n]=e[n]);return o},E=(e,t)=>function(){return e&&(t=(0,e[G(e)[0]])(e=0)),t},Re=(e,t)=>function(){return t||(0,e[G(e)[0]])((t={exports:{}}).exports,t),t.exports};function Te({warn:e}={}){const t=new Set,o=[],n=e!=null?e:(a=>console.warn(a));return{notice(a,u){t.has(a)||(t.add(a),o.push(a),n(`[exe] window.${a} is deprecated and will be removed in a future major. Use ${u}. It still works for now; nothing needs changing today.`))},announced(){return[...o]}}}function ee(e,t,o,n){return typeof Proxy=="undefined"?e:new Proxy(e,{get(a,u,c){return n.notice(t,o),Reflect.get(a,u,c)}})}var $e=E({"src/shared/external-media/compatibility/legacy-globals.ts"(){}});function Se(e){return typeof e=="string"&&te.includes(e)}function De(e){return typeof e=="string"&&re.includes(e)}var O,k,A,te,re,T=E({"src/shared/external-media/protocol/messages.ts"(){O=1,k="exe-embed",A="exe-media",te=["hello","sync"],re=["open","play","pause","seek","getCurrentTime","getDuration","hide","show","close"]}});function Ne({doc:e,translate:t,onClose:o}){var n,a,u;let c=!1,s=!1;const r=e.createElement("dialog");r.className="exe-media-modal",r.setAttribute("aria-label",t("Video player"));try{r.setAttribute("closedby","any")}catch(v){}const l=e.createElement("button");l.setAttribute("type","button"),l.className="exe-media-modal__close",l.setAttribute("aria-label",t("Close video")),l.textContent=t("Close");const i=e.createElement("div");i.className="exe-media-modal__body",r.appendChild(l),r.appendChild(i);function f(){var v,g;c||(c=!0,(v=r.close)==null||v.call(r),(g=r.remove)==null||g.call(r),o())}return l.addEventListener("click",f),r.addEventListener("click",v=>{(v==null?void 0:v.target)===r&&f()}),r.addEventListener("close",()=>{if(s){s=!1;return}f()}),(a=(n=e.body)!=null?n:e.documentElement)==null||a.appendChild(r),(u=r.showModal)==null||u.call(r),{body:()=>i,show:()=>{var v;return(v=r.showModal)==null?void 0:v.call(r)},hide(){var v;c||(s=!0,(v=r.close)==null||v.call(r),s=!1)},close:f,isClosed:()=>c}}var Ue=E({"src/shared/external-media/media/modal.ts"(){}});function Fe(e){const{container:t,doc:o,win:n,dialect:a,videoId:u,origin:c,start:s,autoplay:r,on:l}=e;if(!a)return null;const i=o.createElement("iframe"),f={currentTime:0,duration:0};let v=!1;function g(d){var y;if(!(v||!d))try{(y=i.contentWindow)==null||y.postMessage(JSON.stringify(d),a.targetOrigin)}catch(h){}}function P(d){var y,h,_;d===$.playing?(y=l.play)==null||y.call(l):d===$.paused?(h=l.pause)==null||h.call(l):d===$.ended&&((_=l.ended)==null||_.call(l))}function p(d,y){var h;typeof d=="number"&&(f.currentTime=d),typeof y=="number"&&(f.duration=y),(h=l.time)==null||h.call(l,f.currentTime,f.duration)}function m(d){var y,h,_,b,w;if(v)return;const x=d;if((x==null?void 0:x.source)!==i.contentWindow)return;const I=a.decodeEvent(x.data);if(I)switch(I.kind){case"ready":for(const wt of a.subscribeCommands())g(wt);(y=l.ready)==null||y.call(l,f.duration||void 0);break;case"play":(h=l.play)==null||h.call(l);break;case"pause":(_=l.pause)==null||_.call(l);break;case"ended":(b=l.ended)==null||b.call(l);break;case"error":(w=l.error)==null||w.call(l,I.code);break;case"info":p(I.currentTime,I.duration),P(I.playerState);break;case"timeupdate":p(I.currentTime,I.duration);break;case"state":P(I.playerState);break}}return i.setAttribute("allow","autoplay; encrypted-media; fullscreen; picture-in-picture"),i.setAttribute("allowfullscreen",""),i.setAttribute("referrerpolicy","strict-origin-when-cross-origin"),Object.assign(i.style,{border:"0",width:"100%",height:"100%"}),i.setAttribute("src",a.buildPlayerUrl(u,{origin:c,start:s,autoplay:r})),n.addEventListener("message",m),i.addEventListener("load",()=>{for(const d of a.subscribeCommands())g(d)}),t.appendChild(i),{play:()=>g(a.encodeCommand("play")),pause:()=>g(a.encodeCommand("pause")),seek:d=>g(a.encodeCommand("seek",d)),currentTime:()=>f.currentTime,duration:()=>f.duration,destroy(){var d;v||(v=!0,n.removeEventListener("message",m),(d=i.parentNode)==null||d.removeChild(i))}}}var $,je=E({"src/shared/external-media/media/player-adapter.ts"(){$={ended:0,playing:1,paused:2}}});function M(e){return typeof e=="number"&&Number.isFinite(e)?e:void 0}function ne(e){const t=Number(e);return Number.isFinite(t)&&t>0?t:0}function oe(e){if(typeof e=="string")try{const t=JSON.parse(e);return typeof t=="object"&&t!==null?t:null}catch(t){return null}return typeof e=="object"&&e!==null?e:null}function He(e){var t;return(t=se[e])!=null?t:null}var W,ae,Y,le,ie,se,We=E({"src/shared/external-media/media/provider-dialects.ts"(){W="https://www.youtube-nocookie.com",ae={id:"youtube",targetOrigin:W,buildPlayerUrl(e,{origin:t,start:o,autoplay:n}){const a=new URL(`${W}/embed/${encodeURIComponent(e)}`);return a.searchParams.set("enablejsapi","1"),a.searchParams.set("rel","0"),a.searchParams.set("modestbranding","1"),t&&a.searchParams.set("origin",t),o&&a.searchParams.set("start",String(Math.floor(o))),n&&a.searchParams.set("autoplay","1"),a.href},encodeCommand(e,t){switch(e){case"play":return{event:"command",func:"playVideo",args:[]};case"pause":return{event:"command",func:"pauseVideo",args:[]};case"seek":return{event:"command",func:"seekTo",args:[ne(t),!0]};default:return null}},subscribeCommands:()=>[{event:"listening"}],decodeEvent(e){var t;const o=oe(e);if(!o||typeof o.event!="string")return null;if(o.event==="onReady")return{kind:"ready"};if(o.event==="onError")return{kind:"error",code:String((t=o.info)!=null?t:"")};if(o.event==="infoDelivery"&&typeof o.info=="object"&&o.info!==null){const n=o.info;return{kind:"info",currentTime:M(n.currentTime),duration:M(n.duration),playerState:M(n.playerState)}}if(o.event==="onStateChange"){const n=typeof o.info=="object"&&o.info!==null?o.info.playerState:o.info;return{kind:"state",playerState:M(n)}}return null}},Y="https://player.vimeo.com",le=["playProgress","timeupdate","play","pause","ended","error"],ie={id:"vimeo",targetOrigin:Y,buildPlayerUrl(e,{autoplay:t}){const o=new URL(`${Y}/video/${encodeURIComponent(e)}`);return o.searchParams.set("api","1"),o.searchParams.set("player_id",`exe-vimeo-${e}`),t&&o.searchParams.set("autoplay","1"),o.href},encodeCommand(e,t){switch(e){case"play":return{method:"play"};case"pause":return{method:"pause"};case"seek":return{method:"setCurrentTime",value:ne(t)};default:return null}},subscribeCommands:()=>le.map(e=>({method:"addEventListener",value:e})),decodeEvent(e){const t=oe(e);if(!t||typeof t.event!="string")return null;switch(t.event){case"ready":return{kind:"ready"};case"play":return{kind:"play"};case"pause":return{kind:"pause"};case"ended":case"finish":return{kind:"ended"};case"error":return{kind:"error",code:"vimeo_error"};case"playProgress":case"timeupdate":{if(typeof t.data!="object"||t.data===null)return null;const o=t.data;return{kind:"timeupdate",currentTime:M(o.seconds),duration:M(o.duration)}}default:return null}}},se={youtube:ae,vimeo:ie}}});function Ye(e,t){const o=e.toLowerCase().replace(/\.$/,"");return o===t||o.endsWith(`.${t}`)}var B,V,q,ue=E({"src/shared/external-media/providers/types.ts"(){B="allow-scripts allow-same-origin allow-popups allow-forms allow-presentation",V="autoplay; encrypted-media; fullscreen; picture-in-picture; clipboard-write",q="strict-origin-when-cross-origin"}});function z(e){var t;return(t=ve.get(e))!=null?t:null}function Be(e,t){var o,n;return(n=(o=z(e))==null?void 0:o.buildCanonicalEmbedUrl(t))!=null?n:null}var L,S,de,D,ce,N,fe,U,me,pe,ve,X=E({"src/shared/external-media/providers/registry.ts"(){ue(),L={passive:{supported:!0,sandbox:B,allow:V,referrerPolicy:q},controlled:{supported:!1},facade:{posterStrategy:"none"}},S=/^[A-Za-z0-9_-]{11}$/,de=C({id:"youtube",hosts:["youtube.com","youtu.be","youtube-nocookie.com"],resourceIdPattern:S,kind:"video",parse(e){var t,o,n,a;const u=e.hostname.toLowerCase().replace(/\.$/,"");let c="";return Ye(u,"youtu.be")?c=(t=e.pathname.split("/").filter(Boolean)[0])!=null?t:"":c=(a=(n=e.searchParams.get("v"))!=null?n:(o=e.pathname.match(/^\/(?:embed|v|shorts)\/([^/?#]+)/))==null?void 0:o[1])!=null?a:"",S.test(c)?{provider:"youtube",resourceId:c,kind:"video"}:null},buildCanonicalEmbedUrl(e){return S.test(e)?`https://www.youtube-nocookie.com/embed/${e}`:null}},L),D=/^[0-9]{6,12}$/,ce=C({id:"vimeo",hosts:["vimeo.com"],resourceIdPattern:D,kind:"video",parse(e){var t,o,n;const a=(n=(o=(t=e.pathname.match(/^\/video\/([0-9]+)/))==null?void 0:t[1])!=null?o:e.pathname.split("/").filter(Boolean)[0])!=null?n:"";return D.test(a)?{provider:"vimeo",resourceId:a,kind:"video"}:null},buildCanonicalEmbedUrl(e){return D.test(e)?`https://player.vimeo.com/video/${e}`:null}},L),N=/^[A-Za-z0-9]{5,}$/,fe=C({id:"dailymotion",hosts:["dailymotion.com","dai.ly"],resourceIdPattern:N,kind:"video",parse(e){var t,o,n,a;const u=(a=(n=(t=e.pathname.match(/^\/embed\/video\/([A-Za-z0-9]+)/))==null?void 0:t[1])!=null?n:(o=e.pathname.match(/^\/video\/([A-Za-z0-9]+)/))==null?void 0:o[1])!=null?a:"";return N.test(u)?{provider:"dailymotion",resourceId:u,kind:"video"}:null},buildCanonicalEmbedUrl(e){return N.test(e)?`https://www.dailymotion.com/embed/video/${e}`:null}},L),U=/^[A-Za-z0-9]{8,}$/,me=C({id:"mediateca-madrid",hosts:["mediateca.educa.madrid.org"],resourceIdPattern:U,kind:"video",parse(e){var t,o;const n=(o=(t=e.pathname.match(/^\/video\/([A-Za-z0-9]+)(?:\/fs)?\/?$/))==null?void 0:t[1])!=null?o:"";return U.test(n)?{provider:"mediateca-madrid",resourceId:n,kind:"video"}:null},buildCanonicalEmbedUrl(e){return U.test(e)?`https://mediateca.educa.madrid.org/video/${e}/fs`:null}},L),pe=[de,ce,fe,me],ve=new Map(pe.map(e=>[e.id,e]))}});function ye(e){return typeof e=="object"&&e!==null}function Z(e,t,o){return typeof e=="number"&&Number.isFinite(e)&&e>=t&&e<=o}function he(e){return Z(e,0,Ee)}function _e(e){return Z(e,-F,F)}function ge(e){return Z(e,0,F)}function be(e,t){return ye(e)&&e.type===t}function Ve(e){return!(!ye(e)||typeof e.id!="string"||e.id.length===0||e.id.length>128||!_e(e.x)||!_e(e.y)||!ge(e.w)||!ge(e.h)||e.provider!==void 0&&typeof e.provider!="string"||e.objectId!==void 0&&typeof e.objectId!="string"||e.url!==void 0&&typeof e.url!="string")}function qe(e){return!be(e,k)||!Se(e.action)?!1:e.action==="sync"?!Array.isArray(e.embeds)||e.embeds.length>we?!1:e.embeds.every(Ve):!0}function ze(e){if(!be(e,A)||e.v!==O||!De(e.action))return!1;switch(e.action){case"open":{if(!Number.isInteger(e.reqId)||!(e.start===void 0||e.start===null||he(e.start))||typeof e.provider!="string"||typeof e.videoId!="string")return!1;const t=z(e.provider);return!!t&&t.resourceIdPattern.test(e.videoId)}case"seek":return he(e.t);case"getCurrentTime":case"getDuration":return Number.isInteger(e.reqId);default:return!0}}var Ee,we,F,xe=E({"src/shared/external-media/protocol/schemas.ts"(){X(),T(),Ee=1e6,we=64,F=1e5}});function Xe(e){if(typeof e!="object"||e===null)return!1;const t=e;return t.type===A&&t.v===O&&t.action==="hello"&&typeof t.helloId=="string"&&t.helloId.length>0}function Ze(e){const{contentWindow:t,createChannel:o,onCommand:n,onTeardown:a}=e;let u=null;function c(){var r,l;if(!u)return;const i=u;u=null,i.port.onmessage=null,a==null||a(i),(l=(r=i.port).close)==null||l.call(r)}function s(r){var l,i;const f=o(),v={helloId:r,port:f.port1};u=v,f.port1.onmessage=g=>{u===v&&ze(g==null?void 0:g.data)&&n(v,g.data)},(i=(l=f.port1).start)==null||i.call(l),t.postMessage({type:A,v:O,action:"welcome",helloId:r},"*",[f.port2])}return{handleWindowMessage(r){!r||r.source!==t||Xe(r.data)&&(u==null?void 0:u.helloId)!==r.data.helloId&&(c(),s(r.data.helloId))},current:()=>u,teardown:c}}var Ge=E({"src/shared/external-media/media/session.ts"(){T(),xe()}});function Je(e){const{contentWindow:t,doc:o,win:n,origin:a,translate:u,createChannel:c}=e;let s=null,r=null,l=!1;const i=Ze({contentWindow:t,createChannel:c,onCommand:P,onTeardown:()=>v()});function f(m,d){m.port.postMessage(C({type:A,v:O},d))}function v(){r==null||r.destroy(),r=null,s==null||s.close(),s=null}function g(m,d){const y=He(d.provider);if(!y){f(m,{action:"error",code:"unsupported_provider",fatal:!0});return}v();const h=Ne({doc:o,translate:u,onClose:()=>{r==null||r.destroy(),r=null,s=null,f(m,{action:"closed"})}});s=h,r=Fe({container:h.body(),doc:o,win:n,dialect:y,videoId:d.videoId,origin:a,start:d.start,autoplay:d.autoplay,on:{ready:_=>f(m,{action:"ready",duration:_}),play:()=>f(m,{action:"play"}),pause:()=>f(m,{action:"pause"}),ended:()=>f(m,{action:"ended"}),error:_=>f(m,{action:"error",code:_,fatal:!1}),time:(_,b)=>{typeof _!="number"||typeof b!="number"||b<=0||f(m,{action:"timeupdate",currentTime:_,duration:b})}}})}function P(m,d){var y,h;if(l)return;const _=d;switch(_.action){case"open":g(m,_);return;case"play":r==null||r.play();return;case"pause":r==null||r.pause();return;case"seek":r==null||r.seek(_.t);return;case"hide":s==null||s.hide();return;case"show":s==null||s.show();return;case"close":r==null||r.destroy(),r=null,s==null||s.close(),s=null;return;case"getCurrentTime":f(m,{action:"state",reqId:_.reqId,currentTime:(y=r==null?void 0:r.currentTime())!=null?y:0});return;case"getDuration":f(m,{action:"state",reqId:_.reqId,duration:(h=r==null?void 0:r.duration())!=null?h:0});return;default:return}}function p(m){l||i.handleWindowMessage(m)}return n.addEventListener("message",p),{detach(){l||(l=!0,n.removeEventListener("message",p),v(),i.teardown())}}}var Ke=E({"src/shared/external-media/media/media-host.ts"(){T(),Ue(),je(),We(),Ge()}});function Qe({doc:e,win:t,frameFor:o}){const n=new Map,a=new Map,u=(s,r)=>`${s}::${r}`;function c(s){var r;const l=n.get(s);if(l)return l;const i=e.createElement("div");return i.setAttribute("class",Pe),Object.assign(i.style,{position:"absolute",overflow:"hidden",pointerEvents:"none",zIndex:"2147483646"}),(r=e.body)==null||r.appendChild(i),n.set(s,i),i}return{measureFrame(s){const r=o(s);return r?r.getBoundingClientRect():null},isFrameObscured(s){var r,l,i;const f=o(s);if(!f)return!0;const v=f.getBoundingClientRect();if(v.width<=0||v.height<=0)return!0;const g=(r=t.innerWidth)!=null?r:0,P=(l=t.innerHeight)!=null?l:0,p=Math.max(v.left,0),m=Math.max(v.top,0),d=Math.min(v.left+v.width,g),y=Math.min(v.top+v.height,P);if(d<=p||y<=m)return!1;const h=(i=e.elementFromPoint)==null?void 0:i.call(e,(p+d)/2,(m+y)/2);if(!h||h===f)return!1;for(const _ of a.values())if(h===_)return!1;return!0},setOverlayHidden(s,r){c(s).style.display=r?"none":""},scrollOffset(){var s,r,l,i,f,v;return{x:(l=(r=t.pageXOffset)!=null?r:(s=e.documentElement)==null?void 0:s.scrollLeft)!=null?l:0,y:(v=(f=t.pageYOffset)!=null?f:(i=e.documentElement)==null?void 0:i.scrollTop)!=null?v:0}},positionOverlay(s,r){const l=c(s);l.style.left=`${r.left}px`,l.style.top=`${r.top}px`,l.style.width=`${r.width}px`,l.style.height=`${r.height}px`},mountPlayer(s,r,l){const i=e.createElement("iframe");i.setAttribute(j,"1"),l.sandbox!==void 0&&i.setAttribute("sandbox",l.sandbox),i.setAttribute("allow",l.allow),i.setAttribute("referrerpolicy",l.referrerPolicy),l.allowFullscreen&&i.setAttribute("allowfullscreen",""),Object.assign(i.style,{position:"absolute",border:"0",pointerEvents:"auto"}),i.setAttribute("src",l.src),c(s).appendChild(i),a.set(u(s,r),i)},positionPlayer(s,r,l){const i=a.get(u(s,r));i&&(i.style.left=`${l.left}px`,i.style.top=`${l.top}px`,i.style.width=`${l.width}px`,i.style.height=`${l.height}px`)},unmountPlayer(s,r){var l;const i=u(s,r),f=a.get(i);f&&((l=f.parentNode)==null||l.removeChild(f),a.delete(i))},postToFrame(s,r){var l,i;(i=(l=o(s))==null?void 0:l.contentWindow)==null||i.postMessage(r,"*")}}}var j,Pe,et=E({"src/shared/external-media/host/dom-overlay-adapter.ts"(){j="data-exe-embed-player",Pe="exe-embed-overlay"}});function tt(){const e=new Map;let t=0;function o(n,a,u){return{handle:n,source:a,contentSrc:u,welcomed:!1,lastRect:null,players:[]}}return{register(n,a){for(const[c,s]of e)if(s.source===n)return e.set(c,o(c,n,a)),c;const u=`frame-${++t}`;return e.set(u,o(u,n,a)),u},unregister(n){e.delete(n)},resolve(n){if(n==null)return null;for(const a of e.values())if(a.source===n)return a;return null},get(n){var a;return(a=e.get(n))!=null?a:null},welcome(n){const a=e.get(n);a&&(a.welcomed=!0)},invalidate(n,a){const u=e.get(n);u&&e.set(n,o(n,u.source,a!=null?a:u.contentSrc))},setLastRect(n,a){const u=e.get(n);u&&(u.lastRect=a)},setPlayers(n,a){const u=e.get(n);u&&(u.players=a)},all(){return[...e.values()]}}}var rt=E({"src/shared/external-media/host/frame-registry.ts"(){}});function Ie(e,t){return{left:e.left+t.x,top:e.top+t.y,width:e.width,height:e.height}}function nt(e,t){return e?e.left!==t.left||e.top!==t.top||e.width!==t.width||e.height!==t.height:!0}function ot(e,t){return{left:e.x,top:e.y,width:Math.min(e.w,t.width),height:Math.min(e.h,t.height)}}function at(e,t){const o=new Map(e.map(s=>[s.id,s])),n=[],a=[],u=[],c=new Set;for(const s of t){c.add(s.embed.id);const r=o.get(s.embed.id);if(!r){n.push(s);continue}if(r.src!==s.url){u.push(r.id),n.push(s);continue}a.push(s)}for(const s of e)c.has(s.id)||u.push(s.id);return{toCreate:n,toReposition:a,toRemove:u}}var lt=E({"src/shared/external-media/host/overlay-geometry.ts"(){}});function it(e){return e.kind==="video"?{src:e.url,sandbox:B,allow:V,referrerPolicy:q,allowFullscreen:!0}:e.sameOrigin?{src:e.url,allow:"fullscreen",referrerPolicy:"no-referrer",allowFullscreen:!1}:{src:e.url,sandbox:"allow-same-origin",allow:"fullscreen",referrerPolicy:"no-referrer",allowFullscreen:!1}}var st=E({"src/shared/external-media/host/player-descriptor.ts"(){ue()}});function H(e){return(e||"").toLowerCase().replace(/\.$/,"")}function ut(e){return!!(!e||e==="localhost"||/\.localhost$/.test(e)||/\.local$/.test(e)||e.startsWith("[")||e.includes(":")||/^\d{1,3}(\.\d{1,3}){3}$/.test(e))}function dt(e,t){const o=H(e),n=H(t);return n?o===n||o.endsWith(`.${n}`)||n.endsWith(`.${o}`):!1}function Ce(e,t){if(e.protocol!=="https:"||e.username||e.password||e.origin===t.origin)return!1;const o=H(e.hostname);return!(ut(o)||dt(o,t.hostname))}function ct(e){try{return new URL(e).href.replace(/[^/]*([?#].*)?$/,"")}catch(t){return""}}function ft(e){var t,o;return(o=(t=String(e).match(/[a-f0-9]{12,}/i))==null?void 0:t[0])!=null?o:null}function mt(e,t){const o=ct(t);if(o&&e.href.startsWith(o))return!0;const n=ft(t);return!!(n&&e.pathname.includes(`/${n}/`))}function pt(e,t,o,n={}){let a;try{a=new URL(e)}catch(u){return null}if(a.username||a.password)return null;if(/\.pdf$/i.test(a.pathname))return a.origin===o.origin?mt(a,t)?{url:a.href,kind:"pdf",sameOrigin:!0}:null:Ce(a,o)?{url:a.href,kind:"pdf"}:null;if(n.strict){const u=H(a.hostname);if(n.allowlist&&!n.allowlist.includes(u)||a.protocol!=="https:")return null;for(const c of["youtube","vimeo","dailymotion","mediateca-madrid"]){const s=z(c);if(!(s!=null&&s.hosts.some(i=>u===i||u.endsWith(`.${i}`))))continue;const r=s.parse(a);if(!r)return null;const l=s.buildCanonicalEmbedUrl(r.resourceId);return l?{url:l,kind:"video"}:null}return null}return Ce(a,o)?{url:a.href,kind:"video"}:null}var vt=E({"src/shared/external-media/host/url-policy.ts"(){X()}});function yt(e){var t;return e.provider&&e.objectId?Be(e.provider,e.objectId):(t=e.url)!=null?t:null}function ht(e){var t=e,{location:o,registry:n,adapter:a}=t,u=Le(t,["location","registry","adapter"]);function c(r){var l,i,f;(f=a.setOverlayHidden)==null||f.call(a,r,(i=(l=a.isFrameObscured)==null?void 0:l.call(a,r))!=null?i:!1)}function s(r,l,i){var f;const v=a.measureFrame(r);if(!v)return;c(r),a.positionOverlay(r,Ie(v,a.scrollOffset())),n.setLastRect(r,v);const g=[],P=new Map;for(const d of l){const y=yt(d);if(!y)continue;const h=pt(y,i,o,u);h&&(g.push({embed:d,url:h.url}),P.set(d.id,h))}const p=n.get(r),m=at((f=p==null?void 0:p.players)!=null?f:[],g);for(const d of m.toRemove)a.unmountPlayer(r,d);for(const d of m.toCreate){const y=P.get(d.embed.id);y&&a.mountPlayer(r,d.embed.id,it(y))}for(const d of[...m.toCreate,...m.toReposition])a.positionPlayer(r,d.embed.id,ot(d.embed,v));n.setPlayers(r,g.map(d=>({id:d.embed.id,src:d.url})))}return{attach(r,l){return n.register(r,l)},detach(r){var l;const i=n.get(r);for(const f of(l=i==null?void 0:i.players)!=null?l:[])a.unmountPlayer(r,f.id);n.unregister(r)},handleMessage(r){const l=n.resolve(r==null?void 0:r.source);if(!l)return;const i=r.data;if(!(!i||i.type!==k)){if(i.action==="hello"){n.welcome(l.handle),a.postToFrame(l.handle,{type:k,action:"welcome"});return}if(i.action==="sync"){if(!l.welcomed||!qe(i))return;s(l.handle,i.embeds,l.contentSrc)}}},requestSync(r){const l=r===void 0?n.all():[n.get(r)];for(const i of l)i&&a.postToFrame(i.handle,{type:k,action:"request"})},checkDrift(){let r=0;for(const l of n.all()){const i=a.measureFrame(l.handle);i&&(c(l.handle),nt(l.lastRect,i)&&(a.positionOverlay(l.handle,Ie(i,a.scrollOffset())),n.setLastRect(l.handle,i),r+=1))}return r},notifyNavigated(r,l){var i;const f=n.get(r);for(const v of(i=f==null?void 0:f.players)!=null?i:[])a.unmountPlayer(r,v.id);n.invalidate(r,l)}}}var _t=E({"src/shared/external-media/host/host-runtime.ts"(){T(),xe(),lt(),st(),vt(),X()}});function Me(e,t={}){const o=tt(),n=new Map,a=new Map,u=Qe({doc:e.document,win:e,frameFor:p=>{var m;return(m=n.get(p))!=null?m:null}});let c=null,s=null,r=!1;function l(p){var m,d,y,h;if(!p||o.resolve(p))return;const _=(y=(d=(m=e.document).getElementsByTagName)==null?void 0:d.call(m,"iframe"))!=null?y:[];for(let b=0;b<_.length;b+=1){const w=_[b];if(w.contentWindow===p){if((h=w.getAttribute)!=null&&h.call(w,j))return;g(w);return}}}function i(p){const m=p!=null?p:{};c&&l(m.source),c==null||c.handleMessage(m)}function f(){if(r)return;r=!0;const p=()=>{r=!1,c==null||c.checkDrift()};e.requestAnimationFrame?e.requestAnimationFrame(p):p()}function v(){var p,m,d,y,h,_,b,w,x,I;return c||(c=ht(C(C({location:{origin:(m=(p=e.location)==null?void 0:p.origin)!=null?m:"",hostname:(y=(d=e.location)==null?void 0:d.hostname)!=null?y:""},registry:o,adapter:u},t),t.location?{location:t.location}:{})),(h=e.addEventListener)==null||h.call(e,"message",i),(_=e.addEventListener)==null||_.call(e,"scroll",f,!0),(b=e.addEventListener)==null||b.call(e,"resize",f),(w=e.addEventListener)==null||w.call(e,"transitionend",f,!0),(x=e.addEventListener)==null||x.call(e,"animationend",f,!0),s=(I=e.setInterval)==null?void 0:I.call(e,()=>c==null?void 0:c.checkDrift(),ke),c)}function g(p){var m,d;const y=v(),h=y.attach(p.contentWindow,(m=p.src)!=null?m:"");n.set(h,p);const _=()=>{var b,w;const x=(b=p.src)!=null?b:"";((w=o.get(h))==null?void 0:w.contentSrc)!==x&&y.notifyNavigated(h,x)};return(d=p.addEventListener)==null||d.call(p,"load",_),a.set(h,_),h}function P(p){var m;const d=n.get(p),y=a.get(p);d&&y&&((m=d.removeEventListener)==null||m.call(d,"load",y)),c==null||c.detach(p),n.delete(p),a.delete(p)}return{attach(p){const m=g(p);return{detach:()=>P(m)}},scan(){var p,m,d,y;const h=(d=(m=(p=e.document).getElementsByTagName)==null?void 0:m.call(p,"iframe"))!=null?d:[],_=new Set(n.values());let b=0;for(let w=0;w<h.length;w+=1){const x=h[w];(y=x.getAttribute)!=null&&y.call(x,j)||_.has(x)||(g(x),b+=1)}return v().requestSync(),b},reflow(){c==null||c.checkDrift()},clear(){for(const p of o.all()){for(const m of p.players)u.unmountPlayer(p.handle,m.id);o.setPlayers(p.handle,[])}},dispose(){var p,m,d,y,h,_;for(const b of[...n.keys()])P(b);(p=e.removeEventListener)==null||p.call(e,"message",i),(m=e.removeEventListener)==null||m.call(e,"scroll",f,!0),(d=e.removeEventListener)==null||d.call(e,"resize",f),(y=e.removeEventListener)==null||y.call(e,"transitionend",f,!0),(h=e.removeEventListener)==null||h.call(e,"animationend",f,!0),s!==null&&((_=e.clearInterval)==null||_.call(e,s)),s=null,c=null}}}function Oe(e,t){var o,n;const a=e;return Je({contentWindow:t.contentWindow,doc:e.document,win:e,origin:(n=(o=e.location)==null?void 0:o.origin)!=null?n:"",translate:u=>{var c,s;return(s=(c=a._)==null?void 0:c.call(a,u))!=null?s:u},createChannel:()=>new a.MessageChannel})}function gt(e,t={}){const o=Te(t);e.exeExternalMediaHost={create:(u={})=>Me(e,u),attachMedia:u=>Oe(e,u)};const n={attach(u){const c=Oe(e,u);return{detach:()=>c.detach()}}};e.exeMediaHost=ee(n,"exeMediaHost","window.exeExternalMediaHost.attachMedia(iframe)",o);const a={init(u={}){const c=Me(e,{strict:u.mode==="strict",allowlist:u.whitelist});return c.scan(),{clear:()=>c.clear(),reflow:()=>c.reflow(),dispose:()=>c.dispose(),init(){return c.scan(),this}}}};e.exeEmbedRelay=ee(a,"exeEmbedRelay","window.exeExternalMediaHost.create()",o)}var ke,bt=E({"src/shared/external-media/host-entry.ts"(){$e(),Ke(),et(),rt(),_t(),ke=300}}),Et=Re({"src/shared/external-media/host-bundle.ts"(){bt(),typeof window!="undefined"&&gt(window)}});Et()})();
diff --git a/src/embed/exe_external_media/exe-external-media.manifest.json b/src/embed/exe_external_media/exe-external-media.manifest.json
new file mode 100644
index 0000000..aee6b5f
--- /dev/null
+++ b/src/embed/exe_external_media/exe-external-media.manifest.json
@@ -0,0 +1,18 @@
+{
+    "libraryVersion": "1.0.0",
+    "protocolVersion": 1,
+    "buildHash": "43c776daa551fd770b6dade520629362e5a8ca8745e4245c359447c4689b34d6",
+    "sourceCommit": "3bee9769e",
+    "files": {
+        "child": {
+            "path": "exe-external-media-child.min.js",
+            "sha256": "2b5466f3bcc66e1f793f7b15b75f2912b602cc383ae6031a8fa7a8f77ceedc8e",
+            "bytes": 12973
+        },
+        "host": {
+            "path": "exe-external-media-host.min.js",
+            "sha256": "3bb1cd19df99f8a981315fdeafafe26e4ad42ad0ca92995e257ccebdf7146f49",
+            "bytes": 25539
+        }
+    }
+}
diff --git a/src/embed/exe_external_media/verify.mjs b/src/embed/exe_external_media/verify.mjs
new file mode 100644
index 0000000..1a0f214
--- /dev/null
+++ b/src/embed/exe_external_media/verify.mjs
@@ -0,0 +1,129 @@
+/**
+ * Verify a VENDORED copy of the eXeLearning external-media distribution.
+ *
+ * This is the consumer's tool, and it ships inside the distribution itself — for the same
+ * reason the licence banner does: a check that lives only in eXeLearning's repository is
+ * no check at all to whoever received the files.
+ *
+ * It answers a different question from eXeLearning's own build verifier, which is why the
+ * two are not one file. Ours asks "is this distribution well-formed?" — size budgets,
+ * contract and protocol agreement, reproducibility against a fresh build. A consumer
+ * cannot ask that; it has no build to compare against. It asks "are these the bytes
+ * eXeLearning published, unmodified since?", which is answerable from the manifest alone.
+ *
+ * Deliberately dependency-free and plain ESM: it must run under `node` in a PHP plugin's
+ * CI with no toolchain, no install step and no package.json.
+ *
+ *   node exe_external_media/verify.mjs [dir] [--build-hash <hash>]
+ *
+ * INTEGRITY vs PROVENANCE. Without `--build-hash` this proves only that nothing was edited
+ * after vendoring: a consistent forgery — file and digests changed together — is easy to
+ * produce, and the build hash inside the copy cannot detect a copy that was built with it.
+ * Pass the hash eXeLearning published for the release you meant to vendor, obtained out of
+ * band, and the check becomes one of provenance.
+ *
+ * Copyright (C) 2026 eXeLearning Team
+ *
+ * Dual-licensed so this ONE file can ship inside eXeLearning (AGPL-3.0-or-later)
+ * and inside the GPL-3.0-or-later host plugins (mod_exelearning) without either
+ * project relicensing it. GPLv3 s13 and AGPLv3 s13 already permit COMBINING the
+ * two, but combining never relicenses a file: only the copyright holder can offer
+ * it under both, which is what this grant does. Keep this notice in every mirror.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-or-later OR GPL-3.0-or-later
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const MANIFEST_FILE = 'exe-external-media.manifest.json';
+
+/** ADR-0018. Checked on the received bytes, because that is where it has to be. */
+export const EXPECTED_GRANT = 'SPDX-License-Identifier: AGPL-3.0-or-later OR GPL-3.0-or-later';
+
+const sha256 = contents => createHash('sha256').update(contents, 'utf8').digest('hex');
+
+/**
+ * @param {string} dir directory holding the vendored artifacts and their manifest
+ * @param {{expectBuildHash?: string}} [options] the build hash published for the release
+ *        you meant to vendor; supply it to check provenance, not just integrity
+ * @returns {string[]} human-readable problems; empty means the copy is good
+ */
+export function verifyVendoredArtifacts(dir, options = {}) {
+    const manifestPath = join(dir, MANIFEST_FILE);
+    if (!existsSync(manifestPath)) {
+        return [`manifest is missing: expected ${MANIFEST_FILE} in ${dir}`];
+    }
+
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    } catch (error) {
+        return [`manifest is not readable JSON: ${manifestPath} (${error.message})`];
+    }
+    if (!manifest || typeof manifest.files !== 'object' || manifest.files === null) {
+        return [`manifest has no file list: ${manifestPath}`];
+    }
+
+    const problems = [];
+
+    for (const [key, record] of Object.entries(manifest.files)) {
+        const artifactPath = join(dir, record.path);
+        if (!existsSync(artifactPath)) {
+            problems.push(`${key}: artifact is missing (${record.path})`);
+            continue;
+        }
+
+        const contents = readFileSync(artifactPath, 'utf8');
+        if (sha256(contents) !== record.sha256) {
+            problems.push(
+                `${key}: sha256 mismatch — ${record.path} was modified after it was vendored. ` +
+                    'Change eXeLearning core and re-vendor; a local edit here is invisible upstream.',
+            );
+        }
+        if (typeof record.bytes === 'number' && statSync(artifactPath).size !== record.bytes) {
+            problems.push(`${key}: size mismatch — manifest says ${record.bytes}`);
+        }
+        if (!contents.includes(EXPECTED_GRANT)) {
+            problems.push(`${key}: the dual-licence grant is missing from ${record.path}`);
+        }
+    }
+
+    // The digest list is itself covered, so editing a file and its digest together does
+    // not produce a manifest that agrees with itself.
+    const recomputed = sha256(
+        Object.keys(manifest.files)
+            .sort()
+            .map(key => `${key}:${manifest.files[key].sha256}`)
+            .join('\n'),
+    );
+    if (manifest.buildHash !== recomputed) {
+        problems.push('buildHash does not match the manifest file list — the manifest was edited by hand');
+    }
+
+    if (options.expectBuildHash && manifest.buildHash !== options.expectBuildHash) {
+        problems.push(
+            `buildHash is not the build you expected — vendored ${manifest.buildHash}, ` +
+                `expected ${options.expectBuildHash}`,
+        );
+    }
+
+    return problems;
+}
+
+/* c8 ignore start -- CLI wrapper; the behaviour above is what is tested */
+if (process.argv[1] && import.meta.url.endsWith(process.argv[1].split('/').pop())) {
+    const args = process.argv.slice(2);
+    const hashIndex = args.indexOf('--build-hash');
+    const expectBuildHash = hashIndex !== -1 ? args[hashIndex + 1] : undefined;
+    const dir = args.find(a => !a.startsWith('--') && a !== expectBuildHash) ?? process.cwd();
+
+    const problems = verifyVendoredArtifacts(dir, { expectBuildHash });
+    if (problems.length) {
+        console.error(`[exe-external-media] ${dir} did NOT verify:`);
+        for (const problem of problems) console.error(`  - ${problem}`);
+        process.exit(1);
+    }
+    console.log(`[exe-external-media] ${dir} verified.`);
+}
+/* c8 ignore stop */
diff --git a/src/embed/relay-host.ts b/src/embed/relay-host.ts
new file mode 100644
index 0000000..3850775
--- /dev/null
+++ b/src/embed/relay-host.ts
@@ -0,0 +1,111 @@
+/**
+ * Loads the eXe-core embed relay into the trusted parent (the Viewer page) and
+ * drives it.
+ *
+ * It overlays real YouTube/Vimeo/Dailymotion/PDF players over the geometry
+ * placeholders the shim reports from inside the opaque iframe.
+ * The vendored host bundle attaches `window.exeExternalMediaHost` plus the
+ * `window.exeEmbedRelay` facade this module drives.
+ * The shim itself is NOT imported here — the PHP ContentController inlines it
+ * into the served package so it runs inside the opaque iframe.
+ */
+import './exe_external_media/exe-external-media-host.min.js'
+
+interface RelayInstance {
+	clear?: () => void
+	reflow?: () => void
+}
+
+export interface EmbedRelayConfig {
+	mode?: string
+	whitelist?: string[]
+}
+
+interface EmbedRelayApi {
+	init: (config: EmbedRelayConfig) => RelayInstance
+}
+
+interface AttachedMediaHost {
+	detach: () => void
+}
+
+interface ExternalMediaHostApi {
+	attachMedia: (iframe: HTMLIFrameElement) => AttachedMediaHost
+}
+
+interface BridgeGlobals {
+	exeEmbedRelay?: EmbedRelayApi
+	exeExternalMediaHost?: ExternalMediaHostApi
+}
+
+/** The bridge globals attached to `window` by the imported mirror script. */
+function globals(): BridgeGlobals {
+	return window as unknown as BridgeGlobals
+}
+
+let relayInstance: RelayInstance | null = null
+
+/**
+ * Start the embed relay once (idempotent). Call after the first content iframe
+ * mounts. 'strict' mode overlays only whitelisted providers; 'open' overlays any
+ * cross-origin https player the shim reports.
+ * @param config Relay mode + provider whitelist (defaults to open mode).
+ */
+export function startRelay(config: EmbedRelayConfig = { mode: 'open' }): void {
+	if (relayInstance) {
+		return
+	}
+	const api = globals().exeEmbedRelay
+	if (api) {
+		relayInstance = api.init(config)
+	}
+}
+
+/** One attachment per content iframe; the media host owns the pairing, not the page. */
+const mediaHosts = new WeakMap<HTMLIFrameElement, AttachedMediaHost>()
+
+/**
+ * Attach the MEDIA half to a content iframe.
+ *
+ * Separate from `startRelay` because the two halves are adopted separately (ADR-0024):
+ * the relay promotes declarative embeds it finds by scanning, while this answers an iDevice
+ * that asks the host to open and drive a video over a private port. A viewer with only the
+ * relay looks completely healthy — embeds are promoted, nothing errors — while every bridged
+ * video in the package is dead, because nobody replies to the handshake.
+ *
+ * Memoised per iframe rather than per page: the viewer can mount more than one, and each
+ * needs its own session.
+ * @param iframe The opaque content iframe to serve videos for.
+ */
+export function startMedia(iframe: HTMLIFrameElement): void {
+	if (mediaHosts.has(iframe)) {
+		return
+	}
+	const api = globals().exeExternalMediaHost
+	if (api) {
+		mediaHosts.set(iframe, api.attachMedia(iframe))
+	}
+}
+
+/**
+ * Ask the shim inside the opaque iframe to (re)report its embed placeholders.
+ * @param iframe The opaque content iframe to ping.
+ */
+export function pingEmbeds(iframe: HTMLIFrameElement): void {
+	iframe.contentWindow?.postMessage({ type: 'exe-embed', action: 'request' }, '*')
+}
+
+/** Remove all overlay players — call when the iframe is hidden or torn down. */
+export function clearOverlays(): void {
+	relayInstance?.clear?.()
+}
+
+/** Reposition overlays against the iframe's current box — call after a resize/move. */
+export function reflowOverlays(): void {
+	relayInstance?.reflow?.()
+}
+
+/** Test-only: reset the memoised relay instance between cases. */
+export function resetRelayForTests(): void {
+	relayInstance = null
+}
diff --git a/src/types/shims.d.ts b/src/types/shims.d.ts
index c1a037e..f37a47c 100644
--- a/src/types/shims.d.ts
+++ b/src/types/shims.d.ts
@@ -3,3 +3,9 @@ declare module '*.vue' {
 	const component: DefineComponent<object, object, unknown>
 	export default component
 }
+
+// The eXe-core embed/media bridge mirrors are plain-JS, side-effect modules
+// (they attach window.exeEmbedRelay). We import them only
+// for their side effects and use the window globals via typed casts.
+declare module '*/exe-external-media-host.min.js'
+declare module '*/exe-external-media-child.min.js'
diff --git a/src/viewer/ElpxViewer.vue b/src/viewer/ElpxViewer.vue
index 49f3aba..8fab670 100644
--- a/src/viewer/ElpxViewer.vue
+++ b/src/viewer/ElpxViewer.vue
@@ -34,6 +34,7 @@
 <script lang="ts">
 import { defineComponent } from 'vue'
 import { translate as t } from '@nextcloud/l10n'
+import { loadState } from '@nextcloud/initial-state'
 import { generateUrl } from '@nextcloud/router'
 
 import ViewerError from './ViewerError.vue'
@@ -43,8 +44,24 @@ import { readPackage, ZipReadError } from '../elpx/zip-reader'
 import { validatePackage } from '../elpx/package-validator'
 import { ViewerSession } from '../elpx/viewer-session'
 import { ensureRuntimeWorker, registerSession, unregisterSession, type RuntimeWorker } from '../elpx/service-worker-client'
-import { createPackageIframe, buildSandboxedIframe } from '../elpx/iframe-renderer'
-import { ASSET_PREFIX, buildAssetUrl } from '../elpx/paths'
+import { createAssetIframe, createContentIframe, createPackageIframe } from '../elpx/iframe-renderer'
+import { ASSET_PREFIX, CONTENT_PREFIX } from '../elpx/paths'
+import { clearOverlays, type EmbedRelayConfig, pingEmbeds, reflowOverlays, startMedia, startRelay } from '../embed/relay-host'
+
+/**
+ * Reads a server-provided initial-state value, falling back on any error so the
+ * viewer still boots (e.g. in the @nextcloud/viewer modal, where the /view
+ * ViewController never ran and these keys are absent → legacy path).
+ * @param key The initial-state key registered server-side.
+ * @param fallback Value to return when the key is missing or invalid.
+ */
+function safeLoad<T>(key: string, fallback: T): T {
+	try {
+		return (loadState('exelearning', key, fallback) as T) ?? fallback
+	} catch {
+		return fallback
+	}
+}
 
 type State = 'loading' | 'ready' | 'legacy' | 'error'
 
@@ -57,6 +74,7 @@ interface Data {
 	session: ViewerSession | null
 	worker: RuntimeWorker | null
 	iframe: HTMLIFrameElement | null
+	relayActive: boolean
 }
 
 export default defineComponent({
@@ -86,6 +104,7 @@ export default defineComponent({
 			session: null,
 			worker: null,
 			iframe: null,
+			relayActive: false,
 		}
 	},
 	mounted() {
@@ -122,12 +141,29 @@ export default defineComponent({
 					throw new Error(validation.error ?? 'The package is missing index.html.')
 				}
 
-				this.status = t('exelearning', 'Preparing viewer…')
 				const indexEntry = validation.shape.indexEntry
+				const title = loaded.filename || this.filename || this.basename || 'package.elpx'
+
+				// Secure (default): serve the package into an opaque-origin iframe
+				// over the cookieless /content/{token} route. No Service Worker and
+				// no in-memory session — the server streams entries from the stored
+				// file, and external media is relayed to this trusted page.
+				const contentToken = safeLoad<string | null>('contentToken', null)
+				const secureIframe = safeLoad<boolean>('secureIframe', false)
+				if (secureIframe && contentToken && fileId !== undefined && Number.isFinite(fileId)) {
+					this.state = 'ready'
+					this.status = ''
+					this.$nextTick(() => this.attachContentIframe(contentToken, indexEntry, title))
+					return
+				}
+
+				// Legacy escape hatch (EXELEARNING_UNSAFE_LEGACY_IFRAME): same-origin
+				// Service-Worker path with a server-side asset fallback.
+				this.status = t('exelearning', 'Preparing viewer…')
 				const session = ViewerSession.create({
 					entries,
 					indexEntry,
-					filename: loaded.filename || this.filename || this.basename || 'package.elpx',
+					filename: title,
 				})
 
 				try {
@@ -176,14 +212,50 @@ export default defineComponent({
 			const slot = this.$refs.frameSlot as HTMLElement | undefined
 			if (!slot) return
 			slot.innerHTML = ''
-			const iframe = buildSandboxedIframe(
-				buildAssetUrl(generateUrl(ASSET_PREFIX), fileId, indexEntry),
-				this.basename || this.filename || 'package.elpx',
-			)
+			const iframe = createAssetIframe({
+				assetBase: generateUrl(ASSET_PREFIX),
+				fileId,
+				indexEntry,
+				title: this.basename || this.filename || 'package.elpx',
+			})
 			slot.appendChild(iframe)
 			this.iframe = iframe
 		},
+		attachContentIframe(token: string, indexEntry: string, title: string): void {
+			const slot = this.$refs.frameSlot as HTMLElement | undefined
+			if (!slot) return
+			slot.innerHTML = ''
+			const iframe = createContentIframe({
+				contentBase: generateUrl(CONTENT_PREFIX),
+				token,
+				indexEntry,
+				title,
+			})
+			const relayConfig = safeLoad<EmbedRelayConfig>('embedRelay', { mode: 'open' })
+			iframe.addEventListener('load', () => {
+				// The trusted parent overlays real players over the placeholders
+				// the opaque iframe's shim reports.
+				startRelay(relayConfig)
+				pingEmbeds(iframe)
+			})
+			slot.appendChild(iframe)
+			// Attached as soon as the frame has a window, and deliberately NOT inside the
+			// `load` handler above: the content announces itself while it runs, so a host
+			// that starts listening only after `load` can miss the one hello it sends.
+			startMedia(iframe)
+			this.iframe = iframe
+			this.relayActive = true
+			window.addEventListener('resize', this.onResize)
+		},
+		onResize(): void {
+			reflowOverlays()
+		},
 		teardown(): void {
+			if (this.relayActive) {
+				clearOverlays()
+				window.removeEventListener('resize', this.onResize)
+				this.relayActive = false
+			}
 			this.iframe?.remove()
 			this.iframe = null
 			if (this.worker && this.session) {
diff --git a/tests/Unit/AppInfo/ApplicationTest.php b/tests/Unit/AppInfo/ApplicationTest.php
new file mode 100644
index 0000000..67557f3
--- /dev/null
+++ b/tests/Unit/AppInfo/ApplicationTest.php
@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\AppInfo;
+
+use OCA\ExeLearning\AppInfo\Application;
+use OCA\ExeLearning\Service\IframeSandbox;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Covers the app-config fallback wired into {@see Application::iframeSandboxEnvReader()}.
+ *
+ * IframeSandbox stays OCP-free and secure-by-default (see {@see \OCA\ExeLearning\Tests\Unit\Service\IframeSandboxTest});
+ * this test pins the extra seam that lets the php-wasm Playground flip the
+ * dev-only escape hatch through a Nextcloud app-config value (`config:app:set`)
+ * instead of a process env var it cannot set — without ever weakening the
+ * secure default.
+ */
+final class ApplicationTest extends TestCase {
+	private const HATCH = 'EXELEARNING_UNSAFE_LEGACY_IFRAME';
+
+	/**
+	 * @param array<string,string|false> $env Process-env values (false = unset).
+	 * @param array<string,string> $config App-config values keyed by app-config key.
+	 */
+	private function reader(array $env = [], array $config = []): callable {
+		return Application::iframeSandboxEnvReader(
+			static fn (string $name): string|false => $env[$name] ?? false,
+			static fn (string $key): string => $config[$key] ?? '',
+		);
+	}
+
+	public function testDefaultsToSecureWhenNeitherEnvNorConfigSet(): void {
+		$sandbox = new IframeSandbox($this->reader());
+		self::assertNull($this->reader()(self::HATCH));
+		self::assertSame(IframeSandbox::MODE_SECURE, $sandbox->resolveMode());
+	}
+
+	public function testAppConfigFlipsToLegacyWhenEnvUnset(): void {
+		// This is the Playground path: no process env var, only config:app:set.
+		$reader = $this->reader(config: ['unsafe_legacy_iframe' => '1']);
+		self::assertSame('1', $reader(self::HATCH));
+		self::assertSame(IframeSandbox::MODE_LEGACY, (new IframeSandbox($reader))->resolveMode());
+	}
+
+	public function testEmptyAppConfigStaysSecure(): void {
+		$reader = $this->reader(config: ['unsafe_legacy_iframe' => '']);
+		self::assertNull($reader(self::HATCH));
+		self::assertSame(IframeSandbox::MODE_SECURE, (new IframeSandbox($reader))->resolveMode());
+	}
+
+	public function testProcessEnvWinsOverAppConfig(): void {
+		// A real host's env var must override any lingering app-config value.
+		$reader = $this->reader(env: [self::HATCH => '0'], config: ['unsafe_legacy_iframe' => '1']);
+		self::assertSame('0', $reader(self::HATCH));
+		self::assertSame(IframeSandbox::MODE_SECURE, (new IframeSandbox($reader))->resolveMode());
+	}
+
+	public function testExplicitlyEmptyEnvDisablesTheConfigHatch(): void {
+		// getenv() returning '' (set-but-empty, not false) still shadows config.
+		$reader = $this->reader(env: [self::HATCH => ''], config: ['unsafe_legacy_iframe' => '1']);
+		self::assertSame('', $reader(self::HATCH));
+		self::assertSame(IframeSandbox::MODE_SECURE, (new IframeSandbox($reader))->resolveMode());
+	}
+
+	public function testEnvNameIsMappedToLowercaseAppConfigKey(): void {
+		$seen = [];
+		$reader = Application::iframeSandboxEnvReader(
+			static fn (string $name): string|false => false,
+			static function (string $key) use (&$seen): string {
+				$seen[] = $key;
+				return '';
+			},
+		);
+		$reader('EXELEARNING_UNSAFE_LEGACY_IFRAME');
+		$reader('EXELEARNING_EMBED_OPEN');
+		self::assertSame(['unsafe_legacy_iframe', 'embed_open'], $seen);
+	}
+
+	public function testEmbedOpenHatchAlsoHonoursAppConfig(): void {
+		$reader = $this->reader(config: ['embed_open' => '1']);
+		self::assertSame(IframeSandbox::EMBED_OPEN, (new IframeSandbox($reader))->embedMode());
+	}
+}
diff --git a/tests/Unit/Service/ContentTokenServiceTest.php b/tests/Unit/Service/ContentTokenServiceTest.php
new file mode 100644
index 0000000..dd950fb
--- /dev/null
+++ b/tests/Unit/Service/ContentTokenServiceTest.php
@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\Service;
+
+use OCA\ExeLearning\Service\ContentTokenService;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests for {@see ContentTokenService} — the stateless, fileId+userId-bound
+ * capability token that gates the cookieless opaque content-serving route.
+ */
+final class ContentTokenServiceTest extends TestCase {
+	private function service(int $now = 1000): ContentTokenService {
+		return new ContentTokenService('test-secret-value', static fn (): int => $now);
+	}
+
+	public function testRoundTripsFileIdAndUser(): void {
+		$svc = $this->service();
+		self::assertSame([42, 'alice'], $svc->verify($svc->mint(42, 'alice')));
+	}
+
+	public function testUserIdWithSpecialCharsSurvives(): void {
+		$svc = $this->service();
+		$uid = 'user.with-dots_and@example';
+		self::assertSame([7, $uid], $svc->verify($svc->mint(7, $uid)));
+	}
+
+	public function testTamperedPayloadRejected(): void {
+		$svc = $this->service();
+		$token = $svc->mint(42, 'alice');
+		$mangled = ($token[0] === 'A' ? 'B' : 'A') . substr($token, 1);
+		self::assertNull($svc->verify($mangled));
+	}
+
+	public function testExpiredTokenRejected(): void {
+		$token = $this->service(1000)->mint(42, 'alice', 100); // expires at 1100
+		self::assertNull($this->service(5000)->verify($token));
+	}
+
+	public function testStillValidBeforeExpiry(): void {
+		$token = $this->service(1000)->mint(42, 'alice', 100);
+		self::assertSame([42, 'alice'], $this->service(1050)->verify($token));
+	}
+
+	public function testGarbageRejected(): void {
+		$svc = $this->service();
+		self::assertNull($svc->verify(''));
+		self::assertNull($svc->verify('not-a-token'));
+		self::assertNull($svc->verify('a.b.c'));
+		self::assertNull($svc->verify('@@@.@@@'));
+	}
+}
diff --git a/tests/Unit/Service/EmbedShimInjectorTest.php b/tests/Unit/Service/EmbedShimInjectorTest.php
new file mode 100644
index 0000000..9210d6c
--- /dev/null
+++ b/tests/Unit/Service/EmbedShimInjectorTest.php
@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\Service;
+
+use OCA\ExeLearning\Service\EmbedShimInjector;
+use PHPUnit\Framework\TestCase;
+
+final class EmbedShimInjectorTest extends TestCase {
+	private EmbedShimInjector $injector;
+
+	protected function setUp(): void {
+		$this->injector = new EmbedShimInjector();
+	}
+
+	public function testInjectsBeforeHeadClose(): void {
+		$html = '<html><head><title>x</title></head><body>hi</body></html>';
+		$out = $this->injector->injectIntoHead($html, 'CONSOLE.LOG(1)');
+		self::assertStringContainsString('data-injected-by="eXeLearning-Viewer"', $out);
+		self::assertStringContainsString('CONSOLE.LOG(1)', $out);
+		// Script sits immediately before </head>, i.e. before <body>.
+		self::assertLessThan(strpos($out, '<body'), strpos($out, 'CONSOLE.LOG(1)'));
+	}
+
+	public function testCaseInsensitiveHeadClose(): void {
+		$out = $this->injector->injectIntoHead('<HTML><HEAD></HEAD><BODY></BODY></HTML>', 'X');
+		self::assertStringContainsString('<script data-injected-by="eXeLearning-Viewer">X</script></HEAD>', $out);
+	}
+
+	public function testPreservesRegexSpecialCharsInSource(): void {
+		$source = 'var a = "$1"; var b = "\\\\n"; // $0 \\1';
+		$out = $this->injector->injectIntoHead('<head></head>', $source);
+		self::assertStringContainsString($source, $out);
+	}
+
+	public function testFallsBackToAfterBodyWhenNoHead(): void {
+		$out = $this->injector->injectIntoHead('<body class="p">hi</body>', 'Y');
+		self::assertStringContainsString('<body class="p"><script data-injected-by="eXeLearning-Viewer">Y</script>', $out);
+	}
+
+	public function testPrependsWhenNoHeadNoBody(): void {
+		$out = $this->injector->injectIntoHead('<p>bare</p>', 'Z');
+		self::assertStringStartsWith('<script data-injected-by="eXeLearning-Viewer">Z</script>', $out);
+	}
+}
diff --git a/tests/Unit/Service/ExternalMediaArtifactTest.php b/tests/Unit/Service/ExternalMediaArtifactTest.php
new file mode 100644
index 0000000..30db421
--- /dev/null
+++ b/tests/Unit/Service/ExternalMediaArtifactTest.php
@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\Service;
+
+use OCA\ExeLearning\Service\EmbedShimSource;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * The script inlined into every served package must be the CANONICAL child bundle
+ * published by eXeLearning core, not a copy maintained here.
+ *
+ * A bespoke copy is how this app ended up shipping a pre-handshake runtime while the
+ * parent side had already moved on: the host waits for a `hello` that never comes, so no
+ * embed is ever promoted and the learner sees permanent black boxes. Nothing errors, so
+ * the only way to catch it is to assert which bytes are served.
+ */
+final class ExternalMediaArtifactTest extends TestCase {
+	private const VENDORED = __DIR__ . '/../../../src/embed/exe_external_media';
+
+	public function testServedShimIsTheVendoredChildBundle(): void {
+		$source = (new EmbedShimSource(self::VENDORED))->read();
+
+		self::assertNotNull($source, 'no shim source was produced');
+		self::assertSame(
+			file_get_contents(self::VENDORED . '/exe-external-media-child.min.js'),
+			$source,
+		);
+	}
+
+	public function testServedShimPublishesTheSharedBridgeContract(): void {
+		$source = (new EmbedShimSource(self::VENDORED))->read() ?? '';
+
+		// The three symbols the host and the interactive-video iDevice rely on.
+		self::assertStringContainsString('exeExternalMediaChild', $source);
+		self::assertStringContainsString('exeEmbedShim', $source);
+		self::assertStringContainsString('exeMediaBridge', $source);
+		// And the licence notice ADR-0018 requires to survive minification.
+		self::assertStringContainsString('Dual-licensed', $source);
+	}
+
+	public function testMissingArtifactYieldsNullRatherThanAFatal(): void {
+		self::assertNull((new EmbedShimSource(__DIR__ . '/does-not-exist'))->read());
+	}
+
+	/**
+	 * Byte identity against the manifest core published. Integrity, not provenance —
+	 * the CI step pins the buildHash out of band — but it catches a local edit, which is
+	 * the failure this repo can actually cause on its own.
+	 */
+	public function testVendoredBytesMatchTheManifest(): void {
+		$manifest = json_decode((string)file_get_contents(self::VENDORED . '/exe-external-media.manifest.json'), true);
+		self::assertIsArray($manifest['files'] ?? null);
+
+		foreach ($manifest['files'] as $key => $record) {
+			$path = self::VENDORED . '/' . $record['path'];
+			self::assertFileExists($path, "vendored $key is missing");
+			self::assertSame($record['sha256'], hash_file('sha256', $path), "vendored $key was edited locally");
+		}
+	}
+}
diff --git a/tests/Unit/Service/IframeSandboxTest.php b/tests/Unit/Service/IframeSandboxTest.php
new file mode 100644
index 0000000..5ea0451
--- /dev/null
+++ b/tests/Unit/Service/IframeSandboxTest.php
@@ -0,0 +1,128 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\Service;
+
+use OCA\ExeLearning\Service\IframeSandbox;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests for {@see IframeSandbox} — the single source of truth for the secure
+ * (opaque-origin) iframe policy used to render published .elpx content.
+ */
+final class IframeSandboxTest extends TestCase {
+	/**
+	 * @param array<string,string> $env Environment values keyed by variable name.
+	 */
+	private function service(array $env = []): IframeSandbox {
+		return new IframeSandbox(static fn (string $name): ?string => $env[$name] ?? null);
+	}
+
+	public function testDefaultsToSecureMode(): void {
+		self::assertSame(IframeSandbox::MODE_SECURE, $this->service()->resolveMode());
+	}
+
+	public function testLegacyModeOnlyViaEscapeHatch(): void {
+		$hatch = 'EXELEARNING_UNSAFE_LEGACY_IFRAME';
+		self::assertSame(IframeSandbox::MODE_LEGACY, $this->service([$hatch => '1'])->resolveMode());
+		self::assertSame(IframeSandbox::MODE_LEGACY, $this->service([$hatch => 'true'])->resolveMode());
+		self::assertSame(IframeSandbox::MODE_SECURE, $this->service([$hatch => '0'])->resolveMode());
+		self::assertSame(IframeSandbox::MODE_SECURE, $this->service([$hatch => ''])->resolveMode());
+	}
+
+	public function testEmbedModeDefaultsToStrict(): void {
+		self::assertSame(IframeSandbox::EMBED_STRICT, $this->service()->embedMode());
+	}
+
+	public function testEmbedModeOpensOnlyViaEnv(): void {
+		$env = 'EXELEARNING_EMBED_OPEN';
+		self::assertSame(IframeSandbox::EMBED_OPEN, $this->service([$env => '1'])->embedMode());
+		self::assertSame(IframeSandbox::EMBED_STRICT, $this->service([$env => 'off'])->embedMode());
+	}
+
+	public function testSecureSandboxTokensNeverAllowSameOrigin(): void {
+		$tokens = $this->service()->sandboxTokens(IframeSandbox::MODE_SECURE);
+		self::assertSame('allow-scripts allow-popups allow-forms', $tokens);
+		self::assertStringNotContainsString('allow-same-origin', $tokens);
+		self::assertStringNotContainsString('allow-popups-to-escape-sandbox', $tokens);
+		self::assertStringNotContainsString('allow-top-navigation', $tokens);
+	}
+
+	public function testLegacySandboxTokensReintroduceSameOrigin(): void {
+		$tokens = $this->service()->sandboxTokens(IframeSandbox::MODE_LEGACY);
+		self::assertStringContainsString('allow-same-origin', $tokens);
+	}
+
+	public function testStrictPublishedCspShape(): void {
+		$csp = $this->service()->contentSecurityPolicy();
+		// The opaque sandbox rides in the CSP too (keeps the doc opaque if opened top-level).
+		self::assertStringContainsString('sandbox allow-scripts allow-popups allow-forms', $csp);
+		self::assertStringContainsString("object-src 'none'", $csp);
+		self::assertStringContainsString("frame-ancestors 'self'", $csp);
+		// Only the maintained providers, never bare https: in frame-src.
+		self::assertStringContainsString('https://www.youtube-nocookie.com', $csp);
+		self::assertStringContainsString('https://mediateca.educa.madrid.org', $csp);
+		self::assertStringNotContainsString('frame-src \'self\' https:;', $csp);
+		// No token-exfiltrating bare https: in script/img/media in the strict profile.
+		self::assertDoesNotMatchRegularExpression('~script-src[^;]*\bhttps:(?!//)~', $csp);
+	}
+
+	public function testCompatibleProfileReopensHttps(): void {
+		$csp = $this->service()->contentSecurityPolicy('compatible');
+		self::assertStringContainsString("script-src 'self' 'unsafe-inline' 'unsafe-eval' https:", $csp);
+		self::assertStringContainsString('frame-src \'self\' https:', $csp);
+		// Sandbox stays even in the weaker profile.
+		self::assertStringContainsString('sandbox allow-scripts allow-popups allow-forms', $csp);
+	}
+
+	public function testSvgCspIsScriptFree(): void {
+		$csp = $this->service()->svgCsp();
+		self::assertStringContainsString("script-src 'none'", $csp);
+		self::assertStringContainsString("default-src 'none'", $csp);
+		self::assertStringContainsString('sandbox', $csp);
+	}
+
+	public function testPermissionsPolicyDeniesHardwareButNotFullscreen(): void {
+		$pp = $this->service()->permissionsPolicy();
+		self::assertStringContainsString('camera=()', $pp);
+		self::assertStringContainsString('microphone=()', $pp);
+		self::assertStringContainsString('geolocation=()', $pp);
+		self::assertStringNotContainsString('fullscreen', $pp);
+	}
+
+	public function testProviderWhitelistIsLowercaseAndDeduped(): void {
+		$hosts = $this->service()->providerWhitelist();
+		self::assertContains('www.youtube-nocookie.com', $hosts);
+		self::assertContains('player.vimeo.com', $hosts);
+		self::assertContains('mediateca.educa.madrid.org', $hosts);
+		self::assertSame(array_values(array_unique($hosts)), $hosts);
+		self::assertSame(array_map('strtolower', $hosts), $hosts);
+	}
+
+	/**
+	 * The page CSP must allow exactly the hosts the relay is allowed to promote.
+	 *
+	 * These are two halves of one decision kept in two places, and the failure when they
+	 * drift is silent and ugly: the relay overlays a real player, the browser refuses to
+	 * load a frame the CSP never allowed, and the learner gets a permanent black
+	 * rectangle where the video should be. That is exactly what the viewer shipped —
+	 * `frame-src 'self'` with a ten-host provider whitelist next to it.
+	 */
+	public function testPlayerFrameDomainsCoverEveryWhitelistedProvider(): void {
+		$sandbox = new IframeSandbox();
+
+		$domains = $sandbox->playerFrameDomains();
+
+		foreach ($sandbox->providerWhitelist() as $host) {
+			self::assertContains($host, $domains, "CSP would block a promoted player on $host");
+		}
+	}
+
+	/** And nothing beyond them: the CSP is not a place to widen the gate quietly. */
+	public function testPlayerFrameDomainsAddNothingBeyondTheWhitelist(): void {
+		$sandbox = new IframeSandbox();
+
+		self::assertSame([], array_diff($sandbox->playerFrameDomains(), $sandbox->providerWhitelist()));
+	}
+}
diff --git a/tests/Unit/Service/PackageMimeServiceTest.php b/tests/Unit/Service/PackageMimeServiceTest.php
new file mode 100644
index 0000000..850fcfc
--- /dev/null
+++ b/tests/Unit/Service/PackageMimeServiceTest.php
@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\Service;
+
+use OCA\ExeLearning\Service\PackageMimeService;
+use PHPUnit\Framework\TestCase;
+
+final class PackageMimeServiceTest extends TestCase {
+	private PackageMimeService $service;
+
+	protected function setUp(): void {
+		$this->service = new PackageMimeService();
+	}
+
+	public function testDetectsKnownExtensions(): void {
+		self::assertSame('text/html; charset=utf-8', $this->service->detect('index.html'));
+		self::assertSame('image/svg+xml', $this->service->detect('img/logo.svg'));
+		self::assertSame('text/javascript; charset=utf-8', $this->service->detect('a.js'));
+		self::assertSame('application/xml; charset=utf-8', $this->service->detect('content.xml'));
+	}
+
+	public function testUnknownExtensionFallsBack(): void {
+		self::assertSame('application/octet-stream', $this->service->detect('weird.qux'));
+		self::assertSame('application/octet-stream', $this->service->detect('README'));
+	}
+
+	public function testHtmlDocumentsGetTheEnginePolicy(): void {
+		self::assertTrue($this->service->isHtmlDocument('text/html; charset=utf-8'));
+		self::assertTrue($this->service->isHtmlDocument('application/xhtml+xml'));
+		self::assertFalse($this->service->isHtmlDocument('image/svg+xml'));
+		self::assertFalse($this->service->isHtmlDocument('text/css'));
+	}
+
+	public function testXmlDocumentsAreLocked(): void {
+		self::assertTrue($this->service->isLockedXml('image/svg+xml'));
+		self::assertTrue($this->service->isLockedXml('application/xml; charset=utf-8'));
+		self::assertFalse($this->service->isLockedXml('text/html'));
+		self::assertFalse($this->service->isLockedXml('image/png'));
+	}
+}
diff --git a/tests/Unit/Service/Preview/PreviewPolicyTest.php b/tests/Unit/Service/Preview/PreviewPolicyTest.php
new file mode 100644
index 0000000..cea0843
--- /dev/null
+++ b/tests/Unit/Service/Preview/PreviewPolicyTest.php
@@ -0,0 +1,149 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\Service\Preview;
+
+use OCA\ExeLearning\Service\Preview\PreviewPolicy;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests for {@see PreviewPolicy} — the single source of truth for the editor
+ * preview isolation policy (CSP byte-identity, scriptable classification, MIME
+ * resolution and traversal-safe path normalization).
+ */
+final class PreviewPolicyTest extends TestCase {
+	/**
+	 * Byte-identity with eXe core `previewCspHeader()`. If this ever fails the
+	 * CSP has drifted from core and must be re-synced verbatim (no re-order,
+	 * re-quote, reformat, or trailing `;`).
+	 */
+	public function testCspIsByteIdenticalToCore(): void {
+		$expected = 'sandbox allow-scripts allow-popups allow-forms; '
+			. "default-src 'self'; "
+			. "script-src 'self' 'unsafe-inline' 'unsafe-eval'; "
+			. "style-src 'self' 'unsafe-inline'; "
+			. "img-src 'self' data: blob: https:; "
+			. "media-src 'self' data: blob: https:; "
+			. "font-src 'self' data:; "
+			. "connect-src 'self'; "
+			. "frame-src 'self' https://www.youtube-nocookie.com https://player.vimeo.com; "
+			. "child-src 'self' https://www.youtube-nocookie.com https://player.vimeo.com; "
+			. "object-src 'none'; "
+			. "base-uri 'none'; "
+			. "form-action 'self'; "
+			. "frame-ancestors 'self'";
+		self::assertSame($expected, PreviewPolicy::CSP);
+		// The leading sandbox directive is what makes the document opaque.
+		self::assertStringStartsWith('sandbox allow-scripts allow-popups allow-forms', PreviewPolicy::CSP);
+		self::assertStringNotContainsString('allow-same-origin', PreviewPolicy::CSP);
+	}
+
+	public function testPermissionsPolicyMatchesContract(): void {
+		self::assertSame('camera=(), microphone=(), geolocation=(), payment=()', PreviewPolicy::PERMISSIONS_POLICY);
+	}
+
+	/**
+	 * @dataProvider scriptableTypes
+	 */
+	public function testScriptableTypesAreScriptable(string $mime): void {
+		self::assertTrue(PreviewPolicy::isScriptable($mime));
+	}
+
+	/**
+	 * @return iterable<array{0:string}>
+	 */
+	public static function scriptableTypes(): iterable {
+		yield ['text/html'];
+		yield ['text/html; charset=utf-8'];
+		yield ['image/svg+xml'];
+		yield ['image/svg+xml; charset=utf-8'];
+		yield ['application/xml'];
+		yield ['application/xhtml+xml; charset=utf-8'];
+	}
+
+	/**
+	 * @dataProvider nonScriptableTypes
+	 */
+	public function testNonScriptableTypesAreNotScriptable(string $mime): void {
+		self::assertFalse(PreviewPolicy::isScriptable($mime));
+	}
+
+	/**
+	 * @return iterable<array{0:string}>
+	 */
+	public static function nonScriptableTypes(): iterable {
+		yield ['image/png'];
+		yield ['text/css; charset=utf-8'];
+		yield ['application/json; charset=utf-8'];
+		yield ['video/mp4'];
+		yield ['application/octet-stream'];
+	}
+
+	/**
+	 * @dataProvider mimeCases
+	 */
+	public function testMimeForPath(string $path, string $expected): void {
+		self::assertSame($expected, PreviewPolicy::mimeForPath($path));
+	}
+
+	/**
+	 * @return iterable<array{0:string,1:string}>
+	 */
+	public static function mimeCases(): iterable {
+		yield 'html carries charset' => ['index.html', 'text/html; charset=utf-8'];
+		yield 'png is bare' => ['content/resources/photo.png', 'image/png'];
+		yield 'svg is charset-tagged (scriptable-tab hole)' => ['theme/icon.svg', 'image/svg+xml; charset=utf-8'];
+		yield 'js carries charset' => ['libs/jquery/jquery.min.js', 'text/javascript; charset=utf-8'];
+		yield 'json carries charset' => ['data/index.json', 'application/json; charset=utf-8'];
+		yield 'mp4 is bare' => ['media/clip.mp4', 'video/mp4'];
+		yield 'unknown falls back to octet-stream' => ['blob.bin', 'application/octet-stream'];
+	}
+
+	/**
+	 * @dataProvider safePaths
+	 */
+	public function testNormalizePathAcceptsSafePaths(string $raw, string $expected): void {
+		self::assertSame($expected, PreviewPolicy::normalizePath($raw));
+	}
+
+	/**
+	 * @return iterable<array{0:string,1:string}>
+	 */
+	public static function safePaths(): iterable {
+		yield 'plain file' => ['index.html', 'index.html'];
+		yield 'empty defaults to index' => ['', 'index.html'];
+		yield 'leading slash stripped' => ['/html/page-2.html', 'html/page-2.html'];
+		yield 'dot segments collapsed' => ['a/./b.css', 'a/b.css'];
+		yield 'double slash collapsed' => ['a//b.css', 'a/b.css'];
+		yield 'backslash folded to slash' => ['a\\b.css', 'a/b.css'];
+		yield 'query stripped' => ['page.html?v=3', 'page.html'];
+	}
+
+	/**
+	 * @dataProvider unsafePaths
+	 */
+	public function testNormalizePathRejectsUnsafePaths(string $raw): void {
+		self::assertNull(PreviewPolicy::normalizePath($raw));
+	}
+
+	/**
+	 * @return iterable<array{0:string}>
+	 */
+	public static function unsafePaths(): iterable {
+		yield 'literal parent' => ['../secret'];
+		yield 'percent-encoded parent' => ['%2e%2e%2fsecret'];
+		yield 'internal parent escape' => ['a/../../secret'];
+		yield 'bare dotdot' => ['..'];
+		yield 'trailing parent collapses to empty root' => ['foo/..'];
+		yield 'nul byte' => ["a\0b"];
+	}
+
+	public function testPreviewIdValidation(): void {
+		self::assertTrue(PreviewPolicy::isValidPreviewId('3f2a1b4c-5d6e-4f70-8a90-b1c2d3e4f506'));
+		self::assertFalse(PreviewPolicy::isValidPreviewId('not-a-uuid'));
+		self::assertFalse(PreviewPolicy::isValidPreviewId('3F2A1B4C-5D6E-4F70-8A90-B1C2D3E4F506'));
+		self::assertFalse(PreviewPolicy::isValidPreviewId('../../etc/passwd'));
+	}
+
+}
diff --git a/tests/Unit/Service/Preview/PreviewServerTest.php b/tests/Unit/Service/Preview/PreviewServerTest.php
new file mode 100644
index 0000000..e80edc0
--- /dev/null
+++ b/tests/Unit/Service/Preview/PreviewServerTest.php
@@ -0,0 +1,250 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\Service\Preview;
+
+use OCA\ExeLearning\Service\Preview\PreviewPolicy;
+use OCA\ExeLearning\Service\Preview\PreviewServer;
+use OCA\ExeLearning\Service\Preview\PreviewSnapshotLimits;
+use OCA\ExeLearning\Service\Preview\PreviewSnapshotStore;
+use PHPUnit\Framework\TestCase;
+use ZipArchive;
+
+/**
+ * Tests for {@see PreviewServer} — the serving-route HTTP policy: the hardening
+ * header set on every response (404 included), tiered Cache-Control, the sandbox
+ * CSP on every scriptable type, ETag/304 and single-range 206/416.
+ */
+final class PreviewServerTest extends TestCase {
+	private string $root;
+	private PreviewSnapshotStore $store;
+	private string $previewId;
+
+	protected function setUp(): void {
+		$this->root = sys_get_temp_dir() . '/exe-srv-' . bin2hex(random_bytes(6));
+		$this->store = new PreviewSnapshotStore($this->root, new PreviewSnapshotLimits());
+		$this->previewId = $this->store->replace('alice', $this->zip([
+			'index.html' => '<html><body>hi</body></html>',
+			'img/inline.svg' => '<svg xmlns="http://www.w3.org/2000/svg"></svg>',
+			'content/resources/photo.png' => 'PHOTO-BYTES-v1',
+			'media/clip.mp4' => '0123456789',
+		]))['previewId'];
+	}
+
+	protected function tearDown(): void {
+		$this->removeTree($this->root);
+	}
+
+	/**
+	 * Build a snapshot ZIP on disk from a path => contents map.
+	 *
+	 * @param array<string,string> $entries
+	 */
+	private function zip(array $entries): string {
+		$path = sys_get_temp_dir() . '/exe-srv-zip-' . bin2hex(random_bytes(6)) . '.zip';
+		$zip = new ZipArchive();
+		$zip->open($path, ZipArchive::CREATE);
+		foreach ($entries as $name => $contents) {
+			$zip->addFromString($name, $contents);
+		}
+		$zip->close();
+		return $path;
+	}
+
+	private function server(): PreviewServer {
+		return new PreviewServer($this->store);
+	}
+
+	/** The ETag the store minted for a path (content-independent, so read it back). */
+	private function etagFor(string $path): string {
+		return $this->server()->serve($this->previewId, $path)->headers['ETag'];
+	}
+
+	private function assertBaseHardening(array $headers): void {
+		self::assertSame('nosniff', $headers['X-Content-Type-Options']);
+		self::assertSame('no-referrer', $headers['Referrer-Policy']);
+		self::assertSame('camera=(), microphone=(), geolocation=(), payment=()', $headers['Permissions-Policy']);
+		self::assertSame('*', $headers['Access-Control-Allow-Origin']);
+	}
+
+	public function testServeDocument(): void {
+		$response = $this->server()->serve($this->previewId, 'index.html');
+		self::assertSame(200, $response->status);
+		self::assertSame('<html><body>hi</body></html>', $response->body);
+		self::assertSame('text/html; charset=utf-8', $response->headers['Content-Type']);
+		self::assertSame('no-store', $response->headers['Cache-Control']);
+		self::assertSame(PreviewPolicy::CSP, $response->headers['Content-Security-Policy']);
+		$this->assertBaseHardening($response->headers);
+	}
+
+	public function testServeAssetHasEtagNoCacheAndNoCsp(): void {
+		$response = $this->server()->serve($this->previewId, 'content/resources/photo.png');
+		self::assertSame(200, $response->status);
+		self::assertSame('PHOTO-BYTES-v1', $response->body);
+		self::assertSame('image/png', $response->headers['Content-Type']);
+		self::assertSame('no-cache', $response->headers['Cache-Control']);
+		self::assertSame('bytes', $response->headers['Accept-Ranges']);
+		self::assertArrayHasKey('ETag', $response->headers);
+		self::assertArrayNotHasKey('Content-Security-Policy', $response->headers);
+	}
+
+	public function testConditionalRequestReturns304(): void {
+		$etag = $this->etagFor('content/resources/photo.png');
+		$response = $this->server()->serve($this->previewId, 'content/resources/photo.png', $etag);
+		self::assertSame(304, $response->status);
+		self::assertSame('', $response->body);
+		self::assertSame('nosniff', $response->headers['X-Content-Type-Options']);
+		self::assertSame($etag, $response->headers['ETag']);
+	}
+
+	/**
+	 * The ETag is built from identity rather than from hashing the bytes, so it
+	 * has to turn over on a refresh that mtime and size alone cannot see: two
+	 * publishes inside the same second where the file keeps its length.
+	 */
+	public function testEtagTurnsOverOnASameSizeRefresh(): void {
+		$before = $this->etagFor('media/clip.mp4');
+
+		$this->store->replace('alice', $this->zip([
+			'index.html' => '<html></html>',
+			'media/clip.mp4' => '9876543210',
+		]), $this->previewId);
+
+		$response = $this->server()->serve(
+			$this->previewId,
+			'media/clip.mp4',
+			$before,
+		);
+		self::assertSame(200, $response->status, 'a stale ETag must not win a conditional request');
+		self::assertSame('9876543210', $response->body);
+		self::assertNotSame($before, $response->headers['ETag']);
+	}
+
+	public function testSingleRangeReturns206(): void {
+		$response = $this->server()->serve($this->previewId, 'media/clip.mp4', null, 'bytes=2-4');
+		self::assertSame(206, $response->status);
+		self::assertSame('234', $response->body);
+		self::assertSame('bytes 2-4/10', $response->headers['Content-Range']);
+		self::assertSame('3', $response->headers['Content-Length']);
+	}
+
+	/**
+	 * 416 is reserved for a valid single range that is unsatisfiable: a
+	 * first-byte-pos at/after EOF (`bytes=99-`) or a zero-length suffix
+	 * (`bytes=-0`).
+	 *
+	 * @dataProvider unsatisfiableRangeProvider
+	 */
+	public function testUnsatisfiableRangeReturns416(string $range): void {
+		$response = $this->server()->serve($this->previewId, 'media/clip.mp4', null, $range);
+		self::assertSame(416, $response->status, $range . ' must be 416');
+		self::assertSame('bytes */10', $response->headers['Content-Range']);
+	}
+
+	/** @return array<string,array{0:string}> */
+	public static function unsatisfiableRangeProvider(): array {
+		return [
+			'first-byte-pos past EOF' => ['bytes=99-'],
+			'zero-length suffix' => ['bytes=-0'],
+		];
+	}
+
+	/**
+	 * A malformed, multi-range or non-bytes Range header is IGNORED — the server
+	 * serves a normal 200 full body, never 416.
+	 *
+	 * @dataProvider ignoredRangeProvider
+	 */
+	public function testIgnoredRangeServesFull200(string $range): void {
+		$response = $this->server()->serve($this->previewId, 'media/clip.mp4', null, $range);
+		self::assertSame(200, $response->status, $range . ' must be ignored, not 416');
+		self::assertSame('0123456789', $response->body);
+		self::assertSame('bytes', $response->headers['Accept-Ranges']);
+		self::assertArrayNotHasKey('Content-Range', $response->headers);
+	}
+
+	/** @return array<string,array{0:string}> */
+	public static function ignoredRangeProvider(): array {
+		return [
+			'non-numeric' => ['bytes=abc'],
+			'multi-range' => ['bytes=0-1,2-3'],
+			'non-bytes unit' => ['items=0-1'],
+			'empty range' => ['bytes=-'],
+			'garbage' => ['not-a-range'],
+			'double dash' => ['bytes=1-2-3'],
+			// last-byte-pos < first-byte-pos is an invalid spec (RFC 9110
+			// §14.1.2) → ignore the header, not 416.
+			'last before first' => ['bytes=5-2'],
+		];
+	}
+
+	public function testBareRootRedirectsToIndexHtml(): void {
+		$response = $this->server()->serveRoot($this->previewId);
+		self::assertSame(302, $response->status);
+		// Relative Location so it stays correct under any webroot: it resolves
+		// against the request URI `.../preview/{previewId}`.
+		self::assertSame($this->previewId . '/index.html', $response->headers['Location']);
+		self::assertSame('no-store', $response->headers['Cache-Control']);
+		$this->assertBaseHardening($response->headers);
+	}
+
+	public function testBareRootInvalidPreviewIdIs404(): void {
+		$response = $this->server()->serveRoot('not-a-uuid');
+		self::assertSame(404, $response->status);
+		self::assertArrayNotHasKey('Location', $response->headers);
+		$this->assertBaseHardening($response->headers);
+	}
+
+	/**
+	 * An author-supplied SVG runs its inline <script> top-level, and `nosniff`
+	 * does not help — SVG is already a scriptable type — so it must carry the
+	 * sandbox CSP just like an HTML document.
+	 */
+	public function testScriptableSvgCarriesCsp(): void {
+		$response = $this->server()->serve($this->previewId, 'img/inline.svg');
+		self::assertSame(200, $response->status);
+		self::assertSame('image/svg+xml; charset=utf-8', $response->headers['Content-Type']);
+		self::assertSame(PreviewPolicy::CSP, $response->headers['Content-Security-Policy']);
+	}
+
+	public function testUnknownPathIs404WithHardening(): void {
+		$response = $this->server()->serve($this->previewId, 'nope.css');
+		self::assertSame(404, $response->status);
+		self::assertSame('no-store', $response->headers['Cache-Control']);
+		$this->assertBaseHardening($response->headers);
+	}
+
+	public function testEncodedTraversalIs404(): void {
+		$response = $this->server()->serve($this->previewId, '%2e%2e%2fsecret');
+		self::assertSame(404, $response->status);
+		self::assertSame('no-store', $response->headers['Cache-Control']);
+	}
+
+	public function testInvalidPreviewIdIs404(): void {
+		$response = $this->server()->serve('not-a-uuid', 'index.html');
+		self::assertSame(404, $response->status);
+		$this->assertBaseHardening($response->headers);
+	}
+
+	public function testDeletedSnapshotStopsServing(): void {
+		$this->store->deleteOwned($this->previewId, 'alice');
+		$response = $this->server()->serve($this->previewId, 'index.html');
+		self::assertSame(404, $response->status);
+		self::assertSame('no-store', $response->headers['Cache-Control']);
+	}
+
+	private function removeTree(string $dir): void {
+		if (!is_dir($dir)) {
+			@unlink($dir);
+			return;
+		}
+		foreach (scandir($dir) ?: [] as $item) {
+			if ($item === '.' || $item === '..') {
+				continue;
+			}
+			$this->removeTree($dir . '/' . $item);
+		}
+		@rmdir($dir);
+	}
+}
diff --git a/tests/Unit/Service/Preview/PreviewSnapshotStoreTest.php b/tests/Unit/Service/Preview/PreviewSnapshotStoreTest.php
new file mode 100644
index 0000000..7e6696d
--- /dev/null
+++ b/tests/Unit/Service/Preview/PreviewSnapshotStoreTest.php
@@ -0,0 +1,291 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\Service\Preview;
+
+use OCA\ExeLearning\Service\Preview\PreviewSnapshotLimits;
+use OCA\ExeLearning\Service\Preview\PreviewSnapshotStore;
+use PHPUnit\Framework\TestCase;
+use ZipArchive;
+
+/**
+ * Tests for {@see PreviewSnapshotStore} — capability lifecycle, owner scoping,
+ * the archive guards that stand between untrusted author content and the
+ * filesystem, and the DoS bounds that keep one author from filling a shared
+ * instance.
+ */
+final class PreviewSnapshotStoreTest extends TestCase {
+	private string $root;
+	private int $time = 1000000;
+
+	protected function setUp(): void {
+		$this->root = sys_get_temp_dir() . '/exe-snap-' . bin2hex(random_bytes(6));
+	}
+
+	protected function tearDown(): void {
+		$this->removeTree($this->root);
+	}
+
+	private function store(?PreviewSnapshotLimits $limits = null): PreviewSnapshotStore {
+		return new PreviewSnapshotStore(
+			$this->root,
+			$limits ?? new PreviewSnapshotLimits(),
+			fn (): int => $this->time,
+		);
+	}
+
+	/**
+	 * Build a snapshot ZIP on disk from a path => contents map.
+	 *
+	 * @param array<string,string> $entries
+	 */
+	private function zip(array $entries): string {
+		$path = sys_get_temp_dir() . '/exe-snap-zip-' . bin2hex(random_bytes(6)) . '.zip';
+		$zip = new ZipArchive();
+		$zip->open($path, ZipArchive::CREATE);
+		foreach ($entries as $name => $contents) {
+			$zip->addFromString($name, $contents);
+		}
+		$zip->close();
+		return $path;
+	}
+
+	// =========================================================================
+	// Publication
+	// =========================================================================
+
+	public function testReplaceStoresTheSnapshot(): void {
+		$store = $this->store();
+		$result = $store->replace('alice', $this->zip([
+			'index.html' => 'hello',
+			'assets/app.js' => 'run()',
+		]));
+
+		self::assertArrayHasKey('previewId', $result);
+		self::assertSame('hello', $store->resolve($result['previewId'], 'index.html')['bytes']);
+		self::assertSame('alice', $store->ownerOf($result['previewId']));
+	}
+
+	public function testReplaceSwapsTheWholeTree(): void {
+		$store = $this->store();
+		$id = $store->replace('alice', $this->zip([
+			'index.html' => 'first',
+			'stale.html' => 'gone next time',
+		]))['previewId'];
+
+		$second = $store->replace('alice', $this->zip(['index.html' => 'second']), $id);
+
+		self::assertSame($id, $second['previewId']);
+		self::assertSame('second', $store->resolve($id, 'index.html')['bytes']);
+		self::assertNull($store->resolve($id, 'stale.html'));
+	}
+
+	public function testReplaceRefusesACapabilityOwnedByAnotherUser(): void {
+		$store = $this->store();
+		$id = $store->replace('alice', $this->zip(['index.html' => 'hers']))['previewId'];
+
+		$result = $store->replace('mallory', $this->zip(['index.html' => 'theirs']), $id);
+
+		self::assertSame(403, $result['status']);
+		self::assertSame('hers', $store->resolve($id, 'index.html')['bytes']);
+	}
+
+	public function testReplaceRefusesAnUnknownCapability(): void {
+		$result = $this->store()->replace(
+			'alice',
+			$this->zip(['index.html' => 'ok']),
+			'ffffffff-ffff-4fff-bfff-ffffffffffff',
+		);
+
+		self::assertSame(404, $result['status']);
+	}
+
+	/**
+	 * Both verbs share one verdict, so an unknown capability and a malformed id
+	 * report the same statuses here as they do on publish.
+	 */
+	public function testDeleteReportsTheSameVerdictAsPublish(): void {
+		$store = $this->store();
+
+		self::assertSame(404, $store->deleteOwned('ffffffff-ffff-4fff-bfff-ffffffffffff', 'alice')['status']);
+		self::assertSame(400, $store->deleteOwned('not-a-uuid', 'alice')['status']);
+	}
+
+	public function testDeleteIsOwnerScoped(): void {
+		$store = $this->store();
+		$id = $store->replace('alice', $this->zip(['index.html' => 'ok']))['previewId'];
+
+		self::assertSame(403, $store->deleteOwned($id, 'mallory')['status']);
+		self::assertNotNull($store->resolve($id, 'index.html'));
+
+		self::assertNull($store->deleteOwned($id, 'alice'));
+		self::assertNull($store->resolve($id, 'index.html'));
+	}
+
+	// =========================================================================
+	// Archive guards
+	// =========================================================================
+
+	public function testArchiveMustCarryAnIndex(): void {
+		$result = $this->store()->replace('alice', $this->zip(['page.html' => 'orphan']));
+
+		self::assertSame(400, $result['status']);
+		self::assertStringContainsString('index.html', $result['error']);
+	}
+
+	public function testTraversalIsRefusedBeforeAnythingIsWritten(): void {
+		$result = $this->store()->replace('alice', $this->zip([
+			'index.html' => 'ok',
+			'../escape.html' => 'nope',
+		]));
+
+		self::assertSame(400, $result['status']);
+		self::assertFileDoesNotExist(dirname($this->root) . '/escape.html');
+	}
+
+	public function testAbsolutePathIsRefused(): void {
+		$result = $this->store()->replace('alice', $this->zip([
+			'index.html' => 'ok',
+			'/etc/passwd' => 'nope',
+		]));
+
+		self::assertSame(400, $result['status']);
+	}
+
+	public function testTheEntryCountGuardFailsClosed(): void {
+		$result = $this->store(new PreviewSnapshotLimits(maxFilesPerSnapshot: 1))->replace('alice', $this->zip([
+			'index.html' => 'a',
+			'b.html' => 'b',
+		]));
+
+		self::assertSame(400, $result['status']);
+	}
+
+	public function testTheByteGuardMeasuresRealDecompressedBytes(): void {
+		$result = $this->store(new PreviewSnapshotLimits(maxBytesPerSnapshot: 8))->replace('alice', $this->zip([
+			'index.html' => str_repeat('x', 64),
+		]));
+
+		self::assertSame(400, $result['status']);
+	}
+
+	public function testARejectedUploadLeavesNoStagingBehind(): void {
+		$this->store()->replace('alice', $this->zip(['page.html' => 'no index']));
+
+		$leftovers = array_filter(
+			scandir($this->root) ?: [],
+			static fn (string $entry): bool => str_starts_with($entry, '.staging-'),
+		);
+		self::assertSame([], array_values($leftovers));
+	}
+
+	// =========================================================================
+	// TTL and budgets
+	// =========================================================================
+
+	public function testIdleSnapshotsExpireAndAreSwept(): void {
+		$store = $this->store();
+		$id = $store->replace('alice', $this->zip(['index.html' => 'ok']))['previewId'];
+
+		$this->time += (new PreviewSnapshotLimits())->ttlSeconds + 60;
+
+		self::assertNull($store->resolve($id, 'index.html'));
+		self::assertSame(1, $store->sweepExpired());
+	}
+
+	public function testServingPushesTheIdleClockBack(): void {
+		$store = $this->store();
+		$ttl = (new PreviewSnapshotLimits())->ttlSeconds;
+		$id = $store->replace('alice', $this->zip(['index.html' => 'ok']))['previewId'];
+
+		// Just short of the TTL: resolving must keep it alive past the original
+		// deadline, so a preview in use never expires under the author.
+		$this->time += $ttl - 60;
+		self::assertNotNull($store->resolve($id, 'index.html'));
+
+		$this->time += 120;
+		self::assertNotNull($store->resolve($id, 'index.html'));
+	}
+
+	/**
+	 * A shared instance must not let one author accumulate capabilities: past
+	 * the per-user cap the least-recently-used one is evicted.
+	 */
+	public function testThePerUserCapEvictsTheLeastRecentlyUsed(): void {
+		$store = $this->store(new PreviewSnapshotLimits(maxSnapshotsPerUser: 2));
+		$first = $store->replace('alice', $this->zip(['index.html' => '1']))['previewId'];
+		$this->time += 10;
+		$second = $store->replace('alice', $this->zip(['index.html' => '2']))['previewId'];
+		$this->time += 10;
+
+		$third = $store->replace('alice', $this->zip(['index.html' => '3']))['previewId'];
+
+		self::assertNull($store->resolve($first, 'index.html'), 'the LRU snapshot must be evicted');
+		self::assertNotNull($store->resolve($second, 'index.html'));
+		self::assertNotNull($store->resolve($third, 'index.html'));
+	}
+
+	/** Another user's snapshots are never touched by this user's cap. */
+	public function testThePerUserCapIsScopedToItsOwner(): void {
+		$store = $this->store(new PreviewSnapshotLimits(maxSnapshotsPerUser: 1));
+		$hers = $store->replace('alice', $this->zip(['index.html' => 'hers']))['previewId'];
+		$this->time += 10;
+
+		$store->replace('bob', $this->zip(['index.html' => 'his']));
+
+		self::assertNotNull($store->resolve($hers, 'index.html'));
+	}
+
+	public function testTheGlobalBudgetRefusesWhatItCannotFit(): void {
+		$store = $this->store(new PreviewSnapshotLimits(globalMaxBytes: 4));
+
+		$result = $store->replace('alice', $this->zip(['index.html' => str_repeat('x', 64)]));
+
+		self::assertSame(507, $result['status']);
+	}
+
+	// =========================================================================
+	// Serving
+	// =========================================================================
+
+	public function testResolveRejectsTraversalOutOfTheSnapshot(): void {
+		$store = $this->store();
+		$id = $store->replace('alice', $this->zip(['index.html' => 'ok']))['previewId'];
+
+		self::assertNull($store->resolve($id, '../meta.json'));
+		self::assertNull($store->resolve($id, '%2e%2e%2fmeta.json'));
+	}
+
+	/**
+	 * The store's own metadata lives outside the extracted tree, so an author
+	 * path can never name it — there are no reserved names to police.
+	 */
+	public function testStoreMetadataIsNotReachableFromTheServingRoute(): void {
+		$store = $this->store();
+		$id = $store->replace('alice', $this->zip([
+			'index.html' => 'ok',
+			'meta.json' => '{"ownerUserId":"mallory"}',
+		]))['previewId'];
+
+		// The author's own meta.json is served as ordinary content...
+		$served = $store->resolve($id, 'meta.json');
+		self::assertSame('{"ownerUserId":"mallory"}', file_get_contents($served['filePath']));
+		// ...while the store keeps reading the real owner from outside the tree.
+		self::assertSame('alice', $store->ownerOf($id));
+	}
+
+	private function removeTree(string $dir): void {
+		if (!is_dir($dir)) {
+			@unlink($dir);
+			return;
+		}
+		foreach (scandir($dir) ?: [] as $item) {
+			if ($item === '.' || $item === '..') {
+				continue;
+			}
+			$this->removeTree($dir . '/' . $item);
+		}
+		@rmdir($dir);
+	}
+}
diff --git a/tests/e2e/preview-api-e2e.sh b/tests/e2e/preview-api-e2e.sh
new file mode 100755
index 0000000..602695a
--- /dev/null
+++ b/tests/e2e/preview-api-e2e.sh
@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+#
+# API-level end-to-end test of the opaque editor-preview contract against a REAL
+# running Nextcloud (no browser).
+#
+# Authentication is HTTP Basic auth: it authenticates per request via the
+# Authorization header and needs NO cookies, so it is reliable under the built-in
+# php -S server (where the browser login form's SameSite/session cookies do not
+# round-trip). CSRF is still exercised honestly, using Nextcloud's own rules
+# (lib/private/AppFramework/Http/Request.php::passesCSRFCheck):
+#
+#   * passesCSRFCheck() returns true when the OCS-APIRequest header is present,
+#     so the positive management calls send it (cookieless, no requesttoken).
+#   * Omitting that header on an AUTHENTICATED management POST leaves the CSRF
+#     check to fail (no token, no OCS-APIRequest) → the middleware answers 412
+#     "CSRF check failed" — proving the route is NOT #[NoCSRFRequired]. That is
+#     the real CSRF-enforcement assertion.
+#
+# It asserts: CSRF enforcement (412), the publish->serve round-trip, the authless
+# opaque serving response (200 + sandbox CSP, no allow-same-origin), the
+# bare-root 302, replace-in-place, that a REJECTED archive leaves the live
+# snapshot untouched, owner-scoping (403 on both publish and delete), and 404
+# after delete.
+#
+# Full editor-iframe browser E2E (external video / interactive-video) stays
+# blocked on a capable editor build and is documented as such, not faked here.
+#
+# Required environment:
+#   EXE_E2E_BASE   base URL incl. the front controller, e.g.
+#                  http://127.0.0.1:8080/index.php
+#   EXE_E2E_USER1 / EXE_E2E_PASS1   owner
+#   EXE_E2E_USER2 / EXE_E2E_PASS2   a second, non-owner user
+set -euo pipefail
+
+BASE="${EXE_E2E_BASE:?EXE_E2E_BASE is required}"
+# The host root (no front controller) for endpoints served as top-level scripts
+# under php -S: the OCS entry point (/ocs/v2.php/...).
+ROOT="${BASE%/index.php}"
+TMP="${RUNNER_TEMP:-/tmp}"
+U1="${EXE_E2E_USER1:?EXE_E2E_USER1 is required}"
+P1="${EXE_E2E_PASS1:?EXE_E2E_PASS1 is required}"
+U2="${EXE_E2E_USER2:?EXE_E2E_USER2 is required}"
+P2="${EXE_E2E_PASS2:?EXE_E2E_PASS2 is required}"
+MGMT="$BASE/apps/exelearning/api/preview-session"
+SERVE="$BASE/apps/exelearning/preview"
+
+fail() { echo "E2E FAIL: $*" >&2; exit 1; }
+
+# Authenticated management request. The OCS-APIRequest header makes Nextcloud's
+# passesCSRFCheck() pass without a session cookie or requesttoken (the reliable,
+# cookieless way to drive an authenticated AppFramework route in CI). It does not
+# change the response shape — these are plain (non-OCS) DataResponses.
+api()      { local u="$1" p="$2" m="$3" url="$4"; shift 4; curl -s                       -u "$u:$p" -H 'OCS-APIRequest: true' -X "$m" "$@" "$url"; }
+api_code() { local u="$1" p="$2" m="$3" url="$4"; shift 4; curl -s -o /dev/null -w '%{http_code}' -u "$u:$p" -H 'OCS-APIRequest: true' -X "$m" "$@" "$url"; }
+
+# Build a snapshot ZIP. Args: <output path> then `name=contents` pairs.
+# python3 is used rather than `zip` so the archive contents are exact and the
+# script does not depend on a zip binary being installed on the runner.
+make_zip() {
+	local out="$1"; shift
+	python3 - "$out" "$@" <<-'PY'
+		import sys, zipfile
+		out, *pairs = sys.argv[1:]
+		with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as z:
+		    for pair in pairs:
+		        name, _, body = pair.partition("=")
+		        z.writestr(name, body)
+	PY
+}
+
+# 0. Sanity — Basic auth actually authenticates user1 (so a later 412 is a real
+#    CSRF rejection, not an auth failure hiding behind it).
+who="$(curl -s -u "$U1:$P1" -H 'OCS-APIRequest: true' "$ROOT/ocs/v2.php/cloud/user?format=json" | jq -r '.ocs.data.id // empty' 2>/dev/null || true)"
+[ "$who" = "$U1" ] || fail "Basic auth did not authenticate $U1 (cloud/user id='$who')"
+echo "  ok: Basic auth authenticates $U1"
+
+# 1. CSRF enforced — an AUTHENTICATED management POST WITHOUT the OCS-APIRequest
+#    header (and no requesttoken) trips the CSRF middleware → 412. Proves the
+#    management route is not #[NoCSRFRequired]. The 412 happens in middleware,
+#    before the handler, so no snapshot upload is needed to prove it.
+csrf="$(curl -s -o "$TMP/csrf.txt" -w '%{http_code}' -u "$U1:$P1" -X POST "$MGMT")"
+[ "$csrf" = "412" ] || fail "CSRF proof: expected 412 without the CSRF-safe header, got $csrf (body: $(head -c 200 "$TMP/csrf.txt"))"
+grep -qi 'csrf' "$TMP/csrf.txt" || echo "  note: 412 body did not explicitly mention CSRF: $(head -c 120 "$TMP/csrf.txt")"
+echo "  ok: management enforces CSRF (412 for an authenticated request without the CSRF-safe header/token)"
+
+# 2. Publish a whole-project snapshot → { previewId }.
+make_zip "$TMP/snapshot-v1.zip" \
+	'index.html=<html><body>preview-v1</body></html>' \
+	'content/photo.png=IMGBYTES!'
+resp="$(api "$U1" "$P1" POST "$MGMT" -F "snapshot=@$TMP/snapshot-v1.zip")"
+pid="$(printf '%s' "$resp" | jq -r '.previewId // empty')"
+[ -n "$pid" ] || fail "publish returned no previewId: $resp"
+echo "  ok: published snapshot $pid"
+
+# 3. Serve (authless, NO auth): 200 + opaque sandbox CSP + no allow-same-origin.
+hdrs="$(curl -s -D - -o "$TMP/served.html" "$SERVE/$pid/index.html")"
+printf '%s' "$hdrs" | grep -q '^HTTP/[0-9.]* 200' || fail "serve not 200: $(printf '%s' "$hdrs" | head -1)"
+csp="$(printf '%s' "$hdrs" | grep -i '^content-security-policy:' || true)"
+printf '%s' "$csp" | grep -qi 'sandbox' || fail "serving CSP missing sandbox directive: $csp"
+if printf '%s' "$csp" | grep -qi 'allow-same-origin'; then
+	fail "serving CSP must NOT contain allow-same-origin: $csp"
+fi
+grep -q 'preview-v1' "$TMP/served.html" || fail "served body missing snapshot content"
+echo "  ok: authless serve is 200 with opaque sandbox CSP (no allow-same-origin)"
+
+# 3b. A non-scriptable file from the same snapshot is served too, and without the
+#     sandbox CSP (it is an asset tier, not a document).
+hdrs="$(curl -s -D - -o "$TMP/served.png" "$SERVE/$pid/content/photo.png")"
+printf '%s' "$hdrs" | grep -q '^HTTP/[0-9.]* 200' || fail "asset serve not 200"
+grep -q 'IMGBYTES!' "$TMP/served.png" || fail "asset body mismatch"
+echo "  ok: snapshot assets serve from the same capability"
+
+# 4. Bare capability root → 302 (never inline index.html bytes).
+code="$(curl -s -o /dev/null -w '%{http_code}' "$SERVE/$pid")"
+[ "$code" = "302" ] || fail "bare root expected 302, got $code"
+echo "  ok: bare root 302"
+
+# 5. Replace in place — same capability id, new bytes, and a path the new archive
+#    omits stops resolving (the whole tree is swapped, not merged).
+make_zip "$TMP/snapshot-v2.zip" 'index.html=<html><body>preview-v2</body></html>'
+resp="$(api "$U1" "$P1" POST "$MGMT" -F "snapshot=@$TMP/snapshot-v2.zip" -F "previewId=$pid")"
+[ "$(printf '%s' "$resp" | jq -r '.previewId')" = "$pid" ] || fail "replace changed the capability id: $resp"
+curl -s "$SERVE/$pid/index.html" | grep -q 'preview-v2' || fail "replace did not update the served bytes"
+code="$(curl -s -o /dev/null -w '%{http_code}' "$SERVE/$pid/content/photo.png")"
+[ "$code" = "404" ] || fail "a path the new snapshot omits should 404, got $code"
+echo "  ok: replace-in-place swaps the whole tree under the same capability"
+
+# 6. A REJECTED archive must leave the live snapshot untouched — a bad upload can
+#    never destroy a preview that was working.
+make_zip "$TMP/snapshot-bad.zip" 'page.html=no index here'
+code="$(api_code "$U1" "$P1" POST "$MGMT" -F "snapshot=@$TMP/snapshot-bad.zip" -F "previewId=$pid")"
+[ "$code" = "400" ] || fail "archive without index.html expected 400, got $code"
+curl -s "$SERVE/$pid/index.html" | grep -q 'preview-v2' || fail "a rejected upload clobbered the live snapshot"
+echo "  ok: rejected archive is 400 and leaves the live snapshot intact"
+
+# 7. Owner-scoping — user2 may neither replace nor delete user1's capability.
+code="$(api_code "$U2" "$P2" POST "$MGMT" -F "snapshot=@$TMP/snapshot-v2.zip" -F "previewId=$pid")"
+[ "$code" = "403" ] || fail "cross-user replace expected 403, got $code"
+code="$(api_code "$U2" "$P2" DELETE "$MGMT/$pid")"
+[ "$code" = "403" ] || fail "cross-user delete expected 403, got $code"
+curl -s "$SERVE/$pid/index.html" | grep -q 'preview-v2' || fail "cross-user attempt altered the snapshot"
+echo "  ok: cross-user management is 403 on both publish and delete"
+
+# 8. Owner DELETE → 200, then serve → 404.
+code="$(api_code "$U1" "$P1" DELETE "$MGMT/$pid")"
+[ "$code" = "200" ] || fail "owner delete expected 200, got $code"
+code="$(curl -s -o /dev/null -w '%{http_code}' "$SERVE/$pid/index.html")"
+[ "$code" = "404" ] || fail "serve after delete expected 404, got $code"
+echo "  ok: owner delete 200, serve after delete 404"
+
+echo "Preview API E2E: all checks passed."
diff --git a/tests/js/external-media-bundle.test.ts b/tests/js/external-media-bundle.test.ts
new file mode 100644
index 0000000..f9705e6
--- /dev/null
+++ b/tests/js/external-media-bundle.test.ts
@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * The parent half of the shared bundle, asserted as the artifact this app actually ships.
+ *
+ * `relay-host.ts` drives `window.exeEmbedRelay`, a compatibility facade over the canonical
+ * host. Nothing here would fail if that facade were dropped upstream — the calls would
+ * simply become no-ops and every video would stop being promoted, silently. So the facade
+ * is asserted against the vendored bytes rather than against a mock of them.
+ */
+const VENDORED = join(__dirname, '../../src/embed/exe_external_media')
+const source = readFileSync(join(VENDORED, 'exe-external-media-host.min.js'), 'utf8')
+
+/** Run the classic script the way a browser would, and return what it published. */
+function evaluateBundle(): Record<string, unknown> {
+	const globals = window as unknown as Record<string, unknown>
+	for (const name of ['exeExternalMediaHost', 'exeEmbedRelay', 'exeMediaHost']) delete globals[name]
+	new Function(source).call(window)
+	return globals
+}
+
+describe('vendored external-media host bundle', () => {
+	it('publishes the canonical host and the facade relay-host drives', () => {
+		const globals = evaluateBundle()
+
+		expect(typeof globals.exeExternalMediaHost).toBe('object')
+		// The exact surface src/embed/relay-host.ts calls.
+		expect(typeof (globals.exeEmbedRelay as { init?: unknown })?.init).toBe('function')
+	})
+
+	it('carries the media half the interactive-video iDevice needs', () => {
+		const globals = evaluateBundle()
+
+		expect(typeof (globals.exeMediaHost as { attach?: unknown })?.attach).toBe('function')
+	})
+
+	it('keeps the dual-licence notice through minification', () => {
+		expect(source).toContain('Dual-licensed')
+	})
+
+	it('matches the digest core published for it', async () => {
+		const manifest = JSON.parse(readFileSync(join(VENDORED, 'exe-external-media.manifest.json'), 'utf8'))
+		const { createHash } = await import('node:crypto')
+
+		expect(createHash('sha256').update(source).digest('hex')).toBe(manifest.files.host.sha256)
+	})
+})
diff --git a/tests/js/iframe-renderer.test.ts b/tests/js/iframe-renderer.test.ts
index b829a0f..0a02846 100644
--- a/tests/js/iframe-renderer.test.ts
+++ b/tests/js/iframe-renderer.test.ts
@@ -1,36 +1,59 @@
 import { describe, expect, it } from 'vitest'
 import {
 	buildSandboxedIframe,
+	createAssetIframe,
+	createContentIframe,
 	createPackageIframe,
 } from '../../src/elpx/iframe-renderer'
-import { RUNTIME_PREFIX } from '../../src/elpx/paths'
+import { ASSET_PREFIX, CONTENT_PREFIX, RUNTIME_PREFIX } from '../../src/elpx/paths'
 
 describe('buildSandboxedIframe', () => {
 	it('appends the eXeLearning teacher-mode param to the index src', () => {
-		const iframe = buildSandboxedIframe('/apps/exelearning/asset/42/index.html', 'pkg')
+		const iframe = buildSandboxedIframe('/apps/exelearning/content/tok/index.html', 'pkg')
 		expect(iframe.src).toContain('exe-teacher=1')
-		expect(iframe.src).toContain('/apps/exelearning/asset/42/index.html?exe-teacher=1')
+		expect(iframe.src).toContain('/apps/exelearning/content/tok/index.html?exe-teacher=1')
 	})
 
 	it('uses & when the index src already carries a query string', () => {
-		const iframe = buildSandboxedIframe('/apps/exelearning/asset/42/index.html?foo=bar', 'pkg')
+		const iframe = buildSandboxedIframe('/apps/exelearning/content/tok/index.html?foo=bar', 'pkg')
 		expect(iframe.src).toContain('?foo=bar&exe-teacher=1')
 	})
 
 	it('does not double-append when the param is already present', () => {
-		const iframe = buildSandboxedIframe('/apps/exelearning/asset/42/index.html?exe-teacher=1', 'pkg')
+		const iframe = buildSandboxedIframe('/apps/exelearning/content/tok/index.html?exe-teacher=1', 'pkg')
 		expect(iframe.src.match(/exe-teacher=1/g)).toHaveLength(1)
 	})
 
-	it('sets the sandbox flags and accessible title', () => {
-		const iframe = buildSandboxedIframe('/apps/exelearning/asset/42/index.html', 'My package')
-		expect(iframe.getAttribute('sandbox')).toContain('allow-scripts')
+	it('defaults to the secure opaque sandbox with NO allow-same-origin', () => {
+		const iframe = buildSandboxedIframe('/apps/exelearning/content/tok/index.html', 'My package')
+		const sandbox = iframe.getAttribute('sandbox') ?? ''
+		expect(sandbox).toBe('allow-scripts allow-popups allow-forms')
+		expect(sandbox).not.toContain('allow-same-origin')
+		expect(sandbox).not.toContain('allow-popups-to-escape-sandbox')
 		expect(iframe.title).toBe('My package')
 	})
+
+	it('uses the legacy same-origin sandbox when opaque=false', () => {
+		const iframe = buildSandboxedIframe('/apps/exelearning/runtime/s/index.html', 'pkg', false)
+		expect(iframe.getAttribute('sandbox')).toContain('allow-same-origin')
+	})
+})
+
+describe('createContentIframe', () => {
+	it('builds an opaque /content/{token} index src with the teacher-mode selector', () => {
+		const iframe = createContentIframe({
+			contentBase: CONTENT_PREFIX,
+			token: 'cap-token-123',
+			indexEntry: 'index.html',
+			title: 'pkg',
+		})
+		expect(iframe.src).toContain(`${CONTENT_PREFIX}/cap-token-123/index.html?exe-teacher=1`)
+		expect(iframe.getAttribute('sandbox')).not.toContain('allow-same-origin')
+	})
 })
 
-describe('createPackageIframe', () => {
-	it('builds a runtime index src that exposes the teacher-mode selector', () => {
+describe('createPackageIframe (legacy Service Worker path)', () => {
+	it('builds a same-origin runtime index src', () => {
 		const iframe = createPackageIframe({
 			runtimeBase: RUNTIME_PREFIX,
 			sessionId: 'session-1',
@@ -38,5 +61,19 @@ describe('createPackageIframe', () => {
 			title: 'pkg',
 		})
 		expect(iframe.src).toContain(`${RUNTIME_PREFIX}/session-1/index.html?exe-teacher=1`)
+		expect(iframe.getAttribute('sandbox')).toContain('allow-same-origin')
+	})
+})
+
+describe('createAssetIframe (authenticated server fallback)', () => {
+	it('builds a same-origin asset URL so Nextcloud authentication is retained', () => {
+		const iframe = createAssetIframe({
+			assetBase: ASSET_PREFIX,
+			fileId: 81,
+			indexEntry: 'index.html',
+			title: 'pkg',
+		})
+		expect(iframe.src).toContain(`${ASSET_PREFIX}/81/index.html?exe-teacher=1`)
+		expect(iframe.getAttribute('sandbox')).toContain('allow-same-origin')
 	})
 })
diff --git a/tests/js/paths.test.ts b/tests/js/paths.test.ts
index 709f439..d7effbf 100644
--- a/tests/js/paths.test.ts
+++ b/tests/js/paths.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import {
 	buildAssetUrl,
+	buildContentUrl,
 	buildRuntimeUrl,
 	isExternalUrl,
 	normalizeEntryPath,
@@ -118,3 +119,23 @@ describe('buildAssetUrl', () => {
 		expect(() => buildAssetUrl(base, 1, '../etc/passwd')).toThrow()
 	})
 })
+
+describe('buildContentUrl', () => {
+	const base = '/apps/exelearning/content'
+
+	it('builds an opaque content URL from a capability token and entry', () => {
+		expect(buildContentUrl(base, 'cap-token', 'html/page.html')).toBe(
+			'/apps/exelearning/content/cap-token/html/page.html',
+		)
+	})
+
+	it('encodes the token and each entry segment', () => {
+		expect(buildContentUrl(base, 'a.b_c-d', 'content/Página 1.html')).toBe(
+			'/apps/exelearning/content/a.b_c-d/content/P%C3%A1gina%201.html',
+		)
+	})
+
+	it('refuses unsafe entries', () => {
+		expect(() => buildContentUrl(base, 'tok', '../etc/passwd')).toThrow()
+	})
+})
diff --git a/tests/js/relay-host.test.ts b/tests/js/relay-host.test.ts
new file mode 100644
index 0000000..286fff1
--- /dev/null
+++ b/tests/js/relay-host.test.ts
@@ -0,0 +1,101 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+	clearOverlays,
+	pingEmbeds,
+	reflowOverlays,
+	resetRelayForTests,
+	startMedia,
+	startRelay,
+} from '../../src/embed/relay-host'
+
+type WindowWithBridge = Window & {
+	exeEmbedRelay?: unknown
+	exeExternalMediaHost?: unknown
+}
+
+const w = window as WindowWithBridge
+
+afterEach(() => {
+	resetRelayForTests()
+	delete w.exeEmbedRelay
+	delete w.exeExternalMediaHost
+})
+
+describe('relay-host', () => {
+	it('startRelay inits the embed relay once, in open mode', () => {
+		const instance = { clear: vi.fn(), reflow: vi.fn() }
+		const init = vi.fn().mockReturnValue(instance)
+		w.exeEmbedRelay = { init }
+		startRelay()
+		startRelay()
+		expect(init).toHaveBeenCalledTimes(1)
+		expect(init).toHaveBeenCalledWith({ mode: 'open' })
+	})
+
+	it('passes a custom strict mode + whitelist through to init', () => {
+		const init = vi.fn().mockReturnValue({})
+		w.exeEmbedRelay = { init }
+		startRelay({ mode: 'strict', whitelist: ['player.vimeo.com'] })
+		expect(init).toHaveBeenCalledWith({ mode: 'strict', whitelist: ['player.vimeo.com'] })
+	})
+
+	it('clearOverlays / reflowOverlays drive the relay instance', () => {
+		const instance = { clear: vi.fn(), reflow: vi.fn() }
+		w.exeEmbedRelay = { init: () => instance }
+		startRelay()
+		clearOverlays()
+		reflowOverlays()
+		expect(instance.clear).toHaveBeenCalledOnce()
+		expect(instance.reflow).toHaveBeenCalledOnce()
+	})
+
+	it('pingEmbeds posts the exe-embed request to the iframe window', () => {
+		const postMessage = vi.fn()
+		const iframe = { contentWindow: { postMessage } } as unknown as HTMLIFrameElement
+		pingEmbeds(iframe)
+		expect(postMessage).toHaveBeenCalledWith({ type: 'exe-embed', action: 'request' }, '*')
+	})
+
+	/**
+	 * The media half is adopted SEPARATELY from the embed half (ADR-0024): starting the
+	 * relay overlays declarative embeds, and does nothing for an iDevice that asks the host
+	 * to drive a video. Without this the interactive-video iDevice inside the opaque package
+	 * gets no answer to its handshake and falls back to loading YouTube's SDK, which the
+	 * content CSP blocks — measured here, with the evidence harness, as a silent failure
+	 * every existing assertion sailed straight through.
+	 */
+	it('startMedia attaches the media host to the content iframe', () => {
+		const attachMedia = vi.fn().mockReturnValue({ detach: vi.fn() })
+		w.exeExternalMediaHost = { attachMedia }
+		const iframe = { contentWindow: {} } as unknown as HTMLIFrameElement
+
+		startMedia(iframe)
+
+		expect(attachMedia).toHaveBeenCalledWith(iframe)
+	})
+
+	it('startMedia attaches once per iframe, not once per page', () => {
+		const attachMedia = vi.fn().mockReturnValue({ detach: vi.fn() })
+		w.exeExternalMediaHost = { attachMedia }
+		const first = { contentWindow: {} } as unknown as HTMLIFrameElement
+		const second = { contentWindow: {} } as unknown as HTMLIFrameElement
+
+		startMedia(first)
+		startMedia(first)
+		startMedia(second)
+
+		expect(attachMedia).toHaveBeenCalledTimes(2)
+	})
+
+	it('startMedia is a safe no-op when the host bundle is absent', () => {
+		const iframe = { contentWindow: {} } as unknown as HTMLIFrameElement
+		expect(() => startMedia(iframe)).not.toThrow()
+	})
+
+	it('clear/reflow are safe no-ops when the relay is absent', () => {
+		expect(() => {
+			clearOverlays()
+			reflowOverlays()
+		}).not.toThrow()
+	})
+})