docs: WebXR in iframes — xr-spatial-tracking permission policy

Add an FAQ entry and an embedding-guide troubleshooting note explaining why WebXR
(AR/VR) fails in an iframe with "xr-spatial-tracking is not allowed in this
document": the embedding page must grant the feature, and the iframe `allow`
attribute only delegates a feature the parent already has. It's a document-policy
issue, not a device one (appears even on Quest). Both link the MDN iframe `allow`
docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: marwie

documentation/how-to-guides/deployment/embedding.md

@@ -157,6 +157,20 @@ The `allow` attribute depends on your app's features:
 [See full list of iframe permissions →](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy#directives)
 :::
 
+:::warning AR/VR doesn't work in the iframe? Check the *parent* page
+WebXR needs the `xr-spatial-tracking` permission policy, and the iframe `allow` attribute only **delegates** a feature the **embedding page already has**. If you set `allow="xr; xr-spatial-tracking"` but still see
+
+```
+[Violation] Permissions policy violation: xr-spatial-tracking is not allowed in this document
+```
+
+then the page hosting the iframe isn't granting the feature. Make sure:
+- the `<iframe>` has it in [`allow`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe#allow): `allow="xr; xr-spatial-tracking; fullscreen"`, **and**
+- the **parent page** is itself permitted the feature (don't send a restrictive `Permissions-Policy` response header that omits `xr-spatial-tracking`).
+
+This is about the *document's* policy, not the device — so it can appear even on a Quest. Learn more: [iframe `allow` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe#allow).
+:::
+
 ### 5. `<needle-app>` (Same-Document Embed)
 
 **Best for:** Existing websites (Webflow, custom HTML) where the scene should be *part of the page* — clickable HTML driving the scene, or scroll-driven 3D.

documentation/reference/faq.md

@@ -911,6 +911,20 @@ If you see "WebXR not found" or simply can't enter AR, check the following:
 
 For AR on iOS, Needle Engine supports WebXR via [App Clips (Needle Go)](/docs/how-to-guides/xr/ios-webxr-app-clip). See also the [Platform Support](#does-it-work-on-ios) section.
 
+## AR/VR doesn't work in an iframe (console shows "xr-spatial-tracking is not allowed in this document")
+
+WebXR is gated by the `xr-spatial-tracking` permission policy. When your scene runs inside an `<iframe>`, the **embedding page must grant it** — having the feature on your own page is not enough. Both of these must be true:
+
+1. The `<iframe>` lists it in its [`allow` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe#allow):
+   ```html
+   <iframe src="https://your-app…" allow="xr; xr-spatial-tracking; fullscreen"></iframe>
+   ```
+2. The **page containing the iframe** is itself permitted the feature — the `allow` attribute only *delegates* a feature the parent already has. If the parent page sends a restrictive `Permissions-Policy` header that omits `xr-spatial-tracking`, the iframe can't receive it.
+
+This is about the *document's* permission policy, not the device's capability, so the violation can appear **even on a headset like Quest**. When the policy isn't granted, the engine reports XR as unsupported (and from Needle Engine 5.1.x it does so quietly instead of repeating the violation in the console).
+
+See [iframe `allow` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe#allow) and the [Embedding guide](/docs/how-to-guides/deployment/embedding#_4-iframe-embedding).
+
 ## How do I access the tracked object from an image tracking event?
 
 Each `WebXRTrackedImage` received from the `image-tracking` event gives you access to the assigned 3D object via `img.model.object`: