| @@ -7,9 +7,9 @@ | ||
| 7 | 7 | | Feature | Required | Purpose | |
| 8 | 8 | |---------|----------|---------| |
| 9 | 9 | | WebAssembly | Yes | Runs the wasm-vips image processing library | |
| 10 | 10 | | SharedArrayBuffer | Yes | Enables multi-threaded WASM execution | |
| 11 | -| Document-Isolation-Policy | Yes | Required for SharedArrayBuffer in modern browsers | | |
| 11 | +| Cross-origin isolation | Yes | Required for SharedArrayBuffer in modern browsers | | |
| 12 | 12 | | CSP `blob:` workers | Yes | The WASM worker is loaded via a blob URL | |
| 13 | 13 | |
| 14 | 14 | ### Browser Support Matrix |
| 15 | 15 | |
| @@ -14,12 +14,12 @@ | ||
| 14 | 14 | ### Browser Support Matrix |
| 15 | 15 | |
| 16 | 16 | | Browser | Minimum Version | Notes | |
| 17 | 17 | |---------|-----------------|-------| |
| 18 | -| Chromium | 137+ | Full support via Document-Isolation-Policy | | |
| 19 | -| Edge | 137+ | Full support via Document-Isolation-Policy | | |
| 20 | -| Firefox | Not supported | Does not support Document-Isolation-Policy | | |
| 21 | -| Safari | Not supported | Does not support Document-Isolation-Policy | | |
| 18 | +| Chrome | 92+ | Full support | | |
| 19 | +| Firefox | 79+ | Full support except embed previews | | |
| 20 | +| Safari | 15.2+ | Requires `require-corp` instead of `credentialless` | | |
| 21 | +| Edge | 92+ | Full support | | |
| 22 | 22 | |
| 23 | 23 | ### Automatic Fallback |
| 24 | 24 | |
| 25 | 25 | When client-side media processing is unavailable, the system automatically falls back to server-side processing. This fallback is transparent to users and requires no action. A message is logged to the browser console indicating the reason for the fallback. |
| @@ -26,9 +26,9 @@ | ||
| 26 | 26 | |
| 27 | 27 | The fallback occurs when any of the following conditions are detected: |
| 28 | 28 | - WebAssembly is not supported in the browser |
| 29 | 29 | - SharedArrayBuffer is not available |
| 30 | -- Document-Isolation-Policy is not supported by the browser | |
| 30 | +- Cross-origin isolation is not enabled (missing required headers) | |
| 31 | 31 | - The site's Content Security Policy (CSP) blocks blob URL workers |
| 32 | 32 | |
| 33 | 33 | ## Cross-origin isolation / `SharedArrayBuffer` |
| 34 | 34 | |
| @@ -33,12 +33,10 @@ | ||
| 33 | 33 | ## Cross-origin isolation / `SharedArrayBuffer` |
| 34 | 34 | |
| 35 | 35 | WASM-based image optimization requires `SharedArrayBuffer` support, which in turn requires [cross-origin isolation](https://web.dev/articles/cross-origin-isolation-guide). |
| 36 | 36 | |
| 37 | -This is achieved using the [`Document-Isolation-Policy`](https://github.com/nicolo-ribaudo/tc39-proposal-structs/blob/main/test262-filtering/isolation-explainer.md) header, which provides per-document cross-origin isolation without affecting other iframes on the page. This avoids the breakage that the older `Cross-Origin-Embedder-Policy` / `Cross-Origin-Opener-Policy` headers caused for third-party plugins and embeds. | |
| 37 | +Once the page is served with these headers, `SharedArrayBuffer` will be available in the browser, and WASM-based image optimization will work as expected. However, all embedded resources (e.g., images, iframes, scripts) must also be served with appropriate CORS headers (or iframe with `iframe-credentialless` for supporting browsers) to ensure cross-origin isolation is maintained. For third party embeds (for example a YouTube video), the plugin uses [iframe `credentialless` attribute](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/IFrame_credentialless) to help with this. For browsers that do not support this attribute, embeds will show an information pane instead of a live preview. | |
| 38 | 38 | |
| 39 | -Once the page is served with this header, `SharedArrayBuffer` will be available in the browser, and WASM-based image optimization will work as expected. All embedded resources (e.g., images, scripts) are served with `crossorigin="anonymous"` to ensure cross-origin isolation is maintained. | |
| 40 | - | |
| 41 | 39 | ### Troubleshooting |
| 42 | 40 | |
| 43 | 41 | If client-side media processing is not working, check the browser console for messages. Common issues include: |
| 44 | 42 | |
| @@ -43,8 +41,9 @@ | ||
| 43 | 41 | If client-side media processing is not working, check the browser console for messages. Common issues include: |
| 44 | 42 | |
| 45 | 43 | 1. **"SharedArrayBuffer is not available"**: The server is not sending the required cross-origin isolation headers. |
| 46 | 44 | 2. **"Cross-origin isolation is not enabled"**: The headers are present but cross-origin isolation is not active. This can happen if: |
| 45 | + - Third-party resources are blocking isolation | |
| 47 | 46 | - Headers are being stripped by a proxy or CDN |
| 48 | 47 | - The page is being served over HTTP instead of HTTPS |
| 49 | 48 | |
| 50 | 49 | 3. **"WebAssembly is not supported"**: The browser does not support WebAssembly. This is rare in modern browsers but can occur in older versions or restricted environments. |
| @@ -54,4 +53,5 @@ | ||
| 54 | 53 | - If using a security plugin (e.g., WP Cerber, Wordfence, or similar), check its CSP settings and add `blob:` to the allowed worker sources |
| 55 | 54 | - If the CSP header is set at the server level (e.g., in `.htaccess`, Nginx config, or a CDN), update it there |
| 56 | 55 | |
| 57 | 56 | Check out [this tracking issue](https://github.com/WordPress/gutenberg/issues/74464) for more details and further resources. |
| 57 | + | |
