| 1 |
# Technical Documentation |
| 2 |
|
| 3 |
## Browser Compatibility |
| 4 |
|
| 5 |
Client-side media processing requires the following browser capabilities: |
| 6 |
|
| 7 |
| Feature | Required | Purpose | |
| 8 |
|---------|----------|---------| |
| 9 |
| WebAssembly | Yes | Runs the wasm-vips image processing library | |
| 10 |
| SharedArrayBuffer | Yes | Enables multi-threaded WASM execution | |
| 11 |
| Document-Isolation-Policy | Yes | Required for SharedArrayBuffer in modern browsers | |
| 12 |
| CSP `blob:` workers | Yes | The WASM worker is loaded via a blob URL | |
| 13 |
|
| 14 |
### Browser Support Matrix |
| 15 |
|
| 16 |
| Browser | Minimum Version | Notes | |
| 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 | |
| 22 |
|
| 23 |
### Automatic Fallback |
| 24 |
|
| 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 |
|
| 27 |
The fallback occurs when any of the following conditions are detected: |
| 28 |
- WebAssembly is not supported in the browser |
| 29 |
- SharedArrayBuffer is not available |
| 30 |
- Document-Isolation-Policy is not supported by the browser |
| 31 |
- The site's Content Security Policy (CSP) blocks blob URL workers |
| 32 |
|
| 33 |
## Cross-origin isolation / `SharedArrayBuffer` |
| 34 |
|
| 35 |
WASM-based image optimization requires `SharedArrayBuffer` support, which in turn requires [](https://web.dev/articles/cross-origin-isolation-guidecross-origin isolation](https://web.dev/articles/cross-origin-isolation-guide](https://web.dev/articles/cross-origin-isolation-guide). |
| 36 |
|
| 37 |
This is achieved using the [](https://github.com/nicolo-ribaudo/tc39-proposal-structs/blob/main/test262-filtering/isolation-explainer.md`Document-Isolation-Policy`](https://github.com/nicolo-ribaudo/tc39-proposal-structs/blob/main/test262-filtering/isolation-explainer.md](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. |
| 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 |
### Troubleshooting |
| 42 |
|
| 43 |
If client-side media processing is not working, check the browser console for messages. Common issues include: |
| 44 |
|
| 45 |
1. **"SharedArrayBuffer is not available"**: The server is not sending the required cross-origin isolation headers. |
| 46 |
2. **"Cross-origin isolation is not enabled"**: The headers are present but cross-origin isolation is not active. This can happen if: |
| 47 |
- Headers are being stripped by a proxy or CDN |
| 48 |
- The page is being served over HTTP instead of HTTPS |
| 49 |
|
| 50 |
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. |
| 51 |
|
| 52 |
4. **"Content Security Policy (CSP) does not allow blob: workers"**: A security plugin or server configuration is setting a `worker-src` CSP directive that does not include `blob:`. The WASM image processing worker is loaded via a blob URL, which requires CSP to permit it. To resolve this: |
| 53 |
- Add `blob:` to the `worker-src` directive in the site's CSP header (e.g., `worker-src 'self' blob:`) |
| 54 |
- 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 |
- If the CSP header is set at the server level (e.g., in `.htaccess`, Nginx config, or a CDN), update it there |
| 56 |
|
| 57 |
Check out [](https://github.com/WordPress/gutenberg/issues/74464this tracking issue](https://github.com/WordPress/gutenberg/issues/74464](https://github.com/WordPress/gutenberg/issues/74464) for more details and further resources. |
| 58 |
|
