diff --git a/.eslintrc.cjs b/.eslintrc.cjs
index c41d06b..39a34a3 100644
--- a/.eslintrc.cjs
+++ b/.eslintrc.cjs
@@ -18,6 +18,10 @@ module.exports = {
 		'js/',
 		'node_modules/',
 		'vendor/',
+		// Centrally-maintained, byte-synced eXe-core embed/media bridge mirrors
+		// (see scripts/check-embed-sync.mjs). They keep upstream's code style and
+		// module wrapper, so our lint rules do not apply to them.
+		'src/embed/exe_*.js',
 	],
 	rules: {
 		// `void promise` is the canonical TypeScript way of marking a
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index fc2200c..65c426f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -177,3 +177,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/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..41efaa9 100644
--- a/appinfo/routes.php
+++ b/appinfo/routes.php
@@ -21,6 +21,54 @@
 			'verb' => 'GET',
 			'requirements' => ['path' => '.+'],
 		],
+		[
+			'name' => 'content#serve',
+			'url' => '/content/{token}/{path}',
+			'verb' => 'GET',
+			'requirements' => ['token' => '[A-Za-z0-9._~-]+', 'path' => '.+'],
+			'defaults' => ['path' => 'index.html'],
+		],
+		// Editor-preview serving contract v2. 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#uploadAssets',
+			'url' => '/api/preview-session/{previewId}/assets',
+			'verb' => 'POST',
+			'requirements' => ['previewId' => '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'],
+		],
+		[
+			'name' => 'previewSession#publishRevision',
+			'url' => '/api/preview-session/{previewId}/revisions',
+			'verb' => 'POST',
+			'requirements' => ['previewId' => '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'],
+		],
+		[
+			'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..2276ae5 100644
--- a/biome.json
+++ b/biome.json
@@ -16,7 +16,8 @@
 			"!**/coverage/**",
 			"!**/js/**",
 			"!**/exelearning/**",
-			"!**/*.vue"
+			"!**/*.vue",
+			"!**/src/embed/exe_*.js"
 		]
 	},
 	"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..5d3c365
--- /dev/null
+++ b/docs/preview-serving-contract.md
@@ -0,0 +1,294 @@
+# Host-served opaque HTTP preview — serving contract v2
+
+This Nextcloud app is a **preview host** for the eXeLearning editor: it serves
+the *editor preview* of untrusted, in-progress author content over HTTP from an
+**opaque origin**, isolated from the Nextcloud session.
+
+This document is the host-side companion to the canonical contract in eXe core:
+**`doc/development/preview-serving-contract.md`** (repo `exelearning/exelearning`).
+Core is authoritative; if the two disagree, core wins — in particular the sandbox
+CSP string must stay **byte-identical** to core's `previewCspHeader()`.
+
+**Protocol version: 2.** v1 (a full SHA-256 manifest + content-addressed blob
+diff) is removed, not kept alongside. A create-session response without
+`protocolVersion: 2` must surface an error (no silent fallback).
+
+## Why an HTTP transport (and 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 editor preview is served from a **separate,
+authless, cookieless origin** and never through the Service Worker.
+
+## The three layers (why v2)
+
+v2 splits a preview into three layers with different lifecycles so a refresh
+costs `O(changed documents + new assets)` instead of `O(whole project)`:
+
+| Layer | Contents | Lifecycle | Transferred |
+|---|---|---|---|
+| **Fixed installation resources** (1) | official libraries, base iDevice runtimes, base theme files, PDF.js, content CSS, logo, fonts | immutable per installed editor version | **never** — served from the installed static editor distribution, gated by a build manifest |
+| **Session project assets** (2) | author images/audio/video/PDF — anything with an asset identity | immutable per `assetKey`, whole session | **once per session** |
+| **Generated documents** (3) | page HTML, navigation, generated CSS/JS, user theme/iDevice files | change every edit | **only the changed files**, as an atomic revision delta |
+
+Classification is by **provenance, not name**: a resource is *fixed* only when the
+client resolved it from the installation-immutable editor distribution. Custom
+themes, user-installed iDevices and anything embedded in an `.elpx` ride the
+session layers.
+
+## Implementation map
+
+All protocol logic is OCP-free and unit-testable; the controllers are thin
+Nextcloud adapters.
+
+| Concern | Class |
+|---|---|
+| Isolation policy (CSP, scriptable set, Permissions-Policy, MIME, path normalization) | `lib/Service/Preview/PreviewPolicy.php` |
+| Session store (three layers, atomic revisions, budgets, TTL, immutability) | `lib/Service/Preview/PreviewSessionStore.php` |
+| Fixed-resource layer (manifest lookup + containment) | `lib/Service/Preview/FixedResourceManifest.php` |
+| Serving HTTP policy (headers/CSP/cache tiers/Range/304) | `lib/Service/Preview/PreviewServer.php` |
+| Management HTTP policy (ownership gate, status/body mapping) | `lib/Service/Preview/PreviewSessionApi.php` |
+| Authless serving controller | `lib/Controller/PreviewController.php` |
+| Authenticated management controller | `lib/Controller/PreviewSessionController.php` |
+| Idle-TTL cleanup job | `lib/BackgroundJob/PreviewCleanupJob.php` |
+
+## A. Management API (AUTHENTICATED, owner-scoped)
+
+Served under the normal authenticated app routes (CSRF **on** — these are called
+by the embedded editor same-origin, mirroring `editor#save`; they are **not**
+`#[NoCSRFRequired]`). Ownership is scoped to the `IUserSession` user id.
+
+| Method & path | Body | Success |
+|---|---|---|
+| `POST /apps/exelearning/api/preview-session` | – | `201 { previewId, protocolVersion: 2, revision: 0, limits }` |
+| `POST …/preview-session/{previewId}/assets` | multipart: `assets` (JSON `[{key,size}]`), `files[]` index-aligned | `200 { stored, alreadyStored, rejected }` |
+| `POST …/preview-session/{previewId}/revisions` | multipart: `revision` (JSON, below), `files[]` aligned with `writes` | `200 { revision, active: true }` |
+| `DELETE …/preview-session/{previewId}` | – | `200 { success: true }` |
+
+- **Asset keys** match `^[0-9a-fA-F-]{36}@[0-9a-f]{8,64}$` and are **immutable**:
+  re-uploading an existing key returns it in `alreadyStored` and never replaces
+  bytes (a replaced author file gets a new key). The server treats the key as an
+  opaque token — it never hashes asset bytes. Enforced on the buffered bytes; a
+  declared/actual size mismatch rejects that entry.
+- **Revision JSON** (`writes` = paths, index-aligned with `files[]`):
+
+  ```jsonc
+  {
+    "baseRevision": 17,          // the revision the client believes is active
+    "nextRevision": 18,          // must be baseRevision + 1
+    "writes": ["index.html"],    // aligned with files[]
+    "deletes": ["html/old.html"],
+    "assetRefs": { "content/photo.png": "3f2a…@9c41d2e8" },  // FULL map served path → assetKey
+    "fixedRefs": { "libs/jquery/jquery.min.js": "libs/jquery/jquery.min.js" }  // FULL map served path → fixedResourceId
+  }
+  ```
+
+  Validation order: session exists (`404`) → `baseRevision`/`nextRevision`
+  consistent else `409 { reason: "revision-conflict", currentRevision }` → every
+  path normalized/safe else `400` → every `assetRefs` value stored else
+  `422 { reason: "missing-assets", missing }` → every `fixedRefs` value in the
+  fixed manifest else `422 { reason: "unknown-fixed-resources", resources }` →
+  file-count/byte budgets else `413`.
+- **Atomicity.** A revision is published by writing its content-addressed blobs,
+  writing the revision manifest (temp+rename), then swapping the `current`
+  pointer (temp+rename). A concurrent `GET` reads `current` once then an
+  immutable manifest, so it observes revision *N* or *N+1*, never a mixture.
+- **Budgets & TTL.** 30-min idle TTL, 4 sessions/user, 5000 files/session, 200
+  MiB/session, 128 MiB/asset, 2 GiB global (per-user and global caps evict LRU).
+
+## B. Serving route (AUTHLESS capability URL)
+
+```
+GET /apps/exelearning/preview/{previewId}/{path}
+```
+
+- **Authless, cookieless.** The opaque iframe sends no SameSite cookies, so this
+  route does not depend on the session. It is gated solely on the unguessable
+  server-minted `previewId` UUID + idle TTL (Nextcloud's cookieless serving
+  primitive, `#[PublicPage]` + `#[NoCSRFRequired]`). It never emits a session
+  cookie and always answers `Access-Control-Allow-Origin: *` (sound only because
+  it is cookieless — never paired with credentials).
+- `previewId` must match
+  `^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`; else 404.
+- The bare `/preview/{previewId}` **302-redirects** to `{previewId}/index.html`
+  (a relative `Location`, correct under any webroot). It never serves index.html
+  bytes inline — a document served from the bare URL would resolve its relative
+  subresource references against `preview/` (dropping the id segment) and every
+  asset would 404.
+- **Resolution order** (exact-key against the active revision only):
+  `documents[path]` → `assets[assetRefs[path]]` → `fixed[fixedRefs[path]]` → 404.
+  A path only ever names a stored entry; only the server-controlled manifest
+  `path` reaches the filesystem, contained under the distribution root.
+- **Range** on session assets: `Accept-Ranges: bytes`, a satisfiable single
+  range → `206`, a syntactically valid but unsatisfiable single range (e.g.
+  `bytes=99-` past EOF) → `416`. A malformed, multi-range or non-`bytes` header
+  is **ignored** — the server serves a normal `200` full body. **Conditional**:
+  `ETag: "<assetKey>"`, `If-None-Match` → `304`.
+
+### Required response headers (on EVERY response, including 404)
+
+| Header | Value |
+| --- | --- |
+| `X-Content-Type-Options` | `nosniff` |
+| `Referrer-Policy` | `no-referrer` |
+| `Permissions-Policy` | `camera=(), microphone=(), geolocation=(), payment=()` |
+| `Access-Control-Allow-Origin` | `*` (never with credentials) |
+| `Content-Type` | the served file's real MIME (always set explicitly — Nextcloud serves unknown extensions as `text/plain`) |
+
+`Cache-Control` is **tiered by layer**:
+
+| Response | Cache-Control |
+| --- | --- |
+| Generated document (layer 3) | `no-store` |
+| Session asset (layer 2) | `no-cache` (+ `ETag`, `If-None-Match` → 304) |
+| Fixed resource (layer 1) | `private, max-age=31536000` |
+| 404 / errors | `no-store` |
+
+### Sandbox CSP (every scriptable document type, from every layer)
+
+On `text/html`, `image/svg+xml`, `application/xml`, `text/xml` and
+`application/xhtml+xml` — whether the response resolves from the session or the
+fixed layer — add this `Content-Security-Policy` **verbatim** (byte-identical to
+eXe core `previewCspHeader()`; `PreviewPolicy::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'
+```
+
+The leading `sandbox` directive drops the document into an opaque, unique origin
+even when opened top-level (a raw `*.html` **or** `*.svg` in a new tab stays
+opaque — an author SVG served without it runs its inline `<script>` same-origin).
+
+> **Two CSP strings in this app.** The preview CSP above (`PreviewPolicy::CSP`)
+> is a **different** string from `IframeSandbox::contentSecurityPolicy()` used for
+> *published* content. Published content pins `frame-src`/`img-src` to the
+> maintained provider hosts (token-exfiltration hardening for a longer-lived
+> capability token); the editor preview is a short-lived ephemeral capability and
+> matches core's preview CSP verbatim. They are deliberately **not** unified —
+> unifying would either weaken published-content hardening or drift the preview
+> CSP from core. Do not change published-content behaviour to reconcile them.
+
+## The fixed-resource manifest
+
+The fixed layer resolves ids through
+`bundles/preview-fixed-resources.json` inside the installed static editor
+distribution (`js/editor/`, staged by `make download-editor`). eXe core emits it
+into the distribution; `resources[id].path` is relative to the distribution root.
+`FixedResourceManifest` resolves an id by **exact map lookup** (never path
+arithmetic on client input) and reads the file with a containment check.
+
+When the bundled editor predates the manifest (as with the current v4.0.2
+bundle), the file is absent and the **fixed layer is simply disabled**: any
+`fixedRefs` in a revision is rejected with `422 unknown-fixed-resources` and the
+client demotes those refs into the session layers. This is never fatal.
+
+## Storage
+
+Sessions are file-backed under `{datadirectory}/exelearning/preview-sessions/`
+(PHP is request-scoped — an in-memory map cannot survive between the management
+POSTs and the authless GETs). Each session directory holds `meta.json`, a
+`.accessed` TTL/LRU marker, a `current` pointer, `assets/{sha1(key)}`,
+content-addressed `documents/{sha1(bytes)}`, and `revisions/{N}.json`. The store
+requires a POSIX-local directory (atomic rename + link + flock), matching the
+contract's PHP-host note ("atomic pointer swap … rename a `current` marker"). It
+is resolved from the Nextcloud data directory rather than `IAppData` (which may
+be object storage) — the only OCP seam; the store itself is OCP-free.
+
+## Cleanup
+
+`PreviewCleanupJob` (a `TimedJob` registered in `appinfo/info.xml`
+`<background-jobs>`) sweeps idle-expired sessions every 10 minutes; the serving
+route also drops an expired session opportunistically on access, so preview URLs
+stop resolving at the TTL even if cron is starved.
+
+## Editor activation (wired)
+
+The embedded editor is handed a `previewHttp` block in
+`window.__EXE_EMBEDDING_CONFIG__` by `EditorController::iframe()`
+(`previewHttpConfig()`), following the normalized HTTP preview contract:
+
+```jsonc
+{
+  "previewHttp": {
+    "protocolVersion": 2,
+    "managementBaseUrl": "/apps/exelearning/api/preview-session",
+    "servingBaseUrl": "/apps/exelearning/preview",
+    "managementHeaders": { "requesttoken": "<current Nextcloud CSRF token>" }
+  }
+}
+```
+
+- Both URLs are generated **server-side** through `IURLGenerator::linkToRoute`,
+  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 `servingBaseUrl` is derived by generating the bare
+  capability-root URL for a placeholder id and stripping the id segment.
+- `managementHeaders.requesttoken` is the **current Nextcloud CSRF token** — the
+  same encrypted value the standard template layer exposes as `data-requesttoken`
+  and `OC.requestToken` (obtained from
+  `CsrfTokenManager::getToken()->getEncryptedValue()`). It is required because the
+  management routes keep CSRF **on** (they are **not** `#[NoCSRFRequired]`); the
+  editor replays it on every management request.
+
+**CSRF-token durability (audited).** 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; whenever that happens the parent
+Nextcloud page hosting the iframe is itself invalidated and reloads, re-running
+the bootstrap and injecting a fresh token (and the parent's keepalive heartbeat
+keeps the session and `OC.requestToken` alive meanwhile). The injected-token
+approach is therefore **durable**; a postMessage CONFIGURE refresh into the
+iframe is a future nicety, not a correctness requirement.
+- `previewTransport` / `previewBasePath` are **dead vocabulary** — the earlier
+  single-`previewBasePath` idea was never implemented and the two-URL
+  `previewHttp` model replaces it.
+
+**Editor-build dependency.** The endpoints are live, but preview only lights up
+once the app ships a capable editor build — one that carries the
+`HttpPreviewProvider` and emits `bundles/preview-fixed-resources.json` under
+`js/editor/`. The bundled v4.0.2 editor predates the HTTP preview client, so it
+simply ignores `previewHttp` today and the endpoints stay dormant (harmless). No
+server change is needed when that build lands; only `make download-editor` points
+at a newer distribution.
+
+## Conformance
+
+Beyond the CSP drift-check, the shared vectors in
+`tests/fixtures/preview-contract/vectors.json` (vendored verbatim from eXe core)
+are replayed against this app's seams in
+`tests/Unit/Service/Preview/PreviewContractConformanceTest.php`, so protocol
+semantics — not just the CSP string — stay aligned with every other host.
+
+**Vectors re-vendor pending.** The vendored `vectors.json` predates the two
+contract CHANGES above (bare-root `302` and the malformed-Range→`200` rule). It is
+**not** forked here — core re-vendors it once its own vectors carry these steps,
+and this app re-syncs then. The new behaviours are covered directly by
+`PreviewServerTest` in the meantime.
+
+The API-level end-to-end job in [`ci.yml`](../.github/workflows/ci.yml)
+(`tests/e2e/preview-api-e2e.sh`) exercises the real management + serving surface
+against a live Nextcloud served over the built-in php server. It authenticates
+with **HTTP Basic auth** (per-request, cookieless — the browser login form's
+SameSite/session cookies do not round-trip under `php -S`, so a cookie login is
+unreliable there) and still exercises CSRF honestly using Nextcloud's own rule:
+`Request::passesCSRFCheck()` passes when the `OCS-APIRequest` header is present,
+so the positive calls send it, and an **authenticated management POST *without*
+that header (and no requesttoken) is rejected 412 "CSRF check failed"** — the real
+proof that the management routes are not `#[NoCSRFRequired]`. It then asserts the
+create → asset → revision → serve round-trip, the authless serving response
+(`200` + the `sandbox` CSP with no `allow-same-origin`), the bare-root `302`,
+cross-user ownership denial (`403`), a dropped multipart part rejected `400`
+without advancing the revision, and a deleted session serving `404`.
+
+The full **browser** editor-iframe E2E (opening the editor, external video, the
+interactive-video iDevice) stays blocked on a capable editor build and is
+documented as that dependency rather than faked.
diff --git a/docs/secure-iframe-viewer.md b/docs/secure-iframe-viewer.md
new file mode 100644
index 0000000..3eba4f0
--- /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 embed/media bridge mirrors | `src/embed/exe_embed_shim.js`, `exe_embed_relay.js`, `exe_media_policy.js`, `exe_media_host.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_embed_relay.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/docs/testing-http-preview-core-artifact.md b/docs/testing-http-preview-core-artifact.md
new file mode 100644
index 0000000..f1d7b16
--- /dev/null
+++ b/docs/testing-http-preview-core-artifact.md
@@ -0,0 +1,73 @@
+# Testing the HTTP preview with a core pull-request artifact
+
+The Nextcloud adapter already injects Preview Serving Contract v2 configuration and exposes the management and capability routes. A released editor older than `HttpPreviewProvider` ignores that configuration, so browser activation must be tested against a reproducible static-editor artifact from the target eXeLearning core commit.
+
+## Build one canonical editor artifact
+
+From the eXeLearning core checkout:
+
+```bash
+make bundle
+make build-static
+```
+
+Verify that the static distribution contains:
+
+```text
+public/app/workarea/interface/elements/preview/HttpPreviewProvider.js
+public/app/workarea/interface/elements/preview/StaticServiceWorkerPreviewProvider.js
+public/bundles/preview-fixed-resources.json
+```
+
+It must not contain the removed `SrcdocPreviewProvider` or `srcdocInliner` files.
+
+Archive the distribution once and record its SHA-256. Use the same archive in every LMS/CMS integration test so transport behavior cannot drift between host builds.
+
+## Install it in the Nextcloud development environment
+
+Replace only the generated embedded-editor distribution used by the development container. Do not commit the generated editor bundle to this application repository.
+
+Run the browser test with a normal Nextcloud cookie session. Basic-auth API coverage remains useful, but it does not prove that the embedded editor sends the current `requesttoken` or that the iframe is configured correctly.
+
+Verify this complete flow:
+
+1. The editor bootstrap injects protocol version 2, management base, serving base, and `requesttoken`.
+2. `POST /apps/exelearning/api/preview-session` creates an owner-scoped session.
+3. New assets are uploaded once.
+4. Revision 1 is published atomically.
+5. The iframe loads `/apps/exelearning/preview/{previewId}/index.html`.
+6. The iframe sandbox omits `allow-same-origin`.
+7. Scriptable serving responses include the sandbox CSP.
+8. Editing one page publishes only changed generated documents.
+9. Serving requests omit credentials.
+10. Management requests retain the Nextcloud cookie and `requesttoken`.
+11. A missing or invalid request token is rejected.
+12. Session expiry or process cleanup is recovered through a new session after `404`.
+
+Also cover page navigation, external media, a large single-range asset response, a dropped multipart part, wrong-owner management access, and cleanup.
+
+## Static Service Worker escape hatch
+
+An embedded Nextcloud editor must never use the static Service Worker transport. A development-only php-wasm environment may opt in only with both fields:
+
+```jsonc
+{
+  "previewTransport": "static-service-worker",
+  "allowUnsafeEmbeddedPreview": true
+}
+```
+
+`previewTransport` alone is rejected. This mode is same-origin, is not a security sandbox, and must not be enabled in production.
+
+## Merge evidence
+
+Record in the PR:
+
+- core commit SHA;
+- editor archive SHA-256;
+- Nextcloud and PHP versions;
+- browser version;
+- captured management and serving requests;
+- sandbox and CSP assertions;
+- CSRF-negative result;
+- proof that unchanged assets were not retransmitted.
diff --git a/lib/AppInfo/Application.php b/lib/AppInfo/Application.php
index d7a6019..a0af50a 100644
--- a/lib/AppInfo/Application.php
+++ b/lib/AppInfo/Application.php
@@ -5,11 +5,18 @@
 namespace OCA\ExeLearning\AppInfo;
 
 use OCA\ExeLearning\Preview\ElpxPreviewProvider;
+use OCA\ExeLearning\Service\ContentTokenService;
+use OCA\ExeLearning\Service\IframeSandbox;
+use OCA\ExeLearning\Service\Preview\FixedResourceManifest;
+use OCA\ExeLearning\Service\Preview\PreviewSessionLimits;
+use OCA\ExeLearning\Service\Preview\PreviewSessionStore;
 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 +64,95 @@ 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, ''),
+			));
+		});
+
+		// Editor-preview serving contract v2 (docs/preview-serving-contract.md).
+		// The file-backed session store needs a POSIX-local directory (atomic
+		// rename + link + flock), 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,
+		// PreviewSessionApi and the controllers auto-wire from these two.
+		$context->registerService(PreviewSessionStore::class, static function (ContainerInterface $c): PreviewSessionStore {
+			$config = $c->get(IConfig::class);
+			$dataDir = (string)$config->getSystemValue('datadirectory', '');
+			$base = $dataDir !== '' ? $dataDir : sys_get_temp_dir();
+			$root = rtrim($base, '/') . '/' . self::APP_ID . '/preview-sessions';
+			return new PreviewSessionStore($root, new PreviewSessionLimits());
+		});
+
+		// The fixed-installation-resource layer resolves ids through the manifest
+		// (`bundles/preview-fixed-resources.json`) inside the installed static
+		// editor distribution. When the bundled editor predates the manifest the
+		// layer is simply disabled (revisions referencing fixed ids get 422 and
+		// the client demotes them) — never fatal.
+		$context->registerService(FixedResourceManifest::class, static function (): FixedResourceManifest {
+			return new FixedResourceManifest(dirname(__DIR__, 2) . '/js/editor');
+		});
+	}
+
+	/**
+	 * 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..00f1c28
--- /dev/null
+++ b/lib/BackgroundJob/PreviewCleanupJob.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\BackgroundJob;
+
+use OCA\ExeLearning\Service\Preview\PreviewSessionStore;
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\BackgroundJob\TimedJob;
+
+/**
+ * Periodically sweeps idle-expired preview sessions from disk (serving contract
+ * v2, TTL bound). Registered in appinfo/info.xml `<background-jobs>`. A
+ * belt-and-braces measure: the serving route also drops an expired session
+ * 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 PreviewSessionStore $store,
+	) {
+		parent::__construct($time);
+		// Sessions 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..c964b0a
--- /dev/null
+++ b/lib/Controller/ContentController.php
@@ -0,0 +1,128 @@
+<?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\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 mirror asset 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.
+	 */
+	private function shimSource(): ?string {
+		$path = __DIR__ . '/../../src/embed/exe_embed_shim.js';
+		if (!is_file($path)) {
+			return null;
+		}
+		$source = file_get_contents($path);
+		return $source === false ? null : $source;
+	}
+
+	/** 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..3a1b8b4 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 `previewHttp` block that wires the HTTP editor-preview
+	 *    transport (serving contract v2) — see {@see previewHttpConfig()}.
 	 *  - 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);
 
+		$previewHttp = json_encode($this->previewHttpConfig(), 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],previewHttp:' . $previewHttp . '});'
 			. '})();</script>';
 
 		// The resilience shim must be installed before any editor script
@@ -292,6 +298,65 @@ public function iframe(): DataDisplayResponse|DataResponse {
 		return $response;
 	}
 
+	/**
+	 * The `previewHttp` block handed to the embedded editor so it can drive the
+	 * HTTP editor-preview transport (serving contract v2). Shape frozen by the
+	 * normalized contract: `{ protocolVersion, managementBaseUrl, servingBaseUrl,
+	 * 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{protocolVersion:int,managementBaseUrl:string,servingBaseUrl:string,managementHeaders:object}
+	 */
+	private function previewHttpConfig(): array {
+		$managementBaseUrl = $this->urlGenerator->linkToRoute(Application::APP_ID . '.previewSession.create');
+
+		// 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.
+		$sampleId = '00000000-0000-4000-8000-000000000000';
+		$sampleUrl = $this->urlGenerator->linkToRoute(
+			Application::APP_ID . '.preview.serveRoot',
+			['previewId' => $sampleId],
+		);
+		$servingBaseUrl = str_ends_with($sampleUrl, '/' . $sampleId)
+			? substr($sampleUrl, 0, -(strlen($sampleId) + 1))
+			: $sampleUrl;
+
+		return [
+			'protocolVersion' => 2,
+			'managementBaseUrl' => $managementBaseUrl,
+			'servingBaseUrl' => $servingBaseUrl,
+			'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..aa7e765
--- /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
+ * (serving contract v2 — 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..bd69bd7
--- /dev/null
+++ b/lib/Controller/PreviewSessionController.php
@@ -0,0 +1,220 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Controller;
+
+use OCA\ExeLearning\Service\Preview\PreviewSessionApi;
+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 editor preview sessions
+ * (serving contract v2). 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.
+ *
+ * All protocol semantics live in {@see PreviewSessionApi} (OCP-free); this
+ * controller only reads the multipart request and the authenticated user, then
+ * maps the {@see \OCA\ExeLearning\Service\Preview\ApiResult} onto a DataResponse.
+ */
+class PreviewSessionController extends Controller {
+	public function __construct(
+		string $appName,
+		IRequest $request,
+		private readonly IUserSession $userSession,
+		private readonly PreviewSessionApi $api,
+	) {
+		parent::__construct($appName, $request);
+	}
+
+	/** POST /apps/exelearning/api/preview-session */
+	#[NoAdminRequired]
+	public function create(): DataResponse {
+		$userId = $this->currentUserId();
+		if ($userId === null) {
+			return $this->unauthenticated();
+		}
+		$result = $this->api->create($userId);
+		return new DataResponse($result->body, $result->status);
+	}
+
+	/**
+	 * POST /apps/exelearning/api/preview-session/{previewId}/assets
+	 *
+	 * multipart: `assets` = JSON `[{ key, size }]`, `files[]` index-aligned.
+	 */
+	#[NoAdminRequired]
+	public function uploadAssets(string $previewId): DataResponse {
+		$userId = $this->currentUserId();
+		if ($userId === null) {
+			return $this->unauthenticated();
+		}
+		$declared = $this->decodeJsonParam('assets');
+		$files = $this->uploadedFileBytes('files');
+		$entries = [];
+		foreach ($declared as $index => $meta) {
+			if (!is_array($meta)) {
+				continue;
+			}
+			$entries[] = [
+				'key' => (string)($meta['key'] ?? ''),
+				'declaredSize' => (int)($meta['size'] ?? -1),
+				'bytes' => $files[$index] ?? '',
+			];
+		}
+		$result = $this->api->uploadAssets($previewId, $userId, $entries);
+		return new DataResponse($result->body, $result->status);
+	}
+
+	/**
+	 * POST /apps/exelearning/api/preview-session/{previewId}/revisions
+	 *
+	 * multipart: `revision` = JSON `{ baseRevision, nextRevision, writes:[paths],
+	 * deletes, assetRefs, fixedRefs }`, `files[]` index-aligned with `writes`.
+	 */
+	#[NoAdminRequired]
+	public function publishRevision(string $previewId): DataResponse {
+		$userId = $this->currentUserId();
+		if ($userId === null) {
+			return $this->unauthenticated();
+		}
+		$revision = $this->decodeJsonParam('revision');
+		$parts = $this->uploadedFileParts('files');
+		$writePaths = is_array($revision['writes'] ?? null) ? array_values($revision['writes']) : [];
+
+		// Strict alignment: every declared write MUST have a healthy uploaded part
+		// (present, UPLOAD_ERR_OK, readable). A dropped/failed/unreadable part — or
+		// a part/write count mismatch — rejects the ENTIRE batch with 400 before
+		// any staging, so a silently-empty document (`sha1('')`, size 0) can never
+		// be published. The revision pointer is untouched; a subsequent GET keeps
+		// serving the previous revision.
+		if (count($parts) !== count($writePaths)) {
+			return new DataResponse(
+				['error' => 'Revision upload incomplete: ' . count($writePaths)
+					. ' write(s) declared but ' . count($parts) . ' file part(s) received'],
+				Http::STATUS_BAD_REQUEST,
+			);
+		}
+		$writes = [];
+		foreach ($writePaths as $index => $path) {
+			if (!$parts[$index]['ok']) {
+				return new DataResponse(
+					['error' => 'Revision upload incomplete: missing or unreadable file part for write #' . $index],
+					Http::STATUS_BAD_REQUEST,
+				);
+			}
+			$writes[] = ['path' => (string)$path, 'bytes' => $parts[$index]['bytes']];
+		}
+		$meta = [
+			'baseRevision' => (int)($revision['baseRevision'] ?? -1),
+			'nextRevision' => (int)($revision['nextRevision'] ?? -1),
+			'writes' => $writes,
+			'deletes' => is_array($revision['deletes'] ?? null) ? array_values($revision['deletes']) : [],
+			'assetRefs' => is_array($revision['assetRefs'] ?? null) ? $revision['assetRefs'] : [],
+			'fixedRefs' => is_array($revision['fixedRefs'] ?? null) ? $revision['fixedRefs'] : [],
+		];
+		$result = $this->api->publishRevision($previewId, $userId, $meta);
+		return new DataResponse($result->body, $result->status);
+	}
+
+	/** DELETE /apps/exelearning/api/preview-session/{previewId} */
+	#[NoAdminRequired]
+	public function delete(string $previewId): DataResponse {
+		$userId = $this->currentUserId();
+		if ($userId === null) {
+			return $this->unauthenticated();
+		}
+		$result = $this->api->delete($previewId, $userId);
+		return new DataResponse($result->body, $result->status);
+	}
+
+	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);
+	}
+
+	/**
+	 * Decode a JSON-string form field into an array (empty array on absence or
+	 * malformed JSON).
+	 *
+	 * @return array<mixed>
+	 */
+	private function decodeJsonParam(string $name): array {
+		$raw = $this->request->getParam($name);
+		if (!is_string($raw) || $raw === '') {
+			return [];
+		}
+		$decoded = json_decode($raw, true);
+		return is_array($decoded) ? $decoded : [];
+	}
+
+	/**
+	 * Read the `files[]` multipart parts (index-aligned) into a list of byte
+	 * strings, mapping a missing/failed/unreadable part to an empty string. Used
+	 * by the asset path, where the store rejects a dropped part via its
+	 * declared/actual size guard.
+	 *
+	 * @return list<string>
+	 */
+	private function uploadedFileBytes(string $field): array {
+		return array_map(
+			static fn (array $part): string => $part['bytes'],
+			$this->uploadedFileParts($field),
+		);
+	}
+
+	/**
+	 * Read the `files[]` multipart parts (index-aligned) with their upload
+	 * health, so a caller can reject a batch when a part is missing, errored or
+	 * unreadable. Handles both the array shape (`files[]`, multiple parts) and the
+	 * scalar shape (a single part).
+	 *
+	 * A part is `ok` only when `$_FILES[...]['error']` is `UPLOAD_ERR_OK`, the
+	 * `tmp_name` is a genuine uploaded file, and its bytes read back. A genuinely
+	 * empty but successfully uploaded file is `ok` with empty bytes; a
+	 * dropped/failed/unreadable part is `ok=false` — the distinction the revision
+	 * path needs and that a plain byte string cannot carry.
+	 *
+	 * @return list<array{ok:bool,bytes:string}>
+	 */
+	private function uploadedFileParts(string $field): array {
+		$uploaded = $this->request->getUploadedFile($field);
+		if (!is_array($uploaded) || !isset($uploaded['tmp_name'])) {
+			return [];
+		}
+		$tmpNames = $uploaded['tmp_name'];
+		$errors = $uploaded['error'] ?? UPLOAD_ERR_NO_FILE;
+		if (!is_array($tmpNames)) {
+			$tmpNames = [$tmpNames];
+			$errors = [$errors];
+		}
+		$parts = [];
+		foreach ($tmpNames as $index => $tmpName) {
+			$error = is_array($errors) ? ($errors[$index] ?? UPLOAD_ERR_NO_FILE) : $errors;
+			if ((int)$error !== UPLOAD_ERR_OK || !is_string($tmpName) || $tmpName === '' || !is_uploaded_file($tmpName)) {
+				$parts[] = ['ok' => false, 'bytes' => ''];
+				continue;
+			}
+			$content = file_get_contents($tmpName);
+			if ($content === false) {
+				$parts[] = ['ok' => false, 'bytes' => ''];
+				continue;
+			}
+			$parts[] = ['ok' => true, 'bytes' => $content];
+		}
+		return $parts;
+	}
+}
diff --git a/lib/Controller/ViewController.php b/lib/Controller/ViewController.php
index 87ac8a1..2d29d85 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'),
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..372f0bc
--- /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 shim (exe_embed_shim.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/IframeSandbox.php b/lib/Service/IframeSandbox.php
new file mode 100644
index 0000000..0b38e3d
--- /dev/null
+++ b/lib/Service/IframeSandbox.php
@@ -0,0 +1,150 @@
+<?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_embed_relay.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;
+	}
+}
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/ApiResult.php b/lib/Service/Preview/ApiResult.php
new file mode 100644
index 0000000..a8c7297
--- /dev/null
+++ b/lib/Service/Preview/ApiResult.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service\Preview;
+
+/**
+ * Framework-agnostic description of a management-API response.
+ *
+ * {@see PreviewSessionApi} produces these from pure logic;
+ * {@see \OCA\ExeLearning\Controller\PreviewSessionController} maps them onto a
+ * `DataResponse`. This keeps the full protocol semantics (status codes,
+ * 409/422 shapes, the create-session `limits` block) OCP-free and testable.
+ */
+final class ApiResult {
+	/**
+	 * @param int $status HTTP status code.
+	 * @param array<string,mixed> $body JSON response body.
+	 */
+	public function __construct(
+		public readonly int $status,
+		public readonly array $body,
+	) {
+	}
+}
diff --git a/lib/Service/Preview/FixedResourceManifest.php b/lib/Service/Preview/FixedResourceManifest.php
new file mode 100644
index 0000000..9ec7615
--- /dev/null
+++ b/lib/Service/Preview/FixedResourceManifest.php
@@ -0,0 +1,159 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service\Preview;
+
+/**
+ * Resolver for the **fixed installation-resource** layer (layer 1) of the
+ * preview serving contract.
+ *
+ * The fixed layer is served straight from the host's installed static editor
+ * distribution and is enumerated by a build manifest
+ * (`bundles/preview-fixed-resources.json`) that eXe core emits into the
+ * distribution. It is the ONLY authority for what the serving route may resolve
+ * outside a session:
+ *
+ *  - {@see self::has()} — is $id enumerated by the manifest? (revision validation)
+ *  - {@see self::get()} — read the file at `resources[$id].path` under the
+ *    distribution root, with a containment check. Never path-arithmetic on
+ *    client input: only the server-controlled manifest `path` reaches the disk.
+ *
+ * Provenance, not name: the manifest lists base (repo-shipped) libraries,
+ * base iDevice runtimes, base theme files, PDF.js, content CSS, the logo and
+ * global fonts. Custom themes, user-installed iDevices and anything embedded in
+ * an `.elpx` are never listed — they ride the session layers.
+ *
+ * When the manifest is ABSENT (e.g. an older bundled editor that predates it),
+ * the fixed layer is simply disabled: {@see self::has()} is always false, so any
+ * `fixedRefs` in a revision is rejected with `422 unknown-fixed-resources` and
+ * the client demotes those refs into the session layers. This is never fatal.
+ *
+ * OCP-free: the distribution root is an injected filesystem path and I/O goes
+ * through injected callables, so the whole resolver is unit-testable against a
+ * throwaway root (which is also how the conformance vectors materialize their
+ * fixed resources).
+ */
+final class FixedResourceManifest {
+	private const MANIFEST_RELATIVE_PATH = 'bundles/preview-fixed-resources.json';
+
+	/** @var callable(string):(string|false) */
+	private $reader;
+
+	/** @var callable(string):bool */
+	private $exists;
+
+	/**
+	 * Lazily-parsed `id => ['path' => string, 'size' => int]` map, or null until
+	 * first access. An empty map means "manifest absent or unreadable".
+	 *
+	 * @var array<string,array{path:string,size:int}>|null
+	 */
+	private ?array $resources = null;
+
+	/**
+	 * @param string $distRoot Absolute path to the installed editor distribution
+	 *                         root (e.g. `<app>/js/editor`). Manifest `path`
+	 *                         values are resolved relative to it.
+	 * @param (callable(string):(string|false))|null $reader File reader (defaults
+	 *                                                       to file_get_contents).
+	 * @param (callable(string):bool)|null $exists is_file probe (defaults to is_file).
+	 */
+	public function __construct(
+		private readonly string $distRoot,
+		?callable $reader = null,
+		?callable $exists = null,
+	) {
+		$this->reader = $reader ?? static fn (string $path): string|false => @file_get_contents($path);
+		$this->exists = $exists ?? static fn (string $path): bool => is_file($path);
+	}
+
+	/** Whether $id is enumerated by the manifest. */
+	public function has(string $id): bool {
+		return isset($this->load()[$id]);
+	}
+
+	/**
+	 * Read the file backing $id, or null when the id is unknown, the file is
+	 * missing/unreadable, or the resolved path escapes the distribution root.
+	 *
+	 * @return array{bytes:string,size:int}|null
+	 */
+	public function get(string $id): ?array {
+		$entry = $this->load()[$id] ?? null;
+		if ($entry === null) {
+			return null;
+		}
+		$resolved = $this->resolveContained($entry['path']);
+		if ($resolved === null || !($this->exists)($resolved)) {
+			return null;
+		}
+		$bytes = ($this->reader)($resolved);
+		if ($bytes === false) {
+			return null;
+		}
+		return ['bytes' => $bytes, 'size' => strlen($bytes)];
+	}
+
+	/**
+	 * Parse the manifest once. Any structural problem (missing file, invalid
+	 * JSON, wrong shape) yields an empty map — the fixed layer is disabled, never
+	 * an error.
+	 *
+	 * @return array<string,array{path:string,size:int}>
+	 */
+	private function load(): array {
+		if ($this->resources !== null) {
+			return $this->resources;
+		}
+		$this->resources = [];
+		$manifestPath = $this->distRoot . '/' . self::MANIFEST_RELATIVE_PATH;
+		if (!($this->exists)($manifestPath)) {
+			return $this->resources;
+		}
+		$raw = ($this->reader)($manifestPath);
+		if ($raw === false) {
+			return $this->resources;
+		}
+		$decoded = json_decode($raw, true);
+		if (!is_array($decoded) || !isset($decoded['resources']) || !is_array($decoded['resources'])) {
+			return $this->resources;
+		}
+		foreach ($decoded['resources'] as $id => $entry) {
+			if (!is_string($id) || !is_array($entry) || !isset($entry['path']) || !is_string($entry['path'])) {
+				continue;
+			}
+			$this->resources[$id] = [
+				'path' => $entry['path'],
+				'size' => isset($entry['size']) && is_int($entry['size']) ? $entry['size'] : 0,
+			];
+		}
+		return $this->resources;
+	}
+
+	/**
+	 * Resolve a manifest-declared path under the distribution root and confirm
+	 * it stays contained (rejects `..`, absolute paths and symlink escapes).
+	 * Returns the absolute path or null.
+	 */
+	private function resolveContained(string $relative): ?string {
+		if (str_contains($relative, "\0")) {
+			return null;
+		}
+		$normalized = PreviewPolicy::normalizePath($relative);
+		if ($normalized === null) {
+			return null;
+		}
+		$candidate = $this->distRoot . '/' . $normalized;
+		$realRoot = realpath($this->distRoot);
+		$realCandidate = realpath($candidate);
+		if ($realRoot === false || $realCandidate === false) {
+			return null;
+		}
+		$prefix = rtrim($realRoot, '/') . '/';
+		if ($realCandidate !== $realRoot && !str_starts_with($realCandidate, $prefix)) {
+			return null;
+		}
+		return $realCandidate;
+	}
+}
diff --git a/lib/Service/Preview/PreviewPolicy.php b/lib/Service/Preview/PreviewPolicy.php
new file mode 100644
index 0000000..6dfbc43
--- /dev/null
+++ b/lib/Service/Preview/PreviewPolicy.php
@@ -0,0 +1,219 @@
+<?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}$/';
+
+	/**
+	 * Asset-key wire format: `{assetId}@{contentHashPrefix}` — a 36-char
+	 * UUID-like id plus 8-64 hex chars of the content hash the project model
+	 * already stores. The server validates the shape and treats the key as an
+	 * opaque token; it NEVER hashes asset bytes.
+	 */
+	public const ASSET_KEY_RE = '/^[0-9a-fA-F-]{36}@[0-9a-f]{8,64}$/';
+
+	/**
+	 * 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;
+	}
+
+	/** Whether $key is a well-formed asset key. */
+	public static function isValidAssetKey(string $key): bool {
+		return preg_match(self::ASSET_KEY_RE, $key) === 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..62aff02
--- /dev/null
+++ b/lib/Service/Preview/PreviewServer.php
@@ -0,0 +1,234 @@
+<?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 PreviewSessionStore} + {@see FixedResourceManifest}:
+ * it validates the capability id, resolves the three layers, 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 from any layer. It returns a {@see PreviewResponse} value
+ * object so the whole policy is unit-testable and vector-replayable without a
+ * Nextcloud server; {@see \OCA\ExeLearning\Controller\PreviewController} is the
+ * thin adapter onto `DataDisplayResponse`.
+ */
+final class PreviewServer {
+	public function __construct(
+		private readonly PreviewSessionStore $store,
+		private readonly FixedResourceManifest $fixed,
+	) {
+	}
+
+	/**
+	 * 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, $this->fixed);
+		if ($file === null) {
+			return $this->notFound();
+		}
+
+		return match ($file['kind']) {
+			'asset' => $this->serveAsset($file, $ifNoneMatch, $range),
+			'fixed' => $this->serveBytes($file, 'private, max-age=31536000'),
+			default => $this->serveBytes($file, 'no-store'),
+		};
+	}
+
+	/**
+	 * 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 and vector-replayable. Contract v2.1 §4.
+	 */
+	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, '');
+	}
+
+	/**
+	 * Document (layer 3, `no-store`) or fixed resource (layer 1, immutable and
+	 * cacheable). Both may be scriptable and then carry the sandbox CSP.
+	 *
+	 * @param array{contentType:string,isScriptable:bool,bytes?:string} $file
+	 */
+	private function serveBytes(array $file, string $cacheControl): PreviewResponse {
+		$headers = $this->baseHeaders();
+		$headers['Content-Type'] = $file['contentType'];
+		$headers['Cache-Control'] = $cacheControl;
+		if ($file['isScriptable']) {
+			$headers['Content-Security-Policy'] = PreviewPolicy::CSP;
+		}
+		return new PreviewResponse(200, $headers, $file['bytes'] ?? '');
+	}
+
+	/**
+	 * Session project asset (layer 2): revalidated (`no-cache`) with an ETag,
+	 * `Accept-Ranges: bytes`, `If-None-Match` → 304 and single-range 206/416.
+	 *
+	 * @param array{contentType:string,isScriptable:bool,filePath:string,size:int,etag:string} $file
+	 */
+	private function serveAsset(array $file, ?string $ifNoneMatch, ?string $range): PreviewResponse {
+		$etag = '"' . $file['etag'] . '"';
+
+		if ($ifNoneMatch !== null && trim($ifNoneMatch) === $etag) {
+			$headers = $this->baseHeaders();
+			$headers['Cache-Control'] = 'no-cache';
+			$headers['ETag'] = $etag;
+			return new PreviewResponse(304, $headers, '');
+		}
+
+		$size = $file['size'];
+		$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 = $this->baseHeaders();
+			$headers['Content-Type'] = $file['contentType'];
+			$headers['Cache-Control'] = 'no-cache';
+			$headers['ETag'] = $etag;
+			$headers['Accept-Ranges'] = 'bytes';
+			$headers['Content-Range'] = 'bytes */' . $size;
+			return new PreviewResponse(416, $headers, '');
+		}
+		if ($parsed !== null) {
+			[$start, $end] = [$parsed['start'], $parsed['end']];
+			$length = $end - $start + 1;
+			$headers = $this->baseHeaders();
+			$headers['Content-Type'] = $file['contentType'];
+			$headers['Cache-Control'] = 'no-cache';
+			$headers['ETag'] = $etag;
+			$headers['Accept-Ranges'] = 'bytes';
+			$headers['Content-Range'] = 'bytes ' . $start . '-' . $end . '/' . $size;
+			$headers['Content-Length'] = (string)$length;
+			if ($file['isScriptable']) {
+				$headers['Content-Security-Policy'] = PreviewPolicy::CSP;
+			}
+			return new PreviewResponse(206, $headers, $this->readSlice($file['filePath'], $start, $length));
+		}
+
+		$headers = $this->baseHeaders();
+		$headers['Content-Type'] = $file['contentType'];
+		$headers['Cache-Control'] = 'no-cache';
+		$headers['ETag'] = $etag;
+		$headers['Accept-Ranges'] = 'bytes';
+		if ($file['isScriptable']) {
+			$headers['Content-Security-Policy'] = PreviewPolicy::CSP;
+		}
+		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/PreviewSessionApi.php b/lib/Service/Preview/PreviewSessionApi.php
new file mode 100644
index 0000000..0c5abb0
--- /dev/null
+++ b/lib/Service/Preview/PreviewSessionApi.php
@@ -0,0 +1,112 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service\Preview;
+
+/**
+ * Management-API policy for preview sessions (the authenticated, owner-scoped
+ * surface: create / upload assets / publish revision / delete).
+ *
+ * Pure logic over {@see PreviewSessionStore} + {@see FixedResourceManifest}: it
+ * performs the ownership gate (404 for a missing session, 403 for someone else's)
+ * and maps the store's semantic results onto the contract's wire bodies (the
+ * create-session `protocolVersion`/`revision`/`limits` block, `409
+ * revision-conflict`, `422 missing-assets` / `unknown-fixed-resources`). It
+ * returns {@see ApiResult} value objects so the full protocol is unit-testable
+ * and vector-replayable without a Nextcloud server;
+ * {@see \OCA\ExeLearning\Controller\PreviewSessionController} is the thin adapter
+ * that reads the multipart request and the authenticated user id.
+ */
+final class PreviewSessionApi {
+	/** Serving-contract protocol version negotiated at session creation. */
+	public const PROTOCOL_VERSION = 2;
+
+	public function __construct(
+		private readonly PreviewSessionStore $store,
+		private readonly FixedResourceManifest $fixed,
+	) {
+	}
+
+	/** Create a session owned by $ownerUserId. */
+	public function create(string $ownerUserId): ApiResult {
+		$previewId = $this->store->create($ownerUserId);
+		return new ApiResult(201, [
+			'previewId' => $previewId,
+			'protocolVersion' => self::PROTOCOL_VERSION,
+			'revision' => 0,
+			'limits' => $this->store->limits()->forWire(),
+		]);
+	}
+
+	/**
+	 * Upload session assets (immutable per key).
+	 *
+	 * @param list<array{key:string,declaredSize:int,bytes:string}> $entries
+	 */
+	public function uploadAssets(string $previewId, string $ownerUserId, array $entries): ApiResult {
+		$gate = $this->ownershipGate($previewId, $ownerUserId);
+		if ($gate !== null) {
+			return $gate;
+		}
+		$result = $this->store->storeAssets($previewId, $entries);
+		return new ApiResult(200, $result);
+	}
+
+	/**
+	 * Publish a revision (atomic, optimistic-concurrency).
+	 *
+	 * @param array{baseRevision:int,nextRevision:int,writes:list<array{path:string,bytes:string}>,deletes:list<string>,assetRefs:array<string,string>,fixedRefs:array<string,string>} $meta
+	 */
+	public function publishRevision(string $previewId, string $ownerUserId, array $meta): ApiResult {
+		$gate = $this->ownershipGate($previewId, $ownerUserId);
+		if ($gate !== null) {
+			return $gate;
+		}
+		$result = $this->store->applyRevision($previewId, $meta, $this->fixed);
+		return match ($result['status']) {
+			200 => new ApiResult(200, ['revision' => $result['revision'], 'active' => true]),
+			409 => new ApiResult(409, ['reason' => 'revision-conflict', 'currentRevision' => $result['currentRevision']]),
+			422 => new ApiResult(422, $this->unprocessableBody($result)),
+			413 => new ApiResult(413, ['error' => $result['message'] ?? 'Preview storage budget exceeded']),
+			500 => new ApiResult(500, ['error' => $result['message'] ?? 'Failed to persist revision']),
+			default => new ApiResult(400, ['error' => $result['message'] ?? 'Bad request']),
+		};
+	}
+
+	/** Delete a session. */
+	public function delete(string $previewId, string $ownerUserId): ApiResult {
+		$gate = $this->ownershipGate($previewId, $ownerUserId);
+		if ($gate !== null) {
+			return $gate;
+		}
+		$this->store->delete($previewId);
+		return new ApiResult(200, ['success' => true]);
+	}
+
+	/**
+	 * 404 for a missing session, 403 for someone else's, null when the caller
+	 * owns it.
+	 */
+	private function ownershipGate(string $previewId, string $ownerUserId): ?ApiResult {
+		$owner = $this->store->ownerOf($previewId);
+		if ($owner === null) {
+			return new ApiResult(404, ['error' => 'Preview session not found']);
+		}
+		if ($owner !== $ownerUserId) {
+			return new ApiResult(403, ['error' => 'Access denied']);
+		}
+		return null;
+	}
+
+	/**
+	 * @param array{reason?:string,missing?:list<string>,resources?:list<string>} $result
+	 * @return array<string,mixed>
+	 */
+	private function unprocessableBody(array $result): array {
+		if (($result['reason'] ?? '') === 'missing-assets') {
+			return ['reason' => 'missing-assets', 'missing' => $result['missing'] ?? []];
+		}
+		return ['reason' => 'unknown-fixed-resources', 'resources' => $result['resources'] ?? []];
+	}
+}
diff --git a/lib/Service/Preview/PreviewSessionLimits.php b/lib/Service/Preview/PreviewSessionLimits.php
new file mode 100644
index 0000000..3ea4502
--- /dev/null
+++ b/lib/Service/Preview/PreviewSessionLimits.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service\Preview;
+
+/**
+ * DoS bounds for the preview session store. Reference defaults match eXe core
+ * (`DEFAULT_PREVIEW_SESSION_LIMITS`) and the serving contract: 30-min idle TTL,
+ * 4 sessions/user, 5000 files/session, 200 MiB/session, 128 MiB/asset,
+ * 2 GiB global.
+ */
+final class PreviewSessionLimits {
+	public function __construct(
+		public readonly int $ttlSeconds = 30 * 60,
+		public readonly int $maxSessionsPerUser = 4,
+		public readonly int $maxFilesPerSession = 5000,
+		public readonly int $maxBytesPerSession = 200 * 1024 * 1024,
+		public readonly int $maxAssetBytes = 128 * 1024 * 1024,
+		public readonly int $globalMaxBytes = 2048 * 1024 * 1024,
+		public readonly int $recommendedBatchBytes = 64 * 1024 * 1024,
+	) {
+	}
+
+	/**
+	 * The subset advertised to the client in the create-session response so it
+	 * can size its own upload batches without guessing.
+	 *
+	 * @return array{maxFilesPerSession:int,maxBytesPerSession:int,maxAssetBytes:int,recommendedBatchBytes:int}
+	 */
+	public function forWire(): array {
+		return [
+			'maxFilesPerSession' => $this->maxFilesPerSession,
+			'maxBytesPerSession' => $this->maxBytesPerSession,
+			'maxAssetBytes' => $this->maxAssetBytes,
+			'recommendedBatchBytes' => $this->recommendedBatchBytes,
+		];
+	}
+}
diff --git a/lib/Service/Preview/PreviewSessionStore.php b/lib/Service/Preview/PreviewSessionStore.php
new file mode 100644
index 0000000..257fc62
--- /dev/null
+++ b/lib/Service/Preview/PreviewSessionStore.php
@@ -0,0 +1,820 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Service\Preview;
+
+/**
+ * File-backed store for editor preview sessions (serving contract v2).
+ *
+ * PHP is request-scoped — an in-memory map does not survive between the
+ * management POSTs and the authless GETs — so sessions live on disk under a
+ * per-installation root. Each session directory holds three layers with
+ * different lifecycles, exactly as the contract prescribes:
+ *
+ * ```
+ * {root}/{previewId}/
+ *   meta.json              { ownerUserId, createdAt }
+ *   .accessed              touch-marker; its mtime is the idle-TTL / LRU clock
+ *   .lock                  advisory flock for the revision critical section
+ *   current                the active revision number (absent until first publish)
+ *   assets/{sha1(key)}     immutable per assetKey, session-lifetime (layer 2)
+ *   documents/{sha1(bytes)} content-addressed generated-document blobs (layer 3)
+ *   revisions/{N}.json     { assetRefs, fixedRefs, documents:{path:{hash,size}}, documentBytes }
+ * ```
+ *
+ * Design invariants that make the security/atomicity guarantees testable:
+ *
+ *  - **Atomic revisions.** A revision is published by (1) writing its new
+ *    content-addressed blobs, (2) writing `revisions/{N+1}.json` via temp+rename,
+ *    (3) swapping the `current` pointer via temp+rename, then (4) pruning the
+ *    now-superseded revision. A concurrent GET reads `current` once and then an
+ *    immutable revision manifest, so it always observes revision N or N+1 —
+ *    never a mixture. Only a single active revision is retained (pruned AFTER the
+ *    swap, under the same exclusive publish flock), which bounds physical disk to
+ *    the active revision; the alternative — retaining every revision — is an
+ *    authenticated disk-fill DoS, because the byte budget only ever counts the
+ *    active revision. A GET still pinned to the just-superseded revision may 404
+ *    and re-sync, the contract's designed recovery.
+ *  - **Asset immutability.** Assets are created with an atomic link() keyed by
+ *    sha1(assetKey); re-uploading an existing key never replaces bytes (it is
+ *    reported `alreadyStored`). The server never hashes asset *bytes*.
+ *  - **Traversal safety.** Every client path (served path, revision writes /
+ *    deletes, both ref-map key sets) goes through {@see PreviewPolicy::normalizePath()};
+ *    stored blobs are addressed by hash, so a request can only ever name a
+ *    stored entry — never a filesystem location.
+ *  - **DoS bounds.** Per-session file-count and byte caps, a per-asset cap, a
+ *    per-user session cap and a global cap (both with LRU eviction), and an idle
+ *    TTL swept by a background job and opportunistically on access.
+ *
+ * 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. A
+ * small factory in {@see \OCA\ExeLearning\AppInfo\Application} resolves the real
+ * root from the Nextcloud data directory. It requires a POSIX-local directory
+ * (atomic rename + link + flock); this matches the contract's PHP-host note
+ * ("atomic pointer swap ... rename a `current` marker file").
+ */
+final class PreviewSessionStore {
+	/** @var callable():int */
+	private $clock;
+
+	/**
+	 * @param string $root Absolute path to the sessions root directory.
+	 * @param PreviewSessionLimits $limits DoS bounds.
+	 * @param (callable():int)|null $clock Unix-time source (tests stub it).
+	 */
+	public function __construct(
+		private readonly string $root,
+		private readonly PreviewSessionLimits $limits,
+		?callable $clock = null,
+	) {
+		$this->clock = $clock ?? static fn (): int => time();
+	}
+
+	public function limits(): PreviewSessionLimits {
+		return $this->limits;
+	}
+
+	// =========================================================================
+	// Session lifecycle
+	// =========================================================================
+
+	/**
+	 * Create a new session owned by $ownerUserId and return its capability id.
+	 * Enforces the per-user session cap by evicting that user's least-recently
+	 * accessed session first.
+	 */
+	public function create(string $ownerUserId): string {
+		$this->ensureDir($this->root);
+		$this->enforceUserSessionCap($ownerUserId);
+
+		$previewId = $this->generateUuidV4();
+		$dir = $this->sessionDir($previewId);
+		$this->ensureDir($dir);
+		$this->ensureDir($dir . '/assets');
+		$this->ensureDir($dir . '/documents');
+		$this->ensureDir($dir . '/revisions');
+		$this->writeFileAtomic($dir . '/meta.json', json_encode([
+			'ownerUserId' => $ownerUserId,
+			'createdAt' => ($this->clock)(),
+		], JSON_UNESCAPED_SLASHES));
+		$this->touch($previewId);
+		return $previewId;
+	}
+
+	/** Whether the session exists on disk (independent of TTL). */
+	public function exists(string $previewId): bool {
+		if (!PreviewPolicy::isValidPreviewId($previewId)) {
+			return false;
+		}
+		$meta = $this->sessionDir($previewId) . '/meta.json';
+		clearstatcache(true, $meta);
+		return is_file($meta);
+	}
+
+	/** The owner user id of a session, or null when it does not exist. */
+	public function ownerOf(string $previewId): ?string {
+		$meta = $this->readMeta($previewId);
+		return $meta['ownerUserId'] ?? null;
+	}
+
+	/** Delete a session and everything under it. Returns whether it existed. */
+	public function delete(string $previewId): bool {
+		if (!$this->exists($previewId)) {
+			return false;
+		}
+		$this->removeTree($this->sessionDir($previewId));
+		return true;
+	}
+
+	/** The active revision number, or 0 when nothing has been published yet. */
+	public function activeRevision(string $previewId): int {
+		$raw = @file_get_contents($this->sessionDir($previewId) . '/current');
+		if ($raw === false) {
+			return 0;
+		}
+		$n = (int)trim($raw);
+		return $n > 0 ? $n : 0;
+	}
+
+	// =========================================================================
+	// TTL / cleanup
+	// =========================================================================
+
+	/** Whether a session has been idle longer than the TTL. */
+	public function isExpired(string $previewId): bool {
+		$marker = $this->sessionDir($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 session
+		// 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. globalBytes() is recomputed
+		// from the surviving session directories on every call, so removing the
+		// directory automatically reconciles the accounting.
+		$createdAt = $this->createdAt($previewId);
+		if ($createdAt === null) {
+			return true;
+		}
+		return (($this->clock)() - $createdAt) > $this->limits->ttlSeconds;
+	}
+
+	/**
+	 * Remove every session idle longer than the TTL. Returns the count swept.
+	 * Called by the background cleanup job and opportunistically on access.
+	 */
+	public function sweepExpired(): int {
+		$swept = 0;
+		foreach ($this->listSessionIds() as $previewId) {
+			if ($this->isExpired($previewId)) {
+				$this->removeTree($this->sessionDir($previewId));
+				$swept++;
+			}
+		}
+		return $swept;
+	}
+
+	// =========================================================================
+	// Assets (layer 2)
+	// =========================================================================
+
+	/**
+	 * Store uploaded assets. Keys are immutable: an existing key is reported in
+	 * `alreadyStored` and its bytes are NOT replaced. Per-entry failures land in
+	 * `rejected` with a reason. Budgets are enforced on the actual buffered
+	 * bytes; a declared/actual size mismatch rejects that entry.
+	 *
+	 * @param list<array{key:string,declaredSize:int,bytes:string}> $entries
+	 * @return array{stored:list<string>,alreadyStored:list<string>,rejected:list<array{key:string,reason:string}>}
+	 */
+	public function storeAssets(string $previewId, array $entries): array {
+		$assetDir = $this->sessionDir($previewId) . '/assets';
+		$this->ensureDir($assetDir);
+		clearstatcache();
+
+		$stored = [];
+		$alreadyStored = [];
+		$rejected = [];
+
+		$sessionBytes = $this->sessionBytes($previewId);
+		$globalBytes = $this->globalBytes();
+
+		foreach ($entries as $entry) {
+			$key = $entry['key'] ?? '';
+			$bytes = $entry['bytes'] ?? '';
+			$declared = $entry['declaredSize'] ?? -1;
+			$size = strlen($bytes);
+
+			if (!PreviewPolicy::isValidAssetKey($key)) {
+				$rejected[] = ['key' => $key, 'reason' => 'invalid-key'];
+				continue;
+			}
+			$target = $assetDir . '/' . sha1($key);
+			if (is_file($target)) {
+				$alreadyStored[] = $key;
+				continue;
+			}
+			if ($declared !== $size) {
+				$rejected[] = ['key' => $key, 'reason' => 'size-mismatch'];
+				continue;
+			}
+			if ($size > $this->limits->maxAssetBytes) {
+				$rejected[] = ['key' => $key, 'reason' => 'asset-too-large'];
+				continue;
+			}
+			if ($sessionBytes + $size > $this->limits->maxBytesPerSession) {
+				$rejected[] = ['key' => $key, 'reason' => 'session-budget-exceeded'];
+				continue;
+			}
+			$globalBytes = $this->evictOthersForBudget($previewId, $size, $globalBytes);
+			if ($globalBytes === null) {
+				$rejected[] = ['key' => $key, 'reason' => 'global-budget-exceeded'];
+				$globalBytes = $this->globalBytes();
+				continue;
+			}
+			if (!$this->writeBlobAtomic($assetDir, sha1($key), $bytes)) {
+				clearstatcache(true, $target);
+				if (is_file($target)) {
+					// The key appeared concurrently (immutability race): the bytes
+					// ARE present, so report it as already stored.
+					$alreadyStored[] = $key;
+				} else {
+					// Genuine write failure (disk full / unwritable dir): the bytes
+					// are NOT on disk. Reject it so the client leaves the key
+					// un-uploaded — a later revision referencing it then gets a
+					// 422 missing-assets and the client re-uploads. Reporting
+					// alreadyStored here would strand the asset as a permanent 404.
+					$rejected[] = ['key' => $key, 'reason' => 'write-failed'];
+				}
+				continue;
+			}
+			$sessionBytes += $size;
+			$globalBytes += $size;
+			$stored[] = $key;
+		}
+
+		if ($stored !== []) {
+			$this->touch($previewId);
+		}
+		return ['stored' => $stored, 'alreadyStored' => $alreadyStored, 'rejected' => $rejected];
+	}
+
+	// =========================================================================
+	// Revisions (layer 3 publication)
+	// =========================================================================
+
+	/**
+	 * Publish a revision. Validation order per the contract: revision check
+	 * (409) → path normalization (400) → asset existence (422 missing-assets) →
+	 * fixed-resource existence (422 unknown-fixed-resources) → file-count / byte
+	 * budgets (413). The publish itself is an atomic blob-write → manifest-write
+	 * → pointer-swap under an advisory lock.
+	 *
+	 * A genuine document blob-write failure aborts the publish with `500` before
+	 * the pointer swap, leaving the previously active revision intact.
+	 *
+	 * @param array{baseRevision:int,nextRevision:int,writes:list<array{path:string,bytes:string}>,deletes:list<string>,assetRefs:array<string,string>,fixedRefs:array<string,string>} $meta
+	 * @return array{status:int,revision?:int,currentRevision?:int,reason?:string,missing?:list<string>,resources?:list<string>,message?:string}
+	 */
+	public function applyRevision(string $previewId, array $meta, FixedResourceManifest $fixed): array {
+		$dir = $this->sessionDir($previewId);
+		$lock = $this->acquireLock($dir);
+
+		try {
+			clearstatcache();
+			$active = $this->activeRevision($previewId);
+			$base = $meta['baseRevision'] ?? -1;
+			$next = $meta['nextRevision'] ?? -1;
+			if ($base !== $active || $next !== $active + 1) {
+				return ['status' => 409, 'currentRevision' => $active];
+			}
+
+			// 2. Normalize every client-supplied path.
+			$writes = [];
+			foreach ($meta['writes'] ?? [] as $write) {
+				$normalized = PreviewPolicy::normalizePath($write['path'] ?? '');
+				if ($normalized === null) {
+					return ['status' => 400, 'message' => 'Unsafe path in writes: ' . ($write['path'] ?? '')];
+				}
+				$writes[$normalized] = $write['bytes'] ?? '';
+			}
+			$deletes = [];
+			foreach ($meta['deletes'] ?? [] as $rawPath) {
+				$normalized = PreviewPolicy::normalizePath($rawPath);
+				if ($normalized === null) {
+					return ['status' => 400, 'message' => 'Unsafe path in deletes: ' . $rawPath];
+				}
+				$deletes[] = $normalized;
+			}
+			$assetRefs = [];
+			foreach (($meta['assetRefs'] ?? []) as $rawPath => $key) {
+				$normalized = PreviewPolicy::normalizePath((string)$rawPath);
+				if ($normalized === null) {
+					return ['status' => 400, 'message' => 'Unsafe path in assetRefs: ' . $rawPath];
+				}
+				$assetRefs[$normalized] = (string)$key;
+			}
+			$fixedRefs = [];
+			foreach (($meta['fixedRefs'] ?? []) as $rawPath => $id) {
+				$normalized = PreviewPolicy::normalizePath((string)$rawPath);
+				if ($normalized === null) {
+					return ['status' => 400, 'message' => 'Unsafe path in fixedRefs: ' . $rawPath];
+				}
+				$fixedRefs[$normalized] = (string)$id;
+			}
+
+			// 3. Every referenced asset must already be stored.
+			$missing = [];
+			foreach (array_unique(array_values($assetRefs)) as $key) {
+				if (!is_file($dir . '/assets/' . sha1($key))) {
+					$missing[] = $key;
+				}
+			}
+			if ($missing !== []) {
+				return ['status' => 422, 'reason' => 'missing-assets', 'missing' => array_values($missing)];
+			}
+
+			// 4. Every referenced fixed resource must be manifest-listed.
+			$unknown = [];
+			foreach (array_unique(array_values($fixedRefs)) as $id) {
+				if (!$fixed->has($id)) {
+					$unknown[] = $id;
+				}
+			}
+			if ($unknown !== []) {
+				return ['status' => 422, 'reason' => 'unknown-fixed-resources', 'resources' => array_values($unknown)];
+			}
+
+			// 5. Compute the post-delta document set (deletes first, then writes)
+			//    and enforce the budgets before touching disk.
+			$documents = $active > 0 ? ($this->readRevision($previewId, $active)['documents'] ?? []) : [];
+			foreach ($deletes as $del) {
+				if (!array_key_exists($del, $writes)) {
+					unset($documents[$del]);
+				}
+			}
+			foreach ($writes as $path => $bytes) {
+				$documents[$path] = ['hash' => sha1($bytes), 'size' => strlen($bytes)];
+			}
+			$documentBytes = 0;
+			foreach ($documents as $entry) {
+				$documentBytes += $entry['size'];
+			}
+			$fileCount = count($documents) + count($assetRefs) + count($fixedRefs);
+			if ($fileCount > $this->limits->maxFilesPerSession) {
+				return ['status' => 413, 'message' => 'Too many files (max ' . $this->limits->maxFilesPerSession . ')'];
+			}
+			$assetBytes = $this->assetBytes($previewId);
+			if ($documentBytes + $assetBytes > $this->limits->maxBytesPerSession) {
+				return ['status' => 413, 'message' => 'Session over byte budget'];
+			}
+			$previousDocumentBytes = $active > 0 ? ($this->readRevision($previewId, $active)['documentBytes'] ?? 0) : 0;
+			$byteDelta = $documentBytes - $previousDocumentBytes;
+			if ($byteDelta > 0 && $this->evictOthersForBudget($previewId, $byteDelta, $this->globalBytes()) === null) {
+				return ['status' => 413, 'message' => 'Preview storage budget exceeded'];
+			}
+
+			// 6. Publish. Write new content-addressed blobs, then the revision
+			//    manifest, then atomically swap the pointer. A genuine blob-write
+			//    failure (disk full / unwritable) must abort BEFORE the manifest
+			//    and pointer swap, or the active revision advances onto a document
+			//    whose bytes are absent (a silent permanent 404). This mirrors the
+			//    asset path's write-failed rigor. An "already present" blob is not
+			//    a failure — content-addressing dedups identical bytes.
+			foreach ($writes as $bytes) {
+				$hash = sha1($bytes);
+				$target = $dir . '/documents/' . $hash;
+				if (!$this->writeBlobAtomic($dir . '/documents', $hash, $bytes)) {
+					clearstatcache(true, $target);
+					if (!is_file($target)) {
+						return ['status' => 500, 'message' => 'Failed to persist revision document'];
+					}
+				}
+			}
+			$this->writeFileAtomic($dir . '/revisions/' . $next . '.json', json_encode([
+				'assetRefs' => (object)$assetRefs,
+				'fixedRefs' => (object)$fixedRefs,
+				'documents' => (object)$documents,
+				'documentBytes' => $documentBytes,
+			], JSON_UNESCAPED_SLASHES));
+			$this->writeFileAtomic($dir . '/current', (string)$next);
+
+			// Prune superseded revisions AFTER the pointer swap so that (a) new
+			// readers already resolve `next` and (b) physical disk is bounded by the
+			// active revision — without this, each published revision's unique
+			// document blobs accumulate forever (an authenticated disk-fill DoS),
+			// since the budget only ever counts the ACTIVE revision. Assets are
+			// shared/immutable across revisions and are never pruned here. This runs
+			// under the same exclusive flock as the publish (single writer). A rare
+			// GET still pinned to the just-superseded revision may 404 and re-sync —
+			// the contract's designed recovery.
+			$this->pruneSupersededRevisions($previewId, $next);
+			$this->touch($previewId);
+
+			return ['status' => 200, 'revision' => $next];
+		} finally {
+			$this->releaseLock($lock);
+		}
+	}
+
+	// =========================================================================
+	// Serving (three-layer resolution)
+	// =========================================================================
+
+	/**
+	 * Resolve a served path against the active revision, touching the idle-TTL
+	 * clock. Returns a descriptor, or null for a missing/expired session, an
+	 * unpublished session (revision 0), an unsafe path, or a miss.
+	 *
+	 * @return array{kind:string,contentType:string,isScriptable:bool,bytes?:string,filePath?:string,size?:int,etag?:string}|null
+	 */
+	public function resolve(string $previewId, string $rawPath, FixedResourceManifest $fixed): ?array {
+		if (!$this->exists($previewId)) {
+			return null;
+		}
+		if ($this->isExpired($previewId)) {
+			$this->removeTree($this->sessionDir($previewId));
+			return null;
+		}
+		$this->touch($previewId);
+
+		$active = $this->activeRevision($previewId);
+		if ($active === 0) {
+			return null;
+		}
+		$path = PreviewPolicy::normalizePath($rawPath);
+		if ($path === null) {
+			return null;
+		}
+		$revision = $this->readRevision($previewId, $active);
+		if ($revision === null) {
+			return null;
+		}
+		$dir = $this->sessionDir($previewId);
+		$contentType = PreviewPolicy::mimeForPath($path);
+		$isScriptable = PreviewPolicy::isScriptable($contentType);
+
+		$documents = $revision['documents'] ?? [];
+		if (isset($documents[$path])) {
+			$bytes = @file_get_contents($dir . '/documents/' . $documents[$path]['hash']);
+			if ($bytes === false) {
+				return null;
+			}
+			return ['kind' => 'document', 'contentType' => $contentType, 'isScriptable' => $isScriptable, 'bytes' => $bytes];
+		}
+
+		$assetRefs = $revision['assetRefs'] ?? [];
+		if (isset($assetRefs[$path])) {
+			$key = $assetRefs[$path];
+			$file = $dir . '/assets/' . sha1($key);
+			clearstatcache(true, $file);
+			if (is_file($file)) {
+				return [
+					'kind' => 'asset',
+					'contentType' => $contentType,
+					'isScriptable' => $isScriptable,
+					'filePath' => $file,
+					'size' => (int)filesize($file),
+					'etag' => $key,
+				];
+			}
+		}
+
+		$fixedRefs = $revision['fixedRefs'] ?? [];
+		if (isset($fixedRefs[$path])) {
+			$resource = $fixed->get($fixedRefs[$path]);
+			if ($resource !== null) {
+				return [
+					'kind' => 'fixed',
+					'contentType' => $contentType,
+					'isScriptable' => $isScriptable,
+					'bytes' => $resource['bytes'],
+				];
+			}
+		}
+
+		return null;
+	}
+
+	// =========================================================================
+	// Internals
+	// =========================================================================
+
+	private function sessionDir(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->sessionDir($previewId) . '/meta.json');
+		if ($raw === false) {
+			return null;
+		}
+		$decoded = json_decode($raw, true);
+		return is_array($decoded) ? $decoded : null;
+	}
+
+	/** The session creation unix time from meta.json, or null when missing/corrupt. */
+	private function createdAt(string $previewId): ?int {
+		$meta = $this->readMeta($previewId);
+		if ($meta === null || !isset($meta['createdAt']) || !is_numeric($meta['createdAt'])) {
+			return null;
+		}
+		return (int)$meta['createdAt'];
+	}
+
+	/**
+	 * Read a revision manifest with its inner maps decoded as associative
+	 * arrays.
+	 *
+	 * @return array{assetRefs:array<string,string>,fixedRefs:array<string,string>,documents:array<string,array{hash:string,size:int}>,documentBytes:int}|null
+	 */
+	private function readRevision(string $previewId, int $revision): ?array {
+		$raw = @file_get_contents($this->sessionDir($previewId) . '/revisions/' . $revision . '.json');
+		if ($raw === false) {
+			return null;
+		}
+		$decoded = json_decode($raw, true);
+		if (!is_array($decoded)) {
+			return null;
+		}
+		return [
+			'assetRefs' => $decoded['assetRefs'] ?? [],
+			'fixedRefs' => $decoded['fixedRefs'] ?? [],
+			'documents' => $decoded['documents'] ?? [],
+			'documentBytes' => $decoded['documentBytes'] ?? 0,
+		];
+	}
+
+	/**
+	 * Drop every revision except $active: delete superseded revision manifests
+	 * and any content-addressed document blob no longer referenced by the active
+	 * revision. Bounds physical document disk to a single revision (the
+	 * ephemeral-preview intent). Assets live in a separate directory and are
+	 * intentionally untouched — they are shared and immutable across revisions.
+	 * Best-effort: a failed unlink is harmless (the next publish or the TTL sweep
+	 * reclaims it) and never fails the publish.
+	 */
+	private function pruneSupersededRevisions(string $previewId, int $active): void {
+		$dir = $this->sessionDir($previewId);
+
+		// Document blob hashes still referenced by the active revision.
+		$referenced = [];
+		$revision = $this->readRevision($previewId, $active);
+		if ($revision !== null) {
+			foreach ($revision['documents'] as $entry) {
+				if (isset($entry['hash'])) {
+					$referenced[$entry['hash']] = true;
+				}
+			}
+		}
+
+		$documentsDir = $dir . '/documents';
+		if (is_dir($documentsDir)) {
+			foreach (scandir($documentsDir) ?: [] as $blob) {
+				// Only touch content-addressed blobs (sha1 hex); leave any
+				// in-flight staging temp alone.
+				if (preg_match('/^[0-9a-f]{40}$/', $blob) === 1 && !isset($referenced[$blob])) {
+					@unlink($documentsDir . '/' . $blob);
+				}
+			}
+		}
+
+		$revisionsDir = $dir . '/revisions';
+		if (is_dir($revisionsDir)) {
+			foreach (scandir($revisionsDir) ?: [] as $manifest) {
+				if (preg_match('/^(\d+)\.json$/', $manifest, $m) === 1 && (int)$m[1] !== $active) {
+					@unlink($revisionsDir . '/' . $manifest);
+				}
+			}
+		}
+	}
+
+	/** Refresh the idle-TTL / LRU clock for a session. */
+	private function touch(string $previewId): void {
+		$marker = $this->sessionDir($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 session (0 when unknown). */
+	private function lastAccess(string $previewId): int {
+		$marker = $this->sessionDir($previewId) . '/.accessed';
+		clearstatcache(true, $marker);
+		$mtime = @filemtime($marker);
+		return $mtime === false ? 0 : $mtime;
+	}
+
+	/** Logical bytes a session holds: active-revision documents + all assets. */
+	private function sessionBytes(string $previewId): int {
+		return $this->documentBytes($previewId) + $this->assetBytes($previewId);
+	}
+
+	private function documentBytes(string $previewId): int {
+		$active = $this->activeRevision($previewId);
+		if ($active === 0) {
+			return 0;
+		}
+		return $this->readRevision($previewId, $active)['documentBytes'] ?? 0;
+	}
+
+	private function assetBytes(string $previewId): int {
+		$total = 0;
+		$assetDir = $this->sessionDir($previewId) . '/assets';
+		if (!is_dir($assetDir)) {
+			return 0;
+		}
+		clearstatcache();
+		foreach (scandir($assetDir) ?: [] as $entry) {
+			// Skip '.', '..', staging temps and any dotfile marker.
+			if (str_starts_with($entry, '.')) {
+				continue;
+			}
+			$file = $assetDir . '/' . $entry;
+			if (is_file($file)) {
+				$total += (int)filesize($file);
+			}
+		}
+		return $total;
+	}
+
+	/** Sum of logical bytes across every session. */
+	private function globalBytes(): int {
+		$total = 0;
+		foreach ($this->listSessionIds() as $previewId) {
+			$total += $this->sessionBytes($previewId);
+		}
+		return $total;
+	}
+
+	/** @return list<string> */
+	private function listSessionIds(): 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;
+	}
+
+	/** Evict this user's LRU sessions until they are under the per-user cap. */
+	private function enforceUserSessionCap(string $ownerUserId): void {
+		$owned = [];
+		foreach ($this->listSessionIds() as $previewId) {
+			if ($this->ownerOf($previewId) === $ownerUserId) {
+				$owned[$previewId] = $this->lastAccess($previewId);
+			}
+		}
+		while (count($owned) >= $this->limits->maxSessionsPerUser && $owned !== []) {
+			$lru = array_keys($owned, min($owned))[0];
+			$this->removeTree($this->sessionDir($lru));
+			unset($owned[$lru]);
+		}
+	}
+
+	/**
+	 * Evict OTHER sessions (never $currentId) in LRU order until $incomingBytes
+	 * fits the global budget. Returns the updated global-byte total, or null when
+	 * it cannot fit even after evicting every other session.
+	 */
+	private function evictOthersForBudget(string $currentId, int $incomingBytes, int $globalBytes): ?int {
+		while ($globalBytes + $incomingBytes > $this->limits->globalMaxBytes) {
+			$candidates = [];
+			foreach ($this->listSessionIds() as $previewId) {
+				if ($previewId !== $currentId) {
+					$candidates[$previewId] = $this->lastAccess($previewId);
+				}
+			}
+			if ($candidates === []) {
+				return null;
+			}
+			$lru = array_keys($candidates, min($candidates))[0];
+			$globalBytes -= $this->sessionBytes($lru);
+			$this->removeTree($this->sessionDir($lru));
+		}
+		return $globalBytes;
+	}
+
+	/**
+	 * Atomically create $dir/$name with $bytes. Returns true when newly created,
+	 * false when it already existed (immutability preserved — bytes untouched).
+	 */
+	private function writeBlobAtomic(string $dir, string $name, string $bytes): bool {
+		$target = $dir . '/' . $name;
+		clearstatcache(true, $target);
+		if (is_file($target)) {
+			return false;
+		}
+		$tmp = $dir . '/.tmp.' . bin2hex(random_bytes(8));
+		if (@file_put_contents($tmp, $bytes) === false) {
+			@unlink($tmp);
+			return false;
+		}
+		// link() is atomic and fails if the target already exists, giving both
+		// atomic publication and immutability (never overwrite) in one step.
+		if (@link($tmp, $target)) {
+			@unlink($tmp);
+			return true;
+		}
+		// Filesystem without hardlink support (or a lost race): publish via
+		// rename ONLY when the target is still absent, so existing bytes are
+		// never replaced.
+		clearstatcache(true, $target);
+		if (!is_file($target) && @rename($tmp, $target)) {
+			return true;
+		}
+		@unlink($tmp);
+		return false;
+	}
+
+	/** 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);
+		}
+	}
+
+	/** @return resource|null An exclusive advisory lock handle, or null. */
+	private function acquireLock(string $dir) {
+		$this->ensureDir($dir);
+		$handle = @fopen($dir . '/.lock', 'c');
+		if ($handle === false) {
+			return null;
+		}
+		@flock($handle, LOCK_EX);
+		return $handle;
+	}
+
+	/** @param resource|null $handle */
+	private function releaseLock($handle): void {
+		if (is_resource($handle)) {
+			@flock($handle, LOCK_UN);
+			@fclose($handle);
+		}
+	}
+
+	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/ZipEntryService.php b/lib/Service/ZipEntryService.php
index db55898..7700988 100644
--- a/lib/Service/ZipEntryService.php
+++ b/lib/Service/ZipEntryService.php
@@ -32,13 +32,17 @@ public function readEntry(File $file, string $entry): ?string {
 		}
 
 		$localPath = $file->getStorage()->getLocalFile($file->getInternalPath());
-		if ($localPath === false || $localPath === null) {
+		if (!is_string($localPath) || $localPath === '') {
 			return $this->readEntryFromStream($file, $normalized);
 		}
 
 		$zip = new ZipArchive();
 		if ($zip->open($localPath) !== true) {
-			return null;
+			// Some virtual storage implementations (notably the php-wasm
+			// Playground filesystem) expose a nominal local path that native
+			// ZipArchive still cannot open. Treat it like any other non-local
+			// storage and retry through the portable File::fopen() path.
+			return $this->readEntryFromStream($file, $normalized);
 		}
 		try {
 			if ($zip->numFiles > self::MAX_ENTRIES) {
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_embed_relay.js b/src/embed/exe_embed_relay.js
new file mode 100644
index 0000000..0aab2b1
--- /dev/null
+++ b/src/embed/exe_embed_relay.js
@@ -0,0 +1,640 @@
+/**
+ * Parent-side external-embed relay for the opaque-origin preview / secure package mode.
+ *
+ * Companion to exe_embed_shim.js (runs INSIDE the opaque iframe). In opaque mode the
+ * document is sandboxed, so cross-origin players (YouTube, Vimeo) and PDFs render blank.
+ * The shim replaces each candidate iframe with a placeholder and postMessages its
+ * geometry here; this relay (the trusted half, in the editor / host page) validates each
+ * URL and overlays the real player inline over the placeholder — automatically, with no
+ * click, tracking scroll/resize.
+ *
+ * Trust model: the promoted player is rendered cross-origin and SANDBOXED, so the
+ * same-origin policy isolates it from this host page (it cannot read the DOM, cookies,
+ * session or storage). Two modes:
+ *  - 'open' (default): promote any iframe whose src is https AND cross-origin to the host
+ *    (rejecting same-origin, sub/superdomains of the host, IP/loopback/local hosts and
+ *    userinfo). No host list. The host is irrelevant to escape; the residual is
+ *    phishing/tracking, bounded to the content's own box (the overlay is clamped).
+ *  - 'strict': only a maintained host allowlist with per-provider canonical-URL
+ *    reconstruction, for high-security deployments.
+ * "Any https .pdf" is always allowed (same-origin only for the package's own files).
+ *
+ * Messages are authenticated by window identity (event.source === a known CONTENT
+ * iframe, never a promoted player); the opaque origin has no useful event.origin.
+ *
+ * Exposed two ways from a single body: window.exeEmbedRelay (browser bootstrap) and
+ * module.exports (tests).
+ *
+ * CANONICAL SOURCE for the eXeLearning embedder family lives here in eXeLearning core
+ * (public/app/common/exe_embed_bridge/exe_embed_relay.js). The host plugins
+ * (mod_exelearning, wp-exelearning, omeka-s-exelearning, procomun) mirror this logic
+ * (only the export wrapper differs). Keep them in sync; changes flow from core outward.
+ */
+(function () {
+    'use strict';
+
+    /**
+     * Build a host lookup map from a whitelist array (lowercased). Used by 'strict' mode.
+     *
+     * @param {string[]} list
+     * @returns {Object}
+     */
+    function buildWhitelist(list) {
+        var map = {};
+        (list || []).forEach(function (host) {
+            map[String(host).toLowerCase()] = true;
+        });
+        return map;
+    }
+
+    /**
+     * Directory portion of the content iframe src (everything up to the last '/').
+     *
+     * @param {string} src
+     * @returns {string}
+     */
+    function contentDir(src) {
+        try {
+            return new URL(src, window.location.href).href.replace(/[^/]*([?#].*)?$/, '');
+        } catch (e) {
+            return '';
+        }
+    }
+
+    /**
+     * Long hex token shared by the content URL and its assets (null when there is
+     * none, e.g. content URLs that use numeric ids).
+     *
+     * @param {string} src
+     * @returns {?string}
+     */
+    function packageId(src) {
+        var match = String(src).match(/[a-f0-9]{12,}/i);
+        return match ? match[0] : null;
+    }
+
+    /**
+     * Whether a same-origin URL is one of this package's own extracted files: under
+     * the content's own directory, or carrying the package hash as a path segment.
+     *
+     * @param {URL} url
+     * @param {string} contentSrc
+     * @returns {boolean}
+     */
+    function isSameOriginPackageFile(url, contentSrc) {
+        var dir = contentDir(contentSrc);
+        if (dir && url.href.indexOf(dir) === 0) {
+            return true;
+        }
+        var id = packageId(contentSrc);
+        return !!(id && url.pathname.indexOf('/' + id + '/') !== -1);
+    }
+
+    /**
+     * Whether a host is an IP literal (v4/v6) or a loopback/local name. Such hosts are
+     * cross-origin to the LMS yet target the machine/internal network, so they are
+     * rejected even though SOP would isolate them.
+     *
+     * @param {string} host  Lowercased URL.hostname.
+     * @returns {boolean}
+     */
+    function isIpOrLocalHost(host) {
+        if (!host) { return true; }
+        if (host === 'localhost' || /\.localhost$/.test(host) || /\.local$/.test(host)) { return true; }
+        if (host.charAt(0) === '[' || host.indexOf(':') !== -1) { return true; }  // IPv6 (bracketed).
+        if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) { return true; }                 // Any IPv4 literal.
+        return false;
+    }
+
+    /**
+     * Lowercase a hostname and strip a single trailing dot. 'lms.example.org.' (the
+     * FQDN-root form) resolves to the same vhost as 'lms.example.org' but compares
+     * unequal as a raw string, so without this it would slip past the same-origin /
+     * related-to-LMS gate below and be promoted as a cross-origin player.
+     *
+     * @param {string} host
+     * @returns {string}
+     */
+    function normalizeHost(host) {
+        return (host || '').toLowerCase().replace(/\.$/, '');
+    }
+
+    /**
+     * Whether a host equals, is a subdomain of, or is a superdomain of the LMS host
+     * (dotted boundary so 'evil-lms.example' does not match 'lms.example'). Such hosts
+     * may share the LMS cookies, so they are rejected. Both sides are normalised so the
+     * trailing-dot FQDN-root form cannot evade the comparison.
+     *
+     * @param {string} host
+     * @param {string} lmsHost
+     * @returns {boolean}
+     */
+    function isRelatedToLms(host, lmsHost) {
+        host = normalizeHost(host);
+        lmsHost = normalizeHost(lmsHost);
+        if (!lmsHost) { return false; }
+        return host === lmsHost || host.endsWith('.' + lmsHost) || lmsHost.endsWith('.' + host);
+    }
+
+    /**
+     * The structural invariant: an https URL cross-origin to the LMS and not pointing at
+     * a sub/superdomain, an IP/loopback/local host, or carrying userinfo. This is the
+     * only attacker-influenced gate in 'open' mode, and it is what makes the sandboxed
+     * player's allow-same-origin safe (the embed keeps ITS OWN origin, isolated by SOP).
+     *
+     * @param {URL} url
+     * @returns {boolean}
+     */
+    function isCrossOriginHttps(url) {
+        if (url.protocol !== 'https:') { return false; }
+        if (url.username || url.password) { return false; }
+        if (url.origin === window.location.origin) { return false; }
+        var host = normalizeHost(url.hostname);
+        if (isIpOrLocalHost(host)) { return false; }
+        var lmshost = (window.location && window.location.hostname) ? window.location.hostname : '';
+        if (isRelatedToLms(host, lmshost)) { return false; }
+        return true;
+    }
+
+    // Provider templates for the id-only channel (DEC-0067): the parent rebuilds the canonical
+    // embed URL from {provider, objectId} reported by the shim, re-checking the object id
+    // against a strict per-provider regex so it cannot carry a path/query/fragment and escape
+    // the template (e.g. '../../x' or 'a/b?c'). The reconstructed URL still runs through
+    // validate() (structural invariant / strict whitelist), so this narrows the surface for
+    // recognised providers; it is not, by itself, the trust gate.
+    var PROVIDER_TEMPLATES = {
+        youtube: { re: /^[A-Za-z0-9_-]{6,}$/, build: function (id) { return 'https://www.youtube-nocookie.com/embed/' + id; } },
+        vimeo: { re: /^[0-9]+$/, build: function (id) { return 'https://player.vimeo.com/video/' + id; } },
+        dailymotion: { re: /^[A-Za-z0-9]{5,}$/, build: function (id) { return 'https://www.dailymotion.com/embed/video/' + id; } },
+        'mediateca-madrid': { re: /^[A-Za-z0-9]{8,}$/, build: function (id) { return 'https://mediateca.educa.madrid.org/video/' + id + '/fs'; } }
+    };
+
+    /**
+     * Rebuild the canonical embed URL for a recognised provider from its object id, or null
+     * if the provider is unknown or the id is not the exact shape the template expects.
+     *
+     * @param {string} provider
+     * @param {string} objectId
+     * @returns {?string}
+     */
+    function reconstructProvider(provider, objectId) {
+        var t = PROVIDER_TEMPLATES[provider];
+        if (!t || typeof objectId !== 'string' || !t.re.test(objectId)) {
+            return null;
+        }
+        return t.build(objectId);
+    }
+
+    /**
+     * Validate an embed URL. Returns {url, kind ('video'|'pdf'), sameorigin?} or null.
+     *
+     * @param {string} raw         The reported (absolute) embed URL.
+     * @param {string} contentSrc  The src of the content iframe that reported it.
+     * @param {Object} opts        {strict: boolean, whitelist: Object}.
+     * @returns {?Object}
+     */
+    function validate(raw, contentSrc, opts) {
+        opts = opts || {};
+        var url;
+        try {
+            // Parse as an ABSOLUTE URL (the shim always reports absolute). No base:
+            // a relative/scheme-relative value would otherwise inherit the LMS origin
+            // and pass as same-origin -- here it throws and is rejected instead.
+            url = new URL(raw);
+        } catch (e) {
+            return null;
+        }
+        if (url.username || url.password) {
+            return null; // Reject userinfo, e.g. https://evil.com@youtube.com/.
+        }
+        var host = url.hostname.toLowerCase();
+
+        // PDFs: any cross-origin https .pdf, or a same-origin file that belongs to this
+        // package (served as application/pdf + nosniff, never executable HTML).
+        if (/\.pdf$/i.test(url.pathname)) {
+            if (url.origin === window.location.origin) {
+                return isSameOriginPackageFile(url, contentSrc) ? { url: url.href, kind: 'pdf', sameorigin: true } : null;
+            }
+            return isCrossOriginHttps(url) ? { url: url.href, kind: 'pdf' } : null;
+        }
+
+        // Strict mode: maintained host allowlist + per-provider canonical reconstruction.
+        if (opts.strict) {
+            var whitelist = opts.whitelist || {};
+            if (whitelist[host] && url.protocol === 'https:') {
+                var m;
+                if (host.indexOf('youtube') !== -1) {
+                    m = url.pathname.match(/^\/embed\/([A-Za-z0-9_-]{6,})$/);
+                    return m ? { url: 'https://www.youtube-nocookie.com/embed/' + m[1], kind: 'video' } : null;
+                }
+                if (host.indexOf('vimeo') !== -1) {
+                    m = url.pathname.match(/^\/video\/([0-9]+)$/);
+                    return m ? { url: 'https://player.vimeo.com/video/' + m[1], kind: 'video' } : null;
+                }
+                if (host.indexOf('dailymotion') !== -1) {
+                    m = url.pathname.match(/^\/embed\/video\/([A-Za-z0-9]{5,})$/);
+                    return m ? { url: 'https://www.dailymotion.com/embed/video/' + m[1], kind: 'video' } : null;
+                }
+                if (host === 'mediateca.educa.madrid.org') {
+                    m = url.pathname.match(/^\/video\/([A-Za-z0-9]{8,})(?:\/fs)?$/);
+                    return m ? { url: 'https://mediateca.educa.madrid.org/video/' + m[1] + '/fs', kind: 'video' } : null;
+                }
+            }
+            return null;
+        }
+
+        // Open mode (default): any cross-origin https iframe is a video embed.
+        return isCrossOriginHttps(url) ? { url: url.href, kind: 'video' } : null;
+    }
+
+    /**
+     * Create the player iframe for a validated embed. The video player gets allow-same-origin
+     * (so the cross-origin provider keeps its own origin and renders) while omitting
+     * allow-top-navigation/allow-modals, so a hostile embed cannot redirect the LMS tab or
+     * spam dialogs. A same-origin package PDF is served as application/pdf + nosniff (never
+     * executable HTML) and is left unsandboxed so the browser's built-in viewer renders it; a
+     * CROSS-ORIGIN PDF URL comes from the untrusted package, so it is sandboxed WITHOUT
+     * allow-top-navigation (a server can serve scripted HTML at a .pdf path, which unsandboxed
+     * could top-navigate the parent tab to a phishing page).
+     *
+     * @param {Object} result {url, kind, sameorigin?} from validate().
+     * @returns {HTMLIFrameElement}
+     */
+    function makePlayer(result) {
+        var frame = document.createElement('iframe');
+        frame.style.cssText = 'position:absolute;border:0;pointer-events:auto;';
+        // Mark as a player so it is never mistaken for a content source (message auth).
+        frame.setAttribute('data-exe-embed-player', '1');
+        if (result.kind === 'video') {
+            frame.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-popups allow-forms allow-presentation');
+            frame.setAttribute('allow', 'autoplay; encrypted-media; fullscreen; picture-in-picture; clipboard-write');
+            frame.setAttribute('allowfullscreen', '');
+            frame.setAttribute('referrerpolicy', 'strict-origin-when-cross-origin');
+        } else if (result.sameorigin) {
+            // Same-origin PDF that belongs to THIS package: served application/pdf + nosniff
+            // (never executable HTML, so it cannot script or navigate), left unsandboxed so the
+            // browser's built-in viewer renders it (it shows the broken-document icon inside a
+            // sandbox). The load guard still removes it if it redirects to the LMS origin.
+            frame.setAttribute('allow', 'fullscreen');
+            frame.setAttribute('referrerpolicy', 'no-referrer');
+        } else {
+            // Cross-origin PDF whose URL is controlled by the untrusted package. A server can
+            // serve scripted HTML at a ".pdf" path; unsandboxed, that frame could top-navigate
+            // the Moodle tab to a phishing page on a click (a package must never change the
+            // parent URL). Sandbox it WITHOUT allow-top-navigation/allow-scripts; allow-same-
+            // origin keeps the provider's own origin (SOP-isolated from the LMS). Trade-off: a
+            // genuine cross-origin PDF may render the broken-document icon under the sandbox --
+            // accepted, since local package PDFs (the common case) take the branch above and
+            // blocking the tab-redirect vector matters more than inlining a remote PDF.
+            frame.setAttribute('sandbox', 'allow-same-origin');
+            frame.setAttribute('allow', 'fullscreen');
+            frame.setAttribute('referrerpolicy', 'no-referrer');
+        }
+        frame.src = result.url;
+        // Tag with the URL it renders so sync() can detect when a reused embed id (the
+        // shim restarts its counter per page) now points at a different URL.
+        frame.setAttribute('data-exe-embed-src', result.url);
+        return frame;
+    }
+
+    /**
+     * Create a relay instance.
+     *
+     * @param {Object} config {mode: 'open'|'strict', whitelist: string[]}
+     * @returns {Object}
+     */
+    function createRelay(config) {
+        config = config || {};
+        var strict = config.mode === 'strict';
+        var whitelist = buildWhitelist(config.whitelist);
+        var overlays = [];
+        // Handles for the listeners/timer init() installs, so dispose() can remove
+        // them and init() can stay idempotent (a second init() must not stack a
+        // second drift interval + duplicate window listeners on the same relay).
+        var driftTimer = null;
+        var started = false;
+
+        function findOverlay(iframe) {
+            for (var i = 0; i < overlays.length; i++) {
+                if (overlays[i].iframe === iframe) {
+                    return overlays[i];
+                }
+            }
+            return null;
+        }
+
+        // Resolve the CONTENT iframe a message came from. Promoted players are excluded
+        // (data-exe-embed-player): a sandboxed player with allow-same-origin could
+        // otherwise postMessage a forged 'sync' and impersonate a content source.
+        function frameForSource(source) {
+            var frames = document.getElementsByTagName('iframe');
+            for (var i = 0; i < frames.length; i++) {
+                if (frames[i].getAttribute('data-exe-embed-player')) {
+                    continue;
+                }
+                if (frames[i].contentWindow === source) {
+                    return frames[i];
+                }
+            }
+            return null;
+        }
+
+        function overlayFor(iframe) {
+            var entry = findOverlay(iframe);
+            if (entry) {
+                return entry;
+            }
+            var el = document.createElement('div');
+            el.className = 'exe-embed-overlay';
+            el.style.cssText = 'position:absolute;overflow:hidden;pointer-events:none;z-index:2147483646;';
+            document.body.appendChild(el);
+            entry = { iframe: iframe, el: el, players: {} };
+            overlays.push(entry);
+            return entry;
+        }
+
+        function positionOverlay(entry, rect) {
+            rect = rect || entry.iframe.getBoundingClientRect();
+            var scrollX = window.pageXOffset || document.documentElement.scrollLeft || 0;
+            var scrollY = window.pageYOffset || document.documentElement.scrollTop || 0;
+            entry.el.style.left = (rect.left + scrollX) + 'px';
+            entry.el.style.top = (rect.top + scrollY) + 'px';
+            entry.el.style.width = rect.width + 'px';
+            entry.el.style.height = rect.height + 'px';
+            // Remembered so checkDrift() can detect host-driven moves of the content
+            // iframe (panel toggles, sidebar show/hide) that fire no scroll/resize.
+            entry.lastRect = { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+        }
+
+        /**
+         * Re-position any overlay whose content iframe box moved since it was last
+         * placed. The host page can move or resize the content iframe without any
+         * scroll/resize event firing (editor sidebar toggles, panel slide-ins, CSS
+         * transforms), which would strand the overlay at its old position. Called
+         * from a low-frequency interval in init(); one getBoundingClientRect per
+         * overlay per tick. Returns how many overlays were re-positioned.
+         *
+         * @returns {number}
+         */
+        function checkDrift() {
+            var moved = 0;
+            for (var i = 0; i < overlays.length; i++) {
+                var entry = overlays[i];
+                var rect = entry.iframe.getBoundingClientRect();
+                var last = entry.lastRect;
+                if (
+                    !last ||
+                    rect.left !== last.left ||
+                    rect.top !== last.top ||
+                    rect.width !== last.width ||
+                    rect.height !== last.height
+                ) {
+                    positionOverlay(entry, rect);
+                    moved += 1;
+                }
+            }
+            return moved;
+        }
+
+        // D1: if a promoted embed lands SAME-ORIGIN to the LMS (e.g. a cross-origin URL
+        // that 30x-redirects to this origin), with allow-same-origin it would become
+        // scriptable against this page -> remove it. A genuine cross-origin player throws
+        // on contentWindow.document (expected, kept). Not armed for same-origin package
+        // PDFs (intentionally same-origin, served as application/pdf).
+        function armSameOriginGuard(entry, id, player) {
+            player.addEventListener('load', function () {
+                try {
+                    if (player.contentWindow && player.contentWindow.document) {
+                        if (player.parentNode) { player.parentNode.removeChild(player); }
+                        if (entry.players[id] === player) { delete entry.players[id]; }
+                    }
+                } catch (e) { /* cross-origin: expected, keep the player */ }
+            });
+        }
+
+        function sync(entry, embeds, contentSrc) {
+            // The content iframe's box is invariant across this sync pass (the loop only
+            // mutates the overlay and its players), so read it once and reuse it for the
+            // overlay position and every player clamp -- avoids a forced reflow per embed.
+            var rect = entry.iframe.getBoundingClientRect();
+            positionOverlay(entry, rect);
+            var seen = {};
+            embeds.forEach(function (embed) {
+                if (!embed || typeof embed.id !== 'string') {
+                    return;
+                }
+                if (!isFinite(embed.x) || !isFinite(embed.y) || !isFinite(embed.w) || !isFinite(embed.h)) {
+                    return;
+                }
+                // id-only channel (DEC-0067): for recognised providers the shim reports
+                // {provider, objectId} and the parent rebuilds the canonical URL from a
+                // fixed template (the author URL never crosses for these). Unknown embeds
+                // keep the URL path. Either way validate() runs the structural invariant.
+                var raw = embed.url;
+                if (embed.provider && embed.objectId) {
+                    raw = reconstructProvider(embed.provider, embed.objectId);
+                    if (!raw) {
+                        return;
+                    }
+                }
+                var result = validate(raw, contentSrc, { strict: strict, whitelist: whitelist });
+                if (!result) {
+                    return;
+                }
+                seen[embed.id] = true;
+                var player = entry.players[embed.id];
+                // After the content navigates, the shim reuses ids (exe-embed-1, ...) for
+                // the new page's embeds. If this id now renders a different URL, drop the
+                // stale player so the previous page's video does not linger here.
+                if (player && player.getAttribute('data-exe-embed-src') !== result.url) {
+                    player.parentNode.removeChild(player);
+                    delete entry.players[embed.id];
+                    player = null;
+                }
+                if (!player) {
+                    player = makePlayer(result);
+                    entry.el.appendChild(player);
+                    entry.players[embed.id] = player;
+                    if (!result.sameorigin) {
+                        armSameOriginGuard(entry, embed.id, player);
+                    }
+                }
+                // Defence in depth against clickjacking: the overlay is clamped to the
+                // content iframe's box and clips with overflow:hidden, so a player can
+                // never cover host UI outside the iframe. Cap the player size to the
+                // overlay too (the content reports geometry, the parent owns rendering).
+                // Reuses the iframe rect read once at the top of this pass.
+                player.style.left = embed.x + 'px';
+                player.style.top = embed.y + 'px';
+                player.style.width = Math.min(embed.w, rect.width) + 'px';
+                player.style.height = Math.min(embed.h, rect.height) + 'px';
+            });
+            Object.keys(entry.players).forEach(function (id) {
+                if (!seen[id]) {
+                    entry.players[id].parentNode.removeChild(entry.players[id]);
+                    delete entry.players[id];
+                }
+            });
+        }
+
+        function onMessage(event) {
+            var data = event.data;
+            if (!data || data.type !== 'exe-embed' || data.action !== 'sync' || !Array.isArray(data.embeds)) {
+                return;
+            }
+            var iframe = frameForSource(event.source);
+            if (!iframe) {
+                return;
+            }
+            sync(overlayFor(iframe), data.embeds, iframe.src);
+        }
+
+        // Browser-only glue below (window listeners, reflow on scroll/resize, pinging
+        // the content iframes). Exercised by the Playwright/Firefox e2e
+        // (tests/e2e/embed.spec.cjs), not the happy-dom unit tests.
+        /* v8 ignore start */
+        function pingAll() {
+            var frames = document.getElementsByTagName('iframe');
+            for (var i = 0; i < frames.length; i++) {
+                if (frames[i].getAttribute('data-exe-embed-player')) {
+                    continue;
+                }
+                try {
+                    frames[i].contentWindow.postMessage({ type: 'exe-embed', action: 'request' }, '*');
+                } catch (e) {
+                    // Cross-origin player iframes reject this; harmless.
+                }
+            }
+        }
+
+        var scheduled = false;
+        function scheduleReflow() {
+            if (scheduled) {
+                return;
+            }
+            scheduled = true;
+            window.requestAnimationFrame(function () {
+                scheduled = false;
+                for (var i = 0; i < overlays.length; i++) {
+                    positionOverlay(overlays[i]);
+                }
+            });
+        }
+        /* v8 ignore stop */
+
+        // Tear down every overlay and its players. Used when the host (e.g. the editor
+        // preview panel) hides or closes the content iframe: the overlay lives on the
+        // host's own body, so without this it would linger over the host UI. A later
+        // sync (after the iframe reloads) rebuilds the overlays cleanly.
+        function clear() {
+            for (var i = 0; i < overlays.length; i++) {
+                var entry = overlays[i];
+                var ids = Object.keys(entry.players);
+                for (var j = 0; j < ids.length; j++) {
+                    var player = entry.players[ids[j]];
+                    if (player && player.parentNode) {
+                        player.parentNode.removeChild(player);
+                    }
+                }
+                entry.players = {};
+                if (entry.el && entry.el.parentNode) {
+                    entry.el.parentNode.removeChild(entry.el);
+                }
+            }
+            overlays.length = 0;
+        }
+
+        // Re-place every overlay over its content iframe's CURRENT box. The host (e.g. the
+        // editor preview panel) can move the iframe with a CSS transform (slide-in), which
+        // fires no scroll/resize, so an overlay placed during the animation would stay at
+        // its sync-time position. The host calls this once the move settles.
+        function reflow() {
+            for (var i = 0; i < overlays.length; i++) {
+                positionOverlay(overlays[i]);
+            }
+        }
+
+        // Tear down clear() the overlays AND remove the window listeners + drift
+        // timer that init() installed, so a relay whose host is gone (preview panel
+        // disposed, tab closed) leaves nothing running. Idempotent; init() can run
+        // again afterwards on a reused relay.
+        function dispose() {
+            clear();
+            /* v8 ignore start */
+            if (driftTimer !== null) {
+                window.clearInterval(driftTimer);
+                driftTimer = null;
+            }
+            window.removeEventListener('message', onMessage);
+            window.removeEventListener('resize', scheduleReflow);
+            window.removeEventListener('scroll', scheduleReflow, true);
+            window.removeEventListener('load', pingAll);
+            /* v8 ignore stop */
+            started = false;
+        }
+
+        return {
+            onMessage: onMessage,
+            sync: sync,
+            clear: clear,
+            reflow: reflow,
+            checkDrift: checkDrift,
+            dispose: dispose,
+            validate: function (raw, contentSrc) {
+                return validate(raw, contentSrc, { strict: strict, whitelist: whitelist });
+            },
+            /* v8 ignore start */
+            init: function () {
+                // Idempotent: a second init() on the same relay must not stack a
+                // second drift interval and duplicate window listeners.
+                if (started) {
+                    return this;
+                }
+                started = true;
+                window.addEventListener('message', onMessage);
+                window.addEventListener('resize', scheduleReflow);
+                window.addEventListener('scroll', scheduleReflow, true);
+                window.addEventListener('load', pingAll);
+                pingAll();
+                window.setTimeout(pingAll, 500);
+                // Host layout changes (sidebar toggles, panel slide-ins) move the
+                // content iframe with no scroll/resize event; keep the overlays
+                // pinned to it with a cheap low-frequency drift check.
+                driftTimer = window.setInterval(checkDrift, 300);
+                return this;
+            }
+            /* v8 ignore stop */
+        };
+    }
+
+    /**
+     * Bootstrap: create a relay from config and start listening.
+     *
+     * @param {Object} config {mode: 'open'|'strict', whitelist: string[]}
+     * @returns {Object}
+     */
+    /* v8 ignore next 3 */
+    function init(config) {
+        return createRelay(config).init();
+    }
+
+    var exp = {
+        buildWhitelist: buildWhitelist,
+        contentDir: contentDir,
+        packageId: packageId,
+        isSameOriginPackageFile: isSameOriginPackageFile,
+        isIpOrLocalHost: isIpOrLocalHost,
+        normalizeHost: normalizeHost,
+        isRelatedToLms: isRelatedToLms,
+        isCrossOriginHttps: isCrossOriginHttps,
+        reconstructProvider: reconstructProvider,
+        validate: validate,
+        makePlayer: makePlayer,
+        createRelay: createRelay,
+        init: init
+    };
+    // Test runner (Vitest/Node) consumes module.exports.
+    if (typeof module !== 'undefined' && module.exports) { module.exports = exp; }
+    // Browser bootstrap (view.php) consumes window.exeEmbedRelay.
+    if (typeof window !== 'undefined') { window.exeEmbedRelay = exp; }
+})();
diff --git a/src/embed/exe_embed_shim.js b/src/embed/exe_embed_shim.js
new file mode 100644
index 0000000..bb2d9e9
--- /dev/null
+++ b/src/embed/exe_embed_shim.js
@@ -0,0 +1,354 @@
+/**
+ * In-iframe external-embed shim for the opaque-origin preview / secure package mode.
+ *
+ * Loaded from the <head> of every rendered page. In opaque-origin mode the document
+ * runs in a sandbox without allow-same-origin, so the sandbox flag propagates to nested
+ * iframes and cross-origin players (YouTube, Vimeo) plus PDFs render blank. This shim
+ * replaces each cross-origin (https) or .pdf iframe with a same-size placeholder and
+ * reports its geometry to the parent, which validates it and overlays the real player
+ * inline (see exe_embed_relay.js). It self-activates ONLY in the opaque origin, so the
+ * same file stays dormant in same-origin rendering (where external players already
+ * render inline and the relay is not loaded).
+ *
+ * There is no host list here: the shim promotes any cross-origin https (or .pdf) iframe
+ * as a candidate and the parent relay is the authoritative gate (open vs strict mode).
+ * postMessage targetOrigin is '*' because the opaque origin has no stable value; the
+ * parent authenticates messages by event.source instead.
+ *
+ * Exposed two ways from a single body: window.exeEmbedShim (browser bootstrap) and
+ * module.exports (tests).
+ *
+ * CANONICAL SOURCE for the eXeLearning embedder family lives here in eXeLearning core
+ * (public/app/common/exe_embed_bridge/exe_embed_shim.js). The host plugins
+ * (mod_exelearning, wp-exelearning, omeka-s-exelearning, procomun) mirror this logic
+ * (only the export wrapper differs). Keep them in sync; changes flow from core outward.
+ */
+(function () {
+    'use strict';
+
+    /**
+     * Whether this document runs in an opaque origin (secure sandbox). In an opaque
+     * origin document.cookie throws and window.origin is "null".
+     *
+     * @returns {boolean}
+     */
+    function isOpaqueOrigin() {
+        try {
+            void document.cookie;
+            return window.origin === 'null';
+        } catch (e) {
+            return true;
+        }
+    }
+
+    /**
+     * Whether a URL path ends in .pdf (PDFs also fail under the opaque sandbox).
+     *
+     * @param {string} url
+     * @returns {boolean}
+     */
+    function isPdfUrl(url) {
+        try {
+            return /\.pdf$/i.test(new URL(url, window.location.href).pathname);
+        } catch (e) {
+            return false;
+        }
+    }
+
+    /**
+     * Whether a src resolves to an https URL on a host other than this document's own
+     * (served) host -- i.e. a cross-origin external embed. The opaque document is still
+     * served from the platform, so window.location.hostname is the platform host and the
+     * comparison is reliable. The parent relay re-validates authoritatively (DEC-0061);
+     * this is only a candidate filter so same-origin content iframes are left untouched.
+     *
+     * @param {string} src
+     * @returns {boolean}
+     */
+    function isCrossOriginHttps(src) {
+        try {
+            var u = new URL(src, window.location.href);
+            // Strip a single trailing dot so the LMS host in its FQDN-root form
+            // ('host.') counts as same-host and is not reported as a candidate.
+            var host = u.hostname.toLowerCase().replace(/\.$/, '');
+            var here = window.location.hostname.toLowerCase().replace(/\.$/, '');
+            return u.protocol === 'https:' && host !== here;
+        } catch (e) {
+            return false;
+        }
+    }
+
+    /**
+     * Whether an iframe src should be promoted to the parent: any cross-origin https
+     * embed or a .pdf (both render blank under the opaque sandbox). No host list -- the
+     * parent relay decides what actually renders (open vs strict mode).
+     *
+     * @param {string} src
+     * @returns {boolean}
+     */
+    function isPromotable(src) {
+        return isCrossOriginHttps(src) || isPdfUrl(src);
+    }
+
+    /**
+     * Recognise a known video provider from an embed src and extract its object id, so the
+     * shim can report {provider, objectId} instead of the author URL (DEC-0067 id-only
+     * channel). The parent rebuilds the canonical URL from a fixed template; this avoids
+     * passing the author's URL across the boundary for recognised providers. Returns null
+     * for unknown hosts or unexpected paths (the caller then falls back to URL mode). The
+     * id shape is intentionally permissive here; the parent re-checks it against a strict
+     * regex before templating it.
+     *
+     * @param {string} src
+     * @returns {?{provider: string, objectId: string}}
+     */
+    function extractProvider(src) {
+        var u;
+        try {
+            u = new URL(src, window.location.href);
+        } catch (e) {
+            return null;
+        }
+        if (u.protocol !== 'https:') {
+            return null;
+        }
+        var host = u.hostname.toLowerCase().replace(/\.$/, '');
+        var m;
+        if (host === 'youtu.be') {
+            m = u.pathname.match(/^\/([A-Za-z0-9_-]{6,})$/);
+            return m ? { provider: 'youtube', objectId: m[1] } : null;
+        }
+        if (host.indexOf('youtube') !== -1) {
+            m = u.pathname.match(/^\/embed\/([A-Za-z0-9_-]{6,})$/);
+            return m ? { provider: 'youtube', objectId: m[1] } : null;
+        }
+        if (host.indexOf('vimeo') !== -1) {
+            m = u.pathname.match(/^\/video\/([0-9]+)$/);
+            return m ? { provider: 'vimeo', objectId: m[1] } : null;
+        }
+        if (host.indexOf('dailymotion') !== -1) {
+            m = u.pathname.match(/^\/embed\/video\/([A-Za-z0-9]{5,})$/);
+            return m ? { provider: 'dailymotion', objectId: m[1] } : null;
+        }
+        if (host === 'mediateca.educa.madrid.org') {
+            m = u.pathname.match(/^\/video\/([A-Za-z0-9]{8,})(?:\/fs)?$/);
+            return m ? { provider: 'mediateca-madrid', objectId: m[1] } : null;
+        }
+        return null;
+    }
+
+    /**
+     * Render a width/height attribute value as a CSS length.
+     *
+     * @param {?string} value
+     * @param {string} fallback
+     * @returns {string}
+     */
+    function cssSize(value, fallback) {
+        if (!value) {
+            return fallback;
+        }
+        return /^[0-9]+$/.test(String(value)) ? value + 'px' : String(value);
+    }
+
+    /**
+     * Replace whitelisted/PDF iframes with placeholders that reserve their box and
+     * carry the embed id + url. Returns the created placeholder elements.
+     *
+     * @param {Document|Element} root A document or a container element to scan.
+     * @param {Object} counter {n:int} mutable id counter (kept across calls).
+     * @returns {Element[]}
+     */
+    function promote(root, counter) {
+        var created = [];
+        var maker = root.ownerDocument || root;
+        var frames = root.querySelectorAll('iframe[src]');
+        for (var i = 0; i < frames.length; i++) {
+            var frame = frames[i];
+            if (frame.getAttribute('data-exe-embed-id')) {
+                continue;
+            }
+            var src = frame.getAttribute('src');
+            if (!isPromotable(src)) {
+                continue;
+            }
+            var rect = frame.getBoundingClientRect ? frame.getBoundingClientRect() : { width: 0, height: 0 };
+            var placeholder = maker.createElement('div');
+            counter.n += 1;
+            placeholder.setAttribute('data-exe-embed-id', 'exe-embed-' + counter.n);
+            // Report an ABSOLUTE url: the shim runs inside the content, so resolve the
+            // (possibly relative) src against the content location. The parent relay
+            // cannot — it would resolve a relative url against the host page instead.
+            var absoluteUrl = src;
+            try {
+                absoluteUrl = new URL(src, window.location.href).href;
+            } catch (e) {
+                absoluteUrl = src;
+            }
+            placeholder.setAttribute('data-exe-embed-url', absoluteUrl);
+            // For recognised providers also stamp {provider, objectId} so the parent can
+            // rebuild the canonical URL from a fixed template (DEC-0067 id-only channel)
+            // instead of trusting the author URL. Unknown hosts keep URL-only mode.
+            var provider = extractProvider(absoluteUrl);
+            if (provider) {
+                placeholder.setAttribute('data-exe-embed-provider', provider.provider);
+                placeholder.setAttribute('data-exe-embed-object-id', provider.objectId);
+            }
+            placeholder.className = frame.className;
+            placeholder.style.display = 'block';
+            placeholder.style.maxWidth = '100%';
+            placeholder.style.width = cssSize(frame.getAttribute('width'), (rect.width || 0) + 'px');
+            placeholder.style.height = cssSize(frame.getAttribute('height'), (rect.height || 0) + 'px');
+            placeholder.style.background = '#000';
+            frame.parentNode.replaceChild(placeholder, frame);
+            created.push(placeholder);
+        }
+        return created;
+    }
+
+    /**
+     * Collect the geometry of every placeholder in the document.
+     *
+     * @param {Document} doc
+     * @returns {Object[]}
+     */
+    function collect(doc) {
+        var embeds = [];
+        var nodes = doc.querySelectorAll('[data-exe-embed-id]');
+        for (var i = 0; i < nodes.length; i++) {
+            var node = nodes[i];
+            var rect = node.getBoundingClientRect();
+            var rec = {
+                id: node.getAttribute('data-exe-embed-id'),
+                url: node.getAttribute('data-exe-embed-url'),
+                x: rect.left,
+                y: rect.top,
+                w: rect.width,
+                h: rect.height
+            };
+            var provider = node.getAttribute('data-exe-embed-provider');
+            var objectId = node.getAttribute('data-exe-embed-object-id');
+            if (provider && objectId) {
+                rec.provider = provider;
+                rec.objectId = objectId;
+            }
+            embeds.push(rec);
+        }
+        return embeds;
+    }
+
+    /**
+     * Bootstrap inside the package iframe (no-op outside the secure opaque origin).
+     * Browser-only glue (requires a framed, opaque-origin window); exercised by the
+     * Playwright/Firefox e2e (tests/e2e/embed.spec.cjs), not the happy-dom unit tests.
+     */
+    /* v8 ignore start */
+    function init() {
+        if (window.parent === window || !isOpaqueOrigin()) {
+            return;
+        }
+        var counter = { n: 0 };
+        var scheduled = false;
+        var lastReported = '';
+
+        // force=true always posts (initial run, load, and parent 'request' pings —
+        // the parent may have just started listening or lost its state); observer
+        // -driven reports skip when the geometry did not actually change, so an
+        // attribute-noisy page (carousel animations, aria flips) cannot spam the
+        // parent with identical syncs.
+        function report(force) {
+            var embeds = collect(document);
+            var serialized = JSON.stringify(embeds);
+            if (!force && serialized === lastReported) {
+                return;
+            }
+            lastReported = serialized;
+            window.parent.postMessage({ type: 'exe-embed', action: 'sync', embeds: embeds }, '*');
+        }
+        function schedule() {
+            if (scheduled) {
+                return;
+            }
+            scheduled = true;
+            window.requestAnimationFrame(function () {
+                scheduled = false;
+                report(false);
+            });
+        }
+        function run() {
+            promote(document, counter);
+            report(true);
+        }
+
+        run();
+        if (window.MutationObserver) {
+            // attributes too, not just childList: layout-affecting UI (the exported
+            // page's nav toggle, accordions) usually flips a class/style on an
+            // existing node, which reflows the placeholders without adding or
+            // removing any element. The filter keeps the observer to the
+            // reflow-causing attributes.
+            new MutationObserver(function () {
+                promote(document, counter);
+                schedule();
+            }).observe(document.documentElement, {
+                childList: true,
+                subtree: true,
+                attributes: true,
+                attributeFilter: ['class', 'style', 'hidden', 'open'],
+            });
+        }
+        window.addEventListener('scroll', schedule, true);
+        window.addEventListener('resize', schedule);
+        // A class-toggled layout change usually ANIMATES (CSS transition on the nav
+        // drawer): the mutation fires at the start, so re-measure again when the
+        // transition/animation lands to report the settled geometry.
+        window.addEventListener('transitionend', schedule, true);
+        window.addEventListener('animationend', schedule, true);
+        if (window.ResizeObserver) {
+            // Catches content-box changes that fire no window resize (the drawer
+            // pushing the content column, images loading late and growing the page).
+            var resizeObserver = new ResizeObserver(schedule);
+            resizeObserver.observe(document.documentElement);
+            if (document.body) {
+                resizeObserver.observe(document.body);
+            }
+        }
+        window.addEventListener('load', function () {
+            report(true);
+        });
+        window.addEventListener('message', function (event) {
+            if (event.source !== window.parent) {
+                return;
+            }
+            var data = event.data;
+            if (data && data.type === 'exe-embed' && data.action === 'request') {
+                run();
+            }
+        });
+    }
+    /* v8 ignore stop */
+
+    var exp = {
+        isOpaqueOrigin: isOpaqueOrigin,
+        isPdfUrl: isPdfUrl,
+        isCrossOriginHttps: isCrossOriginHttps,
+        isPromotable: isPromotable,
+        extractProvider: extractProvider,
+        promote: promote,
+        collect: collect,
+        init: init
+    };
+    // Test runner (Vitest/Node) consumes module.exports.
+    if (typeof module !== 'undefined' && module.exports) { module.exports = exp; }
+    // Browser bootstrap consumes window.exeEmbedShim; auto-run inside the iframe.
+    if (typeof window !== 'undefined') {
+        window.exeEmbedShim = exp;
+        if (typeof document !== 'undefined') {
+            if (document.readyState === 'loading') {
+                document.addEventListener('DOMContentLoaded', init);
+            } else {
+                init();
+            }
+        }
+    }
+})();
diff --git a/src/embed/exe_media_host.js b/src/embed/exe_media_host.js
new file mode 100644
index 0000000..b80265f
--- /dev/null
+++ b/src/embed/exe_media_host.js
@@ -0,0 +1,533 @@
+/**
+ * exe-media-host — reference PARENT-side relay for the eXeLearning external-media bridge.
+ *
+ * Host plugins (Moodle, WordPress, Procomún, …) include this one file on the trusted page
+ * that embeds an eXeLearning package inside an opaque-origin sandboxed iframe. It lets the
+ * package's YouTube/Vimeo videos play (which they cannot do inside the opaque frame) by:
+ *
+ *   - completing the capability handshake announced by the child runtime (window identity
+ *     + per-view nonce + a transferred MessageChannel port),
+ *   - opening an accessible <dialog> with the real provider player on the trusted side, and
+ *   - relaying a tiny, validated set of media commands/events over the private port.
+ *
+ * Security: the relay NEVER trusts `event.origin` (it is the string "null"). The only
+ * window-level message accepted is the child's `welcome`-triggering `hello`, gated by
+ * `event.source === iframe.contentWindow`. Steady-state media traffic flows only over the
+ * private port. The child sends just `{provider, videoId}`; the relay reconstructs the
+ * canonical URL from a fixed per-provider template (never a child-supplied URL).
+ *
+ * Classic browser script (no ES module syntax); depends on the shared `exeMediaPolicy`.
+ *
+ * mod_exelearning VARIANT (DEC-0067): vendored from eXeLearning's exe-media-host.js, but the
+ * provider adapters drive the player by RAW postMessage (YouTube enablejsapi=1, Vimeo api=1)
+ * instead of the YouTube IFrame Player API / Vimeo Player SDK, so the trusted Moodle page
+ * never loads third-party player script (erseco). The handshake, accessible modal and the
+ * command/event relay are otherwise unchanged. The child runtime (exe_media_bridge.js +
+ * exe_media_policy.js, baked into the package by eXeLearning) is unmodified; the interactive
+ * video iDevice already speaks this contract (window.exeMediaBridge.openMedia → controller).
+ * Canonical upstream: exelearning/public/app/common/exe_media_bridge/.
+ *
+ * @license AGPL-3.0
+ */
+(function (root) {
+    'use strict';
+
+    var policy = root.exeMediaPolicy;
+    var TYPE = policy.TYPE;
+    var VERSION = policy.VERSION;
+
+    function tr(key) {
+        return typeof root._ === 'function' ? root._(key) : key;
+    }
+
+    function isThenable(v) {
+        return v && typeof v.then === 'function';
+    }
+
+    function genNonce(opts) {
+        if (opts && typeof opts.genId === 'function') return opts.genId();
+        if (root.crypto && typeof root.crypto.randomUUID === 'function') return root.crypto.randomUUID();
+        return 'n-' + Math.random().toString(36).slice(2);
+    }
+
+    function makeChannel(opts) {
+        if (opts && typeof opts.channelFactory === 'function') return opts.channelFactory();
+        return new MessageChannel();
+    }
+
+    function getInterval(opts) {
+        return {
+            set: (opts && opts.setInterval) || (root.setInterval ? root.setInterval.bind(root) : function () {}),
+            clear: (opts && opts.clearInterval) || (root.clearInterval ? root.clearInterval.bind(root) : function () {}),
+        };
+    }
+
+    // ---- Raw-postMessage provider adapters (NO YouTube IFrame API / Vimeo SDK) ----------
+    // mod_exelearning controls the promoted player by posting the providers' documented
+    // postMessage commands straight to the player iframe and parsing its event messages, so
+    // the trusted Moodle page never loads third-party player SDK script (erseco, DEC-0067).
+    // Both providers use JSON-STRING messages. The host polls getCurrentTime()/getDuration()
+    // every 250ms to emit timeupdate; these adapters keep those values fresh from the
+    // player's pushed infoDelivery (YouTube) / timeupdate (Vimeo) events. Adapters are still
+    // injectable (opts.youtubeFactory / opts.vimeoFactory) for tests.
+
+    function num(v) {
+        return typeof v === 'number' && isFinite(v) ? v : undefined;
+    }
+
+    function parentOrigin() {
+        try {
+            return (root.location && root.location.origin) || '';
+        } catch (e) {
+            return '';
+        }
+    }
+
+    // Pure command builders (exposed for unit tests). Closed action set; null otherwise.
+    function ytCommand(action, value) {
+        switch (action) {
+            case 'play': return { event: 'command', func: 'playVideo', args: [] };
+            case 'pause': return { event: 'command', func: 'pauseVideo', args: [] };
+            case 'seek': return { event: 'command', func: 'seekTo', args: [Number(value) || 0, true] };
+            case 'listen': return { event: 'listening' };
+            default: return null;
+        }
+    }
+    function vimeoCommand(action, value) {
+        switch (action) {
+            case 'play': return { method: 'play' };
+            case 'pause': return { method: 'pause' };
+            case 'seek': return { method: 'setCurrentTime', value: Number(value) || 0 };
+            default: return null;
+        }
+    }
+
+    // Pure inbound-event parsers (exposed for unit tests). Both providers post JSON strings.
+    function parseRaw(raw) {
+        if (typeof raw === 'string') {
+            try { return JSON.parse(raw); } catch (e) { return null; }
+        }
+        return raw && typeof raw === 'object' ? raw : null;
+    }
+    function parseYtEvent(raw) {
+        var d = parseRaw(raw);
+        if (!d || typeof d.event !== 'string') return null;
+        if (d.event === 'onReady') return { kind: 'ready' };
+        if (d.event === 'onError') return { kind: 'error', code: String(d.info != null ? d.info : '') };
+        if (d.event === 'infoDelivery' && d.info && typeof d.info === 'object') {
+            return { kind: 'info', currentTime: num(d.info.currentTime), duration: num(d.info.duration), playerState: num(d.info.playerState) };
+        }
+        if (d.event === 'onStateChange') {
+            return { kind: 'state', playerState: num(typeof d.info === 'object' && d.info ? d.info.playerState : d.info) };
+        }
+        return null;
+    }
+    function parseVimeoEvent(raw) {
+        var d = parseRaw(raw);
+        if (!d || typeof d.event !== 'string') return null;
+        if (d.event === 'ready') return { kind: 'ready' };
+        if (d.event === 'timeupdate' && d.data) return { kind: 'timeupdate', currentTime: num(d.data.seconds), duration: num(d.data.duration) };
+        if (d.event === 'play') return { kind: 'play' };
+        if (d.event === 'pause') return { kind: 'pause' };
+        if (d.event === 'ended' || d.event === 'finish') return { kind: 'ended' };
+        if (d.event === 'error') return { kind: 'error', code: 'vimeo_error' };
+        return null;
+    }
+
+    function youtubeRawAdapter(container, videoId, cb) {
+        var doc = container.ownerDocument || root.document;
+        var origin = parentOrigin();
+        var target = 'https://www.youtube-nocookie.com';
+        var src = target + '/embed/' + videoId + '?enablejsapi=1&rel=0&modestbranding=1' +
+            (origin ? '&origin=' + encodeURIComponent(origin) : '') +
+            (cb.start ? '&start=' + Math.floor(cb.start) : '') +
+            (cb.autoplay ? '&autoplay=1' : '');
+        var frame = doc.createElement('iframe');
+        frame.setAttribute('src', src);
+        frame.setAttribute('allow', 'autoplay; encrypted-media; fullscreen; picture-in-picture');
+        frame.setAttribute('allowfullscreen', '');
+        frame.setAttribute('referrerpolicy', 'strict-origin-when-cross-origin');
+        frame.style.cssText = 'border:0;width:100%;height:100%;';
+        var cache = { currentTime: 0, duration: 0 };
+
+        function post(msg) {
+            if (!msg) return;
+            try { frame.contentWindow.postMessage(JSON.stringify(msg), target); } catch (e) { /* not ready */ }
+        }
+        function onMessage(e) {
+            if (e.source !== frame.contentWindow) return;
+            var ev = parseYtEvent(e.data);
+            if (!ev) return;
+            if (ev.kind === 'ready') {
+                if (cb.onReady) cb.onReady(cache.duration || undefined);
+            } else if (ev.kind === 'info') {
+                if (typeof ev.currentTime === 'number') cache.currentTime = ev.currentTime;
+                if (typeof ev.duration === 'number') cache.duration = ev.duration;
+                signalState(ev.playerState);
+            } else if (ev.kind === 'state') {
+                signalState(ev.playerState);
+            } else if (ev.kind === 'error' && cb.onError) {
+                cb.onError(ev.code);
+            }
+        }
+        function signalState(s) {
+            if (s === 1 && cb.onPlay) cb.onPlay();
+            else if (s === 2 && cb.onPause) cb.onPause();
+            else if (s === 0 && cb.onEnded) cb.onEnded();
+        }
+        if (root.addEventListener) root.addEventListener('message', onMessage);
+        frame.addEventListener('load', function () { post(ytCommand('listen')); });
+        container.appendChild(frame);
+
+        return {
+            play: function () { post(ytCommand('play')); },
+            pause: function () { post(ytCommand('pause')); },
+            seek: function (t) { post(ytCommand('seek', t)); },
+            getCurrentTime: function () { return cache.currentTime; },
+            getDuration: function () { return cache.duration; },
+            destroy: function () {
+                if (root.removeEventListener) root.removeEventListener('message', onMessage);
+                if (frame.parentNode) frame.parentNode.removeChild(frame);
+            },
+        };
+    }
+
+    function vimeoRawAdapter(container, videoId, cb) {
+        var doc = container.ownerDocument || root.document;
+        var target = 'https://player.vimeo.com';
+        var pid = 'exe-vimeo-' + videoId;
+        var src = target + '/video/' + videoId + '?api=1&player_id=' + encodeURIComponent(pid) +
+            (cb.autoplay ? '&autoplay=1' : '');
+        var frame = doc.createElement('iframe');
+        frame.setAttribute('src', src);
+        frame.setAttribute('id', pid);
+        frame.setAttribute('allow', 'autoplay; fullscreen; picture-in-picture');
+        frame.setAttribute('allowfullscreen', '');
+        frame.setAttribute('referrerpolicy', 'strict-origin-when-cross-origin');
+        frame.style.cssText = 'border:0;width:100%;height:100%;';
+        var cache = { currentTime: 0, duration: 0 };
+
+        function post(msg) {
+            if (!msg) return;
+            try { frame.contentWindow.postMessage(JSON.stringify(msg), target); } catch (e) { /* not ready */ }
+        }
+        function subscribe() {
+            ['timeupdate', 'play', 'pause', 'ended', 'error'].forEach(function (name) {
+                post({ method: 'addEventListener', value: name });
+            });
+            if (cb.start) post(vimeoCommand('seek', cb.start));
+        }
+        function onMessage(e) {
+            if (e.source !== frame.contentWindow) return;
+            var ev = parseVimeoEvent(e.data);
+            if (!ev) return;
+            if (ev.kind === 'ready') {
+                subscribe();
+                if (cb.onReady) cb.onReady(cache.duration || undefined);
+            } else if (ev.kind === 'timeupdate') {
+                if (typeof ev.currentTime === 'number') cache.currentTime = ev.currentTime;
+                if (typeof ev.duration === 'number') cache.duration = ev.duration;
+            } else if (ev.kind === 'play' && cb.onPlay) {
+                cb.onPlay();
+            } else if (ev.kind === 'pause' && cb.onPause) {
+                cb.onPause();
+            } else if (ev.kind === 'ended' && cb.onEnded) {
+                cb.onEnded();
+            } else if (ev.kind === 'error' && cb.onError) {
+                cb.onError(ev.code);
+            }
+        }
+        if (root.addEventListener) root.addEventListener('message', onMessage);
+        container.appendChild(frame);
+
+        return {
+            play: function () { post(vimeoCommand('play')); },
+            pause: function () { post(vimeoCommand('pause')); },
+            seek: function (t) { post(vimeoCommand('seek', t)); },
+            getCurrentTime: function () { return cache.currentTime; },
+            getDuration: function () { return cache.duration; },
+            destroy: function () {
+                if (root.removeEventListener) root.removeEventListener('message', onMessage);
+                if (frame.parentNode) frame.parentNode.removeChild(frame);
+            },
+        };
+    }
+
+    // ---- Accessible modal -------------------------------------------------------------
+
+    function buildModal(session) {
+        var opts = session.opts || {};
+        var doc = opts.document || root.document;
+        var dialog = doc.createElement('dialog');
+        dialog.className = 'exe-media-modal';
+        dialog.setAttribute('aria-label', tr('Video player'));
+        try {
+            dialog.setAttribute('closedby', 'any'); // light-dismiss where supported
+        } catch (e) {
+            /* older engines */
+        }
+
+        var closeBtn = doc.createElement('button');
+        closeBtn.setAttribute('type', 'button');
+        closeBtn.className = 'exe-media-modal__close';
+        closeBtn.setAttribute('aria-label', tr('Close video'));
+        closeBtn.textContent = tr('Close');
+        closeBtn.addEventListener('click', function () {
+            requestClose(session);
+        });
+
+        var body = doc.createElement('div');
+        body.className = 'exe-media-modal__body';
+
+        dialog.appendChild(closeBtn);
+        dialog.appendChild(body);
+
+        // Safari light-dismiss fallback: a click whose target is the dialog itself is the backdrop.
+        dialog.addEventListener('click', function (e) {
+            if (e.target === dialog) requestClose(session);
+        });
+        // Esc / platform close request.
+        dialog.addEventListener('close', function () {
+            if (session.hiding) {
+                session.hiding = false;
+                return;
+            }
+            requestClose(session);
+        });
+
+        (doc.body || doc.documentElement).appendChild(dialog);
+        if (typeof dialog.showModal === 'function') dialog.showModal();
+
+        session.dialog = dialog;
+        return body;
+    }
+
+    function showModal(session) {
+        if (session.dialog && typeof session.dialog.showModal === 'function') session.dialog.showModal();
+    }
+
+    function hideModal(session) {
+        if (session.dialog && typeof session.dialog.close === 'function') {
+            session.hiding = true;
+            session.dialog.close();
+        }
+    }
+
+    function requestClose(session) {
+        if (session.closed) return;
+        session.closed = true;
+        sendEvent(session, { action: 'closed' });
+        destroyAdapter(session);
+        if (session.dialog) {
+            if (typeof session.dialog.close === 'function') session.dialog.close();
+            if (typeof session.dialog.remove === 'function') session.dialog.remove();
+        }
+    }
+
+    function destroyAdapter(session) {
+        if (session.pollTimer != null) {
+            session.interval.clear(session.pollTimer);
+            session.pollTimer = null;
+        }
+        if (session.adapter && session.adapter.destroy) session.adapter.destroy();
+        session.adapter = null;
+    }
+
+    // ---- Media event relay ------------------------------------------------------------
+
+    function sendEvent(session, ev) {
+        ev.type = TYPE;
+        ev.v = VERSION;
+        if (session.port1) session.port1.postMessage(ev);
+    }
+
+    function emitTimeupdate(session, ct, dur) {
+        if (typeof ct === 'number' && isFinite(ct) && typeof dur === 'number' && isFinite(dur)) {
+            sendEvent(session, { action: 'timeupdate', currentTime: ct, duration: dur });
+        }
+    }
+
+    function startPolling(session) {
+        if (session.pollTimer != null) return;
+        session.pollTimer = session.interval.set(function () {
+            if (!session.adapter) return;
+            var ct = session.adapter.getCurrentTime();
+            var dur = session.adapter.getDuration();
+            if (isThenable(ct) || isThenable(dur)) {
+                Promise.all([Promise.resolve(ct), Promise.resolve(dur)]).then(function (r) {
+                    emitTimeupdate(session, r[0], r[1]);
+                });
+            } else {
+                emitTimeupdate(session, ct, dur);
+            }
+        }, 250);
+    }
+
+    function openMedia(session, provider, videoId, openOpts) {
+        var opts = session.opts || {};
+        // Single active media per session: discard any previous player/poll-timer/<dialog>
+        // before opening a new one, so repeated 'open' commands cannot stack modals or orphan
+        // provider players (host-page resource exhaustion). Remove the old dialog directly
+        // (no .close()) so its 'close' listener does not fire a spurious 'closed' to the child.
+        destroyAdapter(session);
+        if (session.dialog) {
+            if (typeof session.dialog.remove === 'function') session.dialog.remove();
+            session.dialog = null;
+        }
+        var container = buildModal(session);
+        var callbacks = {
+            start: openOpts.start,
+            autoplay: openOpts.autoplay,
+            onReady: function (duration) {
+                sendEvent(session, { action: 'ready', duration: duration });
+                startPolling(session);
+            },
+            onPlay: function () { sendEvent(session, { action: 'play' }); },
+            onPause: function () { sendEvent(session, { action: 'pause' }); },
+            onEnded: function () { sendEvent(session, { action: 'ended' }); },
+            onSeeked: function (t) { sendEvent(session, { action: 'seeked', currentTime: t }); },
+            onError: function (code) { sendEvent(session, { action: 'error', code: String(code), fatal: true }); },
+        };
+        var factory =
+            provider === 'vimeo'
+                ? opts.vimeoFactory || vimeoRawAdapter
+                : opts.youtubeFactory || youtubeRawAdapter;
+        session.adapter = factory(container, videoId, callbacks);
+    }
+
+    function answerState(session, reqId, field) {
+        if (!session.adapter) return;
+        var value = field === 'duration' ? session.adapter.getDuration() : session.adapter.getCurrentTime();
+        Promise.resolve(value).then(function (v) {
+            var ev = { action: 'state', reqId: reqId };
+            ev[field === 'duration' ? 'duration' : 'currentTime'] = v;
+            sendEvent(session, ev);
+        });
+    }
+
+    function processCommand(session, data) {
+        if (!data || data.type !== TYPE || data.v !== VERSION) return;
+        if (data.exelearningBridge !== session.nonce) return; // nonce gate
+        if (!policy.COMMANDS[data.action]) return;
+
+        if (data.action === 'open') {
+            var url = policy.canonicalEmbedUrl(data.provider, data.videoId);
+            if (!url) {
+                sendEvent(session, { action: 'error', code: 'unsupported_provider', fatal: true });
+                return;
+            }
+            session.closed = false;
+            openMedia(session, data.provider, data.videoId, { start: data.start, autoplay: data.autoplay });
+            return;
+        }
+        if (!policy.validateCommand(data, session.nonce)) return;
+
+        var a = session.adapter;
+        switch (data.action) {
+            case 'play': if (a) a.play(); break;
+            case 'pause': if (a) a.pause(); break;
+            case 'seek': if (a) a.seek(data.t); break;
+            case 'getCurrentTime': answerState(session, data.reqId, 'currentTime'); break;
+            case 'getDuration': answerState(session, data.reqId, 'duration'); break;
+            case 'hide': hideModal(session); break;
+            case 'show': showModal(session); break;
+            case 'close': requestClose(session); break;
+            default: break;
+        }
+    }
+
+    // ---- Handshake + attachment -------------------------------------------------------
+
+    var records = [];
+
+    function teardown(session) {
+        if (!session) return;
+        destroyAdapter(session);
+        if (session.port1 && session.port1.close) session.port1.close();
+        if (session.dialog && session.dialog.remove) session.dialog.remove();
+    }
+
+    function handleHello(rec, data) {
+        var existing = rec.session;
+        if (existing && existing.helloId === data.helloId) return; // duplicate
+        if (existing) teardown(existing); // new helloId → re-pair
+
+        var nonce = genNonce(rec.opts);
+        var channel = makeChannel(rec.opts);
+        var session = {
+            iframe: rec.iframe,
+            opts: rec.opts,
+            nonce: nonce,
+            helloId: data.helloId,
+            port1: channel.port1,
+            adapter: null,
+            dialog: null,
+            pollTimer: null,
+            hiding: false,
+            closed: false,
+            interval: getInterval(rec.opts),
+        };
+        rec.session = session;
+
+        channel.port1.onmessage = function (e) {
+            processCommand(session, e.data);
+        };
+        if (typeof channel.port1.start === 'function') channel.port1.start();
+
+        rec.iframe.contentWindow.postMessage(
+            { type: TYPE, v: VERSION, action: 'welcome', helloId: data.helloId, exelearningBridge: nonce },
+            '*',
+            [channel.port2],
+        );
+    }
+
+    function onWindowMessage(rec, e) {
+        if (!rec.iframe || !rec.iframe.contentWindow || e.source !== rec.iframe.contentWindow) return;
+        if (policy.isHello(e.data)) handleHello(rec, e.data);
+    }
+
+    /**
+     * Register an iframe that renders eXeLearning content and start relaying its media.
+     * @returns {{detach: function}} handle
+     */
+    function attach(iframe, opts) {
+        opts = opts || {};
+        var win = opts.win || root;
+        var rec = { iframe: iframe, opts: opts, session: null, win: win, handler: null };
+        rec.handler = function (e) {
+            onWindowMessage(rec, e);
+        };
+        if (win.addEventListener) win.addEventListener('message', rec.handler);
+        records.push(rec);
+        return {
+            detach: function () {
+                if (win.removeEventListener) win.removeEventListener('message', rec.handler);
+                teardown(rec.session);
+                var i = records.indexOf(rec);
+                if (i >= 0) records.splice(i, 1);
+            },
+        };
+    }
+
+    function resetForTests() {
+        for (var i = 0; i < records.length; i++) {
+            var rec = records[i];
+            if (rec.win && rec.win.removeEventListener) rec.win.removeEventListener('message', rec.handler);
+            teardown(rec.session);
+        }
+        records = [];
+    }
+
+    root.exeMediaHost = {
+        attach: attach,
+        buildModal: buildModal,
+        _youtubeAdapter: youtubeRawAdapter,
+        _vimeoAdapter: vimeoRawAdapter,
+        _ytCommand: ytCommand,
+        _vimeoCommand: vimeoCommand,
+        _parseYtEvent: parseYtEvent,
+        _parseVimeoEvent: parseVimeoEvent,
+        _processCommand: processCommand,
+        _resetForTests: resetForTests,
+    };
+})(typeof window !== 'undefined' ? window : globalThis);
diff --git a/src/embed/exe_media_policy.js b/src/embed/exe_media_policy.js
new file mode 100644
index 0000000..34cf942
--- /dev/null
+++ b/src/embed/exe_media_policy.js
@@ -0,0 +1,258 @@
+/**
+ * exe_media_policy — pure, framework-free policy for the external-media bridge.
+ *
+ * Single source of truth shared by:
+ *   - the child runtime (exe_media_bridge.js) that runs inside exported content, and
+ *   - the reference parent relay (exe-media-host.js) that runs in the trusted host page.
+ *
+ * Responsibilities (all pure — no DOM mutation, no postMessage):
+ *   - Detect and normalize supported external media (YouTube, Vimeo) into a neutral
+ *     descriptor; recognize PDFs for a deferred open-in-new-tab fallback.
+ *   - Rebuild canonical, privacy-friendly embed URLs from a bare provider id, so the
+ *     bridge never has to trust an attacker-supplied URL (kills redirect-laundering).
+ *   - Validate the versioned postMessage/MessageChannel contract (handshake, commands,
+ *     events) with a strict schema, a closed action enum and a provider allowlist.
+ *
+ * This file is a CLASSIC browser script (no ES module syntax) so it can be shipped
+ * verbatim inside exported packages and loaded over file:// — while still being
+ * importable (for its side effect) by the Vitest suite, which reads the global it sets.
+ *
+ * @license AGPL-3.0
+ */
+(function (root) {
+    'use strict';
+
+    var TYPE = 'exe-media';
+    var VERSION = 1;
+
+    // Bare-id shapes. YouTube ids are exactly 11 url-safe chars; Vimeo ids are numeric.
+    var ID_RE = {
+        youtube: /^[A-Za-z0-9_-]{11}$/,
+        vimeo: /^[0-9]{6,12}$/,
+    };
+
+    // Host allow-lists per provider. Anything else never matches a provider, so IPs,
+    // loopback, *.local and look-alike domains (evil.com/watch?v=...) cannot slip in.
+    var YOUTUBE_HOSTS = {
+        'youtube.com': 1,
+        'www.youtube.com': 1,
+        'm.youtube.com': 1,
+        'music.youtube.com': 1,
+        'youtube-nocookie.com': 1,
+        'www.youtube-nocookie.com': 1,
+    };
+    var YOUTU_BE_HOSTS = { 'youtu.be': 1, 'www.youtu.be': 1 };
+    var VIMEO_HOSTS = { 'vimeo.com': 1, 'www.vimeo.com': 1 };
+    var VIMEO_PLAYER_HOSTS = { 'player.vimeo.com': 1 };
+
+    // Closed action enums. Anything outside these is dropped before any work happens.
+    var COMMANDS = { open: 1, play: 1, pause: 1, seek: 1, getCurrentTime: 1, getDuration: 1, hide: 1, show: 1, close: 1 };
+    var EVENTS = { ready: 1, play: 1, pause: 1, ended: 1, timeupdate: 1, seeked: 1, state: 1, error: 1, closed: 1 };
+
+    function isObject(v) {
+        return v !== null && typeof v === 'object';
+    }
+
+    function finiteNonNeg(n) {
+        return typeof n === 'number' && isFinite(n) && n >= 0;
+    }
+
+    function isAllowedProvider(provider) {
+        return provider === 'youtube' || provider === 'vimeo';
+    }
+
+    function isValidVideoId(provider, id) {
+        var re = ID_RE[provider];
+        return !!re && typeof id === 'string' && re.test(id);
+    }
+
+    /**
+     * Build the canonical, privacy-friendly embed URL for a provider id. Returns null
+     * for unknown providers or ids that fail the provider's shape — so a malicious id
+     * can never be templated into a live URL.
+     */
+    function canonicalEmbedUrl(provider, id) {
+        if (provider === 'youtube' && isValidVideoId('youtube', id)) {
+            return 'https://www.youtube-nocookie.com/embed/' + id;
+        }
+        if (provider === 'vimeo' && isValidVideoId('vimeo', id)) {
+            return 'https://player.vimeo.com/video/' + id;
+        }
+        return null;
+    }
+
+    function firstPathSegment(pathname) {
+        var parts = pathname.split('/');
+        for (var i = 0; i < parts.length; i++) {
+            if (parts[i]) return parts[i];
+        }
+        return '';
+    }
+
+    function youtubeIdFromUrl(u) {
+        var host = u.hostname.toLowerCase();
+        if (YOUTU_BE_HOSTS[host]) {
+            return firstPathSegment(u.pathname);
+        }
+        if (YOUTUBE_HOSTS[host]) {
+            var v = u.searchParams.get('v');
+            if (v) return v;
+            var m = u.pathname.match(/^\/(?:embed|v|shorts)\/([^/?#]+)/);
+            if (m) return m[1];
+        }
+        return '';
+    }
+
+    function vimeoIdFromUrl(u) {
+        var host = u.hostname.toLowerCase();
+        if (VIMEO_PLAYER_HOSTS[host]) {
+            var m = u.pathname.match(/^\/video\/([0-9]+)/);
+            if (m) return m[1];
+        }
+        if (VIMEO_HOSTS[host]) {
+            return firstPathSegment(u.pathname);
+        }
+        return '';
+    }
+
+    function descriptor(provider, id, originalUrl, embedUrl, extra) {
+        var d = {
+            provider: provider,
+            providerVideoId: id,
+            originalUrl: originalUrl,
+            embedUrl: embedUrl,
+            aspectRatio: provider === 'pdf' ? undefined : '16:9',
+            interactive: false,
+            requiresBridge: provider !== 'pdf',
+        };
+        if (extra && extra.title) d.title = extra.title;
+        return d;
+    }
+
+    /**
+     * Normalize a URL string or an element (iframe/anchor) into a neutral media
+     * descriptor, or null when it is not a supported external embed.
+     */
+    function parseExternalMedia(input) {
+        var url = input;
+        var title;
+        if (input && typeof input.getAttribute === 'function') {
+            url = input.getAttribute('src') || input.getAttribute('href') || '';
+            title = input.getAttribute('title') || undefined;
+        }
+        if (typeof url !== 'string' || !url) return null;
+
+        var u;
+        try {
+            u = new URL(url);
+        } catch (e) {
+            return null;
+        }
+        // Reject userinfo (https://user@host/...) and non-web schemes outright.
+        if (u.username || u.password) return null;
+        if (u.protocol !== 'https:' && u.protocol !== 'http:') return null;
+
+        var ytId = youtubeIdFromUrl(u);
+        if (ytId) {
+            if (!isValidVideoId('youtube', ytId)) return null;
+            return descriptor('youtube', ytId, url, canonicalEmbedUrl('youtube', ytId), { title: title });
+        }
+
+        var vId = vimeoIdFromUrl(u);
+        if (vId) {
+            if (!isValidVideoId('vimeo', vId)) return null;
+            return descriptor('vimeo', vId, url, canonicalEmbedUrl('vimeo', vId), { title: title });
+        }
+
+        if (u.pathname.toLowerCase().slice(-4) === '.pdf') {
+            return descriptor('pdf', null, url, url, { title: title });
+        }
+
+        return null;
+    }
+
+    function hasEnvelope(d) {
+        return isObject(d) && d.type === TYPE && d.v === VERSION;
+    }
+
+    function isHello(d) {
+        return hasEnvelope(d) && d.action === 'hello' && typeof d.helloId === 'string' && d.helloId.length > 0;
+    }
+
+    function isWelcome(d) {
+        return (
+            hasEnvelope(d) &&
+            d.action === 'welcome' &&
+            typeof d.helloId === 'string' &&
+            typeof d.exelearningBridge === 'string' &&
+            d.exelearningBridge.length > 0
+        );
+    }
+
+    /**
+     * Validate a child→parent command. Defense in depth: envelope + a present, matching
+     * nonce (the `!!expectedNonce` guard prevents an absent expected nonce from ever
+     * authenticating a forged message) + closed action enum + per-action payload checks.
+     */
+    function validateCommand(d, expectedNonce) {
+        if (!hasEnvelope(d)) return false;
+        if (!expectedNonce) return false;
+        if (typeof d.exelearningBridge !== 'string' || d.exelearningBridge !== expectedNonce) return false;
+        if (!COMMANDS[d.action]) return false;
+        switch (d.action) {
+            case 'open':
+                return (
+                    Number.isInteger(d.reqId) &&
+                    isAllowedProvider(d.provider) &&
+                    isValidVideoId(d.provider, d.videoId) &&
+                    (d.start == null || finiteNonNeg(d.start))
+                );
+            case 'seek':
+                return finiteNonNeg(d.t);
+            case 'getCurrentTime':
+            case 'getDuration':
+                return Number.isInteger(d.reqId);
+            default:
+                return true; // play / pause / hide / show / close — no payload
+        }
+    }
+
+    /**
+     * Validate a parent→child event. Same envelope + closed enum + per-action payload.
+     */
+    function validateEvent(d) {
+        if (!hasEnvelope(d)) return false;
+        if (!EVENTS[d.action]) return false;
+        switch (d.action) {
+            case 'timeupdate':
+                return finiteNonNeg(d.currentTime) && finiteNonNeg(d.duration);
+            case 'seeked':
+                return finiteNonNeg(d.currentTime);
+            case 'state':
+                return Number.isInteger(d.reqId);
+            case 'ready':
+                return d.duration == null || finiteNonNeg(d.duration);
+            case 'error':
+                return typeof d.code === 'string' && typeof d.fatal === 'boolean';
+            default:
+                return true; // play / pause / ended / closed
+        }
+    }
+
+    var api = {
+        TYPE: TYPE,
+        VERSION: VERSION,
+        COMMANDS: COMMANDS,
+        EVENTS: EVENTS,
+        parseExternalMedia: parseExternalMedia,
+        canonicalEmbedUrl: canonicalEmbedUrl,
+        isAllowedProvider: isAllowedProvider,
+        isValidVideoId: isValidVideoId,
+        isHello: isHello,
+        isWelcome: isWelcome,
+        validateCommand: validateCommand,
+        validateEvent: validateEvent,
+    };
+
+    root.exeMediaPolicy = api;
+})(typeof window !== 'undefined' ? window : globalThis);
diff --git a/src/embed/relay-host.ts b/src/embed/relay-host.ts
new file mode 100644
index 0000000..a4a837d
--- /dev/null
+++ b/src/embed/relay-host.ts
@@ -0,0 +1,94 @@
+/**
+ * Loads the eXe-core external-media bridge into the trusted parent (the Viewer
+ * page) and drives it.
+ *
+ * - Channel A (`exe-embed`): overlays real YouTube/Vimeo/Dailymotion/PDF players
+ *   over the geometry placeholders the shim reports from inside the opaque
+ *   iframe. `exe_embed_relay.js` attaches `window.exeEmbedRelay`.
+ * - Channel B (`exe-media`): hosts the interactive-video iDevice modal bridge.
+ *   `exe_media_host.js` (+ its `exe_media_policy.js` dependency) attaches
+ *   `window.exeMediaHost`.
+ *
+ * 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_embed_relay.js'
+import './exe_media_policy.js'
+import './exe_media_host.js'
+
+interface RelayInstance {
+	clear?: () => void
+	reflow?: () => void
+}
+
+export interface EmbedRelayConfig {
+	mode?: string
+	whitelist?: string[]
+}
+
+interface EmbedRelayApi {
+	init: (config: EmbedRelayConfig) => RelayInstance
+}
+
+interface MediaHostApi {
+	attach: (iframe: HTMLIFrameElement, opts: Record<string, unknown>) => void
+}
+
+interface BridgeGlobals {
+	exeEmbedRelay?: EmbedRelayApi
+	exeMediaHost?: MediaHostApi
+}
+
+/** The bridge globals attached to `window` by the imported mirror scripts. */
+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)
+	}
+}
+
+/**
+ * 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' }, '*')
+}
+
+/**
+ * Attach the interactive-video media host to a content iframe (Channel B).
+ * @param iframe The opaque content iframe to attach the media host to.
+ */
+export function attachMedia(iframe: HTMLIFrameElement): void {
+	globals().exeMediaHost?.attach(iframe, {})
+}
+
+/** 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..20211fe 100644
--- a/src/types/shims.d.ts
+++ b/src/types/shims.d.ts
@@ -3,3 +3,11 @@ 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 / window.exeMediaHost). We import them only
+// for their side effects and use the window globals via typed casts.
+declare module '*/exe_embed_relay.js'
+declare module '*/exe_embed_shim.js'
+declare module '*/exe_media_policy.js'
+declare module '*/exe_media_host.js'
diff --git a/src/viewer/ElpxViewer.vue b/src/viewer/ElpxViewer.vue
index 49f3aba..6b30622 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 { attachMedia, clearOverlays, type EmbedRelayConfig, pingEmbeds, reflowOverlays, 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,48 @@ 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 (Channel A) and hosts the
+				// interactive-video bridge (Channel B).
+				startRelay(relayConfig)
+				pingEmbeds(iframe)
+				attachMedia(iframe)
+			})
+			slot.appendChild(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/IframeSandboxTest.php b/tests/Unit/Service/IframeSandboxTest.php
new file mode 100644
index 0000000..8043e0e
--- /dev/null
+++ b/tests/Unit/Service/IframeSandboxTest.php
@@ -0,0 +1,102 @@
+<?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);
+	}
+}
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/FixedResourceManifestTest.php b/tests/Unit/Service/Preview/FixedResourceManifestTest.php
new file mode 100644
index 0000000..249cbb8
--- /dev/null
+++ b/tests/Unit/Service/Preview/FixedResourceManifestTest.php
@@ -0,0 +1,108 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\Service\Preview;
+
+use OCA\ExeLearning\Service\Preview\FixedResourceManifest;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests for {@see FixedResourceManifest} — the fixed-installation-resource
+ * (layer 1) resolver: exact-key manifest lookup, distribution-root containment,
+ * and graceful disable when the manifest is absent.
+ */
+final class FixedResourceManifestTest extends TestCase {
+	private string $distRoot;
+
+	protected function setUp(): void {
+		$this->distRoot = sys_get_temp_dir() . '/exe-fixed-' . bin2hex(random_bytes(6));
+		mkdir($this->distRoot . '/bundles', 0770, true);
+		mkdir($this->distRoot . '/libs/jquery', 0770, true);
+	}
+
+	protected function tearDown(): void {
+		$this->removeTree($this->distRoot);
+		$this->removeTree(dirname($this->distRoot) . '/exe-outside-' . basename($this->distRoot));
+	}
+
+	private function writeManifest(array $resources): void {
+		file_put_contents(
+			$this->distRoot . '/bundles/preview-fixed-resources.json',
+			json_encode(['schemaVersion' => 1, 'buildVersion' => 'test', 'resources' => $resources]),
+		);
+	}
+
+	public function testResolvesEnumeratedResource(): void {
+		$body = 'window.jQuery=function(){};';
+		file_put_contents($this->distRoot . '/libs/jquery/jquery.min.js', $body);
+		$this->writeManifest([
+			'libs/jquery/jquery.min.js' => ['path' => 'libs/jquery/jquery.min.js', 'size' => strlen($body)],
+		]);
+		$manifest = new FixedResourceManifest($this->distRoot);
+
+		self::assertTrue($manifest->has('libs/jquery/jquery.min.js'));
+		$resource = $manifest->get('libs/jquery/jquery.min.js');
+		self::assertNotNull($resource);
+		self::assertSame($body, $resource['bytes']);
+		// get() reports the ACTUAL byte length read from disk, not the manifest's
+		// declared size (which the server never trusts for serving).
+		self::assertSame(strlen($body), $resource['size']);
+	}
+
+	public function testUnknownIdIsNeitherHadNorResolved(): void {
+		$this->writeManifest(['libs/jquery/jquery.min.js' => ['path' => 'libs/jquery/jquery.min.js']]);
+		$manifest = new FixedResourceManifest($this->distRoot);
+
+		self::assertFalse($manifest->has('libs/does/not/exist.js'));
+		self::assertNull($manifest->get('libs/does/not/exist.js'));
+	}
+
+	public function testAbsentManifestDisablesTheLayer(): void {
+		// No bundles/preview-fixed-resources.json written.
+		$manifest = new FixedResourceManifest($this->distRoot);
+		self::assertFalse($manifest->has('anything'));
+		self::assertNull($manifest->get('anything'));
+	}
+
+	public function testMalformedManifestDisablesTheLayer(): void {
+		file_put_contents($this->distRoot . '/bundles/preview-fixed-resources.json', '{ not json');
+		$manifest = new FixedResourceManifest($this->distRoot);
+		self::assertFalse($manifest->has('anything'));
+	}
+
+	public function testManifestPathEscapingRootIsRejected(): void {
+		$outside = dirname($this->distRoot) . '/exe-outside-' . basename($this->distRoot);
+		file_put_contents($outside, 'SECRET');
+		$this->writeManifest(['evil' => ['path' => '../exe-outside-' . basename($this->distRoot)]]);
+		$manifest = new FixedResourceManifest($this->distRoot);
+
+		// The id is enumerated, but the containment check refuses to read it.
+		self::assertTrue($manifest->has('evil'));
+		self::assertNull($manifest->get('evil'));
+	}
+
+	public function testMissingBackingFileYieldsNull(): void {
+		$this->writeManifest(['ghost' => ['path' => 'libs/jquery/ghost.js']]);
+		$manifest = new FixedResourceManifest($this->distRoot);
+		self::assertTrue($manifest->has('ghost'));
+		self::assertNull($manifest->get('ghost'));
+	}
+
+	private function removeTree(string $dir): void {
+		if (is_file($dir)) {
+			@unlink($dir);
+			return;
+		}
+		if (!is_dir($dir)) {
+			return;
+		}
+		foreach (scandir($dir) ?: [] as $item) {
+			if ($item === '.' || $item === '..') {
+				continue;
+			}
+			$this->removeTree($dir . '/' . $item);
+		}
+		@rmdir($dir);
+	}
+}
diff --git a/tests/Unit/Service/Preview/PreviewContractConformanceTest.php b/tests/Unit/Service/Preview/PreviewContractConformanceTest.php
new file mode 100644
index 0000000..2dedf7c
--- /dev/null
+++ b/tests/Unit/Service/Preview/PreviewContractConformanceTest.php
@@ -0,0 +1,252 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\Service\Preview;
+
+use OCA\ExeLearning\Service\Preview\ApiResult;
+use OCA\ExeLearning\Service\Preview\FixedResourceManifest;
+use OCA\ExeLearning\Service\Preview\PreviewResponse;
+use OCA\ExeLearning\Service\Preview\PreviewServer;
+use OCA\ExeLearning\Service\Preview\PreviewSessionApi;
+use OCA\ExeLearning\Service\Preview\PreviewSessionLimits;
+use OCA\ExeLearning\Service\Preview\PreviewSessionStore;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Replays the shared eXeLearning preview-serving-contract v2 conformance vectors
+ * (tests/fixtures/preview-contract/vectors.json, vendored verbatim from eXe
+ * core) against this app's management API + serving route. Porting the harness
+ * interpretation — not just the assertions — keeps the protocol semantics
+ * aligned with every other host (Moodle / WordPress / Omeka S / Procomún /
+ * Electron / core) beyond the CSP drift-check.
+ *
+ * The vectors drive the OCP-free seams ({@see PreviewSessionApi} +
+ * {@see PreviewServer}) directly: the multipart encoding the harness describes
+ * is exactly what {@see \OCA\ExeLearning\Controller\PreviewSessionController}
+ * decodes into these calls.
+ */
+final class PreviewContractConformanceTest extends TestCase {
+	private const OWNER = 'conformance-user';
+
+	private string $root;
+	private string $distRoot;
+	private PreviewSessionApi $api;
+	private PreviewServer $server;
+	private string $previewId = '';
+
+	protected function setUp(): void {
+		$this->root = sys_get_temp_dir() . '/exe-vec-' . bin2hex(random_bytes(6));
+		$this->distRoot = sys_get_temp_dir() . '/exe-vec-dist-' . bin2hex(random_bytes(6));
+		mkdir($this->distRoot, 0770, true);
+	}
+
+	protected function tearDown(): void {
+		$this->removeTree($this->root);
+		$this->removeTree($this->distRoot);
+	}
+
+	public function testReplayVectors(): void {
+		$vectors = json_decode(
+			(string)file_get_contents(__DIR__ . '/../../../fixtures/preview-contract/vectors.json'),
+			true,
+		);
+		self::assertSame(2, $vectors['protocolVersion']);
+
+		$fixed = $this->materializeFixedResources($vectors['fixedResources']);
+		$store = new PreviewSessionStore($this->root, new PreviewSessionLimits());
+		$this->api = new PreviewSessionApi($store, $fixed);
+		$this->server = new PreviewServer($store, $fixed);
+
+		foreach ($vectors['steps'] as $step) {
+			$this->runStep($step);
+		}
+	}
+
+	/**
+	 * Write each fixed resource under a throwaway distribution root and register
+	 * it in the host's manifest copy, then resolve fixed refs through that
+	 * manifest only (harness semantics step 1).
+	 *
+	 * @param array<string,array{path:string,content:string}> $resources
+	 */
+	private function materializeFixedResources(array $resources): FixedResourceManifest {
+		$manifest = [];
+		foreach ($resources as $id => $resource) {
+			$target = $this->distRoot . '/' . $resource['path'];
+			@mkdir(dirname($target), 0770, true);
+			file_put_contents($target, $resource['content']);
+			$manifest[$id] = ['path' => $resource['path'], 'size' => strlen($resource['content'])];
+		}
+		@mkdir($this->distRoot . '/bundles', 0770, true);
+		file_put_contents(
+			$this->distRoot . '/bundles/preview-fixed-resources.json',
+			json_encode(['schemaVersion' => 1, 'resources' => $manifest]),
+		);
+		return new FixedResourceManifest($this->distRoot);
+	}
+
+	private function runStep(array $step): void {
+		$id = $step['id'];
+		$method = $step['request']['method'];
+		$path = str_replace('{previewId}', $this->previewId, $step['request']['path']);
+		$expect = $step['expect'];
+
+		if ($method === 'GET') {
+			$response = $this->dispatchServe($path, $step['request']['headers'] ?? []);
+			$this->assertServe($id, $response, $expect);
+			return;
+		}
+		$result = $this->dispatchManagement($method, $path, $step['request']['body'] ?? null);
+		$this->assertManagement($id, $result, $expect);
+		if ($id === 'create-session') {
+			$this->previewId = $result->body['previewId'];
+		}
+	}
+
+	private function dispatchServe(string $path, array $headers): PreviewResponse {
+		self::assertSame(1, preg_match('#^/preview/([^/]+)/(.*)$#', $path, $m), "unexpected serve path: $path");
+		return $this->server->serve(
+			$m[1],
+			$m[2],
+			$headers['If-None-Match'] ?? null,
+			$headers['Range'] ?? null,
+		);
+	}
+
+	private function dispatchManagement(string $method, string $path, ?array $body): ApiResult {
+		if ($method === 'POST' && $path === '/api/preview-session') {
+			return $this->api->create(self::OWNER);
+		}
+		if ($method === 'POST' && str_ends_with($path, '/assets')) {
+			return $this->api->uploadAssets($this->previewId, self::OWNER, $this->assetEntries($body));
+		}
+		if ($method === 'POST' && str_ends_with($path, '/revisions')) {
+			return $this->api->publishRevision($this->previewId, self::OWNER, $this->revisionMeta($body));
+		}
+		if ($method === 'DELETE') {
+			return $this->api->delete($this->previewId, self::OWNER);
+		}
+		self::fail("unhandled management request: $method $path");
+	}
+
+	/**
+	 * `body.kind === "assets"`: each entry becomes `{ key, size, bytes }` (the
+	 * harness's `size` = byte length of `content`).
+	 *
+	 * @return list<array{key:string,declaredSize:int,bytes:string}>
+	 */
+	private function assetEntries(?array $body): array {
+		$entries = [];
+		foreach ($body['entries'] ?? [] as $entry) {
+			$entries[] = [
+				'key' => $entry['key'],
+				'declaredSize' => strlen($entry['content']),
+				'bytes' => $entry['content'],
+			];
+		}
+		return $entries;
+	}
+
+	/**
+	 * `body.kind === "revision"`: `meta` plus `writes` mapped to `{ path, bytes }`
+	 * (the harness sends `writes` as paths + index-aligned file parts).
+	 *
+	 * @return array<string,mixed>
+	 */
+	private function revisionMeta(?array $body): array {
+		$meta = $body['meta'];
+		$writes = [];
+		foreach ($body['writes'] ?? [] as $write) {
+			$writes[] = ['path' => $write['path'], 'bytes' => $write['content']];
+		}
+		$meta['writes'] = $writes;
+		return $meta;
+	}
+
+	private function assertManagement(string $id, ApiResult $result, array $expect): void {
+		self::assertSame($expect['status'], $result->status, "status for step $id");
+		if (isset($expect['body'])) {
+			$this->assertBodySubset($expect['body'], $result->body, $id);
+		}
+	}
+
+	private function assertServe(string $id, PreviewResponse $response, array $expect): void {
+		self::assertSame($expect['status'], $response->status, "status for step $id");
+		if (isset($expect['bodyText'])) {
+			self::assertSame($expect['bodyText'], $response->body, "bodyText for step $id");
+		}
+		foreach ($expect['headers'] ?? [] as $name => $spec) {
+			$this->assertHeader($id, $response->headers, $name, $spec);
+		}
+	}
+
+	/**
+	 * @param array<string,string> $headers
+	 * @param string|array<string,mixed> $spec
+	 */
+	private function assertHeader(string $id, array $headers, string $name, string|array $spec): void {
+		$value = null;
+		$present = false;
+		foreach ($headers as $key => $headerValue) {
+			if (strcasecmp($key, $name) === 0) {
+				$value = $headerValue;
+				$present = true;
+				break;
+			}
+		}
+		if (is_string($spec)) {
+			self::assertTrue($present, "header $name present for step $id");
+			self::assertSame($spec, $value, "header $name for step $id");
+			return;
+		}
+		if (isset($spec['absent'])) {
+			self::assertFalse($present, "header $name must be absent for step $id");
+			return;
+		}
+		self::assertTrue($present, "header $name present for step $id");
+		if (isset($spec['startsWith'])) {
+			self::assertStringStartsWith($spec['startsWith'], (string)$value, "header $name startsWith for step $id");
+		}
+		if (isset($spec['contains'])) {
+			self::assertStringContainsString($spec['contains'], (string)$value, "header $name contains for step $id");
+		}
+	}
+
+	/**
+	 * Recursive subset match: JSON arrays (PHP lists) must match exactly, JSON
+	 * objects (assoc) may carry extra keys.
+	 *
+	 * @param array<mixed> $expected
+	 * @param array<mixed> $actual
+	 */
+	private function assertBodySubset(array $expected, array $actual, string $id): void {
+		foreach ($expected as $key => $value) {
+			self::assertArrayHasKey($key, $actual, "body.$key for step $id");
+			if (is_array($value)) {
+				if (array_is_list($value)) {
+					self::assertSame($value, $actual[$key], "body.$key (array) for step $id");
+				} else {
+					self::assertIsArray($actual[$key], "body.$key (object) for step $id");
+					$this->assertBodySubset($value, $actual[$key], $id);
+				}
+			} else {
+				self::assertSame($value, $actual[$key], "body.$key for step $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/Unit/Service/Preview/PreviewPolicyTest.php b/tests/Unit/Service/Preview/PreviewPolicyTest.php
new file mode 100644
index 0000000..2a33903
--- /dev/null
+++ b/tests/Unit/Service/Preview/PreviewPolicyTest.php
@@ -0,0 +1,155 @@
+<?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'));
+	}
+
+	public function testAssetKeyValidation(): void {
+		self::assertTrue(PreviewPolicy::isValidAssetKey('aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57'));
+		self::assertFalse(PreviewPolicy::isValidAssetKey('too-short@9c41'));
+		self::assertFalse(PreviewPolicy::isValidAssetKey('aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@NOTHEX!!'));
+		self::assertFalse(PreviewPolicy::isValidAssetKey('no-at-sign-1234567890123456789012'));
+	}
+}
diff --git a/tests/Unit/Service/Preview/PreviewServerTest.php b/tests/Unit/Service/Preview/PreviewServerTest.php
new file mode 100644
index 0000000..4b7cefd
--- /dev/null
+++ b/tests/Unit/Service/Preview/PreviewServerTest.php
@@ -0,0 +1,260 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\Service\Preview;
+
+use OCA\ExeLearning\Service\Preview\FixedResourceManifest;
+use OCA\ExeLearning\Service\Preview\PreviewPolicy;
+use OCA\ExeLearning\Service\Preview\PreviewServer;
+use OCA\ExeLearning\Service\Preview\PreviewSessionLimits;
+use OCA\ExeLearning\Service\Preview\PreviewSessionStore;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * 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 scriptable types from every layer, ETag/304 and single-range 206/416.
+ */
+final class PreviewServerTest extends TestCase {
+	private const PHOTO_KEY = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57';
+	private const CLIP_KEY = '12345678-90ab-4cde-8f01-234567890abc@00112233';
+
+	private string $root;
+	private string $distRoot;
+	private PreviewSessionStore $store;
+	private FixedResourceManifest $fixed;
+	private string $previewId;
+
+	protected function setUp(): void {
+		$this->root = sys_get_temp_dir() . '/exe-srv-' . bin2hex(random_bytes(6));
+		$this->distRoot = sys_get_temp_dir() . '/exe-srv-dist-' . bin2hex(random_bytes(6));
+		mkdir($this->distRoot . '/bundles', 0770, true);
+		mkdir($this->distRoot . '/base', 0770, true);
+		file_put_contents($this->distRoot . '/base/jquery.min.js', 'window.jQuery=function(){};');
+		file_put_contents(
+			$this->distRoot . '/base/icon.svg',
+			'<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>',
+		);
+		file_put_contents($this->distRoot . '/bundles/preview-fixed-resources.json', json_encode([
+			'resources' => [
+				'libs/jquery/jquery.min.js' => ['path' => 'base/jquery.min.js'],
+				'theme:base/icon.svg' => ['path' => 'base/icon.svg'],
+			],
+		]));
+		$this->fixed = new FixedResourceManifest($this->distRoot);
+		$this->store = new PreviewSessionStore($this->root, new PreviewSessionLimits());
+
+		$this->previewId = $this->store->create('alice');
+		$this->store->storeAssets($this->previewId, [
+			['key' => self::PHOTO_KEY, 'declaredSize' => 14, 'bytes' => 'PHOTO-BYTES-v1'],
+			['key' => self::CLIP_KEY, 'declaredSize' => 10, 'bytes' => '0123456789'],
+		]);
+		$this->store->applyRevision($this->previewId, [
+			'baseRevision' => 0,
+			'nextRevision' => 1,
+			'writes' => [
+				['path' => 'index.html', 'bytes' => '<html><body>hi</body></html>'],
+				['path' => 'img/inline.svg', 'bytes' => '<svg xmlns="http://www.w3.org/2000/svg"></svg>'],
+			],
+			'deletes' => [],
+			'assetRefs' => [
+				'content/resources/photo.png' => self::PHOTO_KEY,
+				'media/clip.mp4' => self::CLIP_KEY,
+			],
+			'fixedRefs' => [
+				'libs/jquery/jquery.min.js' => 'libs/jquery/jquery.min.js',
+				'theme/icon.svg' => 'theme:base/icon.svg',
+			],
+		], $this->fixed);
+	}
+
+	protected function tearDown(): void {
+		$this->removeTree($this->root);
+		$this->removeTree($this->distRoot);
+	}
+
+	private function server(): PreviewServer {
+		return new PreviewServer($this->store, $this->fixed);
+	}
+
+	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('"' . self::PHOTO_KEY . '"', $response->headers['ETag']);
+		self::assertSame('bytes', $response->headers['Accept-Ranges']);
+		self::assertArrayNotHasKey('Content-Security-Policy', $response->headers);
+	}
+
+	public function testConditionalRequestReturns304(): void {
+		$response = $this->server()->serve(
+			$this->previewId,
+			'content/resources/photo.png',
+			'"' . self::PHOTO_KEY . '"',
+		);
+		self::assertSame(304, $response->status);
+		self::assertSame('', $response->body);
+		self::assertSame('nosniff', $response->headers['X-Content-Type-Options']);
+		self::assertSame('"' . self::PHOTO_KEY . '"', $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. (The previous behaviour of 416
+	 * on any parse failure was wrong per the serving contract.)
+	 *
+	 * @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::assertSame('"' . self::CLIP_KEY . '"', $response->headers['ETag']);
+		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);
+	}
+
+	public function testServeFixedResourceIsAggressivelyCacheable(): void {
+		$response = $this->server()->serve($this->previewId, 'libs/jquery/jquery.min.js');
+		self::assertSame(200, $response->status);
+		self::assertSame('window.jQuery=function(){};', $response->body);
+		self::assertSame('private, max-age=31536000', $response->headers['Cache-Control']);
+		self::assertSame('*', $response->headers['Access-Control-Allow-Origin']);
+	}
+
+	public function testScriptableSvgFromFixedLayerCarriesCsp(): void {
+		$response = $this->server()->serve($this->previewId, 'theme/icon.svg');
+		self::assertSame(200, $response->status);
+		self::assertSame('image/svg+xml; charset=utf-8', $response->headers['Content-Type']);
+		self::assertSame('private, max-age=31536000', $response->headers['Cache-Control']);
+		self::assertSame(PreviewPolicy::CSP, $response->headers['Content-Security-Policy']);
+	}
+
+	public function testScriptableSvgFromSessionLayerCarriesCsp(): 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 testDeletedSessionStopsServing(): void {
+		$this->store->delete($this->previewId);
+		$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/PreviewSessionApiTest.php b/tests/Unit/Service/Preview/PreviewSessionApiTest.php
new file mode 100644
index 0000000..9a01681
--- /dev/null
+++ b/tests/Unit/Service/Preview/PreviewSessionApiTest.php
@@ -0,0 +1,151 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\Service\Preview;
+
+use OCA\ExeLearning\Service\Preview\FixedResourceManifest;
+use OCA\ExeLearning\Service\Preview\PreviewSessionApi;
+use OCA\ExeLearning\Service\Preview\PreviewSessionLimits;
+use OCA\ExeLearning\Service\Preview\PreviewSessionStore;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests for {@see PreviewSessionApi} — the management-API policy: protocol
+ * negotiation on create, the ownership gate (404 vs 403), and the mapping of
+ * store results onto the contract wire bodies (409/422/413/200).
+ */
+final class PreviewSessionApiTest extends TestCase {
+	private const KEY = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57';
+
+	private string $root;
+	private PreviewSessionApi $api;
+	private PreviewSessionStore $store;
+
+	protected function setUp(): void {
+		$this->root = sys_get_temp_dir() . '/exe-api-' . bin2hex(random_bytes(6));
+		$this->store = new PreviewSessionStore($this->root, new PreviewSessionLimits());
+		$this->api = new PreviewSessionApi($this->store, new FixedResourceManifest($this->root . '/absent'));
+	}
+
+	protected function tearDown(): void {
+		$this->removeTree($this->root);
+	}
+
+	public function testCreateNegotiatesProtocolV2WithLimits(): void {
+		$result = $this->api->create('alice');
+		self::assertSame(201, $result->status);
+		self::assertSame(2, $result->body['protocolVersion']);
+		self::assertSame(0, $result->body['revision']);
+		self::assertTrue(PreviewSessionApi::PROTOCOL_VERSION === 2);
+		self::assertArrayHasKey('previewId', $result->body);
+		self::assertArrayHasKey('recommendedBatchBytes', $result->body['limits']);
+		self::assertSame(5000, $result->body['limits']['maxFilesPerSession']);
+	}
+
+	public function testMissingSessionIs404(): void {
+		$absent = '3f2a1b4c-5d6e-4f70-8a90-b1c2d3e4f506';
+		self::assertSame(404, $this->api->uploadAssets($absent, 'alice', [])->status);
+		self::assertSame(404, $this->api->delete($absent, 'alice')->status);
+		self::assertSame(404, $this->api->publishRevision($absent, 'alice', $this->emptyMeta())->status);
+	}
+
+	public function testForeignOwnerIs403(): void {
+		$id = $this->api->create('alice')->body['previewId'];
+		self::assertSame(403, $this->api->uploadAssets($id, 'bob', [])->status);
+		self::assertSame(403, $this->api->delete($id, 'bob')->status);
+		self::assertSame(403, $this->api->publishRevision($id, 'bob', $this->emptyMeta())->status);
+	}
+
+	public function testUploadAssetsReturnsStoreResult(): void {
+		$id = $this->api->create('alice')->body['previewId'];
+		$result = $this->api->uploadAssets($id, 'alice', [
+			['key' => self::KEY, 'declaredSize' => 5, 'bytes' => 'PHOTO'],
+		]);
+		self::assertSame(200, $result->status);
+		self::assertSame([self::KEY], $result->body['stored']);
+		self::assertSame([], $result->body['alreadyStored']);
+		self::assertSame([], $result->body['rejected']);
+	}
+
+	public function testPublishRevisionSuccessBody(): void {
+		$id = $this->api->create('alice')->body['previewId'];
+		$result = $this->api->publishRevision($id, 'alice', [
+			'baseRevision' => 0,
+			'nextRevision' => 1,
+			'writes' => [['path' => 'index.html', 'bytes' => 'x']],
+			'deletes' => [],
+			'assetRefs' => [],
+			'fixedRefs' => [],
+		]);
+		self::assertSame(200, $result->status);
+		self::assertSame(['revision' => 1, 'active' => true], $result->body);
+	}
+
+	public function testRevisionConflictBody(): void {
+		$id = $this->api->create('alice')->body['previewId'];
+		$this->api->publishRevision($id, 'alice', [
+			'baseRevision' => 0, 'nextRevision' => 1,
+			'writes' => [['path' => 'index.html', 'bytes' => 'v1']],
+			'deletes' => [], 'assetRefs' => [], 'fixedRefs' => [],
+		]);
+		$stale = $this->api->publishRevision($id, 'alice', [
+			'baseRevision' => 0, 'nextRevision' => 1,
+			'writes' => [['path' => 'index.html', 'bytes' => 'stale']],
+			'deletes' => [], 'assetRefs' => [], 'fixedRefs' => [],
+		]);
+		self::assertSame(409, $stale->status);
+		self::assertSame(['reason' => 'revision-conflict', 'currentRevision' => 1], $stale->body);
+	}
+
+	public function testMissingAssetBody(): void {
+		$id = $this->api->create('alice')->body['previewId'];
+		$ghost = '99999999-9999-4999-8999-999999999999@deadbeef';
+		$result = $this->api->publishRevision($id, 'alice', [
+			'baseRevision' => 0, 'nextRevision' => 1, 'writes' => [], 'deletes' => [],
+			'assetRefs' => ['content/ghost.png' => $ghost], 'fixedRefs' => [],
+		]);
+		self::assertSame(422, $result->status);
+		self::assertSame(['reason' => 'missing-assets', 'missing' => [$ghost]], $result->body);
+	}
+
+	public function testUnknownFixedBody(): void {
+		$id = $this->api->create('alice')->body['previewId'];
+		$result = $this->api->publishRevision($id, 'alice', [
+			'baseRevision' => 0, 'nextRevision' => 1, 'writes' => [], 'deletes' => [],
+			'assetRefs' => [], 'fixedRefs' => ['theme/x.css' => 'theme:unknown'],
+		]);
+		self::assertSame(422, $result->status);
+		self::assertSame(['reason' => 'unknown-fixed-resources', 'resources' => ['theme:unknown']], $result->body);
+	}
+
+	public function testDeleteBody(): void {
+		$id = $this->api->create('alice')->body['previewId'];
+		$result = $this->api->delete($id, 'alice');
+		self::assertSame(200, $result->status);
+		self::assertSame(['success' => true], $result->body);
+		self::assertFalse($this->store->exists($id));
+	}
+
+	/** @return array<string,mixed> */
+	private function emptyMeta(): array {
+		return [
+			'baseRevision' => 0, 'nextRevision' => 1, 'writes' => [],
+			'deletes' => [], 'assetRefs' => [], 'fixedRefs' => [],
+		];
+	}
+
+	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/PreviewSessionStoreTest.php b/tests/Unit/Service/Preview/PreviewSessionStoreTest.php
new file mode 100644
index 0000000..44902bd
--- /dev/null
+++ b/tests/Unit/Service/Preview/PreviewSessionStoreTest.php
@@ -0,0 +1,551 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\ExeLearning\Tests\Unit\Service\Preview;
+
+use OCA\ExeLearning\Service\Preview\FixedResourceManifest;
+use OCA\ExeLearning\Service\Preview\PreviewSessionLimits;
+use OCA\ExeLearning\Service\Preview\PreviewSessionStore;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests for {@see PreviewSessionStore} — the file-backed session store:
+ * lifecycle, per-user session cap, asset immutability, atomic revision ordering,
+ * the full revision validation ladder, three-layer resolution, budgets and TTL.
+ */
+final class PreviewSessionStoreTest extends TestCase {
+	private string $root;
+	private string $distRoot;
+	private int $now = 1000;
+
+	protected function setUp(): void {
+		$this->root = sys_get_temp_dir() . '/exe-store-' . bin2hex(random_bytes(6));
+		$this->distRoot = sys_get_temp_dir() . '/exe-store-dist-' . bin2hex(random_bytes(6));
+		mkdir($this->distRoot . '/bundles', 0770, true);
+		mkdir($this->distRoot . '/libs/jquery', 0770, true);
+	}
+
+	protected function tearDown(): void {
+		$this->removeTree($this->root);
+		$this->removeTree($this->distRoot);
+	}
+
+	private function store(?PreviewSessionLimits $limits = null): PreviewSessionStore {
+		return new PreviewSessionStore(
+			$this->root,
+			$limits ?? new PreviewSessionLimits(),
+			fn (): int => $this->now,
+		);
+	}
+
+	/** Manifest with two fixed resources (a JS lib and a scriptable SVG). */
+	private function fixedManifest(): FixedResourceManifest {
+		file_put_contents($this->distRoot . '/libs/jquery/jquery.min.js', 'window.jQuery=function(){};');
+		file_put_contents(
+			$this->distRoot . '/libs/jquery/icon.svg',
+			'<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>',
+		);
+		file_put_contents($this->distRoot . '/bundles/preview-fixed-resources.json', json_encode([
+			'resources' => [
+				'libs/jquery/jquery.min.js' => ['path' => 'libs/jquery/jquery.min.js'],
+				'theme:base/icon.svg' => ['path' => 'libs/jquery/icon.svg'],
+			],
+		]));
+		return new FixedResourceManifest($this->distRoot);
+	}
+
+	/** An empty (disabled) fixed layer. */
+	private function noFixed(): FixedResourceManifest {
+		return new FixedResourceManifest($this->distRoot . '/absent');
+	}
+
+	private function asset(string $key, string $bytes): array {
+		return ['key' => $key, 'declaredSize' => strlen($bytes), 'bytes' => $bytes];
+	}
+
+	// -- Lifecycle -----------------------------------------------------------
+
+	public function testCreateAndOwnership(): void {
+		$store = $this->store();
+		$id = $store->create('alice');
+
+		self::assertTrue($store->exists($id));
+		self::assertSame('alice', $store->ownerOf($id));
+		self::assertSame(0, $store->activeRevision($id));
+		self::assertMatchesRegularExpression(
+			'/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/',
+			$id,
+		);
+	}
+
+	public function testDeleteRemovesSession(): void {
+		$store = $this->store();
+		$id = $store->create('alice');
+		self::assertTrue($store->delete($id));
+		self::assertFalse($store->exists($id));
+		self::assertFalse($store->delete($id));
+		self::assertNull($store->ownerOf($id));
+	}
+
+	public function testPerUserSessionCapEvictsLeastRecentlyUsed(): void {
+		$store = $this->store(new PreviewSessionLimits(maxSessionsPerUser: 2));
+		$this->now = 1000;
+		$first = $store->create('alice');
+		$this->now = 1001;
+		$second = $store->create('alice');
+		$this->now = 1002;
+		$third = $store->create('alice');
+
+		self::assertFalse($store->exists($first), 'oldest owned session evicted');
+		self::assertTrue($store->exists($second));
+		self::assertTrue($store->exists($third));
+		// A different user is unaffected by alice's cap.
+		$bob = $store->create('bob');
+		self::assertTrue($store->exists($bob));
+	}
+
+	// -- Assets --------------------------------------------------------------
+
+	public function testStoreAssetsAndImmutability(): void {
+		$store = $this->store();
+		$id = $store->create('alice');
+		$key = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57';
+
+		$first = $store->storeAssets($id, [$this->asset($key, 'PHOTO-BYTES-v1')]);
+		self::assertSame([$key], $first['stored']);
+		self::assertSame([], $first['alreadyStored']);
+
+		// Re-upload the SAME key with DIFFERENT bytes → alreadyStored, not replaced.
+		$second = $store->storeAssets($id, [$this->asset($key, 'PHOTO-BYTES-v2-DIFFERENT')]);
+		self::assertSame([], $second['stored']);
+		self::assertSame([$key], $second['alreadyStored']);
+
+		// Publish a revision referencing it and prove the ORIGINAL bytes serve.
+		$this->publish($store, $id, 0, 1, [], ['content/photo.png' => $key], []);
+		$file = $store->resolve($id, 'content/photo.png', $this->noFixed());
+		self::assertNotNull($file);
+		self::assertSame($key, $file['etag']);
+		self::assertSame('PHOTO-BYTES-v1', file_get_contents($file['filePath']));
+	}
+
+	public function testStoreAssetsRejections(): void {
+		$store = $this->store(new PreviewSessionLimits(maxAssetBytes: 8, maxBytesPerSession: 20));
+		$id = $store->create('alice');
+		$goodKey = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57';
+		$bigKey = 'bbbbbbbb-cccc-4ddd-8eee-ffff00001111@0011223344';
+
+		$result = $store->storeAssets($id, [
+			['key' => 'not-a-valid-key', 'declaredSize' => 3, 'bytes' => 'abc'],
+			['key' => $goodKey, 'declaredSize' => 99, 'bytes' => 'abc'],
+			$this->asset($bigKey, 'TOO-LONG-BYTES'),
+		]);
+
+		$reasons = [];
+		foreach ($result['rejected'] as $entry) {
+			$reasons[$entry['key']] = $entry['reason'];
+		}
+		self::assertSame('invalid-key', $reasons['not-a-valid-key']);
+		self::assertSame('size-mismatch', $reasons[$goodKey]);
+		self::assertSame('asset-too-large', $reasons[$bigKey]);
+		self::assertSame([], $result['stored']);
+	}
+
+	public function testBlobWriteFailureIsRejectedNotAlreadyStored(): void {
+		$store = $this->store();
+		$id = $store->create('alice');
+		$key = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57';
+
+		// Force the underlying blob write to fail deterministically (and
+		// root-independently): replace the session's assets/ directory with a
+		// regular file, so any write under it fails with ENOTDIR.
+		$assetsPath = $this->root . '/' . $id . '/assets';
+		$this->removeTree($assetsPath);
+		file_put_contents($assetsPath, 'not-a-directory');
+
+		$result = $store->storeAssets($id, [$this->asset($key, 'PHOTO-BYTES')]);
+
+		// A write failure must be REJECTED, never stored/alreadyStored: reporting
+		// alreadyStored would make the client mark the key uploaded, stranding the
+		// asset as a permanent 404 that the missing-assets loop can never repair.
+		self::assertSame([], $result['stored']);
+		self::assertSame([], $result['alreadyStored']);
+		self::assertSame([['key' => $key, 'reason' => 'write-failed']], $result['rejected']);
+
+		// The blob is genuinely absent...
+		self::assertFileDoesNotExist($assetsPath . '/' . sha1($key));
+
+		// ...so a revision referencing it returns 422 missing-assets (the client's
+		// recovery path then re-uploads it), instead of a silent permanent 404.
+		$revision = $store->applyRevision($id, [
+			'baseRevision' => 0,
+			'nextRevision' => 1,
+			'writes' => [],
+			'deletes' => [],
+			'assetRefs' => ['content/photo.png' => $key],
+			'fixedRefs' => [],
+		], $this->noFixed());
+		self::assertSame(422, $revision['status']);
+		self::assertSame('missing-assets', $revision['reason']);
+		self::assertSame([$key], $revision['missing']);
+	}
+
+	// -- Revisions -----------------------------------------------------------
+
+	public function testPublishRevisionHappyPath(): void {
+		$store = $this->store();
+		$fixed = $this->fixedManifest();
+		$id = $store->create('alice');
+		$key = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57';
+		$store->storeAssets($id, [$this->asset($key, 'PHOTO')]);
+
+		$result = $store->applyRevision($id, [
+			'baseRevision' => 0,
+			'nextRevision' => 1,
+			'writes' => [
+				['path' => 'index.html', 'bytes' => '<html><body>hi</body></html>'],
+				['path' => 'img/inline.svg', 'bytes' => '<svg xmlns="http://www.w3.org/2000/svg"></svg>'],
+			],
+			'deletes' => [],
+			'assetRefs' => ['content/photo.png' => $key],
+			'fixedRefs' => ['libs/jquery/jquery.min.js' => 'libs/jquery/jquery.min.js'],
+		], $fixed);
+
+		self::assertSame(200, $result['status']);
+		self::assertSame(1, $result['revision']);
+		self::assertSame(1, $store->activeRevision($id));
+
+		$doc = $store->resolve($id, 'index.html', $fixed);
+		self::assertSame('document', $doc['kind']);
+		self::assertSame('<html><body>hi</body></html>', $doc['bytes']);
+
+		$fixedFile = $store->resolve($id, 'libs/jquery/jquery.min.js', $fixed);
+		self::assertSame('fixed', $fixedFile['kind']);
+		self::assertSame('window.jQuery=function(){};', $fixedFile['bytes']);
+	}
+
+	public function testStaleBaseRevisionConflicts(): void {
+		$store = $this->store();
+		$id = $store->create('alice');
+		$this->publish($store, $id, 0, 1, [['path' => 'index.html', 'bytes' => 'v1']], [], []);
+
+		$result = $store->applyRevision($id, [
+			'baseRevision' => 0,
+			'nextRevision' => 1,
+			'writes' => [['path' => 'index.html', 'bytes' => 'stale']],
+			'deletes' => [],
+			'assetRefs' => [],
+			'fixedRefs' => [],
+		], $this->noFixed());
+
+		self::assertSame(409, $result['status']);
+		self::assertSame(1, $result['currentRevision']);
+		// The active revision is untouched by the rejected apply (atomicity).
+		self::assertSame('v1', $store->resolve($id, 'index.html', $this->noFixed())['bytes']);
+	}
+
+	public function testUnsafeWritePathRejected(): void {
+		$store = $this->store();
+		$id = $store->create('alice');
+		$result = $store->applyRevision($id, [
+			'baseRevision' => 0,
+			'nextRevision' => 1,
+			'writes' => [['path' => '../escape.html', 'bytes' => 'x']],
+			'deletes' => [],
+			'assetRefs' => [],
+			'fixedRefs' => [],
+		], $this->noFixed());
+		self::assertSame(400, $result['status']);
+		self::assertSame(0, $store->activeRevision($id));
+	}
+
+	public function testMissingAssetRefRejected(): void {
+		$store = $this->store();
+		$id = $store->create('alice');
+		$ghost = '99999999-9999-4999-8999-999999999999@deadbeef';
+		$result = $store->applyRevision($id, [
+			'baseRevision' => 0,
+			'nextRevision' => 1,
+			'writes' => [],
+			'deletes' => [],
+			'assetRefs' => ['content/ghost.png' => $ghost],
+			'fixedRefs' => [],
+		], $this->noFixed());
+		self::assertSame(422, $result['status']);
+		self::assertSame('missing-assets', $result['reason']);
+		self::assertSame([$ghost], $result['missing']);
+	}
+
+	public function testUnknownFixedRefRejected(): void {
+		$store = $this->store();
+		$id = $store->create('alice');
+		$result = $store->applyRevision($id, [
+			'baseRevision' => 0,
+			'nextRevision' => 1,
+			'writes' => [],
+			'deletes' => [],
+			'assetRefs' => [],
+			'fixedRefs' => ['theme/x.css' => 'theme:not-in-manifest'],
+		], $this->noFixed());
+		self::assertSame(422, $result['status']);
+		self::assertSame('unknown-fixed-resources', $result['reason']);
+		self::assertSame(['theme:not-in-manifest'], $result['resources']);
+	}
+
+	public function testFileCountBudgetRejected(): void {
+		$store = $this->store(new PreviewSessionLimits(maxFilesPerSession: 1));
+		$id = $store->create('alice');
+		$result = $store->applyRevision($id, [
+			'baseRevision' => 0,
+			'nextRevision' => 1,
+			'writes' => [
+				['path' => 'a.html', 'bytes' => 'a'],
+				['path' => 'b.html', 'bytes' => 'b'],
+			],
+			'deletes' => [],
+			'assetRefs' => [],
+			'fixedRefs' => [],
+		], $this->noFixed());
+		self::assertSame(413, $result['status']);
+	}
+
+	public function testRevisionDocumentWriteFailureAbortsBeforePointerSwap(): void {
+		$store = $this->store();
+		$id = $store->create('alice');
+		// Establish revision 1.
+		$this->publish($store, $id, 0, 1, [['path' => 'index.html', 'bytes' => 'v1']], [], []);
+
+		// Force the next document blob write to fail deterministically: replace
+		// the documents/ directory with a regular file so any write under it
+		// fails with ENOTDIR.
+		$documentsPath = $this->root . '/' . $id . '/documents';
+		$this->removeTree($documentsPath);
+		file_put_contents($documentsPath, 'not-a-directory');
+
+		$result = $store->applyRevision($id, [
+			'baseRevision' => 1,
+			'nextRevision' => 2,
+			'writes' => [['path' => 'index.html', 'bytes' => 'v2-NEW-UNIQUE-BYTES']],
+			'deletes' => [],
+			'assetRefs' => [],
+			'fixedRefs' => [],
+		], $this->noFixed());
+
+		// The publish aborts with 500 and never advances the pointer, so the
+		// previously active revision stays intact (no silent 404 document).
+		self::assertSame(500, $result['status']);
+		self::assertSame(1, $store->activeRevision($id));
+		self::assertFileDoesNotExist($this->root . '/' . $id . '/revisions/2.json');
+	}
+
+	public function testSupersededRevisionsArePrunedToBoundDisk(): void {
+		$store = $this->store();
+		$id = $store->create('alice');
+		// An asset that must survive every revision (shared/immutable across them).
+		$key = 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57';
+		$store->storeAssets($id, [$this->asset($key, str_repeat('A', 4096))]);
+
+		// Publish several revisions, each replacing index.html with UNIQUE content
+		// (unique hash => a new blob every time; content-addressing cannot mask the
+		// leak). Without pruning, physical disk grows with revision count even though
+		// the active-revision budget stays flat — the disk-fill DoS.
+		$docSize = 50000;
+		$revisions = 6;
+		for ($rev = 1; $rev <= $revisions; $rev++) {
+			$unique = str_repeat('x', $docSize) . '-rev-' . $rev;
+			$this->publish($store, $id, $rev - 1, $rev, [
+				['path' => 'index.html', 'bytes' => $unique],
+			], ['content/photo.png' => $key], []);
+		}
+
+		$sessionDir = $this->root . '/' . $id;
+
+		// (a) Only the active revision's manifest and its single document blob remain.
+		$manifests = array_values(array_filter(
+			scandir($sessionDir . '/revisions') ?: [],
+			static fn (string $f): bool => preg_match('/^\d+\.json$/', $f) === 1,
+		));
+		self::assertSame([$revisions . '.json'], $manifests, 'superseded revision manifests must be pruned');
+
+		$blobs = array_values(array_filter(
+			scandir($sessionDir . '/documents') ?: [],
+			static fn (string $f): bool => preg_match('/^[0-9a-f]{40}$/', $f) === 1,
+		));
+		self::assertCount(1, $blobs, 'superseded document blobs must be pruned');
+
+		// The active revision still serves correctly after pruning.
+		$doc = $store->resolve($id, 'index.html', $this->noFixed());
+		self::assertNotNull($doc);
+		self::assertSame($docSize + strlen('-rev-' . $revisions), strlen($doc['bytes']));
+
+		// (b) The asset persists across every revision.
+		$assetFile = $store->resolve($id, 'content/photo.png', $this->noFixed());
+		self::assertNotNull($assetFile);
+		self::assertSame(str_repeat('A', 4096), file_get_contents($assetFile['filePath']));
+
+		// (c) On-disk bytes stay bounded (~one document + one asset), not revisions x docSize.
+		$onDisk = $this->diskBytes($sessionDir);
+		self::assertLessThan($store->limits()->maxBytesPerSession, $onDisk);
+		self::assertLessThan($docSize * 3, $onDisk, 'retained disk must not grow with revision count');
+	}
+
+	public function testIncrementalDeltaAndDeletes(): void {
+		$store = $this->store();
+		$id = $store->create('alice');
+		$this->publish($store, $id, 0, 1, [
+			['path' => 'index.html', 'bytes' => 'home'],
+			['path' => 'gone.html', 'bytes' => 'temp'],
+		], [], []);
+		// Revision 2: rewrite index.html, delete gone.html.
+		$this->publish($store, $id, 1, 2, [['path' => 'index.html', 'bytes' => 'home-v2']], [], [], ['gone.html']);
+
+		self::assertSame(2, $store->activeRevision($id));
+		self::assertSame('home-v2', $store->resolve($id, 'index.html', $this->noFixed())['bytes']);
+		self::assertNull($store->resolve($id, 'gone.html', $this->noFixed()));
+	}
+
+	// -- Resolution edge cases ----------------------------------------------
+
+	public function testResolveBeforeFirstRevisionIsNull(): void {
+		$store = $this->store();
+		$id = $store->create('alice');
+		self::assertNull($store->resolve($id, 'index.html', $this->noFixed()));
+	}
+
+	public function testResolveUnknownPathIsNull(): void {
+		$store = $this->store();
+		$id = $store->create('alice');
+		$this->publish($store, $id, 0, 1, [['path' => 'index.html', 'bytes' => 'x']], [], []);
+		self::assertNull($store->resolve($id, 'nope.css', $this->noFixed()));
+		self::assertNull($store->resolve($id, '../escape', $this->noFixed()));
+	}
+
+	public function testResolveOnMissingSessionIsNull(): void {
+		$store = $this->store();
+		self::assertNull($store->resolve('3f2a1b4c-5d6e-4f70-8a90-b1c2d3e4f506', 'index.html', $this->noFixed()));
+	}
+
+	// -- TTL -----------------------------------------------------------------
+
+	public function testExpiredSessionIsDroppedOnAccessAndSwept(): void {
+		$store = $this->store(new PreviewSessionLimits(ttlSeconds: 100));
+		$this->now = 1000;
+		$id = $store->create('alice');
+		$this->publish($store, $id, 0, 1, [['path' => 'index.html', 'bytes' => 'x']], [], []);
+
+		// Within TTL: still served.
+		$this->now = 1050;
+		self::assertNotNull($store->resolve($id, 'index.html', $this->noFixed()));
+
+		// Past TTL: opportunistically dropped on access.
+		$this->now = 2000;
+		self::assertNull($store->resolve($id, 'index.html', $this->noFixed()));
+		self::assertFalse($store->exists($id));
+	}
+
+	public function testSweepExpiredRemovesIdleSessions(): void {
+		$store = $this->store(new PreviewSessionLimits(ttlSeconds: 100));
+		$this->now = 1000;
+		$stale = $store->create('alice');
+		$this->now = 1900;
+		$fresh = $store->create('bob');
+
+		$this->now = 1950; // stale is 950s idle, fresh is 50s idle
+		self::assertSame(1, $store->sweepExpired());
+		self::assertFalse($store->exists($stale));
+		self::assertTrue($store->exists($fresh));
+	}
+
+	public function testMissingAccessedMarkerFallsBackToCreatedAtForTtl(): void {
+		// A lost `.accessed` marker (crash between touch and fsync, manual fs
+		// surgery, backup restore) must NOT make a session immortal: the age
+		// clock falls back to meta.json createdAt so the session still expires.
+		$store = $this->store(new PreviewSessionLimits(ttlSeconds: 100));
+		$this->now = 1000;
+		$id = $store->create('alice');
+		$this->publish($store, $id, 0, 1, [['path' => 'index.html', 'bytes' => str_repeat('x', 128)]], [], []);
+		unlink($this->root . '/' . $id . '/.accessed');
+
+		// Within TTL of createdAt (1000): not yet expired.
+		$this->now = 1050;
+		self::assertSame(0, $store->sweepExpired());
+		self::assertTrue($store->exists($id));
+
+		// Past TTL of createdAt: swept, and the directory is physically gone — so
+		// its bytes no longer contribute to the recomputed global byte budget.
+		$this->now = 1200;
+		self::assertSame(1, $store->sweepExpired());
+		self::assertFalse($store->exists($id));
+		self::assertDirectoryDoesNotExist($this->root . '/' . $id);
+	}
+
+	public function testCorruptSessionDirectoryIsReclaimed(): void {
+		// A directory that looks like a session id but has neither `.accessed`
+		// nor a readable meta.json can never be owned or served — it must be
+		// reclaimed rather than lingering forever.
+		$store = $this->store(new PreviewSessionLimits(ttlSeconds: 100));
+		$this->now = 1000;
+		$corruptId = '3f2a1b4c-5d6e-4f70-8a90-b1c2d3e4f506';
+		mkdir($this->root . '/' . $corruptId, 0770, true);
+
+		self::assertTrue($store->isExpired($corruptId));
+		self::assertSame(1, $store->sweepExpired());
+		self::assertDirectoryDoesNotExist($this->root . '/' . $corruptId);
+	}
+
+	// -- Helpers -------------------------------------------------------------
+
+	/**
+	 * @param list<array{path:string,bytes:string}> $writes
+	 * @param array<string,string> $assetRefs
+	 * @param array<string,string> $fixedRefs
+	 * @param list<string> $deletes
+	 */
+	private function publish(
+		PreviewSessionStore $store,
+		string $id,
+		int $base,
+		int $next,
+		array $writes,
+		array $assetRefs,
+		array $fixedRefs,
+		array $deletes = [],
+	): void {
+		$result = $store->applyRevision($id, [
+			'baseRevision' => $base,
+			'nextRevision' => $next,
+			'writes' => $writes,
+			'deletes' => $deletes,
+			'assetRefs' => $assetRefs,
+			'fixedRefs' => $fixedRefs,
+		], $this->noFixed());
+		self::assertSame(200, $result['status'], 'publish helper expects success');
+	}
+
+	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);
+	}
+
+	/** Total physical bytes stored under a directory tree. */
+	private function diskBytes(string $dir): int {
+		$total = 0;
+		foreach (scandir($dir) ?: [] as $item) {
+			if ($item === '.' || $item === '..') {
+				continue;
+			}
+			$path = $dir . '/' . $item;
+			$total += is_dir($path) ? $this->diskBytes($path) : (int)filesize($path);
+		}
+		return $total;
+	}
+}
diff --git a/tests/Unit/Service/ZipEntryServiceTest.php b/tests/Unit/Service/ZipEntryServiceTest.php
index e0f792d..2bc43c7 100644
--- a/tests/Unit/Service/ZipEntryServiceTest.php
+++ b/tests/Unit/Service/ZipEntryServiceTest.php
@@ -44,4 +44,48 @@ public function testRejectsEmptyAndNulTaintedPaths(): void {
 		self::assertNull($this->service->normalizeEntry(''));
 		self::assertNull($this->service->normalizeEntry("a\0b"));
 	}
+
+	public function testReadEntryFallsBackToStreamWhenLocalPathCannotBeOpened(): void {
+		if (!class_exists('OCP\\Files\\File')) {
+			eval('namespace OCP\\Files; class File {}');
+		}
+
+		$archivePath = tempnam(sys_get_temp_dir(), 'elpx_test_');
+		self::assertNotFalse($archivePath);
+		$zip = new \ZipArchive();
+		self::assertTrue($zip->open($archivePath, \ZipArchive::OVERWRITE) === true);
+		$zip->addFromString('index.html', '<h1>Playground</h1>');
+		$zip->close();
+		$archive = file_get_contents($archivePath);
+		@unlink($archivePath);
+		self::assertIsString($archive);
+
+		$file = new class($archive) extends \OCP\Files\File {
+			public function __construct(
+				private readonly string $archive,
+			) {
+			}
+
+			public function getStorage(): object {
+				return new class {
+					public function getLocalFile(string $path): string {
+						return '/virtual/php-wasm/package.elpx';
+					}
+				};
+			}
+
+			public function getInternalPath(): string {
+				return 'files/package.elpx';
+			}
+
+			public function fopen(string $mode) {
+				$stream = fopen('php://temp', 'w+b');
+				fwrite($stream, $this->archive);
+				rewind($stream);
+				return $stream;
+			}
+		};
+
+		self::assertSame('<h1>Playground</h1>', $this->service->readEntry($file, 'index.html'));
+	}
 }
diff --git a/tests/e2e/preview-api-e2e.sh b/tests/e2e/preview-api-e2e.sh
new file mode 100755
index 0000000..2c6496a
--- /dev/null
+++ b/tests/e2e/preview-api-e2e.sh
@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+#
+# API-level end-to-end test of the editor-preview serving contract v2 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 create->asset->revision->serve
+# round-trip, the authless opaque serving response (200 + sandbox CSP, no
+# allow-same-origin), the bare-root 302, owner-scoping (403), dropped-part
+# rejection (400) without advancing the revision, 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"; }
+
+# 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, so
+#    no session is created.
+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. Create → 201 { previewId, protocolVersion: 2 }.
+resp="$(api "$U1" "$P1" POST "$MGMT")"
+pid="$(printf '%s' "$resp" | jq -r '.previewId // empty')"
+[ -n "$pid" ] || fail "create returned no previewId: $resp"
+[ "$(printf '%s' "$resp" | jq -r '.protocolVersion')" = "2" ] || fail "protocolVersion != 2: $resp"
+echo "  ok: created session $pid"
+
+# 3. Upload an asset (multipart: assets JSON + index-aligned files[]).
+KEY="aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8"
+printf 'IMGBYTES!' > "$TMP/asset.bin" # 9 bytes
+api "$U1" "$P1" POST "$MGMT/$pid/assets" \
+	-F "assets=[{\"key\":\"$KEY\",\"size\":9}]" \
+	-F "files[]=@$TMP/asset.bin" >/dev/null
+echo "  ok: uploaded asset"
+
+# 4. Publish revision 1.
+printf '<html><body>preview-v1</body></html>' > "$TMP/index.html"
+resp="$(api "$U1" "$P1" POST "$MGMT/$pid/revisions" \
+	-F "revision={\"baseRevision\":0,\"nextRevision\":1,\"writes\":[\"index.html\"],\"deletes\":[],\"assetRefs\":{\"content/photo.png\":\"$KEY\"},\"fixedRefs\":{}}" \
+	-F "files[]=@$TMP/index.html")"
+[ "$(printf '%s' "$resp" | jq -r '.revision')" = "1" ] || fail "publish revision != 1: $resp"
+echo "  ok: published revision 1"
+
+# 5. 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 revision content"
+echo "  ok: authless serve is 200 with opaque sandbox CSP (no allow-same-origin)"
+
+# 6. 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"
+
+# 7. Owner-scoping — user2 on user1's session → 403.
+code="$(api_code "$U2" "$P2" DELETE "$MGMT/$pid")"
+[ "$code" = "403" ] || fail "cross-user delete expected 403, got $code"
+echo "  ok: cross-user management is 403"
+
+# 8. Dropped multipart part — 1 write declared, 0 file parts → 400, revision unchanged.
+code="$(api_code "$U1" "$P1" POST "$MGMT/$pid/revisions" \
+	-F "revision={\"baseRevision\":1,\"nextRevision\":2,\"writes\":[\"index.html\"],\"deletes\":[],\"assetRefs\":{},\"fixedRefs\":{}}")"
+[ "$code" = "400" ] || fail "dropped-part revision expected 400, got $code"
+curl -s "$SERVE/$pid/index.html" | grep -q 'preview-v1' || fail "revision advanced despite dropped part"
+echo "  ok: dropped-part revision rejected (400), revision pointer unchanged"
+
+# 9. 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/fixtures/preview-contract/vectors.json b/tests/fixtures/preview-contract/vectors.json
new file mode 100644
index 0000000..c98880d
--- /dev/null
+++ b/tests/fixtures/preview-contract/vectors.json
@@ -0,0 +1,299 @@
+{
+    "description": "Machine-readable conformance vectors for eXeLearning preview serving contract v2 (doc/development/preview-serving-contract.md). Replay every step, in order, against a host implementation. See README.md for harness semantics.",
+    "protocolVersion": 2,
+    "fixedResources": {
+        "libs/jquery/jquery.min.js": {
+            "path": "libs/jquery/jquery.min.js",
+            "content": "window.jQuery=function(){};"
+        },
+        "theme:base/icon.svg": {
+            "path": "files/perm/themes/base/base/icon.svg",
+            "content": "<svg xmlns=\"http://www.w3.org/2000/svg\"><script>alert(1)</script></svg>"
+        }
+    },
+    "constants": {
+        "photoKey": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57",
+        "clipKey": "12345678-90ab-4cde-8f01-234567890abc@00112233"
+    },
+    "steps": [
+        {
+            "id": "create-session",
+            "request": { "method": "POST", "path": "/api/preview-session" },
+            "expect": {
+                "status": 201,
+                "body": { "protocolVersion": 2, "revision": 0 }
+            }
+        },
+        {
+            "id": "upload-assets",
+            "request": {
+                "method": "POST",
+                "path": "/api/preview-session/{previewId}/assets",
+                "body": {
+                    "kind": "assets",
+                    "entries": [
+                        { "key": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57", "content": "PHOTO-BYTES-v1" },
+                        { "key": "12345678-90ab-4cde-8f01-234567890abc@00112233", "content": "0123456789" }
+                    ]
+                }
+            },
+            "expect": {
+                "status": 200,
+                "body": {
+                    "stored": [
+                        "aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57",
+                        "12345678-90ab-4cde-8f01-234567890abc@00112233"
+                    ],
+                    "alreadyStored": [],
+                    "rejected": []
+                }
+            }
+        },
+        {
+            "id": "reupload-asset-immutability",
+            "comment": "Same key, DIFFERENT bytes: reported alreadyStored, bytes NOT replaced (asserted later by serve-asset).",
+            "request": {
+                "method": "POST",
+                "path": "/api/preview-session/{previewId}/assets",
+                "body": {
+                    "kind": "assets",
+                    "entries": [
+                        {
+                            "key": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57",
+                            "content": "PHOTO-BYTES-v2-DIFFERENT"
+                        }
+                    ]
+                }
+            },
+            "expect": {
+                "status": 200,
+                "body": {
+                    "stored": [],
+                    "alreadyStored": ["aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57"],
+                    "rejected": []
+                }
+            }
+        },
+        {
+            "id": "publish-revision-1",
+            "request": {
+                "method": "POST",
+                "path": "/api/preview-session/{previewId}/revisions",
+                "body": {
+                    "kind": "revision",
+                    "meta": {
+                        "baseRevision": 0,
+                        "nextRevision": 1,
+                        "deletes": [],
+                        "assetRefs": {
+                            "content/resources/photo.png": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57",
+                            "media/clip.mp4": "12345678-90ab-4cde-8f01-234567890abc@00112233"
+                        },
+                        "fixedRefs": {
+                            "libs/jquery/jquery.min.js": "libs/jquery/jquery.min.js",
+                            "theme/icon.svg": "theme:base/icon.svg"
+                        }
+                    },
+                    "writes": [
+                        { "path": "index.html", "content": "<html><body>conformance</body></html>" },
+                        {
+                            "path": "img/inline.svg",
+                            "content": "<svg xmlns=\"http://www.w3.org/2000/svg\"><script>alert(2)</script></svg>"
+                        }
+                    ]
+                }
+            },
+            "expect": { "status": 200, "body": { "revision": 1, "active": true } }
+        },
+        {
+            "id": "serve-document",
+            "request": { "method": "GET", "path": "/preview/{previewId}/index.html" },
+            "expect": {
+                "status": 200,
+                "bodyText": "<html><body>conformance</body></html>",
+                "headers": {
+                    "Content-Type": "text/html; charset=utf-8",
+                    "Cache-Control": "no-store",
+                    "X-Content-Type-Options": "nosniff",
+                    "Referrer-Policy": "no-referrer",
+                    "Access-Control-Allow-Origin": "*",
+                    "Content-Security-Policy": { "startsWith": "sandbox allow-scripts allow-popups allow-forms" }
+                }
+            }
+        },
+        {
+            "id": "serve-asset",
+            "comment": "Bytes are the ORIGINAL upload — proves reupload-asset-immutability did not replace them.",
+            "request": { "method": "GET", "path": "/preview/{previewId}/content/resources/photo.png" },
+            "expect": {
+                "status": 200,
+                "bodyText": "PHOTO-BYTES-v1",
+                "headers": {
+                    "Content-Type": "image/png",
+                    "Cache-Control": "no-cache",
+                    "ETag": "\"aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57\"",
+                    "Accept-Ranges": "bytes",
+                    "Content-Security-Policy": { "absent": true }
+                }
+            }
+        },
+        {
+            "id": "serve-asset-304",
+            "request": {
+                "method": "GET",
+                "path": "/preview/{previewId}/content/resources/photo.png",
+                "headers": { "If-None-Match": "\"aaaaaaaa-bbbb-4ccc-8ddd-eeeeffff0000@9c41d2e8a1b03f57\"" }
+            },
+            "expect": {
+                "status": 304,
+                "headers": { "X-Content-Type-Options": "nosniff" }
+            }
+        },
+        {
+            "id": "serve-asset-range",
+            "request": {
+                "method": "GET",
+                "path": "/preview/{previewId}/media/clip.mp4",
+                "headers": { "Range": "bytes=2-4" }
+            },
+            "expect": {
+                "status": 206,
+                "bodyText": "234",
+                "headers": { "Content-Range": "bytes 2-4/10", "Content-Length": "3" }
+            }
+        },
+        {
+            "id": "serve-asset-range-unsatisfiable",
+            "request": {
+                "method": "GET",
+                "path": "/preview/{previewId}/media/clip.mp4",
+                "headers": { "Range": "bytes=99-" }
+            },
+            "expect": {
+                "status": 416,
+                "headers": { "Content-Range": "bytes */10" }
+            }
+        },
+        {
+            "id": "serve-fixed",
+            "request": { "method": "GET", "path": "/preview/{previewId}/libs/jquery/jquery.min.js" },
+            "expect": {
+                "status": 200,
+                "bodyText": "window.jQuery=function(){};",
+                "headers": {
+                    "Cache-Control": "private, max-age=31536000",
+                    "X-Content-Type-Options": "nosniff",
+                    "Access-Control-Allow-Origin": "*"
+                }
+            }
+        },
+        {
+            "id": "serve-fixed-scriptable-svg",
+            "comment": "The sandbox CSP must be emitted on scriptable types from EVERY layer, fixed included.",
+            "request": { "method": "GET", "path": "/preview/{previewId}/theme/icon.svg" },
+            "expect": {
+                "status": 200,
+                "headers": {
+                    "Content-Type": "image/svg+xml; charset=utf-8",
+                    "Cache-Control": "private, max-age=31536000",
+                    "Content-Security-Policy": { "startsWith": "sandbox allow-scripts allow-popups allow-forms" }
+                }
+            }
+        },
+        {
+            "id": "serve-session-scriptable-svg",
+            "request": { "method": "GET", "path": "/preview/{previewId}/img/inline.svg" },
+            "expect": {
+                "status": 200,
+                "headers": {
+                    "Content-Type": "image/svg+xml; charset=utf-8",
+                    "Content-Security-Policy": { "startsWith": "sandbox allow-scripts allow-popups allow-forms" }
+                }
+            }
+        },
+        {
+            "id": "serve-unknown-404",
+            "request": { "method": "GET", "path": "/preview/{previewId}/nope.css" },
+            "expect": {
+                "status": 404,
+                "headers": {
+                    "Cache-Control": "no-store",
+                    "X-Content-Type-Options": "nosniff",
+                    "Access-Control-Allow-Origin": "*"
+                }
+            }
+        },
+        {
+            "id": "serve-traversal-raw",
+            "comment": "A literal ../ is normalized away by URL parsing before it reaches the server; whatever survives must still 404.",
+            "request": { "method": "GET", "path": "/preview/{previewId}/../secret" },
+            "expect": { "status": 404 }
+        },
+        {
+            "id": "serve-traversal-encoded",
+            "comment": "Percent-encoded traversal reaches the server verbatim and must be rejected by path normalization.",
+            "request": { "method": "GET", "path": "/preview/{previewId}/%2e%2e%2fsecret" },
+            "expect": { "status": 404, "headers": { "Cache-Control": "no-store" } }
+        },
+        {
+            "id": "conflicting-revision-409",
+            "comment": "Stale baseRevision (client believes 0, server is at 1).",
+            "request": {
+                "method": "POST",
+                "path": "/api/preview-session/{previewId}/revisions",
+                "body": {
+                    "kind": "revision",
+                    "meta": {
+                        "baseRevision": 0,
+                        "nextRevision": 1,
+                        "deletes": [],
+                        "assetRefs": {},
+                        "fixedRefs": {}
+                    },
+                    "writes": [{ "path": "index.html", "content": "stale" }]
+                }
+            },
+            "expect": {
+                "status": 409,
+                "body": { "reason": "revision-conflict", "currentRevision": 1 }
+            }
+        },
+        {
+            "id": "missing-asset-revision-422",
+            "request": {
+                "method": "POST",
+                "path": "/api/preview-session/{previewId}/revisions",
+                "body": {
+                    "kind": "revision",
+                    "meta": {
+                        "baseRevision": 1,
+                        "nextRevision": 2,
+                        "deletes": [],
+                        "assetRefs": {
+                            "content/resources/ghost.png": "99999999-9999-4999-8999-999999999999@deadbeef"
+                        },
+                        "fixedRefs": {}
+                    },
+                    "writes": []
+                }
+            },
+            "expect": {
+                "status": 422,
+                "body": {
+                    "reason": "missing-assets",
+                    "missing": ["99999999-9999-4999-8999-999999999999@deadbeef"]
+                }
+            }
+        },
+        {
+            "id": "delete-session",
+            "request": { "method": "DELETE", "path": "/api/preview-session/{previewId}" },
+            "expect": { "status": 200, "body": { "success": true } }
+        },
+        {
+            "id": "serve-after-delete-404",
+            "request": { "method": "GET", "path": "/preview/{previewId}/index.html" },
+            "expect": { "status": 404, "headers": { "Cache-Control": "no-store" } }
+        }
+    ]
+}
diff --git a/tests/js/exe-embed-relay.test.ts b/tests/js/exe-embed-relay.test.ts
new file mode 100644
index 0000000..898b342
--- /dev/null
+++ b/tests/js/exe-embed-relay.test.ts
@@ -0,0 +1,122 @@
+import { beforeAll, beforeEach, describe, expect, it } from 'vitest'
+// Side-effect import: the mirror attaches its API on window.exeEmbedRelay,
+// exactly as relay-host.ts loads it in the browser. This exercises the raw
+// eXe-core relay mirror (src/embed/exe_embed_relay.js) directly, not the
+// relay-host.ts wrapper (which mocks the bridge).
+import '../../src/embed/exe_embed_relay.js'
+
+interface RelayInstance {
+	onMessage: (event: { source: unknown; data: unknown }) => void
+	checkDrift: () => number
+	reflow: () => void
+	dispose: () => void
+}
+
+interface EmbedRelayApi {
+	createRelay: (config: { mode: string }) => RelayInstance
+}
+
+const relay = (window as unknown as { exeEmbedRelay: EmbedRelayApi }).exeEmbedRelay
+
+/** A full DOMRect from a box, so it can be assigned to getBoundingClientRect under strict TS. */
+function fakeRect(left: number, top: number, width: number, height: number): DOMRect {
+	return {
+		left,
+		top,
+		width,
+		height,
+		right: left + width,
+		bottom: top + height,
+		x: left,
+		y: top,
+		toJSON: () => ({}),
+	}
+}
+
+describe('exe_embed_relay checkDrift (mirror of eXe core)', () => {
+	let iframe: HTMLIFrameElement
+
+	beforeAll(() => {
+		// The relay overlays a real <iframe> player pointing at the (cross-origin)
+		// provider URL. Keep the unit test deterministic and offline: stop
+		// happy-dom from navigating child frames (it falls back to just setting the
+		// URL, no network call) and from loading CSS/JS files, so no escaped
+		// fire-and-forget rejection noises the run.
+		interface HappyDomSettings {
+			disableJavaScriptFileLoading: boolean
+			disableCSSFileLoading: boolean
+			handleDisabledFileLoadingAsSuccess: boolean
+			navigation: { disableChildFrameNavigation: boolean }
+		}
+		const dom = (window as unknown as { happyDOM?: { settings?: HappyDomSettings } }).happyDOM
+		if (dom?.settings) {
+			dom.settings.navigation.disableChildFrameNavigation = true
+			dom.settings.disableJavaScriptFileLoading = true
+			dom.settings.disableCSSFileLoading = true
+			dom.settings.handleDisabledFileLoadingAsSuccess = true
+		}
+		// This happy-dom build leaves window.location.hostname undefined, which the
+		// relay's cross-origin check relies on (real browsers always set it).
+		if (!window.location.hostname) {
+			try {
+				Object.defineProperty(window.location, 'hostname', {
+					value: new URL(window.location.href).hostname,
+					configurable: true,
+				})
+			} catch {
+				/* location may be read-only in some environments */
+			}
+		}
+	})
+
+	beforeEach(() => {
+		document.body.innerHTML = ''
+		iframe = document.createElement('iframe')
+		document.body.appendChild(iframe)
+	})
+
+	it('re-pins an overlay whose content iframe moved without any event', () => {
+		const r = relay.createRelay({ mode: 'open' })
+		r.onMessage({
+			source: iframe.contentWindow,
+			data: {
+				type: 'exe-embed',
+				action: 'sync',
+				embeds: [{ id: 'e1', url: 'https://www.youtube.com/embed/abc123', x: 0, y: 0, w: 480, h: 270 }],
+			},
+		})
+		const overlay = document.querySelector<HTMLElement>('.exe-embed-overlay')
+		expect(overlay).not.toBeNull()
+
+		// Nothing moved yet: the drift check must be a no-op.
+		expect(r.checkDrift()).toBe(0)
+
+		// The host toggles a sidebar: the iframe box shifts with no scroll/resize.
+		iframe.getBoundingClientRect = () => fakeRect(120, 30, 500, 320)
+		expect(r.checkDrift()).toBe(1)
+		expect(overlay?.style.left).toBe('120px')
+		expect(overlay?.style.top).toBe('30px')
+		expect(overlay?.style.width).toBe('500px')
+
+		// Settled: a second pass changes nothing.
+		expect(r.checkDrift()).toBe(0)
+	})
+
+	it('dispose() tears down overlays like clear() and can be called before init()', () => {
+		const r = relay.createRelay({ mode: 'open' })
+		r.onMessage({
+			source: iframe.contentWindow,
+			data: {
+				type: 'exe-embed',
+				action: 'sync',
+				embeds: [{ id: 'e1', url: 'https://www.youtube.com/embed/abc123', x: 0, y: 0, w: 480, h: 270 }],
+			},
+		})
+		expect(document.querySelectorAll('.exe-embed-overlay iframe').length).toBe(1)
+
+		r.dispose()
+		expect(document.querySelectorAll('.exe-embed-overlay').length).toBe(0)
+		// Idempotent: a second dispose() (or one before init) must not throw.
+		expect(() => r.dispose()).not.toThrow()
+	})
+})
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..07183e8
--- /dev/null
+++ b/tests/js/relay-host.test.ts
@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+	attachMedia,
+	clearOverlays,
+	pingEmbeds,
+	reflowOverlays,
+	resetRelayForTests,
+	startRelay,
+} from '../../src/embed/relay-host'
+
+type WindowWithBridge = Window & {
+	exeEmbedRelay?: unknown
+	exeMediaHost?: unknown
+}
+
+const w = window as WindowWithBridge
+
+afterEach(() => {
+	resetRelayForTests()
+	delete w.exeEmbedRelay
+	delete w.exeMediaHost
+})
+
+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' }, '*')
+	})
+
+	it('attachMedia attaches the media host to the iframe', () => {
+		const attach = vi.fn()
+		w.exeMediaHost = { attach }
+		const iframe = {} as HTMLIFrameElement
+		attachMedia(iframe)
+		expect(attach).toHaveBeenCalledWith(iframe, {})
+	})
+
+	it('clear/reflow/attach are safe no-ops when the bridge is absent', () => {
+		expect(() => {
+			clearOverlays()
+			reflowOverlays()
+			attachMedia({} as HTMLIFrameElement)
+		}).not.toThrow()
+	})
+})