Opaque-origin published viewer and opt-in opaque editor preview

.gitignore

@@ -54,6 +54,7 @@ public/style/workarea/*.css.map
 # Test results
 test-results/
 test-results/*
+playwright-report/
 
 # Built static editor - download from releases or build with `make build-editor`
 dist/static/

.phpcs.xml.dist

@@ -9,9 +9,16 @@
     <exclude-pattern>/tests/*</exclude-pattern>
     <exclude-pattern>/includes/vendor/*</exclude-pattern>
     <exclude-pattern>/dist/*</exclude-pattern>
-    <exclude-pattern>/exelearning/*</exclude-pattern>
+    <!-- Only the WordPress uploads extraction dir, path-anchored. A bare
+         `/exelearning/*` matched ANY checkout path containing an `exelearning/`
+         segment, silently excluding the whole plugin from local phpcs runs. -->
+    <exclude-pattern>*/wp-content/uploads/exelearning/*</exclude-pattern>
     <!-- Standalone developer CLI tooling; not shipped (see .distignore). -->
     <exclude-pattern>/bin/*</exclude-pattern>
+    <!-- Local, git-ignored scratch space for manual test seeds and Playwright
+         reports. It never reaches CI, so linting it only breaks `make lint`
+         on the developer's machine. -->
+    <exclude-pattern>/artifacts/*</exclude-pattern>
 
     <arg name="extensions" value="php"/>
     <arg name="colors"/>

README.md

@@ -55,6 +55,18 @@ EXELEARNING_EDITOR_REF=my-feature EXELEARNING_EDITOR_REF_TYPE=branch make build-
 
 > **Important:** For production use, always install an official release from [Releases](https://github.com/exelearning/wp-exelearning/releases): release packages include the embedded editor pre-built under `dist/static/`, and that bundle is the only editor the plugin ever uses. The plugin never downloads editor code at runtime, and administrators cannot update the editor independently of the plugin — updating the editor means updating the plugin (a new plugin release is published automatically for every editor release). Source checkouts do not contain `dist/static/`; build it with `make build-editor` as shown above. See [ADR-0002](docs/architecture/adr/ADR-0002-bundle-editor-exclusively-in-release-packages.md).
 
+### Server configuration (nginx)
+
+The live editor **preview** requires **pretty permalinks** (Settings → Permalinks; any structure other than *Plain*) — under plain permalinks the plugin fails closed and shows an admin notice.
+
+On **nginx**, also block direct web access to the ephemeral preview session store: the plugin serves those bytes through an opaque-origin capability URL with a sandbox CSP, and unlike Apache (`.htaccess`) nginx will otherwise serve the materialized author HTML same-origin without that CSP. Include the shipped snippet from your `server { … }` block:
+
+```nginx
+include /path/to/wp-content/plugins/exelearning/nginx-exelearning-preview.conf;
+```
+
+See [`nginx-exelearning-preview.conf`](nginx-exelearning-preview.conf) and [`docs/preview-serving-contract.md`](docs/preview-serving-contract.md) for details.
+
 ## Usage
 
 ### Uploading ELPX Files
@@ -103,6 +115,30 @@ Administrators can upload eXeLearning style packages and control which styles th
 
 Uploaded ZIPs are validated against path traversal, absolute paths, oversize archives (default 20 MB, filterable via `exelearning_styles_max_zip_size`), and a strict file-extension allow-list.
 
+## External embeds in secure mode
+
+In secure mode the `.elpx` content runs in a sandboxed, opaque-origin iframe. That
+opaque origin propagates to any nested iframe, so cross-origin video players and PDF
+viewers render blank. To keep them working, whitelisted video embeds (YouTube and
+Vimeo hosts), any cross-origin `https` `.pdf`, and the package's own local PDFs are
+*promoted* to the trusted parent page and rendered inline on top of the content.
+
+Two cooperating scripts make this work:
+
+- `assets/js/exe-embed-shim.js` runs inside the content iframe, replaces each
+  promotable iframe with a same-size placeholder, and `postMessage`s its geometry
+  and URL to the parent.
+- `assets/js/exe-embed-relay.js` runs on the host page, validates each reported URL
+  against the whitelist, rebuilds the canonical player URL, and overlays the real
+  player exactly over the placeholder.
+
+A static Firefox end-to-end test exercises the real shim and relay against a
+self-contained harness (no WordPress runtime needed):
+
+```bash
+npm run test:e2e:embed
+```
+
 ## Developer hooks
 
 The plugin exposes a set of WordPress actions and filters (all prefixed with

admin/views/editor-bootstrap.php

@@ -111,6 +111,21 @@
 		'fallbackTheme'      => 'base',
 	);
 
+// Opaque snapshot editor-preview (capability contract v1). The editor POSTs a
+// whole-project ZIP snapshot to the authenticated management route and loads the
+// result from an authless, opaque-origin capability URL. REST URLs resolve under
+// both pretty and plain permalinks. wp_json_encode() output is valid JS syntax.
+$exelearning_preview_delete_url  = rest_url(
+	'exelearning/v1/preview-session/' . $exelearning_attachment_id . '/__PREVIEW_ID__'
+);
+$exelearning_preview_snapshot    = array(
+	'managementUrl'     => rest_url( 'exelearning/v1/preview-session/' . $exelearning_attachment_id ),
+	'servingBaseUrl'    => rest_url( 'exelearning/v1/preview/' ),
+	'deleteUrlTemplate' => str_replace( '__PREVIEW_ID__', '{previewId}', $exelearning_preview_delete_url ),
+	'managementHeaders' => array( 'X-WP-Nonce' => $exelearning_nonce ),
+);
+$exelearning_preview_snapshot_js = "\n            previewSnapshot: " . wp_json_encode( $exelearning_preview_snapshot ) . ',';
+
 // Inject WordPress configuration BEFORE the closing </head> tag.
 // phpcs:disable WordPress.WP.EnqueuedResources.NonEnqueuedScript -- Standalone HTML page output, not a WordPress template.
 $exelearning_wp_config_script = sprintf(
@@ -200,15 +215,18 @@ enumerable: true,
                 fileMenu: true,
                 saveButton: true,
                 userMenu: true,
-            },
+            },%s
         };
 
-        // TODO: Remove when editor ResourceFetcher handles 404 gracefully.
-        // Patch fetch and jQuery AJAX to handle CSS/idevices 404s without breaking.
+        // Embedded-editor shims: hide the chrome the host owns and soften CSS /
+        // idevice 404s so a missing optional asset never breaks boot. The live
+        // preview travels as an opaque snapshot capability (see previewSnapshot
+        // above), never a Service Worker on the WordPress origin — so there is no
+        // preview-sw / /viewer/ wiring here.
+        // TODO: Remove the 404 shim when the editor ResourceFetcher handles 404
+        // gracefully.
         (function() {
             var editorBaseUrl = (window.__WP_EXE_CONFIG__ && window.__WP_EXE_CONFIG__.editorBaseUrl) || "";
-            var editorBasePathname = "";
-            var originalServiceWorker = navigator.serviceWorker || null;
             var forceHideSelectors = [
                 "#dropdownFile",
                 "#head-top-save-button",
@@ -218,12 +236,6 @@ enumerable: true,
                 "#mobile-navbar-button-openuserodefiles"
             ];
 
-            try {
-                editorBasePathname = editorBaseUrl ? new URL(editorBaseUrl, window.location.origin).pathname : "";
-            } catch (e) {
-                editorBasePathname = "";
-            }
-
             function forceHideEmbeddedUi() {
                 for (var i = 0; i < forceHideSelectors.length; i += 1) {
                     var nodes = document.querySelectorAll(forceHideSelectors[i]);
@@ -243,94 +255,20 @@ function forceHideEmbeddedUi() {
                 }
             }
 
-            function normalizePreviewIframeSrc(url) {
-                if (!url || !editorBaseUrl) {
-                    return url;
-                }
-
-                var baseNoSlash = editorBaseUrl.replace(/\/$/, "");
-                var raw = url;
-
-                try {
-                    if (raw.startsWith("http://") || raw.startsWith("https://")) {
-                        raw = new URL(raw).pathname;
-                    }
-                } catch (e) {}
-
-                if (raw.indexOf("/wp-admin/admin.php/viewer/") === 0) {
-                    return baseNoSlash + "/viewer/" + raw.substring("/wp-admin/admin.php/viewer/".length);
-                }
-                if (raw.indexOf("/viewer/") === 0) {
-                    return baseNoSlash + raw;
-                }
-                if (raw.indexOf("viewer/") === 0) {
-                    return baseNoSlash + "/" + raw;
-                }
-
-                return url;
-            }
-
-            function ensurePreviewIframeSrc() {
-                var previewIframe = document.getElementById("preview-iframe");
-                if (!previewIframe) {
-                    return;
-                }
-
-                var currentSrc = previewIframe.getAttribute("src") || previewIframe.src || "";
-                var fixedSrc = normalizePreviewIframeSrc(currentSrc);
-                if (fixedSrc && fixedSrc !== currentSrc) {
-                    previewIframe.setAttribute("src", fixedSrc);
-                }
-            }
-
             if (document.readyState === "loading") {
                 document.addEventListener("DOMContentLoaded", forceHideEmbeddedUi);
-                document.addEventListener("DOMContentLoaded", ensurePreviewIframeSrc);
             } else {
                 forceHideEmbeddedUi();
-                ensurePreviewIframeSrc();
             }
 
             var hideObserver = new MutationObserver(function() {
                 forceHideEmbeddedUi();
-                ensurePreviewIframeSrc();
             });
             hideObserver.observe(document.documentElement || document.body, {
                 childList: true,
-                subtree: true,
-                attributes: true,
-                attributeFilter: ["src"]
+                subtree: true
             });
 
-            // Fix preview service worker paths in WP mode.
-            if (originalServiceWorker && editorBasePathname) {
-                var registerOriginal = originalServiceWorker.register.bind(originalServiceWorker);
-                var getRegistrationOriginal = originalServiceWorker.getRegistration.bind(originalServiceWorker);
-                var fixedSwPath = editorBasePathname.replace(/\/$/, "") + "/preview-sw.js";
-                var fixedScope = editorBasePathname.replace(/\/$/, "") + "/viewer/";
-
-                originalServiceWorker.register = function(scriptURL, options) {
-                    var nextScript = scriptURL;
-                    var nextOptions = options || {};
-                    if (typeof nextScript === "string" && nextScript.indexOf("preview-sw.js") !== -1) {
-                        nextScript = fixedSwPath;
-                        nextOptions = Object.assign({}, nextOptions, { scope: fixedScope });
-                    }
-                    return registerOriginal(nextScript, nextOptions);
-                };
-
-                originalServiceWorker.getRegistration = function(clientURL) {
-                    var nextClientUrl = clientURL;
-                    if (
-                        !nextClientUrl ||
-                        (typeof nextClientUrl === "string" && nextClientUrl.indexOf("/wp-admin/") === 0)
-                    ) {
-                        nextClientUrl = fixedScope;
-                    }
-                    return getRegistrationOriginal(nextClientUrl);
-                };
-            }
-
             function normalizeEditorAssetUrl(url) {
                 if (!url || typeof url !== "string" || !editorBaseUrl) {
                     return url;
@@ -482,6 +420,7 @@ function normalizeEditorAssetUrl(url) {
 	wp_json_encode( $exelearning_editor_base_url ),
 	wp_json_encode( $exelearning_i18n ),
 	wp_json_encode( $exelearning_theme_registry_override ),
+	$exelearning_preview_snapshot_js,
 	esc_url( $exelearning_plugin_assets_url )
 );
 // phpcs:enable WordPress.WP.EnqueuedResources.NonEnqueuedScript
@@ -538,10 +477,23 @@ function normalizeEditorAssetUrl(url) {
 // Insert config script and styles before </head>.
 $exelearning_template = str_replace( '</head>', $exelearning_wp_config_script . $exelearning_page_styles . '</head>', $exelearning_template );
 
-// Add <base> tag to set the base URL for all relative paths.
-// This ensures paths like "files/perm/..." resolve to the static editor directory.
+// Add <base> tag to set the base URL for all relative paths, and a first-thing
+// Service Worker hygiene script that purges caches left by an earlier editor
+// build (stale assets could otherwise drive the preview into a refresh loop).
+// It does NOT block registration: the trust-boundary editor registers its own
+// /viewer/ preview worker, which serves only DOMPurify-sanitized ("filtered")
+// content from a real same-origin URL — required so whitelisted external videos
+// play inline (see ExeLearning_Editor::purge_stale_editor_caches_script). Both are
+// injected right after <head>, before any editor script runs.
+// phpcs:disable WordPress.WP.EnqueuedResources.NonEnqueuedScript -- Standalone HTML page output, not a WordPress template.
+$exelearning_cache_purge_tag = '<script>' . ExeLearning_Editor::purge_stale_editor_caches_script() . '</script>';
+// phpcs:enable WordPress.WP.EnqueuedResources.NonEnqueuedScript
 $exelearning_base_tag = sprintf( '<base href="%s/">', esc_url( $exelearning_editor_base_url ) );
-$exelearning_template = preg_replace( '/(<head[^>]*>)/i', '$1' . $exelearning_base_tag, $exelearning_template );
+$exelearning_template = preg_replace(
+	'/(<head[^>]*>)/i',
+	'$1' . $exelearning_cache_purge_tag . $exelearning_base_tag,
+	$exelearning_template
+);
 
 // Fix asset paths: Replace relative paths with absolute plugin paths.
 // The static build uses relative paths like "./app/", we need absolute paths.

assets/css/exelearning.css

@@ -291,6 +291,56 @@
     max-width: 100%;
 }
 
+/* Loading state for the embedded package.
+   The package is fetched, parsed and laid out inside the iframe before anything
+   paints, so without this the visitor stares at an empty frame. The spinner is
+   hidden unless the enqueued loader adds `is-loading`, so with JS disabled
+   nothing is shown that JS would never be able to clear. */
+.exelearning-embed-loader {
+    position: relative;
+}
+
+.exelearning-embed-loader__spinner {
+    display: none;
+    position: absolute;
+    inset: 0;
+    align-items: center;
+    justify-content: center;
+    gap: 0.6em;
+    background: #fff;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    color: #50575e;
+    font-size: 0.875rem;
+}
+
+/* Only the visibility depends on the state. */
+.exelearning-embed-loader.is-loading .exelearning-embed-loader__spinner {
+    display: flex;
+}
+
+.exelearning-embed-loader__spinner::before {
+    content: "";
+    width: 1.25em;
+    height: 1.25em;
+    border: 2px solid currentColor;
+    border-top-color: transparent;
+    border-radius: 50%;
+    animation: exelearning-embed-spin 0.8s linear infinite;
+}
+
+@keyframes exelearning-embed-spin {
+    to {
+        transform: rotate(360deg);
+    }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .exelearning-embed-loader__spinner::before {
+        animation-duration: 3s;
+    }
+}
+
 .exelearning-screenshot-img {
     display: block;
     width: 100%;