client-side-media-docs.md in Gutenberg 23.2.0, at lib/media/docs/client-side-media-docs.md

58 lines 3.7 KB Raw Download Zip

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