FramePort 1.3.0

Site: contributor data and games list refreshed (1.3.0)
Lint: wrap long lines, raise ... from None in the room-scan lock, zip(strict=True) in the scene tests (CI's ruff check failed on the MR merge)
2026-10-19 21:01:35 +02:00 · 2026-10-19 00:59:27 -04:00 · 2026-10-19 00:58:53 -04:00 · 2026-10-19 00:57:08 -04:00 · 2026-10-19 00:23:58 -04:00 · 2026-10-19 00:23:57 -04:00
151 changed files with 16211 additions and 357 deletions
@@ -59,7 +59,21 @@ Detailed device findings per game/issue: docs/DEVICE_NOTES.md (read before debug
    agent ends at EOF); sources and costs in docs/FRAME_RUNTIME.md "Monitoring sources"; game card (fps from
    FrameBridge pacing; End game = Steam's Exit game, then cmd_stop), tiles with `C.Sparkline` (Flet canvas, no charts
    extension), details, a pooled process table (Game / Steam & SteamVR / All; right-click: end / force kill / end
-    game; MON_CRITICAL needs force, MON_NEVER is refused)); settings; welcome; activity panel). Files, Screenshots and the Library share right-click menus
+    game; MON_CRITICAL needs force, MON_NEVER is refused)); room (`views/room.py`, persistent, "experimental" pill:
+    scan with progress + Cancel = agent v109 `room_capture_stop`, play area, delete; cache `ui/room_state.py` shared
+    with the Frame page's short card, mesh cached in `<data>/rooms-cache/<frame>/`; in-window 3D `ui/room3d.py`
+    RoomCanvas over `mr/view3d.py` (pure-Python projection, mesh reduced to ≤4k/≤1.5k edges at rest/moving, ≤18 fps
+    worker; each redraw sends NEW shape controls: changing a Points list made Flet diff it item by item, 0.3-1 s);
+    "Open full 3D view" = `mr/room_viewer.py` token server on 127.0.0.1 + hand-written WebGL `mr/viewer_page.py`,
+    stopped on disconnect/close; Test Quest MR tip = `mr.TESTER_*`; editing cards `views/room_edit.py` (agent v109):
+    Clean-up = fp_roomscan's refinement settings, `install/rooms.REFINE_DEFAULTS` = the owner's defaults + slider
+    metadata (agent `ROOM_REFINE_DEFAULTS` must match, a test checks), saved non-defaults in the Frame's
+    `rooms/refine.json`, used by every build; Apply = job → agent `room_refine` (`--refine-only` on a copy of the room
+    folder from `room-raw.txt`/`room-mesh-raw.bin`, scan.json → status `report`/`labels`/`suggestions`); Labels =
+    the label rules' decisions + Add as door / Add as closet; Furniture & screens = box editor (click a box in the
+    canvas: `view3d.pick`) + doors/windows on a wall (`mr.room.plane_on_wall`), Save = `rooms.put_room` → `room_put
+    edited` (keeps raw files, `edits.txt` survives a new clean-up; "Back to the scan's boxes" = keep_edits false); no
+    eraser in the GUI (`rooms.refine(erase=)` only)); settings; welcome; activity panel). Files, Screenshots and the Library share right-click menus
    (one `ft.ContextMenu` per view, filled on right-click; on one of several selected items they act on the whole
    selection, `C.menu_targets`) and click-and-drag multi-select (`C.DragSelect`: pan start/end on the area + item
    hover events, which Flutter also sends with the button held; Flet can't report item positions, so no rubber band).
@@ -455,7 +469,9 @@ Repo is on an NTFS drive (`core.fileMode=false`); line endings are LF (`.gitattr
 - No XR_FB_display_refresh_rate (`xrGetDisplayRefreshRateFB` -7), yet OVRPort's dispatcher offers it and answered 0 Hz
  → FrameBridge always answers with the measured rate (1/predictedDisplayPeriod, else 72). PreyVR (#306, idTech 4:
  `USERCMD_MSEC = 1000 / GetRefresh()`) had 0 ms tics: async thread spinning, `com_frameTime` stuck at 0, menu black.
- Guardian STAGE bounds report 1×1 m (scene emulation uses ≥1.5 m).
+- Guardian STAGE bounds report 1×1 m (scene emulation uses ≥1.5 m). OVRPlugin treats that rect as a configured
+  boundary but can't outline it ("ovrpBoundary_Outer is not supported"): Demeter's guardian check indexed an empty
+  array → with `scene_emul` the app's STAGE `xrGetReferenceSpaceBoundsRect` returns XR_SPACE_BOUNDS_UNAVAILABLE.
 - GL goes through **Zink** (Mesa GL on Vulkan). Mesa GLSL is strict: `#pragma` before `#extension` fails, implicit
  int/float conversions fail (enable `GL_EXT_shader_implicit_conversions`), num_views=2 shaders on single-view FBOs
  give GL_INVALID_OPERATION. Some GLES games hit `zink: DEVICE LOST` (Unity MSAA RTT; Sniper Elite VR even without).
@@ -590,6 +606,7 @@ Toy Master doesn't request a model after that (it uses its own), so the glb load
 **Vader Immortal (GitHub #49):** stuck on its loading card and leaked GPU mappings (solved below: `gl_error_clear`); diagnostics FrameBridge `layer_debug`, `strip_color_bias`, `frame_balance`, `snapshot=N` (`snapshot_gl.c`: saves the submitted left-eye image as `files/fb_snap_*.ppm`). → docs/DEVICE_NOTES.md#vader-immortal-headless-investigation
 **SteamVR overlay apps:** host OpenVR overlays composite over Lepton games; detection `analysis/vroverlay.py`, patch `pcvr.vr_overlay`, Linux fields `vr_overlay`/`vr_overlay_autostart`, agent `register_vr_overlay`/`unregister_vr_overlay`/`launch_vr_overlay`; SteamVR on the Frame reads only `binary_path_linux_arm`; FramePort's own autostart (`ensure_overlay_service`, `frameport-vr-overlays.service`). See also docs/FRAME_RUNTIME.md "Overlay apps". → docs/DEVICE_NOTES.md#steamvr-overlay-apps
 **Vader's leak solved / AC Nexus flips:** stale GL errors broke SteamVR's GL interop → adapter `gl_error_clear` (GLES, catalog for Vader ep1-3); read `xrclient_<pkg>.txt` in Steam's logs for runtime errors; the runtime caps swapchains per session (~15) → flip emulation in place; adapter `flip_dump`. → docs/DEVICE_NOTES.md#vaders-leak-solved--ac-nexus-flips
+**Mixed reality: scanned rooms (branch mr-scene):** agent `room_capture` records Valve's RoomView 3D depth mesh -> `fp_roomscan` -> `room.txt` + `room-mesh.bin` (docs/mr/ROOM_FORMAT.md; refined by default: the owner's cleanup passes + label rules in `native/roomscan/refine.c`/`rules.c`, unrefined output kept as `room-raw.txt` + `room-mesh-raw.bin`, head path/settings/report/labels/door suggestions in `scan.json`, `--refine-only <dir>` re-runs it, `--refine 0` = old output; docs/mr/scan.md "Refinement") in `~/.local/share/frameport/rooms/<universe>/`, copied next to settings.conf (`_room_sync`); FrameBridge (`scene_room.c/scene_meta.c/scene_anchors.c`, all through xrshim) serves walls, volumes, planes, the room mesh, META discovery/persistence, saved anchors and `XR_META_boundary_visibility`; `scene_emul` + `frame.meta_permissions` for every USE_SCENE/USE_ANCHOR_API game (migrations `scene_emul_all`, `scene_permissions`); per-game `scene_hide_bounds` (Demeter). → docs/DEVICE_NOTES.md#mixed-reality-scanned-rooms
 **Unreal's self-restart:** UE 4.21+ restarts itself after the first shader precompile and Lepton ends the container → launch.sh RESTART_BLOCK starts Lepton once more (`upgrade_launchers`; `FRAMEPORT_NO_RESTART=1` off). → docs/DEVICE_NOTES.md#unreals-self-restart
 **xrWaitFrame runs ahead:** the runtime sometimes returns a display time <1 refresh after the last submit and rejects the second submission (`VRCompositorError_AlreadySubmitted`) → the VrApi bridge re-waits (`pacing 2s:` counters). → docs/DEVICE_NOTES.md#xrwaitframe-runs-ahead-journey-of-the-gods
 **Lepton's logcat mirror dies** (EOF, read failure, or silent) → launch.sh `_logcat_keeper` reads `podman exec <container> logcat` itself into launch.log (log `<base>/logcat-keeper.log`). → docs/DEVICE_NOTES.md#leptons-logcat-mirror-dies
@@ -36,6 +36,9 @@ Frame, patches each game so it runs there, uploads it and adds it to your Steam
  in FramePort.
 - **Your Frame from your PC:** Type on Frame (your keyboard on the Frame), Files, Screenshots, Live view (what the
  headset shows, in your browser) and Monitor (frame rate, temperatures, battery, processes).
+- **Your room for mixed reality (experimental):** scan the room in the headset, see it in 3D, clean up the scan and
+  fix furniture, screen and door labels, so mixed-reality games get your room. Try it with
+  [Test Quest MR](https://github.com/spoopyghosty0/TestQuestMR).
 - **Updates itself**, and reports problems without personal data.

 Details for each: [Install and first steps](docs/INSTALL.md).
@@ -44,6 +47,8 @@ Details for each: [Install and first steps](docs/INSTALL.md).

 ![Screenshots](docs/images/screenshots.png)

+![Room (experimental): the scanned room in 3D, clean-up and labels](docs/images/room.png)
+
 ## Quick start

 1. [Download](https://github.com/spoopyghosty0/frameport/releases/latest) the build for Windows, macOS (Apple
@@ -14,11 +14,11 @@ e32f9b3222bfe2e58c193db809ac2cf54086df36fd2ec6651aa2e58308f6b39d  ./arm64-v8a/li
 4a13a33e112c9e4e3c5ff4337ed6e988a9e5b3602f48d654df148ef5fafbf426  ./arm64-v8a/libfpglmv.so
 36400eae4ba3807bcfcd54463daa217347032b07218792faa448d8cbbd086a0e  ./arm64-v8a/libframe_xrshim.so
 19ba5ed3c4b780f5ae46251f6958f552acfc5f13c8bb39f995579593fa8990c6  ./arm64-v8a/libglshim.so
-95f4ad50a33ac1bc6c58b70771cd22963c78a8d8fef3e33a7e41f2e2ffe6f940  ./arm64-v8a/libopenxr_loader_generic.so
+7c33d7fb9fd176ca222efb2d87cf525e2f0604457c16896027a5881594495f76  ./arm64-v8a/libopenxr_loader_generic.so
 1feaeafad467c4cafdf2b018a4d84b0bee200c3f711697b4ce97e66a3ba256ca  ./arm64-v8a/libovrplatformcompat.so
 a4ed80ae45ca90758239f152ea5a2e8c127d491e1e697ea5680db6fd7f72db07  ./arm64-v8a/libvrapi.so
 a4ed80ae45ca90758239f152ea5a2e8c127d491e1e697ea5680db6fd7f72db07  ./arm64-v8a/libvrapi_foveation.so
-ff9e03b526ef9f67ce36f8ebe8943c0d5b765dc31b1ca4c9d5655ded141cf39f  ./armeabi-v7a/libopenxr_loader_generic.so
+19ae0a45e80d8031300eea0d54810c14e4711fa8cd383c29ca65d85a74f577c4  ./armeabi-v7a/libopenxr_loader_generic.so
 1871eae093432d277da4bc751bf5f3269dfcf11f9168260b0c3caadb0dedb19d  ./dex/oculusos-stubs.dex
 b634ab5640e258563c536e658cad87080553df6f34f62269a21d554844e58bfe  ./hevc/COPYING.FFmpeg
 141de01f0d40b97d4f9a720db5ab8ea442f6aa35db5272048899292884994a1c  ./hevc/libstagefrighthw.so
@@ -28,6 +28,38 @@ b634ab5640e258563c536e658cad87080553df6f34f62269a21d554844e58bfe  ./hevc/COPYING
 6cda3076a8c09b31bb1f90da614ea89e7ee194589626eeac613e522849604e47  ./licenses/LuaJIT.txt
 1aa733117cf57ccff7cf23f0425dbfd73b0332a3ef1c905ceeca0ccd0449c4e0  ./linux-arm64/XR_APILAYER_FRAMEPORT_timefix.json
 28c2430a02bbd8902c5bfb9562c6fd0e318654f9e05c095bfeb94b0450ab1b07  ./linux-arm64/libxr_frameport_timefix.so
+2cc16b90abcd3d359f1658c581172bd650017bf2725e24268915f50904c000ec  ./linux-arm64-bin/fp_roomscan
 b10b3a5c10c3339fc63fd9f6cb4d01ea29be11a863d0ebad1389ea69fd471940  ./linux-arm64-bin/fp_venc
+00c2dead0fd7497929833467f0e55699d57d26be1b85dce35402993852f7b111  ./roomscan/ceiling.png
+c1962de31ed2810d31c760cf9ee63316ac2b8c9528ccbcd9299ebf5ba39b2995  ./roomscan/done.png
+0dfaea4c68979b0a45a9fef06fdf1a92468ffc8f46f80a3a014fce1d805972d5  ./roomscan/failed.png
+f2bae84f1d1512f87b25e688acdddb29b3f360f3f0d0cd4fdeeb741a79e7b19a  ./roomscan/finish_00.png
+9be7720c45f162e99813cb9a7a03e026fed53b41f06637b30ded309eeac91759  ./roomscan/finish_01.png
+220d699f879b3a8669cfaf4dc714496e8c1db7e7878e7cd12b1a41aec9b62faa  ./roomscan/finish_02.png
+42871b440b77449d4fe41be1c809a930148a874caa8bc92b13b5d25bb6effa83  ./roomscan/finish_03.png
+a470f62624c94ed6791cc7ee03066e1ffb0a676d520658a0a8b02a6af1605b3b  ./roomscan/finish_04.png
+195ff1c649fd9b42bfa6eea29c43a8b67116fd6ffe9b0fe53dcbdb1074bd34fa  ./roomscan/finish_05.png
+a45accab86b02d7b78327a17b84a6fea543ecc549282055dd3182c686fc2b1b8  ./roomscan/finish_06.png
+b88d6c590ea839a9d11b3a4de8c3effb39752f7114318966fddae09995e0fd37  ./roomscan/finish_07.png
+4a3615db26cf765b855a997be3e067aed58464894dab4a6700fdec5c2b854501  ./roomscan/finish_08.png
+f532a83044e707c66dbc74787ce7b844890bc05829d3e9c8f7e33dae9db246a5  ./roomscan/finish_09.png
+ffce61a9f13bbb250fad3582396a5bec82a1bad1d585b7ef9b8f65d343806b26  ./roomscan/finish_10.png
+4a63772adacb31004749ab04b592076bd36cda61eef52f59037d5abdc9e527db  ./roomscan/finish_11.png
+f373e7021cfce0d1078227f473425a10035ee426102b78f13e0fea4833b736d5  ./roomscan/finish_12.png
+1147391822be3f1aa5351374b8fd9ec85f8b5ce40e3cb9f3146d778e6fbc652a  ./roomscan/floor.png
+eb3c8b55a9dbafa030797ca9f06a22c3ee3bbef96cb7adea26d433ebad43d43f  ./roomscan/look_00.png
+6ba965ff6d22a469c558f2a68229bd2ff48fc28badb95889ca245310d1dd3e96  ./roomscan/look_01.png
+0a11cec25ebc76fe11d505d1f2ec162c9b4a6754393065800e73b1f81e2d94c8  ./roomscan/look_02.png
+fa5a4c94d20af56797b9fcc111148767847a6633ade9217cab373de232efad90  ./roomscan/look_03.png
+e80fa493e380fba39084be2ee62859adcff4e39aa66566abee10a4d6339c52e9  ./roomscan/look_04.png
+133617f0d8d1e69c37408aac80033f71856b592b62e3b780cc12b446bd974680  ./roomscan/look_05.png
+d5dd296ff23641c6973c57ac139147e99c7b783316ab60537adb2155dd196880  ./roomscan/look_06.png
+c08570aa78f966ae937b2e21d0bad887c5352fbca56aa579a2a7ef8541fb96ad  ./roomscan/look_07.png
+3767e7db5fb6babc872fa62c42604f749c65936717d332101745b201cd450cd5  ./roomscan/look_08.png
+2924dc65e5c497545340209edc16060e12e1834d11af6871d1c1baa50b7b2562  ./roomscan/look_09.png
+cd0150dfc10b2aea39403c74eff72fd05fb0111178ef39b4c98657a6d16d105e  ./roomscan/look_10.png
+011355e412f73ade3896e9037490e607c4365d0cf8ceb807d236bf68b414d3ed  ./roomscan/look_11.png
+1b8b47ffb47568d540921f065b5958eeb44a6489498d58e0f33f5d1f535154e2  ./roomscan/look_12.png
+926c7bc6a103adee5b9bf938f5d4e39095ab77fd6270b5301be3b0428edd9ae6  ./roomscan/start.png
 c2c70f4af1a5c3e6089dff1130161dd417f8044f99ec639eeecf1083930aab16  ./win-x64/fp_oculushmd.exe
 60ebc5fea05b8945082e2ca8b9f2eb74616012a26eb50133af273dff0fcddc42  ./win-x64/fp_vrsettings.exe
@@ -0,0 +1,16 @@
+package: com.And7Limited.Hitstream
+title: Hitstream
+status: works
+tested_version: 2.06bQuest
+engine: Unity
+xr: OpenXR
+frame:
+- frame.unity_text_input
+adapter:
+  controller_models: 1
+  haptic_fix: 1
+notes: Fitness rhythm game; uses controller models and haptics fix.
+verified:
+  date: '2026-10-12'
+  known_good_sha256: ecc9e2eee79073ae97ad5d3f70c21e8f049f899f21b51dfd541430bb7dd04cac
+source_hint: Hitstream
@@ -12,6 +12,7 @@ overport_extra:
 - patch_force_passthrough
 adapter:
  scene_emul: 1
+  scene_hide_bounds: 1
 device:
 - device.text_input_window
 verified:
@@ -22,4 +23,4 @@ verified:
 frame:
 - frame.meta_permissions
 - frame.unity_text_input
-updated: '2026-10-15'
+updated: '2026-10-17'
@@ -5,8 +5,10 @@ source_hint: NOPE CHALLENGE
 engine: Unreal
 xr: OpenXR
 status: works
-notes: Meta XR Audio telemetry patch + nodebug. MR "Reality Breach" mode unavailable.
-details: The MR 'Reality Breach' mode needs passthrough; standard VR mode used.
+notes: "Meta XR Audio telemetry patch + nodebug. MR mode: needs a scanned room."
+details: The MR 'Reality Breach' mode needs passthrough and a room; standard VR mode was verified.
+adapter:
+  scene_emul: 1
 alt_overport:
 - patch_remove_unreal_force_quit
 frame:
@@ -0,0 +1,19 @@
+package: com.mrf.tvb.laser_dance
+title: Laser Dance
+engine: Unity
+xr: OpenXR
+status: works
+notes: Mixed reality laser obstacle course; requires spatial data and room layout emulation (scene_emul=1). frame.meta_depth_occlusion keeps close lasers visible (its asset fixes only for the build they were made for); tested version not recorded (PR #246).
+details: Mixed reality game that projects lasers across your room; needs Meta scene emulation and spatial data permission.
+adapter:
+  controller_fix: 1
+  haptic_fix: 1
+  scene_emul: 1
+  passthrough_emul: 1
+frame:
+- frame.meta_permissions
+- frame.meta_depth_occlusion
+- frame.unity_scene_active_rooms
+- frame.unity_text_input
+min_app: 1.2.2
+updated: '2026-10-18'
@@ -1,13 +1,14 @@
 package: com.zenstudios.PFXVRQuest
 title: Pinball FX VR
 status: issues
-notes: Plays; mixed reality mode not working yet. Space warp off (fewer stutters).
+notes: "Plays; space warp off (fewer stutters). MR mode: needs a scanned room."
 tested_version: '1.9'
 engine: Unreal
 xr: OpenXR
 alt_overport:
 - patch_remove_unreal_force_quit
 adapter:
+  scene_emul: 1
  equirect_emul: 1
  hide_space_warp: 1
 verified:
@@ -0,0 +1,21 @@
+package: jp.strippers.punchfit
+title: Punch Fit
+status: works
+tested_version: 1.7.2
+engine: Unity
+xr: OpenXR
+frame:
+- frame.meta_permissions
+- frame.unity_text_input
+adapter:
+  haptic_fix: 1
+  pose_time_fix: 1
+  scene_emul: 1
+  passthrough_emul: 1
+notes: Mixed reality workout arena; composition layer trimming prevents 21+ layer overflow.
+verified:
+  date: '2026-10-12'
+  known_good_sha256: 1a0050272526360542d62e7e6d1fc2daecb765c34378a6fe4ad51568ec550c0d
+source_hint: Punch Fit
+min_app: 1.2.2
+updated: '2026-10-18'
@@ -6,6 +6,18 @@
 # with diagnostics. Launch tests and real play sessions (agent session_log, `frameport session`) are both matched.
 # Sources: every failure we hit porting 34 games to the Steam Frame (see docs/PLAYBOOK.md).
 signatures:
+  - id: mr-no-room
+    pattern: 'FrameBridge[^\r\n]*scene: (?:capture requested -> (?:guardian box|using guardian room)|room from guardian|room [^\r\n]*(?:from guardian|configured/default size|box))'
+    severity: info
+    diagnosis: 'The game is using a simple fallback room. Scan your room for mixed reality, or use Frame > Room > Use my play area for walls without furniture. A recorded scan can be imported until headset capture is available.'
+    suggest: []
+  - id: mr-discovery-unsupported
+    pattern: '(?:Unknown proc addr:\s*xrDiscoverSpacesMETA|(?:MRUK[^\r\n]*)?NoRoomsFound)'
+    # discovery reached FrameBridge and found the room (OVRPort's "Unknown proc addr" comes before the shim takes over)
+    unless: 'FrameBridge[^\r\n]*scene: discovery request=\d+ results=[1-9]'
+    severity: warning
+    diagnosis: 'The game cannot discover a Meta room. Enable room layout (adapter.scene_emul), rebuild and reinstall for the updated extension shim, then save a room under Frame > Room.'
+    suggest: [adapter.scene_emul]
  - id: dynamic-resolution-foveation
    pattern: 'projection view [01](?: rect change)?:[^\r\n]*rect=(?:[1-9]\d*,\d+|0,[1-9]\d*) '
    unless: 'fixed_resolution: recommended'
@@ -405,6 +417,8 @@ signatures:
    # "Name=XR_FB_scene SpecVersion=1", OVRPort's "overportOXR: - XR_FB_scene 1", Unity's 'Meta XR Feature: ...
    # Extensions="..."' (GitHub #404); XR_FB_scene_capture alone doesn't count either
    pattern: '(?m)^(?!.*(?:Unavailable OpenXR extension: |Name=|overportOXR: - |Extensions=")).*XR_FB_scene\b|XR_FB_spatial_entity.*(not supported|UNSUPPORTED)|xrQuerySpacesFB'
+    # FrameBridge serves the room (OVRPort still lists XR_FB_scene and the shim names xrQuerySpacesFB): no finding
+    unless: 'FrameBridge[^\r\n]*scene: emulation active'
    severity: warning
    diagnosis: The game wants Meta's room data (scene API), which the Frame lacks. The adapter can emulate a room from the guardian bounds.
    suggest: [adapter.scene_emul]
@@ -753,6 +753,63 @@ can be enabled and persist after restart. Check actual runtime refresh/pacing se
 identity alone does not implement refresh-rate support. Rebuild with Quest 2 for the control: original `Oculus Quest2`,
 original Quest 2 UUID, type 9 if logged, and previous option visibility. Also smoke-test a Unity OVRPlugin game
 with the default Quest 3 choice for regressions. No device access was used during implementation.
+
+## Mixed reality: scanned rooms
+
+Live floor coverage (agent v104) is enabled by default for manual and game-requested scans; the capture
+payload accepts `preview: false`, and `frameport frame room scan --no-preview` disables it. A world-locked,
+upward-facing 6 m square at floor height follows the current raw-to-STAGE calibration and stays centred on the
+scan's first recorded camera position. Every 16th depth vertex contributes to raw-space 10 cm voxels; at most once
+per second, newly occupied cells redraw a 256×256 RGBA map in one colour (FramePort's secondary blue), each cell a
+filled 10 cm square, only the opacity telling floor (<0.3 m, faint), raised surfaces (0.3–1.5 m) and tall surfaces
+(>1.5 m, strongest, the room's outline) apart; unseen transparent. Overlays have no depth (they draw over hands and
+passthrough), so the map stays faint; three colours in 3x3 blotches clashed in the owner's first run. It shows
+coverage, not a validated room boundary. IVROverlay_028 slots 1/3/20/22/33/43/62 (OpenVR 2.15.6 header)
+create/destroy/sort order (1, below the scan prompts' 10)/set width/set absolute STAGE transform/show/upload raw
+pixels. Each upload is 256 KiB (at most 256 KiB/s); timing for the first
+20 uploads and every tenth thereafter, plus failures, goes to `rooms/scans/scan-*.fprs.log` and the built room’s `scan.log`. Overlay errors or an
+upload taking over 50 ms disable the preview while capture continues; headset appearance and upload cost still
+need device validation.
+
+When an MR game asks for a room scan, FramePort scans in the headset and FrameBridge loads the new room before
+answering the game. If no scanner answers within five seconds, the game gets the stored room. Set
+`scene_scan_request=0` to always use the stored room. A scan that starts but fails keeps the old room and reports
+a capture failure to the game.
+
+**Mixed reality: scanned rooms (agent v92, 2026-10-16, branch mr-scene; docs/mr/):** Quest MR games read the room
+through Meta's scene APIs; the Frame offers none, and Valve's chaperone is no room (2D outline raised to 2.43 m, often
+the default 1 m circle -> the Android runtime's STAGE rect falls back to 1x1 m; XRService's plane detection is
+horizontal-only, its persistent map sparse ORB, its XRIPC single-client; cameras are XRService's alone,
+IVRTrackedCamera gives no frames). **The passthrough's RoomView 3D depth mesh is readable** (docs/mr/PHASE0.md:
+IVRBlockQueue_005 `/xrservice/roomview3d/meshData|meshLayout`, metadata through the C++ `IVRPaths_002` on the block
+handle, `meshIsUpToDate` on the queue handle; 132x128 fan, ~30/s; raw->standing moves during a session -> convert
+with the final one), so FramePort scans rooms itself: agent `room_capture` (Background/Overlay OpenVR app, prompts =
+artifacts/roomscan/*.png via IVROverlay_028 slots 1/3/20/22/35/43/44/63, `scripts/mr/render_prompts.py`) -> `.fprs`
+dump -> `fp_roomscan` (native/roomscan, freestanding, offline) -> `room.txt` + `room-mesh.bin`
+(docs/mr/ROOM_FORMAT.md; outline = positive shoelace in x-z, wall inward normal (-dz, dx)) in
+`~/.local/share/frameport/rooms/<universe>/`; launch.sh copies it next to settings.conf (`_room_sync`, games with
+`scene_emul`); FrameBridge (`scene_room.c/scene_meta.c/scene_anchors.c`) serves N walls, volumes (BOUNDED_3D),
+planes, GLOBAL_MESH (XR_META_spatial_entity_mesh), XR_META discovery/persistence (newer Meta SDKs and MRUK), anchors
+saved in `files/framebridge-anchors.txt`; all through xrshim (OVRPort's dispatcher drops unknown META calls).
+`scene_emul` is now suggested for every USE_SCENE/USE_ANCHOR_API game (migration `scene_emul_all`; NOPE and Pinball
+FX had none). PC: Frame page "Room" card, `frameport frame room scan|status|from-boundary|import|export|build|show`.
+Real data (owner's room, 2026-10-16): floor at 0, table surfaces, orthogonal walls found; the ceiling needs "look up".
+
+Scan on request (agent v103): scene-emulation launchers run `_scan_watch` alongside the game. FrameBridge's
+`framebridge-scan-request` in the game's external files directory gets an ack, then the existing prompted headset
+capture/build flow saves and copies the new room before an `ok` result; errors, cancellation and timeout return
+`failed`. Captures share a global lock, stale protocol files are cleared on launch, and the watcher stops with the
+launcher. Logs: `<base>/scan-watch.log`. Device validation is still required.
+
+PR #246 (@alicecatpaw, merged into mr-scene 2026-10-18): FrameBridge trims frames to maxLayerCount (Punch Fit sent
+21+ layers; projection layers and FrameBridge's fade quad always stay), drops quads with zero size or an empty image
+rect, and logs up to 10 quads with pose and swapchain. Two Unity patches, both only from a catalog recipe or the
+user's choice: `frame.meta_depth_occlusion` (Depth API occlusion off; Laser Dance's lasers vanished up close) and
+`frame.unity_scene_active_rooms` (OVRSceneManager's player-in-room check). The PR's own META discovery and boundary
+visibility code was replaced by this branch's (`scene_meta.c`). The PR's recipes were checked on the author's Frame
+only; open question: does OVRPort's dispatcher advertise XR_META_environment_depth (then a FrameBridge setting that
+hides it would fix depth occlusion for every engine).
+
 ## Vulkan pipelines refused: Fossilize and Turnip (Transformers, #349)

 Transformers Beyond Reality: Redux (Unreal, Vulkan) ended its first frames with Unreal's "Shader compilation failures
@@ -66,6 +66,53 @@
  `launch.sh` at the new folder and only then deletes the old copy; on the same filesystem it renames instead.
  Moving a game whose Lepton data holds absolute paths, or a PC VR prefix, is not yet verified on the device.

+## Room data
+
+Live floor coverage (agent v104) is enabled by default for manual and game-requested scans; the capture
+payload accepts `preview: false`, and `frameport frame room scan --no-preview` disables it. A world-locked,
+upward-facing 6 m square at floor height follows the current raw-to-STAGE calibration and stays centred on the
+scan's first recorded camera position. Every 16th depth vertex contributes to raw-space 10 cm voxels; at most once
+per second, newly occupied cells redraw a 256×256 RGBA map in one colour (FramePort's secondary blue), each cell a
+filled 10 cm square, only the opacity telling floor (<0.3 m, faint), raised surfaces (0.3–1.5 m) and tall surfaces
+(>1.5 m, strongest, the room's outline) apart; unseen transparent. Overlays have no depth (they draw over hands and
+passthrough), so the map stays faint; three colours in 3x3 blotches clashed in the owner's first run. It shows
+coverage, not a validated room boundary. IVROverlay_028 slots 1/3/20/22/33/43/62 (OpenVR 2.15.6 header)
+create/destroy/sort order (1, below the scan prompts' 10)/set width/set absolute STAGE transform/show/upload raw
+pixels. Each upload is 256 KiB (at most 256 KiB/s); timing for the first
+20 uploads and every tenth thereafter, plus failures, goes to `rooms/scans/scan-*.fprs.log` and the built room’s `scan.log`. Overlay errors or an
+upload taking over 50 ms disable the preview while capture continues; headset appearance and upload cost still
+need device validation.
+
+- SteamVR on the Frame has no Meta scene/anchor extensions. Its chaperone supplies only a 2D outline raised to
+  2.43 m, without furniture, ceiling or a room mesh. Valve's default boundary is a 20-point circle of roughly 1 m
+  radius; FramePort refuses to treat it as a room.
+- FrameBridge's `scene_emul=1` serves saved room data, with a guardian box when no room is available. OVRPort's
+  loader only dispatches functions in its own table: newer Meta entry points go through FramePort's extension shim.
+  MRUK uses discovery (`xrDiscoverSpacesMETA`, older versions `xrQuerySpacesFB`) and requests Space Setup when
+  discovery returns no rooms. Volumes hang below their top-face anchor in Meta's coordinate convention.
+- Room files use STAGE coordinates (metres, +Y up, floor y=0, -Z forward). The format contract is
+  [mr/ROOM_FORMAT.md](mr/ROOM_FORMAT.md). On the Frame: `~/.local/share/frameport/rooms/<universe>/room.txt`,
+  optional `room-mesh.bin` and `scan.log`; `rooms/current` points to the most recently saved room.
+- A room belongs to its chaperone universe. The agent reads the last universe switch from `vrserver.txt`, falling
+  back to the newest universe in `~/.config/openvr/config/chaperone_info.vrchap`; dummy 424242 means none.
+  A matching room is selected first, else `current`; the app reports `aligned: false` after a universe change.
+- Quest launchers copy that room beside `settings.conf` before Lepton starts; FrameBridge reads
+  `dirname($FRAMEBRIDGE_CONFIG)/room.txt`. Stale copies are removed if no room exists or emulation is disabled.
+  Each game's persistent anchors stay in `/sdcard/Android/data/<pkg>/files/framebridge-anchors.txt`.
+- With `scene_emul`, launch.sh starts `_scan_watch <pkg>` after Lepton, closing fd 9; its exit trap stops the
+  watcher, which also exits if the launcher disappears. It polls once a second and logs to `<base>/scan-watch.log`.
+  In `<base>/lepton-data/external/Android/data/<pkg>/files/`, FrameBridge writes `framebridge-scan-request`
+  (`request <id> <unix_seconds>`); the watcher clears stale request/ack/result files at startup, writes
+  `framebridge-scan-ack` (`ack <id>`), reuses the headset capture/build worker, stores the current room and copies
+  it beside settings.conf before atomically writing `framebridge-scan-result` (`ok <id>` or `failed <id> <reason>`).
+  A global `rooms/.scan.lock` excludes concurrent captures, including manual scans; `rooms/.lock` still protects
+  room publication. Launcher exit cancels the scan; a 350-second deadline leaves time for the six-minute protocol timeout.
+- Frame → Room and `frameport frame room` manage rooms. `from-boundary` creates walls without furniture;
+  `import` / `export` transfer room files; `show` writes an SVG preview; `build <dump.fprs>` syncs the bundled
+  `fp_roomscan` by SHA-256 and runs it on the Frame with `--offline`. `scan` = agent `room_capture`: records the
+  RoomView meshes (`/xrservice/roomview3d/meshData` + `/meshLayout`, `IVRBlockQueue_005`) while in-headset prompts
+  guide the player, then builds the room from that recording.
+
 ## Save backups (Quest games, agent v101, discussion #352)
 - A Lepton game's saves are two folders of `<base>/lepton-data`: `internal/<pkg>` (= `/data/data/<pkg>`:
  `shared_prefs/`, `files/`, `databases/`; Unreal's `files/UE4Game|UnrealGame/.../Saved` often lives here) and
@@ -67,6 +67,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Gravity Lab | Quest | ✅ Works |  |
 | Gunjack | Quest | ✅ Works |  |
 | H.U.N.T | Quest | ✅ Works |  |
+| Hitstream | Quest | ✅ Works |  |
 | I Am Cat | Quest | ✅ Works |  |
 | I Am Monkey | Quest | ✅ Works |  |
 | I Expect You To Die 2 | Quest | ✅ Works |  |
@@ -81,6 +82,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | KillerFrequency | Quest | ✅ Works |  |
 | Ladder | Quest | ✅ Works |  |
 | Lambda1VR | Quest | ✅ Works |  |
+| Laser Dance | Quest | ✅ Works |  |
 | LEGO® Bricktales | Quest | ✅ Works |  |
 | Lost Recipes | Quest | ✅ Works |  |
 | Lucky's Tale | Quest | ✅ Works |  |
@@ -109,6 +111,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Pistol Whip | PC VR | ✅ Works |  |
 | Please Don't Touch Anything | Quest | ✅ Works |  |
 | PowerWash Simulator VR | Quest | ✅ Works |  |
+| Punch Fit | Quest | ✅ Works |  |
 | QuestCraft | Quest | ✅ Works |  |
 | Racket: Nx | Quest | ✅ Works |  |
 | RacketPinball | Quest | ✅ Works |  |
@@ -146,6 +149,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Taskmaster | Quest | ✅ Works |  |
 | Tea For God | Quest | ✅ Works |  |
 | Test Quest Controllers | Quest | ✅ Works |  |
+| Test Quest MR | Quest | ✅ Works |  |
 | TetrisEffect | Quest | ✅ Works |  |
 | The Boys VR | Quest | ✅ Works |  |
 | The Climb | Quest | ✅ Works |  |
@@ -194,7 +198,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Majora's Mask VR | Quest | ⚠️ Works with issues | Audio on the file select screen sounds crunchy. |
 | Myst | Quest | ⚠️ Works with issues | Minor graphical glitches on some objects. |
 | Phantom: Covert Ops | Quest | ⚠️ Works with issues | DLC/store button crashes (no Meta store). |
-| Pinball FX VR | Quest | ⚠️ Works with issues | Plays; mixed reality mode not working yet. |
+| Pinball FX VR | Quest | ⚠️ Works with issues | Plays; space warp off (fewer stutters). |
 | Plezy | Quest | ⚠️ Works with issues | Some videos play with strong artifacts and wrong colours; the cause is unknown, possibly hardware video decoding. |
 | Puzzling Places | Quest | ⚠️ Works with issues | Works fine, but pointers dont show well on main menu, easy to work around. |
 | Quantum Void | Quest | ⚠️ Works with issues | no hands |
@@ -183,6 +183,29 @@ Website owners: see [Install button](INSTALL_BUTTON.md).
  so stop it when you're done.
 - **Screenshots** shows the screenshots you took in the headset, sorted by game and day, to view or download.

+## Your room (mixed reality, experimental)
+
+Mixed-reality games ask for your room: walls, furniture and its surfaces. **Room** (in the sidebar) keeps it:
+
+- **Scan room in the headset**, then put the headset on with passthrough and look around for about a minute; the tab
+  shows how far the scan is. **Cancel scan** stops it and keeps your saved room. **Use my play area** makes walls from
+  the SteamVR play area instead (no furniture).
+- The room shows in 3D: drag to turn it, scroll to zoom, right-drag to move it, double-click to see all of it.
+  **Open full 3D view** shows every detail of the scan in your browser (a page on this PC only).
+- **Clean-up** tidies every scan (flat walls, no scan behind walls or where you walked, no loose bits). The
+  recommended settings suit most rooms; change them (**More settings** has all of them) and press **Apply** to clean
+  up your saved scan again. Your settings are also used for your next scans.
+- **Labels** shows what the scanner's boxes became and why. A tall, thin box by a wall can be **Add as door** or
+  **Add as closet**.
+- **Furniture & screens**: pick a box in the list or click it in the 3D view to change its type, place or size, add
+  or delete boxes, and add doors and windows on a wall. **Save** sends them to the Frame; they stay when you clean up
+  the scan again (**Back to the scan's boxes** under Labels drops them).
+- The free **Test Quest MR** app (Get Test Quest MR on the tab) shows what a game receives from your scan.
+
+![Room](images/room.png)
+
+![Room: a box picked to edit, and the labels of the clean-up](images/room-editing.png)
+
 ## Updating

 FramePort checks for a new version at start and every 6 hours. When there is one, the Library shows **Update now**:
@@ -2,7 +2,7 @@

 # Patches

-Every patch and game setting FramePort knows: 190 entries in 5 groups. A game's recipe is its chosen patches and settings; tested games get theirs from the catalog ([GAMES.md](GAMES.md)), and other games get the patches FramePort suggests from its analysis. You change them on the game page under Customize.
+Every patch and game setting FramePort knows: 194 entries in 5 groups. A game's recipe is its chosen patches and settings; tested games get theirs from the catalog ([GAMES.md](GAMES.md)), and other games get the patches FramePort suggests from its analysis. You change them on the game page under Customize.

 Each entry says what the patch does, whether it changes the APK or only the install, when FramePort suggests it, its options, the catalog games whose recipe names it and the launch-test signatures that suggest it. Patches that are on by default are on for every game, so the catalog rarely names them.

@@ -11,8 +11,8 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 ## Groups

 - [Patches from OVRPort](#group-overport) (25)
- [Steam Frame patches](#group-frame) (63)
- [Game settings](#group-adapter) (79)
+- [Steam Frame patches](#group-frame) (65)
+- [Game settings](#group-adapter) (81)
 - [Files and settings on the Frame](#group-device) (10)
 - [PC VR (Proton and Revive)](#group-pcvr) (13)

@@ -64,7 +64,8 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [GL wrapper: OpenGL ES depth formats (Minecraft)](#frame-ltw_depth) | `frame.ltw_depth` | Steam Frame patches | default |
 | [Fix Lua startup crashes on Frame](#frame-luajit_pointers) | `frame.luajit_pointers` | Steam Frame patches | 1 |
 | [Start the game in the app's main process](#frame-main_process) | `frame.main_process` | Steam Frame patches | default |
-| [Declare Meta-only permissions](#frame-meta_permissions) | `frame.meta_permissions` | Steam Frame patches | 5 |
+| [Unity: disable Meta depth occlusion](#frame-meta_depth_occlusion) | `frame.meta_depth_occlusion` | Steam Frame patches | 1 |
+| [Declare Meta-only permissions](#frame-meta_permissions) | `frame.meta_permissions` | Steam Frame patches | 7 |
 | [Meta XR Audio: skip Quest telemetry class](#frame-metaxr_telemetry) | `frame.metaxr_telemetry` | Steam Frame patches | default |
 | [Clear android:debuggable](#frame-nodebug) | `frame.nodebug` | Steam Frame patches | 3 |
 | [Oculus OS telemetry class stubs](#frame-oculusos) | `frame.oculusos` | Steam Frame patches | 17 |
@@ -88,7 +89,8 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Unity: skip OVROverlay layers (fades, splash screens)](#frame-unity_no_overlay_copy) | `frame.unity_no_overlay_copy` | Steam Frame patches | 2 |
 | [Unity: start VR without Meta's system apps](#frame-unity_oculus_check) | `frame.unity_oculus_check` | Steam Frame patches | 14 |
 | [Unity: keep MSAA off at runtime (OVRManager)](#frame-unity_runtime_msaa_off) | `frame.unity_runtime_msaa_off` | Steam Frame patches | 33 |
-| [Make Unity text fields work](#frame-unity_text_input) | `frame.unity_text_input` | Steam Frame patches | 119 |
+| [Unity: skip Meta's player-in-room check](#frame-unity_scene_active_rooms) | `frame.unity_scene_active_rooms` | Steam Frame patches | 1 |
+| [Make Unity text fields work](#frame-unity_text_input) | `frame.unity_text_input` | Steam Frame patches | 122 |
 | [Unity: share thread keys (games that run out of them)](#frame-unity_tls_key_pool) | `frame.unity_tls_key_pool` | Steam Frame patches | 1 |
 | [Unity: headset always counts as worn](#frame-unity_user_presence) | `frame.unity_user_presence` | Steam Frame patches | 1 |
 | [GL shim for Unreal (no multisampled render-to-texture)](#frame-unreal_gl_shim) | `frame.unreal_gl_shim` | Steam Frame patches | 1 |
@@ -113,8 +115,8 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Pointer angle](#adapter-aim_pitch) | `adapter.aim_pitch` | Game settings |  |
 | [Pointer turn](#adapter-aim_yaw) | `adapter.aim_yaw` | Game settings |  |
 | [Fix inside-out mixed reality](#adapter-alpha_blend_emul) | `adapter.alpha_blend_emul` | Game settings |  |
-| [Use controllers](#adapter-controller_fix) | `adapter.controller_fix` | Game settings | 1 |
-| [Show Steam Frame controllers](#adapter-controller_models) | `adapter.controller_models` | Game settings | 6 |
+| [Use controllers](#adapter-controller_fix) | `adapter.controller_fix` | Game settings | 2 |
+| [Show Steam Frame controllers](#adapter-controller_models) | `adapter.controller_models` | Game settings | 7 |
 | [Show cube loading screens](#adapter-cube_quads) | `adapter.cube_quads` | Game settings |  |
 | [Stand in for cube layers](#adapter-cube_standin) | `adapter.cube_standin` | Game settings |  |
 | [Show curved menus and screens](#adapter-cylinder_strips) | `adapter.cylinder_strips` | Game settings |  |
@@ -140,7 +142,7 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [GL shim: high-precision vertex shaders](#adapter-gl_highp_markers) | `adapter.gl_highp_markers` | Game settings | 1 |
 | [GL shim: integer vertex inputs](#adapter-gl_int_attribs) | `adapter.gl_int_attribs` | Game settings | 1 |
 | [Flat panel diagnostics (log)](#adapter-gl_mv_debug) | `adapter.gl_mv_debug` | Game settings |  |
-| [Fix freezes when controllers vibrate](#adapter-haptic_fix) | `adapter.haptic_fix` | Game settings | 104 |
+| [Fix freezes when controllers vibrate](#adapter-haptic_fix) | `adapter.haptic_fix` | Game settings | 107 |
 | [Vibration strength](#adapter-haptic_scale) | `adapter.haptic_scale` | Game settings |  |
 | [Turn off Quest Vulkan foveation](#adapter-hide_fb_foveation) | `adapter.hide_fb_foveation` | Game settings |  |
 | [Turn off space warp](#adapter-hide_space_warp) | `adapter.hide_space_warp` | Game settings | 5 |
@@ -150,10 +152,10 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Vulkan format workaround](#adapter-mutable_fix) | `adapter.mutable_fix` | Game settings |  |
 | [Unity frame loop: wait for skipped frames](#adapter-ovrp_begin_gate) | `adapter.ovrp_begin_gate` | Game settings | 1 |
 | [Steadier hands (older Unity)](#adapter-ovrp_hold_physics) | `adapter.ovrp_hold_physics` | Game settings | 1 |
-| [See your room](#adapter-passthrough_emul) | `adapter.passthrough_emul` | Game settings |  |
+| [See your room](#adapter-passthrough_emul) | `adapter.passthrough_emul` | Game settings | 2 |
 | [Steadier head tracking](#adapter-pose_consistency) | `adapter.pose_consistency` | Game settings | 2 |
 | [Pose timing diagnostics (log)](#adapter-pose_debug) | `adapter.pose_debug` | Game settings |  |
-| [Fix hands lagging behind controllers](#adapter-pose_time_fix) | `adapter.pose_time_fix` | Game settings | 16 |
+| [Fix hands lagging behind controllers](#adapter-pose_time_fix) | `adapter.pose_time_fix` | Game settings | 17 |
 | [Treat newer Quest controllers as Touch](#adapter-profile_remap) | `adapter.profile_remap` | Game settings |  |
 | [Animate fingers from touch](#adapter-proximity_emul) | `adapter.proximity_emul` | Game settings |  |
 | [Controller buttons](#adapter-quest_buttons) | `adapter.quest_buttons` | Game settings |  |
@@ -163,8 +165,10 @@ Link to an entry with its id, dots replaced by dashes: `PATCHES.md#frame-unity_t
 | [Re-create play space](#adapter-respace_kick) | `adapter.respace_kick` | Game settings |  |
 | [Render resolution (supersampling)](#adapter-scale) | `adapter.scale` | Game settings | 15 |
 | [Room depth](#adapter-scene_depth) | `adapter.scene_depth` | Game settings |  |
-| [Pretend room layout](#adapter-scene_emul) | `adapter.scene_emul` | Game settings | 14 |
+| [Use room layout](#adapter-scene_emul) | `adapter.scene_emul` | Game settings | 18 |
 | [Room height](#adapter-scene_height) | `adapter.scene_height` | Game settings |  |
+| [Hide play-area size](#adapter-scene_hide_bounds) | `adapter.scene_hide_bounds` | Game settings | 1 |
+| [Scan when requested](#adapter-scene_scan_request) | `adapter.scene_scan_request` | Game settings |  |
 | [Room width](#adapter-scene_width) | `adapter.scene_width` | Game settings |  |
 | [Eye-image snapshots (diagnostics)](#adapter-snapshot) | `adapter.snapshot` | Game settings |  |
 | [Keep menus in place](#adapter-stable_local) | `adapter.stable_local` | Game settings | 1 |
@@ -763,6 +767,18 @@ Keeps the game from being closed about a minute after it starts (it runs in a se

 > Some apps run their game activity in a process of its own (android:process, e.g. Halo CE VR's ":halo_game"), started from a 2D launcher activity. Lepton starts the game activity directly and watches only the app's main process, which then never exists: about a minute in, Lepton decides the app "did not start" and closes it, at whatever point the game has reached. This runs those activities in the main process (only their android:process value changes).

+### <a id="frame-meta_depth_occlusion"></a>Unity: disable Meta depth occlusion
+
+Keeps objects visible up close in mixed-reality games that would hide them behind your room using Meta's depth sensor, which the Frame lacks (for example Laser Dance).
+
+- `frame.meta_depth_occlusion`
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Offered (off):** Uses Meta's Depth API occlusion (HARD_OCCLUSION / SOFT_OCCLUSION): turn on if objects vanish when you come close to them.
+- **Catalog games (1):** Laser Dance.
+- **Source:** [patches/frame/meta_depth_occlusion.py](../src/frameport/patches/frame/meta_depth_occlusion.py)
+
+> The Frame has no depth sensor (XR_META_environment_depth), so the environment depth Meta's Depth API reads is never valid. Shaders using it then hide virtual objects near the player behind a room that isn't there (for example Laser Dance's lasers vanish when approached). Rewrites EnvironmentDepthManager's support/availability checks and its occlusion-keyword setter in libil2cpp.so (found with Cpp2IL), and renames the HARD_OCCLUSION / SOFT_OCCLUSION shader keywords in the game's asset files that contain them, so occlusion is never turned on. For Laser Dance's known build it also keeps the laser beams' materials and close-range LODs visible. Only for games with this symptom.
+
 ### <a id="frame-meta_permissions"></a>Declare Meta-only permissions

 Declares Meta's permissions some mixed-reality games ask for, so they don't stop.
@@ -770,7 +786,8 @@ Declares Meta's permissions some mixed-reality games ask for, so they don't stop
 - `frame.meta_permissions`
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Mixed-reality game that needs the room model: its 'use spatial data' permission must be granted (for example Demeter).
- **Catalog games (5):** Arkio, BattleTalent, Demeter, Real VR Fishing, Test Quest MR.
+- **Suggested (on):** Uses Meta's room or anchor APIs: their permissions must be granted, or the game never asks for the room (for example NOPE's MR mode).
+- **Catalog games (7):** Arkio, BattleTalent, Demeter, Laser Dance, Punch Fit, Real VR Fishing, Test Quest MR.
 - **Source:** [patches/frame/manifest_fixes.py](../src/frameport/patches/frame/manifest_fixes.py)

 > Declares com.oculus.permission.* / horizonos.permission.* that the app uses, so Android grants them at install (for example the 'use spatial data' permission of mixed-reality games like Demeter).
@@ -1089,6 +1106,18 @@ Keeps a smoothing setting off that the game turns on itself and that can freeze

 > Meta's OVRManager switches Unity to the headset's recommended MSAA level (4x) while the game runs, whatever its quality settings say (log: "Switching to the recommended level"). Multisampled render-to-texture on GLES can hang the Frame's GPU, up to a restart of the whole headset (for example Lucky's Tale in a menu) or a crash of its GL driver (for example The Room VR, whose own code sets 4x). Rewrites OVRDisplay.recommendedMSAALevel -&gt; 0 and makes QualitySettings.antiAliasing's setter do nothing in libil2cpp.so (found with Cpp2IL), so MSAA stays off.

+### <a id="frame-unity_scene_active_rooms"></a>Unity: skip Meta's player-in-room check
+
+Lets a mixed-reality game load the room even if it thinks you stand outside it (for example Laser Dance asking again and again to scan your room).
+
+- `frame.unity_scene_active_rooms`
+- **Changes:** Changes the APK (a rebuild and reinstall apply it).
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Catalog games (1):** Laser Dance.
+- **Source:** [patches/frame/unity_runtime.py](../src/frameport/patches/frame/unity_runtime.py)
+
+> Meta's OVRSceneManager (ActiveRoomsOnly) loads only the room whose floor outline contains the player (IsUserInRoom). If the player is outside the emulated room's floor, loading stops with 'No scene model found' (for example Laser Dance with the play-area room). Rewrites OVRSceneManager.IsUserInRoom and PointInPolygon2D -&gt; true in libil2cpp.so (found with Cpp2IL), so the room loads wherever the player stands. Only for games with this symptom: a scanned room around the player usually passes the check by itself.
+
 ### <a id="frame-unity_text_input"></a>Make Unity text fields work

 Lets you type into this app's text fields on the Frame (they'd close at once).
@@ -1096,7 +1125,7 @@ Lets you type into this app's text fields on the Frame (they'd close at once).
 - `frame.unity_text_input` · also for 2D apps
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Unity app with text fields (…): they close at once on the Frame because it has no system keyboard.
- **Catalog games (119):** AgeOfJoy, AllInOneSports, Ancient_Dungeon, Arcsmith, Arkio, Assassin's Creed Nexus, Attack on Titan VR: Unbreakable, Audica and 111 more.
+- **Catalog games (122):** AgeOfJoy, AllInOneSports, Ancient_Dungeon, Arcsmith, Arkio, Assassin's Creed Nexus, Attack on Titan VR: Unbreakable, Audica and 114 more.
 - **Source:** [patches/frame/unity_text_input.py](../src/frameport/patches/frame/unity_text_input.py)

 > Unity's TMP_InputField / InputField wait for Android's on-screen keyboard and close themselves a frame later when there is none (Lepton has no on-screen keyboard; Meta's system keyboard does this on a Quest), so a selected text field only flashes a caret. Rewrites TouchScreenKeyboardShouldBeUsed -&gt; false and isKeyboardUsingEvents (TMP) / InPlaceEditing (uGUI) -&gt; true in libil2cpp.so, found per game with Cpp2IL (downloaded on first use), so fields stay selected and take key presses: Steam's keyboard (with "Show the app window") or Type on Frame from the PC.
@@ -1441,7 +1470,7 @@ Turn off only for games you play with your hands instead of controllers.
 - **Options:**
  - Value: int, default `1` (always written).
  - Game settings → Controllers → "Use controllers".
- **Catalog games (1):** Silhouette.
+- **Catalog games (2):** Laser Dance, Silhouette.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)

 > Reports Frame controllers as Oculus Touch and hides synthetic hand tracking. Set 0 for games that require hand tracking (for example Silhouette).
@@ -1456,7 +1485,7 @@ For games that show the headset's own controllers. Takes effect after a reinstal
 - **Options:**
  - Value: int, default `0`.
  - Game settings → Controllers → "Show Steam Frame controllers".
- **Catalog games (6):** Neko Atsume Purrfect, Ocean Rift, Real VR Fishing, SynthRiders, VR HOT Quest, Walkabout Mini Golf.
+- **Catalog games (7):** Hitstream, Neko Atsume Purrfect, Ocean Rift, Real VR Fishing, SynthRiders, VR HOT Quest, Walkabout Mini Golf.
 - **Suggested by launch-test signatures:**
  - `render-model-requested` (info): The game shows Quest controllers (or none) because the Frame doesn't provide controller models.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
@@ -1841,7 +1870,7 @@ For games that freeze the Frame when a controller vibrates (for example Lucky's
 - **Options:**
  - Value: int, default `0`.
  - Game settings → Controllers → "Fix freezes when controllers vibrate" (advanced).
- **Catalog games (104):** AgeOfJoy, Ancient_Dungeon, Attack on Titan VR: Unbreakable, Audica, AugmentedEmpire, Battlemarked, BattleSisters, BattleTalent and 96 more.
+- **Catalog games (107):** AgeOfJoy, Ancient_Dungeon, Attack on Titan VR: Unbreakable, Audica, AugmentedEmpire, Battlemarked, BattleSisters, BattleTalent and 99 more.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)

 > Routes OVRPlugin through FramePort's extension shim, which turns Meta's amplitude-envelope vibrations into plain ones: OVRPort's loader reads their nanosecond duration as seconds and allocates gigabytes, freezing the Frame when the game vibrates a controller (for example Lucky's Tale's save slots, GitHub #9). Needs a rebuild.
@@ -1989,6 +2018,7 @@ Shows the Frame's cameras where the game expects passthrough.
 - **Options:**
  - Value: int, default `1`.
  - Game settings → Mixed reality → "See your room".
+- **Catalog games (2):** Laser Dance, Punch Fit.
 - **Suggested by launch-test signatures:**
  - `passthrough-missing` (error): The game needs Meta passthrough (the camera view), which the Frame lacks; the adapter emulates it.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
@@ -2035,7 +2065,7 @@ For games whose hands trail the controllers when you move them (for example Batt
 - **Options:**
  - Value: int, default `0`.
  - Game settings → Controllers → "Fix hands lagging behind controllers" (advanced).
- **Catalog games (16):** Battlemarked, BattleSisters, Beat Saber, Dance Central, Dungeons of Eternity, Mini Motor Racing X, OrbusVR, Phantom: Covert Ops and 8 more.
+- **Catalog games (17):** Battlemarked, BattleSisters, Beat Saber, Dance Central, Dungeons of Eternity, Mini Motor Racing X, OrbusVR, Phantom: Covert Ops and 9 more.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)

 > Poses a game asks for at a CLOCK_MONOTONIC time, or more than 0.5 s before the frame's display time, are located at the same moment in the runtime's time (or now). Meta's OVRPlugin passes the monotonic clock on as the OpenXR time, which on the Frame runs seconds behind the runtime's clock, so its "now" poses (Unity's physics step, controller poses) came from the past: hands trailing the controllers (for example BattleSisters, Sniper Elite VR).
@@ -2168,23 +2198,23 @@ Changes the game's render resolution. Higher is sharper but slower; 1.0× is the

 > Override the guardian depth (0 = use guardian, min 1.5 m).

-### <a id="adapter-scene_emul"></a>Pretend room layout
+### <a id="adapter-scene_emul"></a>Use room layout

-Mixed-reality games that build their level from your room get a simple room with walls.
+Scene games get your saved room. Without one, they get a simple room from the play area.

 - `adapter.scene_emul`
 - **Changes:** Game setting: stored in the build and on the Frame (settings.conf); can be changed without a rebuild.
- **Suggested (on), value `1`:** Mixed-reality game that builds its level from the room model: emulate a guardian-sized room (for example Demeter).
- **Suggested (on), value `1`:** The game asks Meta's system for your room layout (scene), which the Frame doesn't have: emulate a room from the play area (for example VR HOT's room setup).
+- **Suggested (on), value `1`:** The game uses Meta's scene or spatial anchor APIs: serve the saved room on the Frame, or a simple play-area room until one is scanned.
 - **Options:**
  - Value: int, default `0`.
-  - Game settings → Mixed reality → "Pretend room layout".
- **Catalog games (14):** Arkio, AugmentedEmpire, Battlemarked, BattleTalent, cubism, Demeo, Demeter, Ghostbusters: Rise of the Ghost Lord and 6 more.
+  - Game settings → Mixed reality → "Use room layout".
+- **Catalog games (18):** Arkio, AugmentedEmpire, Battlemarked, BattleTalent, cubism, Demeo, Demeter, Ghostbusters: Rise of the Ghost Lord and 10 more.
 - **Suggested by launch-test signatures:**
+  - `mr-discovery-unsupported` (warning): The game cannot discover a Meta room.
  - `scene-missing` (warning): The game wants Meta's room data (scene API), which the Frame lacks.
 - **Source:** [patches/settings.py](../src/frameport/patches/settings.py)

-> Fake XR_FB_scene/spatial entities: a guardian-sized room with floor, ceiling and four walls, for mixed-reality games that build their level from the room (for example Demeter).
+> Serve Meta scene and spatial entity APIs from the saved room (walls, furniture and mesh). Without a saved room, use a simple play-area box (for example Demeter).

 ### <a id="adapter-scene_height"></a>Room height

@@ -2200,6 +2230,35 @@ Ceiling height of the pretend room.

 > Ceiling height for scene_emul.

+### <a id="adapter-scene_hide_bounds"></a>Hide play-area size
+
+For games that reject the room because of the play area.
+
+- `adapter.scene_hide_bounds`
+- **Changes:** Game setting: stored in the build and on the Frame (settings.conf); can be changed without a rebuild.
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Options:**
+  - Value: int, default `0`.
+  - Game settings → Mixed reality → "Hide play-area size" (advanced); shown while `adapter.scene_emul` is on.
+- **Catalog games (1):** Demeter.
+- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
+
+> With scene_emul, the game's play-area (STAGE bounds) query answers "no play area". The Frame reports a 1x1 m area whose outline OVRPlugin can't give, and some Unity MR games then fail their guardian check (for example Demeter). Off by default: other games stalled without a play area.
+
+### <a id="adapter-scene_scan_request"></a>Scan when requested
+
+Scan your room in the headset when the game asks for a room scan.
+
+- `adapter.scene_scan_request`
+- **Changes:** Game setting: stored in the build and on the Frame (settings.conf); can be changed without a rebuild.
+- **Suggested:** not automatically; set on the game page (Customize), by a recipe or after a launch test.
+- **Options:**
+  - Value: int, default `1`.
+  - Game settings → Mixed reality → "Scan when requested" (advanced); shown while `adapter.scene_emul` is on.
+- **Source:** [patches/settings.py](../src/frameport/patches/settings.py)
+
+> With scene_emul, let FramePort scan your room in the headset when the game requests a scan. If no scanner answers, use the saved room. Turn off to always use the saved room.
+
 ### <a id="adapter-scene_width"></a>Room width

 0 = the size of your play area.
@@ -202,7 +202,16 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Mixed reality inside out: the room shows on the game's objects, black where the room should be (Unreal, for example Star Wars: Beyond Victory, GitHub #329) | Unreal keeps 1 - coverage in the scene alpha and OVRPlugin chains XrCompositionLayerAlphaBlendFB (colour factors ONE_MINUS_SRC_ALPHA / SRC_ALPHA, `layer_debug` shows `n=1000041001(3,2/3,2)`) to the eye layer; the Frame's runtime ignores it | adapter `alpha_blend_emul=1` (default, Vulkan): inverts the alpha of the eye images in place while passthrough is emulated; logs `alpha_blend: inverting the alpha of swapchain=…` |
 | Quest Touch controllers (or none) shown in a game that uses Meta's runtime controller models | XR_FB_render_model missing on the Frame | adapter `controller_models=1`: the agent converts the Frame's SteamVR controller models to glb at install, the adapter serves them. Games with their own controller meshes aren't affected (none of the 34 catalog games use runtime models) |
 | `overportOXR: Unknown proc addr: xr…` for a function the adapter emulates | overport's dispatcher only forwards functions in its own table | route the plugin's lookups through `native/xrshim` (done for XR_FB_render_model when `controller_models=1`) |
-| MR game stuck waiting for room data (Demeter) | no Meta scene API | adapter `scene_emul=1` (+ `frame.meta_permissions`) |
+| MR game asks for a room scan | The game requested a new room through Meta scene capture | FramePort scans in the headset and loads the new room. `scene_scan_request=0` turns it off and uses the stored room. |
+| MR game stuck waiting for room data (e.g. Demeter) | No Meta scene API | `adapter.scene_emul=1` (+ `frame.meta_permissions`); Frame → Room → Use my play area, or import a scanned room |
+| Unity MR game rejects every room / its "use guardian" fallback does nothing; `ovrpBoundary_Outer is not supported`, `IndexOutOfRangeException` in a guardian check (e.g. Demeter's `RemoveObjectNotInGuardian`) | OVRPlugin calls the Frame's 1x1 m STAGE rect a configured boundary but can't give its outline | `adapter.scene_hide_bounds=1` (with `scene_emul`): FrameBridge then answers the app's STAGE `xrGetReferenceSpaceBoundsRect` with `XR_SPACE_BOUNDS_UNAVAILABLE` (log `scene: STAGE bounds hidden`). Per game only: NOPE stalled without a play area. Demeter also needs a floor of at least 2.5 x 2.5 m, as on a Quest |
+| MR game with `scene_emul` never asks for the room (no `scene: query`/`discovery` lines), black screen or MR mode with no room (e.g. NOPE, Pinball FX); `m_XR_META_boundary_visibility extension is not supported` every frame | Meta's scene/anchor permissions undeclared (Lepton can't grant them); boundary suppression unsupported | `frame.meta_permissions` (now with every `scene_emul` recipe of a USE_SCENE/USE_ANCHOR_API game, migration `scene_permissions`); FrameBridge emulates `XR_META_boundary_visibility` (log `scene: boundary suppressed`). `passthrough:` lines show the app's passthrough calls |
+| Build says `Unity text fields: not fixed: Cpp2IL couldn't start on this PC` (older versions: `Cpp2IL couldn't read this game's code: at Cpp2IL.Program.Main`) | .NET aborts without libicu (fresh WSL/Linux) | FramePort runs Cpp2IL with `DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1`; such failures aren't cached, so the next build retries |
+| MR uses an empty/simple room; FrameBridge `scene: capture requested -> guardian box` / `using guardian room`, `room from guardian`, or fallback box dimensions (`mr-no-room`) | No saved room, so FrameBridge uses its guardian box | Save a room in Frame → Room. A real SteamVR boundary supplies walls; Valve's default circle is refused. Import a scanner-built room for furniture/mesh; headset capture is not implemented yet |
+| `Unknown proc addr: xrDiscoverSpacesMETA` or MRUK `NoRoomsFound` (`mr-discovery-unsupported`) | Scene discovery is unavailable or no room was discovered | Enable `adapter.scene_emul`, rebuild/reinstall to get the updated extension shim, then save a room. All games declaring USE_SCENE or USE_ANCHOR_API now get this suggestion |
+| MR game: virtual objects (e.g. Laser Dance's lasers) vanish when you come close to them | Meta's Depth API occlusion: the Frame has no depth sensor (XR_META_environment_depth), so the environment depth the occlusion shaders read is never valid and near objects count as hidden behind the room | `frame.meta_depth_occlusion` (Unity IL2CPP; offered, not turned on, when the game has the HARD_OCCLUSION / SOFT_OCCLUSION keywords; analysis `meta_depth_occlusion`): EnvironmentDepthManager's checks -> false and its keyword setter does nothing (Cpp2IL), the keywords renamed in the asset files that contain them; Laser Dance's known build also gets its laser materials/LODs fixed. From PR #246; not checked in the owner's headset yet |
+| Unity MR game keeps asking for a room scan / `No scene model found` although FrameBridge served a room (OVRSceneManager with ActiveRoomsOnly) | OVRSceneManager loads only the room whose floor outline contains the player (IsUserInRoom); with the play-area room the player can stand outside it (FrameBridge logs the head against the floor outline: `scene: head in STAGE ... OUTSIDE the floor outline`) | Scan the room first (Frame → Room). Still stuck: `frame.unity_scene_active_rooms` (catalog or by hand, Unity IL2CPP scene games): IsUserInRoom / PointInPolygon2D -> true (Cpp2IL). From PR #246 (Laser Dance) |
+| MR game with many quads (21+): frames refused with `XR_ERROR_LAYER_LIMIT_EXCEEDED` (e.g. Punch Fit) | The runtime takes at most maxLayerCount (16) layers | FrameBridge keeps the projection layers and its own fade quad, then the app's other layers in submission order up to the limit (log `xrEndFrame: N layers exceed the runtime limit 16`). From PR #246 |
 | Hand-tracking game janky (Silhouette) | Frame synthesizes hands from controllers | `controller_fix=0` passes hands through; not really fixable |
 | Eye distortion while moving (Arcsmith, Time Stall) | unknown (not eye swap, tracking, Valve layers, depth or pacing) | unresolved |
 | The Climb 666.0: hand outlines ripple in both eyes while menus and gameplay work (GitHub #238) | Unknown. Sessions paced around 72 fps, controller tracking reported valid, and SteamVR motion smoothing was already off; these checks do not establish the cause | Unresolved after wearer comparisons on 2026-10-12: disabling Valve's Vulkan layers, setting `r_AntialiasingMode = 1`, and setting `r_AntialiasingMode = 0` with `r_MotionBlur = 0` each gave the same or worse result. These were config comparisons; runtime cvar values were not verified. Restored the playable configuration (`r_vr_foveated = 0` with the default Vulkan layers), retaining the startup/rendering crash fixes above. Do not keep the unsuccessful experimental settings as a fix |
@@ -117,6 +117,10 @@ Hooks (`steps.HOOKS`) cover what a real Frame would do:
 - `pairing_done`: the Frame ran the setup command, so FramePort connects.
 - `live_stream`: a test picture through the real relay.
 - `monitor_details`, `type_tab`, `select_files` and `settings_section`.
+- `open_room` (the Room tab with the pretend Frame's room drawn) and `room_editing` (its editing cards: `cleanup`,
+  `more`, `box`, `doors`, `suggestion`). The room is a made-up bedroom built in code (`fakes.fake_room`, never a real
+  scan): a bed under a wall-mounted TV, a desk with two monitors under a window, a closet, a door, a lamp and a plant,
+  with a noisy scanned-surface mesh and a clean-up report and labels that match it.

 In a video, clicking Install runs the scripted install, and the game is then installed on the pretend Frame.

@@ -0,0 +1,49 @@
+# Phase 0: reading Valve's RoomView 3D mesh (dev Frame, SteamOS 0.4.5 build 20261007, 2026-10-16)
+
+Result: **a third-party OpenVR client can read the passthrough depth mesh, and it carries enough of the room for
+a scan** (floor, table-height surfaces, orthogonal walls; the ceiling only weakly).
+
+## Access
+- Background OpenVR app (`VR_InitInternal2(..., VRApplication_Background)`, never starts SteamVR) through
+  `/opt/steamvr/bin/linuxarm64/libopenvr_api.so`.
+- `FnTable:IVRBlockQueue_005`: `Connect("/xrservice/roomview3d/meshData")` and `.../meshLayout` work (created by
+  Valve's cv driver; no exclusivity seen next to the compositor's own reader). Read with
+  `WaitAndAcquireReadOnlyBlock(queue, &block, &buffer, EBlockQueueReadType_New, timeout_ms)` + `ReleaseReadOnlyBlock`.
+- Metadata through the C++ interface `IVRPaths_002` (vtable slot 0 `ReadPathBatch(root, PathRead_t*, n)`, slot 2
+  `StringToHandle(&handle, path)`; `FnTable:IVRPaths_001` doesn't exist), root = the **block** handle, except
+  `/meshData/meshIsUpToDate` which is a property of the **queue** handle:
+
+| path | tag | meaning |
+|---|---|---|
+| `/meshLayout/layoutId` | 3 (u64) | id of the index layout (static while the mesh resolution stays) |
+| `/meshLayout/vertexCount` | 2 (i32) | 16896 = 132 x 128 |
+| `/meshLayout/indexCount` | 2 | 99822 (u32 triangle indices into the grid, row width 132) |
+| `/meshData/meshId` | 3 | frame counter (~30 per second while passthrough runs) |
+| `/meshData/layoutId` | 3 | matches the layout block |
+| `/meshData/elementCount` | 2 | floats in the data block (vertexCount x 3) |
+| `/meshData/rawFromMeshPose` | 20 (HmdMatrix34) | mesh -> SteamVR raw tracking space |
+| `/meshData/posePredictionBaseTime` | 7 (f64) | seconds (system uptime clock) |
+| `/meshData/meshIsUpToDate` (queue) | 4 (bool) | false in standby / headset off |
+
+- STAGE (= standing universe) = `IVRSystem_023` vtable slot 13 `GetRawZeroPoseToStandingAbsoluteTrackingPose()` x
+  rawFromMeshPose. Check: the mesh origin is 6.7 cm from `GetDeviceToAbsoluteTrackingPose(Standing)`'s head
+  position in every frame (camera vs head centre). **The raw->standing transform changes during a session** (its
+  height went 1.60 -> 1.07 m while recording: Valve's floor estimate) -> capture raw poses and convert all frames
+  with the transform at the end of the capture.
+
+## The mesh
+- A fixed fan of view directions, +Z forward, rows top->bottom (row 0 = up in the image, -Y), ~126 deg across the
+  corners (corner directions ~(+-0.67, +-0.66, 0.34)); one depth per grid point. Not head-locked in world terms:
+  its pose is the passthrough camera pose at capture.
+- Range: reliable ~0.3-4 m; far values are inpainted (up to ~10 m) -> drop > 4 m. Strongly smoothed (soft edges,
+  small objects lost); locally planar: plane-fit residual of 12x12 patches median 5-17 mm.
+- First frames after tracking starts can have NaN poses -> skip non-finite frames.
+- Fused normals (60 s of looking around, ~3 frames/s used): floor clearly at y ~= 0, a table-height surface at
+  0.7 m, a lower one at 0.5 m; vertical surfaces in two orientation clusters ~85 deg apart (orthogonal walls), wall
+  offsets readable; ceiling: few down-facing points (people rarely look straight up; prompt for it).
+- Data rate: 16896 x 12 B vertices + 99822 x 4 B indices per frame (the dump repeats the indices per frame).
+
+## Consequences for the design
+- Capture = stdlib Python on the Frame (ctypes), as above; the C scanner works offline on the dump.
+- Scanner input quality: smooth, noisy at depth discontinuities; walls/floor via normals + RANSAC are robust;
+  furniture only as coarse boxes; ceiling needs a guided "look up" step, else the default height.
@@ -0,0 +1,113 @@
+# FramePort room files (mixed reality)
+
+Quest MR games read a room model (floor, ceiling, walls, furniture, a global mesh) through Meta's scene APIs. The
+Steam Frame has no such data for apps (see docs/FRAME_RUNTIME.md "Room data"), so FramePort scans the room itself
+(`fp_roomscan`) and FrameBridge (`native/adapter/scene_emu.c`) serves it to games. This file is the contract between
+the scanner, the Frame agent, the PC app and FrameBridge.
+
+## Coordinates
+- Everything is in **STAGE space** = SteamVR's standing universe = OpenXR `XR_REFERENCE_SPACE_TYPE_STAGE`:
+  metres, right-handed, +Y up, floor at y = 0, -Z = the universe's forward.
+- A room belongs to one chaperone universe (`universe` line). The Frame sometimes starts a new universe without
+  relocalizing; then the stored room may be misaligned (the agent reports `aligned: false`, nothing breaks).
+
+## room.txt (UTF-8 text, one record per line, `#` starts a comment, fields separated by spaces)
+```
+frameport-room 1                    # magic + format version (required, first line)
+universe <decimal u64>              # chaperone universe id the room was scanned in (0 = unknown)
+source scan|boundary|box|manual     # how it was made
+time <unix seconds>
+room <uuid>                         # the room anchor
+floor <uuid> <y>                    # floor height (normally 0)
+ceiling <uuid> <y>                  # ceiling height
+outline <n> x0 z0 x1 z1 ... x(n-1) z(n-1)
+                                    # floor polygon, n >= 3, not closed, POSITIVE signed area:
+                                    # sum(x[i]*z[i+1] - x[i+1]*z[i]) > 0 (turning from +X towards +Z; seen from
+                                    # above with -Z forward that is clockwise). Readers reverse a negative outline.
+wall <uuid> x0 z0 x1 z1 <y0> <y1> [LABEL]
+                                    # one wall face from (x0,z0) to (x1,z1), bottom y0, top y1.
+                                    # Its normal points INTO the room: walls follow the outline's order, and the
+                                    # inward normal is (-dz, dx)/|d| for d = (x1-x0, z1-z0).
+                                    # LABEL (optional, default WALL_FACE): INVISIBLE_WALL_FACE for an edge the
+                                    # scanner closed without seeing a wall (open side of a room, doorway gap).
+volume <uuid> <LABEL> cx cz top_y yaw_deg w d h
+                                    # furniture box: top-face centre (cx, top_y, cz), yaw about +Y in degrees
+                                    # (0 = local X along world X), width w along local X, depth d along the
+                                    # horizontal local axis perpendicular to it, height h downwards from the top
+plane <uuid> <LABEL> px py pz qx qy qz qw w h
+                                    # extra 2D plane (DOOR_FRAME, WINDOW_FRAME, WALL_ART, ...): pose of its centre,
+                                    # Meta convention (bounds in local XY, local +Z = the plane's normal)
+mesh <uuid> <file name> <vertex count> <index count>
+                                    # global mesh sidecar in the same folder (GLOBAL_MESH entity)
+```
+- `<uuid>` = 32 lowercase hex digits (no dashes). New ones per scan; FrameBridge uses them as the XrUuidEXT bytes.
+- Labels are Meta's semantic label strings: FLOOR, CEILING, WALL_FACE, INVISIBLE_WALL_FACE, TABLE, COUCH, BED,
+  STORAGE, SCREEN, LAMP, PLANT, DOOR_FRAME, WINDOW_FRAME, WALL_ART, OTHER, GLOBAL_MESH.
+- Readers ignore unknown record types (forward compatibility) and reject a file whose first line isn't
+  `frameport-room <version>` with a version they know. Missing ceiling -> 2.5 m above the floor. Missing walls ->
+  walls from the outline edges. Missing outline -> the bounding rectangle of the walls.
+
+### How FrameBridge maps records to Meta entities (scene_emu.c)
+- ROOM: ROOM_LAYOUT (floor, ceiling, walls in file order) + SPACE_CONTAINER (every other entity) + LOCATABLE/STORABLE.
+- floor/ceiling: pose at the outline centroid at height y; local +Z = +Y (floor) / -Y (ceiling);
+  BOUNDED_2D = the outline's bounding rect in local XY; BOUNDARY_2D = the outline polygon in local XY.
+- wall: pose at the segment midpoint, height (y0+y1)/2; local +X along the wall (x0,z0)->(x1,z1), local +Y up,
+  local +Z = inward normal; BOUNDED_2D = length x (y1-y0) centred.
+- volume: pose at the top-face centre, rotation = yaw about +Y then local +Z pointing up (+Y); BOUNDED_3D offset
+  (-w/2, -d/2, -h), extent (w, d, h) (Meta: volumes hang below their anchor); BOUNDED_2D = the top face (w x d).
+- plane: pose as given; BOUNDED_2D = w x h centred.
+- mesh: entity at the identity pose labelled GLOBAL_MESH with TRIANGLE_MESH (XR_META_spatial_entity_mesh).
+
+## room-mesh.bin (little-endian)
+```
+char[4] "FPRM", u32 version = 1, u32 vertex_count, u32 index_count,
+float32 xyz[vertex_count], u32 indices[index_count]   (triangles; counter-clockwise seen from the room's inside)
+```
+Coordinates in STAGE space. Kept below 200k triangles (decimated).
+
+## Raw files and scan.json (scanner sidecars)
+`fp_roomscan` refines its output by default (docs/mr/scan.md "Refinement"). `room.txt` + `room-mesh.bin` are always
+the refined room (what games and the GUI read; the contract above is unchanged). Next to them:
+- `room-raw.txt` + `room-mesh-raw.bin`: the scanner's unrefined output in the same formats (its `mesh` record names
+  `room-mesh-raw.bin`). Same UUIDs as the refined room.txt, so anchors stay the same when the room is refined again.
+  The refined room differs in: the ceiling height (re-estimated from the scan, wall tops follow it), the volumes
+  (after the label rules) and the mesh. Records the scanner doesn't model (e.g. `plane`) are copied verbatim.
+- `scan.json` (UTF-8 JSON, `version` 1):
+  ```
+  {"version": 1,
+   "heads": [[x, y, z], ...],          # head path of the recording (STAGE), <= 2000 points, decimated evenly
+   "refine": {"refine": 1, "walls": "panels", "band": 0.35, ..., "erase": [[x, y, z, r], ...]},
+                                       # every refinement setting used (keys = the CLI options, docs/mr/scan.md)
+   "report": {"triangles", "kept", "structural", "near_walls", "outside", "small_pieces", "thin_pieces",
+              "erased", "walked", "tops", "panel_triangles", "truncated", "walked_skipped", "floor_y",
+              "ceiling_y", "boxes", "relabelled", "removed_boxes", "suggestions",
+              "plane_shifts": [{"kind": "wall"|"floor"|"ceiling", "wall": i, "shift": m}, ...]},
+   "labels": [{"from": "COUCH", "to": "TABLE"|null, "reason": "top 0.69 m", "suggest": "door"|"closet" (optional),
+               "id": "<volume uuid>", "box": {"cx", "cz", "top_y", "yaw_deg", "w", "d", "h"}}, ...],
+                                       # one per scanner volume, in room-raw.txt order; to = null: removed
+   "suggestions": [{"kind": "door"|"closet", "box": {...}, "wall": i, "along": t, "reason": "..."}, ...]}
+                                       # tall thin slabs; never applied by the scanner. wall = index of the nearest
+                                       # wall record in room-raw.txt, along = 0..1 position on it (from x0,z0)
+  ```
+  `report` counts triangles of the raw mesh per pass (`panel_triangles` are added ones), `wall` in `plane_shifts`
+  indexes the wall records. Readers ignore unknown keys.
+- `fp_roomscan --refine-only <dir>` re-runs only the refinement from these files (an older folder without them:
+  its room.txt + mesh are copied to the raw names first). Publishing order: [raw mesh, raw text,] `scan.json`,
+  `room-mesh.bin`, `room.txt`.
+
+## Where the files live
+- Frame: `~/.local/share/frameport/rooms/<universe>/room.txt` + `room-mesh.bin` (+ `scan.log`, the raw files and
+  `scan.json` above).
+  `~/.local/share/frameport/rooms/current` = symlink to the newest room's folder.
+- Per game: launch.sh copies the current universe's room (else `current`) to `<app_dir>/room.txt` (+ mesh) before
+  Lepton starts, next to `settings.conf`; FrameBridge reads `dirname($FRAMEBRIDGE_CONFIG)/room.txt`. No room ->
+  the old guardian box.
+- A game's own saved anchors: `/sdcard/Android/data/<pkg>/files/framebridge-anchors.txt`
+  (`anchor <uuid> px py pz qx qy qz qw` per line, STAGE space), written by FrameBridge on save/erase.
+
+## Scan dumps (*.fprs) — recorded RoomView 3D meshes, input of `fp_roomscan --offline`
+```
+char[4] "FPRS", u32 version = 1, then frames until EOF:
+  f64 time_s, float32 pose[7] (px py pz qx qy qz qw: mesh -> STAGE), u32 vertex_count, u32 index_count,
+  float32 xyz[vertex_count] (mesh space), u32 indices[index_count]
+```
@@ -0,0 +1,216 @@
+# Scene emulation stream
+
+Implemented against `ROOM_FORMAT.md` without changing the contract, patch revisions, agent version or analysis version.
+No Frame access or external downloads were used. Headset behavior still needs maintainer verification.
+
+## Implementation
+
+- `scene_emu.c` owns entities, component APIs, pose transforms, bounded query snapshots and the event queue.
+  `scene_room.c` parses room files and meshes; `scene_meta.c` implements META discovery and batch persistence;
+  `scene_anchors.c` implements per-game saved anchors. All are included by the adapter, with no new dependencies.
+- At session creation, read `dirname(FRAMEBRIDGE_CONFIG)/room.txt`. Invalid magic/version, unusable geometry or
+  absent files retain the original guardian box, settings and seven deterministic UUIDs. Unknown records are
+  ignored; malformed records are logged and skipped. Missing ceiling, outline and walls follow the contract.
+- Floor/ceiling use the polygon area centroid and real local-XY polygons. Walls retain file order, with local +X
+  along their segment, +Y up and +Z inward. Furniture poses use yaw then +Z up; volume bounds extend downwards.
+  The room container includes every other room-file entity, excluding independently created application anchors.
+- Geometry exposes BOUNDED_2D, BOUNDED_3D, semantic labels and TRIANGLE_MESH as appropriate. OpenXR has no separate
+  `BOUNDARY_2D` component enum: `xrGetSpaceBoundary2DFB` belongs to BOUNDED_2D. Labels preserve comma-separated strings.
+  All variable-sized outputs support count-only and insufficient-capacity calls, including independent mesh arrays.
+- Limits: 2,048 entities including application anchors, 1,024 outline points, 255 label bytes, 64 KiB record lines,
+  one global mesh, 600,000 vertices/indices (200,000 triangles) and 16 MiB mesh payload. Sidecar filenames cannot
+  escape the config directory. Magic, version, counts, exact byte size, finite coordinates and indices are checked.
+- FB queries and META discovery snapshot results under the mutation lock, before queuing available/complete events.
+  META component/UUID filters intersect; unrecognized filters impose no restriction. FB max-result limits are honored.
+  There are 64 retained query snapshots and 63 queued events; calls that cannot fit their events return
+  `XR_ERROR_LIMIT_REACHED`. Geometry readers share the mutation lock with persistence.
+- Application anchors use kernel randomness (`getrandom`, then `/dev/urandom`), never index-derived UUIDs.
+  Saved poses are in STAGE space. FB/META saves write a private temporary file, flush/fsync, then rename to
+  `/sdcard/Android/data/<package>/files/framebridge-anchors.txt`. A process suffix such as `:game` is stripped.
+  Erase removes application anchors from disk and the discoverable in-memory set. Failed writes report failure
+  through completion events and restore memory. Room-file entities remain owned by the scan: save/erase are no-ops
+  for those entities. Storage is local; there is no cloud synchronization.
+- A new session reloads the room and saved anchors. Fake handles fit both adapter ABIs and include a session
+  generation; erased/stale fake spaces are never passed to SteamVR. Session generations wrap after 256 sessions.
+- Capture completes immediately and logs exactly `scene: capture requested -> scanned room` for a usable room file,
+  or `scene: capture requested -> guardian box` for the fallback. The former covers all file sources, including manual
+  and boundary files. The load summary preserves the actual `source` and `universe`.
+
+The cached `openxr-f2448a8797` headers already contain discovery, persistence and mesh declarations and enum values.
+No local structure/enum substitutes were necessary. Both META extensions are added to the existing conditional
+extension advertisement/instance filtering. Their system capability structures report support when emulation is active.
+Passthrough and unrelated adapter settings are unchanged.
+
+## Routing and integration
+
+All of the following use `scene_emulation` through **both** the adapter's normal `xrGetInstanceProcAddr` and
+`framebridge_extension_proc`, reached through xrshim's existing name-agnostic lookup:
+
+```
+xrQuerySpacesFB                         xrRetrieveSpaceQueryResultsFB
+xrGetSpaceUuidFB                        xrEnumerateSpaceSupportedComponentsFB
+xrSetSpaceComponentStatusFB             xrGetSpaceComponentStatusFB
+xrGetSpaceContainerFB                   xrGetSpaceRoomLayoutFB
+xrGetSpaceBoundingBox2DFB               xrGetSpaceBoundingBox3DFB
+xrGetSpaceBoundary2DFB                  xrGetSpaceSemanticLabelsFB
+xrRequestSceneCaptureFB                xrCreateSpatialAnchorFB
+xrSaveSpaceFB                          xrEraseSpaceFB
+xrGetSpaceTriangleMeshMETA              xrDiscoverSpacesMETA
+xrRetrieveSpaceDiscoveryResultsMETA     xrSaveSpacesMETA
+xrEraseSpacesMETA
+```
+
+The shim additionally routes `xrPollEvent`, `xrGetSystemProperties`, `xrLocateSpace`, `xrLocateSpaces`,
+`xrLocateSpacesKHR` and `xrDestroySpace` to the adapter while scene emulation is active. Other shim names continue to
+OVRPort, preserving existing haptics/render-model handling. The real shim is host-tested against a dispatcher that
+refuses every scene function; every emulated scene lookup succeeds and an actual discovery/retrieve round trip runs.
+
+**Plumb-stream requirement:** ensure `scene_emul=1` also installs xrshim and rewrites OVRPlugin's loader string to it.
+The pre-existing adapter patch only did this for other shim settings. These files are outside this stream's ownership.
+Delivery of room files before Lepton starts and detection of universe misalignment also belong to plumb. FrameBridge
+serves the supplied coordinates; it does not silently transform a room belonging to another universe.
+
+No contract changes are needed. Whether each MRUK version accepts a room without further permissions, how it chooses
+volume versus mesh geometry, and whether its visible placement matches the scan need headset tests. The existing
+single-active-session architecture is retained; simultaneous independent sessions are not implemented.
+
+## Offline verification
+
+- 25 host tests passed, compiling the actual emulation and shim. Coverage includes malformed records, unknown
+  records, mesh corruption/path/cap checks, derived geometry, 300 walls, poses/normals, all buffer sizing idioms,
+  discovery event order/filters/backpressure, UUID query/discovery of saved anchors, new sessions/processes,
+  FB/META save/erase and atomic-write failure rollback.
+- ASan/UBSan: scanned room, generated walls and box cases passed. LeakSanitizer was disabled because this sandbox
+  prohibits ptrace; its default exit failed with that environmental limitation.
+- `python native/build.py --only adapter,xrshim` succeeded from cached tools. Two final builds were byte-identical,
+  including `SHA256SUMS`. The shim was rebuilt and is byte-identical to its previous artifact (the routing lives in
+  the adapter). Artifact content changes are the two adapter binaries and two checksum lines.
+- Full pytest was attempted: **1,771 passed, 40 skipped, 11 failed, 16 errors**. All 27 failing/erroring tests create
+  local HTTP sockets, which the sandbox prohibits (`PermissionError: [Errno 1] Operation not permitted`). They are
+  in `test_deeplink`, `test_devkit`, `test_install_links_extra`, `test_livestream`, `test_setup_url` and `test_ui_state`.
+  With exactly those 27 tests deselected, and the additional real-shim test included: **1,772 passed, 40 skipped,
+  27 deselected**. An unrestricted maintainer run of the whole suite is still required.
+- The worktree had no usable venv. Verification reused the existing local dependencies through an ignored venv
+  `.pth`, with `PYTHONPATH="$PWD/src"`, `UV_CACHE_DIR=/tmp/frameport-uv-cache`, `UV_OFFLINE=true` and
+  `uv run --no-sync pytest`. No dependencies were downloaded. The build cache was made a local directory with
+  symlinks to cached tools/headers so generated shader files stayed inside this writable worktree.
+
+Adapter SHA-256:
+
+```
+arm64-v8a:   a90c8d58904857bc198a48fd7a411b7807f68f14fa58fd268c57e2c2ca87e389
+armeabi-v7a: 92daecaf5b86e1857ee8a61b76598e5645f8b427e5f373067c1f87bf8ff99d07
+```
+
+## Maintainer device tests
+
+These commands are a handoff, not commands run by this agent. Use an isolated populated `FRAMEPORT_HOME`, cached
+build tools, a paired Frame and legally obtained game sources. Stop games before changing their files. Back up the
+existing recipe, APK, room files and saved anchors first. Integrate plumb before testing normal room delivery.
+
+On the PC, from the integrated checkout (replace `frame.local` if necessary):
+
+```sh
+export FRAMEPORT_HOME="$PWD/.home"
+export FRAMEPORT_NO_UPDATE_CHECK=1 FRAMEPORT_NO_CATALOG_UPDATE=1
+FRAME=steamos@frame.local
+PKG=com.Novelab.Demeter
+uv run frameport recipe "$PKG" --set scene_emul=1
+uv run frameport install "$PKG" --frame "$FRAME" --force
+uv run frameport test "$PKG" --frame "$FRAME" --seconds 45
+ssh "$FRAME"
+```
+
+In that Frame shell, find the deployment's actual base (also supports a game moved to another drive):
+
+```sh
+PKG=com.Novelab.Demeter
+BASE=$(python3 -c 'import json,os,sys; p=os.path.expanduser("~/Applications/quest-frame/"+sys.argv[1]+"/deployment.json"); print(json.load(open(p)).get("base",os.path.dirname(p)))' "$PKG")
+grep -E 'scene:|extension shim:.*(Spaces|TriangleMesh|BoundingBox3D|PollEvent)' "$BASE/launch.log"
+```
+
+With a current scan delivered beside `settings.conf`, expect:
+
+```
+scene: room from scan file (N walls, M volumes, P planes, K mesh triangles, universe U)
+scene: capture requested -> scanned room
+```
+
+The capture line appears only if the game requests capture. A source made from a boundary/manual file names that
+source in the summary. The shim logs each requested function, for example
+`extension shim: xrDiscoverSpacesMETA -> FrameBridge`. There must be no `Unknown proc addr` for a scene function
+that the game obtains through the shim. Repeat the rebuild/install/headset check for `com.gritGames.Nope` and
+`com.zenstudios.PFXVRQuest` with `scene_emul=1`; these exercise newer MRUK discovery/persistence paths.
+
+Wear the headset and launch from Steam. Enter each game's MR mode and request room setup if offered. Verify the
+floor polygon, every wall, ceiling and furniture match the scan; tables sit below their top-face anchors; doors and
+windows have the correct orientation. Headless startup alone cannot prove tracking or visual placement.
+
+Fallback/undo test, while stopped: preserve `$BASE/room.txt` and `$BASE/room-mesh.bin` under a separate backup
+folder, then disable plumb's room delivery for this run or move the source room out of `rooms/current` as well.
+Without that precaution launch.sh will restore the file. Launch again; expect the original box summary and
+`scene: capture requested -> guardian box`. Test `scene_width=3 scene_depth=4 scene_height=2.7` with the existing
+`frameport settings` command and expect `scene: room 3.00 x 4.00 x 2.70 m`. Restore the saved files, recipe/settings
+and normal room delivery afterward. Do not delete a real game's saved anchors to test the fallback.
+
+### Android persistence probe (independent of a game's UI)
+
+This probe uses the **real scene code with the fake runtime from the host harness**. It checks Android storage,
+process-name handling and both persistence APIs; the headset tests above check the real SteamVR integration.
+The following cross-compilation command was verified offline:
+
+```sh
+native/.cache/ndk-27.2.12479018/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android29-clang \
+  -std=gnu11 -O2 -Wall -Wextra -Werror -Wno-unused-function \
+  -I native/.cache/openxr-f2448a8797 -I native/adapter tests/native/scene_emu_test.c \
+  -lm -o /tmp/frameport-scene-test-android
+scp /tmp/frameport-scene-test-android "$FRAME":/tmp/
+```
+
+Keep a freshly installed game running so its Lepton container exists, then run in the Frame shell:
+
+```sh
+APPID=$(python3 -c 'import json,os,sys; print(json.load(open(os.path.expanduser("~/Applications/quest-frame/"+sys.argv[1]+"/deployment.json")))["appid"])' "$PKG")
+CONTAINER=lepton-steamlaunch-$APPID
+podman cp /tmp/frameport-scene-test-android "$CONTAINER":/data/local/tmp/frameport-scene-test
+podman exec "$CONTAINER" test ! -e /sdcard/Android/data/org.frameport.scenetest
+# Continue only if that test succeeds: use a fresh test-only package directory.
+podman exec "$CONTAINER" mkdir -p /sdcard/Android/data/org.frameport.scenetest/files /data/local/tmp/frameport-scene-probe
+for mode in save reload erase-failure reload erase empty; do
+  podman exec "$CONTAINER" sh -c "FRAMEBRIDGE_CONFIG=/data/local/tmp/frameport-scene-probe/settings.conf exec -a org.frameport.scenetest /data/local/tmp/frameport-scene-test $mode" || break
+done
+podman exec "$CONTAINER" wc -l /sdcard/Android/data/org.frameport.scenetest/files/framebridge-anchors.txt
+```
+
+Every invocation must exit 0 without `FAIL`; logs show `anchors saved`, `loaded 2 saved anchors`, a deliberate
+`anchor write failed` during `erase-failure` (then the following reload still finds two), and `anchors erased`.
+The final file has zero lines. `save` also recreates a session internally, while separate invocations validate
+new-process reload. Undo, before stopping this container:
+
+```sh
+podman exec "$CONTAINER" rm -rf /sdcard/Android/data/org.frameport.scenetest /data/local/tmp/frameport-scene-probe
+podman exec "$CONTAINER" rm -f /data/local/tmp/frameport-scene-test
+rm -f /tmp/frameport-scene-test-android
+```
+
+Remove the PC's temporary probe binary too. Restore backed-up game files/settings and install the previous APK if
+rolling the feature back. No probe command changes real application anchors.
+
+## Commit handoff under the sandbox
+
+This worktree's real Git metadata is on a read-only mount. Commits therefore live on `mr/emul` in
+`/tmp/frameport-mr-emul.git`, with a portable bundle at `/tmp/frameport-mr-emul.bundle`. The actual worktree contains
+all final source/artifact edits but its original branch metadata cannot be advanced here. No local instruction,
+app-data or credential files were staged. The base is `4bf48d3`.
+
+After reviewing the worktree and verifying it contains exactly these changes, the maintainer can import the commits
+and align the existing worktree index without discarding its files:
+
+```sh
+git bundle verify /tmp/frameport-mr-emul.bundle
+git fetch /tmp/frameport-mr-emul.bundle mr/emul
+git log --oneline 4bf48d3..FETCH_HEAD
+git reset --mixed FETCH_HEAD
+```
+
+Run the unrestricted whole suite before merging. The bundle preserves the ordered implementation/test/build commits.
@@ -0,0 +1,171 @@
+# Room plumbing stream
+
+Implemented on `mr/plumb`; no Frame access or device verification. The shared `ROOM_FORMAT.md`, agent version,
+analysis version and patch revisions were left unchanged. No native binaries belong to this stream.
+
+## What changed
+
+- `frameport.mr.room`: room/entity dataclasses, v1 text and binary-mesh validation, canonical serialization,
+  missing ceiling/wall/outline defaults, clockwise outline/wall repair, summaries and top-down SVG previews.
+  Mesh counts, indices, finite coordinates, UUIDs and sidecar basenames are checked before import.
+- Standalone stdlib agent room commands live in one marked block. Rooms are staged under
+  `~/.local/share/frameport/rooms/<universe>/`; a `current` symlink selects the latest saved room. Uploads validate
+  before replacing a room. Deleting the current room selects the newest remaining room.
+- `room_status` returns `rooms`, current `universe`, selected `room`, `room_text`, `aligned`, `default_circle`
+  (null when no usable boundary exists) and `scanner_installed`. Summaries include wall/plane counts, furniture
+  counts by label, floor area and ceiling height. Status text lets the UI preview a room without another transfer.
+- Universe detection takes the last matching vrserver log line, then the newest chaperone record if no log match
+  exists. Dummy universe 424242 means unknown. Boundary conversion chains collision quads' bottom edges and refuses
+  the default 20-point, roughly 1 m circle. Boundary ceilings default to 2.5 m; SteamVR's 2.43 m wall extrusion
+  does not measure the real ceiling.
+- Finalize records `scene_room` from adapter settings. A marked `_room_sync` launcher line follows the existing
+  config-sync pattern, before Lepton starts. Launcher upgrades also handle old recipes listing
+  `adapter.scene_emul`. Matching universe wins over `current`; absent rooms remove stale sidecars. Live setting
+  changes update the launcher and clear copies when disabled. Non-scene launchers keep their existing layout.
+- PC room helpers implement status/import/export/delete/boundary/build/show/capture. Scanner upload reuses the
+  SHA-256 helper extracted from live view; `fp_venc` retains its soft-failure behavior. Import uploads canonical
+  text. Export checks mesh counts; build uploads FPRS dumps, runs the scanner and cleans its staging directory.
+- CLI: `frameport frame room status|from-boundary|import|export|delete|build|show`, with `--frame` on each command.
+  `show --output <path.svg>` writes a preview (default below `FRAMEPORT_HOME/rooms`). Build accepts `--universe`.
+- Frame page Room card: checklist, asset-URL preview, boundary/delete/capture actions, refresh and recoverable errors.
+  SSH and preview writes run in a background worker; state is cached per connection. Scene-game pages link to Room
+  setup when the connected Frame has no room. `ui_smoke.py --fake-frame` supplies local room-command answers.
+- Every USE_SCENE/USE_ANCHOR_API game gets the scene-emulation suggestion. Migration `scene_emul_all` enables it once
+  in automatic recipes, preserving user recipes. NOPE and Pinball FX keep their other recipe fields and now request
+  scene emulation. Triage explains guardian fallback and missing discovery; patch docs and translation template
+  were regenerated.
+
+## Integration questions and limits
+
+1. Headset capture is intentionally unfinished: `room_capture` returns `{"error":"not implemented yet"}`. The
+   `capture_roomview(seconds, out_path)` hook documents the pending RoomView queue work. The GUI explains this and
+   offers the boundary path. Do not present the capture button as a completed scan workflow yet.
+2. This branch has no `fp_roomscan` artifact; merge the scan stream before using `frame room build`. The exact scanner
+   invocation is `fp_roomscan --offline <dump> --out <temporary directory> --universe U --json`. Stdout must contain
+   one JSON value, stderr is saved as `scan.log`, and output must include a valid `room.txt` with the requested U.
+3. Merge the emulation/shim stream before expecting games to use saved rooms, meshes or new Meta entry points.
+   Runtime log spelling is owned there; triage accepts both existing `using guardian room`/dimension logs and the
+   brief's `guardian box`/`room from guardian` messages. Reconcile new success logs at integration.
+4. Confirm the chaperone JSON path, exact universe-switch logs and whether collision quads are already in STAGE on
+   the device. This implementation follows the brief's path and coordinate contract; it does not apply a second
+   standing-origin transform. A universe match alone cannot detect Valve changing an origin without changing its ID.
+5. Agent and desktop perform independent validation because the deployed agent cannot import the desktop package.
+   The desktop canonicalizes outlines and fills defaults; the agent preserves scanner output and validates it.
+   The format contract needed no changes.
+6. Rooms are shared across games; per-game saved anchors are not deleted or rewritten by these commands. Replacing
+   a room creates new entity UUIDs, so a game may need its own room-setup reset. No automatic game reset was added.
+
+## Offline validation
+
+All commands used `FRAMEPORT_HOME` in this worktree (tests use temporary isolated homes), an existing dependency
+venv and offline/no-sync uv settings. No dependencies or native toolchains were downloaded.
+
+- Room, PC/CLI, UI, heuristics, migration, MR triage and translation checks passed: 63 tests. The related
+  agent/launcher/screenshots/codec/gamepad regression group passed 170 tests. The final deployment/configuration
+  regression check passed 48 tests, including all four recipe/settings precedence cases.
+- Ruff over changed Python files and `scripts/patch_docs.py --check` passed. The UI detector reported no findings.
+  `scripts/i18n_extract.py` regenerated `src/frameport/locales/template.json`.
+- `pytest -m games`: 3 skipped (no game dumps). Dev/holdout evaluation used only the checked-in demo analysis
+  snapshot, 21 catalog matches: dev dated 9/17 exact, F1 81.1%; holdout dated 1/4 exact, F1 73.3%. These are limited
+  fixture results, not a new score for the owner's complete collection; the evaluator exits 1 for recipe differences.
+- Final full suite: **1790 passed, 40 skipped, 11 failed, 16 errors** in 87.35 s. All 27 failures/errors are
+  `PermissionError: [Errno 1] Operation not permitted` when existing tests create sockets. The whole-suite green
+  requirement cannot be met in this sandbox; rerun `uv run pytest -q` on a host permitting loopback sockets.
+  Browser UI smoke also requires a loopback server, so it
+  was not run. New UI tests construct the real Flet controls and exercise deferred preview/error/cache states.
+
+## Exact device checks (maintainer only)
+
+Run these after integrating emul + scan. Substitute the paired Frame address below; keep the current worktree's
+`FRAMEPORT_HOME=.home` and use explicit `--frame` so the test does not open another app data directory. The source
+connection syncs the agent by digest even without a version bump, unless the Frame has a newer agent version.
+The maintainer must perform integration version bumps before testing against a newer installed agent.
+
+```sh
+export FRAME='steamos@<frame>'
+export PKG='com.gritGames.Nope'  # repeat with com.zenstudios.PFXVRQuest and a known scene game
+uv run frameport frame info --frame "$FRAME"
+uv run frameport frame room status --frame "$FRAME" > .home/mr-status.json
+# Back up ALL rooms on the Frame before destructive checks; use an unused backup name.
+ssh "$FRAME" 'test ! -e ~/.local/share/frameport/rooms.before-mr-test && { test ! -d ~/.local/share/frameport/rooms || cp -a ~/.local/share/frameport/rooms ~/.local/share/frameport/rooms.before-mr-test; }'
+```
+
+1. Inspect status: no room gives `room: null`, `aligned: false`. With Valve's default circle, `default_circle: true`;
+   `uv run frameport frame room from-boundary --frame "$FRAME"` must fail with the default-circle explanation.
+   Set a real play area in SteamVR, repeat `from-boundary`: expect source `boundary`, one wall per boundary edge,
+   correct floor area and `aligned: true`. Open Frame → Room: visible preview, warning for the unscanned room,
+   aligned row ready; the capture button should show the friendly unavailable message without crashing.
+2. Exercise import/export and preview with a manual fixture in the current universe:
+
+```sh
+uv run frameport frame room status --frame "$FRAME" > .home/mr-status.json
+uv run python - <<'PY'
+import json
+from pathlib import Path
+from frameport.mr.room import Mesh, Volume, box_room, dumps, write_mesh
+p = Path('.home/mr-check'); p.mkdir(parents=True, exist_ok=True)
+r = box_room(4, 3, 2.5)
+r.source = 'manual'
+r.universe = json.loads(Path('.home/mr-status.json').read_text())['universe']
+r.volumes.append(Volume('a'*32, 'TABLE', .5, 0, .8, 20, 1.2, .7, .8))
+r.mesh = Mesh(vertices=[(-2, 0, -1.5), (2, 0, -1.5), (2, 0, 1.5)], indices=[0, 1, 2])
+(p/'room.txt').write_text(dumps(r))
+(p/'room-mesh.bin').write_bytes(write_mesh(r.mesh))
+PY
+uv run frameport frame room import .home/mr-check/room.txt --frame "$FRAME"
+uv run frameport frame room export .home/mr-export --frame "$FRAME"
+uv run frameport frame room show --output .home/mr-check/preview.svg --frame "$FRAME"
+cmp .home/mr-check/room-mesh.bin .home/mr-export/room-mesh.bin
+```
+
+   Expect four walls, one TABLE, area 12 m² and height 2.5 m. The preview must label TABLE and the game must show it
+   hanging below its top-face anchor. Check the corresponding universe folder and `rooms/current` on the Frame.
+3. Use a recorded dump from the same standing universe (do not invent one). Copy it to `.home/mr-check/scan.fprs`,
+   then run the command below. Expect the scanner JSON under `report`, source `scan`, aligned room data, `scan.log`
+   on the Frame and an installed executable. Run twice: an unchanged scanner must not upload again.
+
+```sh
+uv run frameport frame room build .home/mr-check/scan.fprs --frame "$FRAME"
+uv run frameport frame room status --frame "$FRAME"
+```
+
+   If the recording is from another universe, pass its original `--universe <id>`; do not relabel its coordinates.
+4. Prepare the game's source and its existing backed-up signing key in the isolated test library, then force a
+   rebuild/reinstall after integration: `uv run frameport install "$PKG" --frame "$FRAME" --force --apk-only`.
+   Repeat for both catalog games. In each deployment, expect `scene_room: true`. Run `frame info` twice to upgrade
+   old launchers and check one marker only:
+
+```sh
+uv run frameport frame info --frame "$FRAME"
+uv run frameport frame info --frame "$FRAME"
+ssh "$FRAME" "grep -c '# frameport-room-sync' ~/Applications/quest-frame/$PKG/launch.sh"
+uv run frameport settings "$PKG" scene_emul=1 --frame "$FRAME"
+```
+
+   Expected marker count: 1. Start the game with Steam's Play button in the headset, enter its MR mode, then inspect
+   `<deployment.base>/room-sync.log`: JSON has the selected universe and alignment. The two room files must be
+   beside `<deployment.base>/settings.conf`. FrameBridge must load that room; `xrDiscoverSpacesMETA` must resolve
+   through the extension shim, with no `Unknown proc addr`/MRUK `NoRoomsFound`. Exact new native success log strings
+   should be taken from the emul stream. Verify walls/table placement physically; never infer alignment from FPS.
+5. Exit the game. Switch `scene_emul=0` using Game settings (or the settings command above with 0): marker and game
+   sidecars disappear. Switch it back to 1: one marker returns. Delete the room and launch again: stale copies are
+   removed and existing FrameBridge guardian fallback logs trigger informational `mr-no-room` triage.
+6. To check a universe mismatch, back up/export the room, change its `universe` record to another valid ID and import
+   it, then delete the original universe's room with `frame room delete --universe <original-id>`. Status must select
+   `current` but report `aligned: false`; the Room card warns. Restore the original file before playing physically.
+   The dummy universe 424242 should report current universe 0 rather than claim alignment.
+
+## Undo device checks
+
+Close all games. Restore the backed-up store (or remove only the fixture universes if there was no previous store):
+
+```sh
+ssh "$FRAME" 'if test -d ~/.local/share/frameport/rooms.before-mr-test; then rm -rf ~/.local/share/frameport/rooms; mv ~/.local/share/frameport/rooms.before-mr-test ~/.local/share/frameport/rooms; fi'
+```
+
+Set each tested game's `scene_emul` back to its recorded original value. To remove a test room without a backup:
+`uv run frameport frame room delete --universe <fixture-universe> --frame "$FRAME"`. Start a scene game once to
+refresh/remove its copies. The scanner can be removed with
+`ssh "$FRAME" 'rm -f ~/.local/share/frameport/bin/fp_roomscan'`; the next build reinstalls it. Game saves and
+`framebridge-anchors.txt` are untouched. Restore the previous app/agent/native artifacts through the maintainer's
+normal integration rollback if testing the combined native implementation fails.
@@ -0,0 +1,452 @@
+# Offline room scanner (scan stream)
+
+`fp_roomscan` converts recorded FPRS v1 meshes to the [room contract](ROOM_FORMAT.md), including the optional
+wall label adopted from upstream commit `8cb2783`:
+`room.txt` and `room-mesh.bin`, refined by default (see "Refinement" below), plus the unrefined `room-raw.txt` +
+`room-mesh-raw.bin` and `scan.json` (head path, settings, per-pass report, label decisions, door/closet
+suggestions; ROOM_FORMAT.md "Raw files and scan.json"). It does not capture RoomView queues, contact a headset, install rooms, or modify
+the current-room symlink. Scanner work changes `native/roomscan/`, its build target and artifact/checksum,
+`scripts/mr/synth_scan.py`, `tests/test_roomscan.py`, and this note. The upstream contract commit also brings its
+existing prompt assets and renderer unchanged. No runtime, agent, patch, or analysis versions were bumped.
+
+## Build and run
+
+Use the cached NDK; no downloads are needed for this target:
+
+```sh
+python native/build.py --only roomscan
+```
+
+The result is `artifacts/linux-arm64-bin/fp_roomscan`, a static aarch64 Linux ELF with its own `_start`, raw Linux
+syscalls, and no interpreter, dynamic section, libc, libm, UAPI headers, generated tables, or new dependencies.
+`platform.h` is the reconstruction code's entire I/O/allocation boundary. The same eight C sources compile on the
+host:
+
+```sh
+cc -std=c11 -O2 -Wall -Wextra -Werror -ffp-contract=off -fno-math-errno -DFP_HOSTED native/roomscan/*.c -o /tmp/fp_roomscan
+python scripts/mr/synth_scan.py /tmp/room.fprs
+/tmp/fp_roomscan --offline /tmp/room.fprs --out /tmp/scanned-room --universe 0 --json
+```
+
+The output directory's parent must exist; the scanner creates the final directory if needed. It always prints
+exactly one JSON summary, whether `--json` is supplied or omitted. Success exits 0, errors exit 2 with
+`{"ok":false,"error":"..."}`. `--help` prints usage and exits 0. Successful summaries contain:
+
+```json
+{"ok":true,"frames":30,"skipped_frames":0,"far_vertices":0,"discontinuity_triangles":0,
+ "walls":4,"detected_walls":4,"volumes":2,"floor_y":-0.0023,
+ "ceiling_y":2.5992,"coverage_percent":100.0,"hint_used":false,"triangles":70997,
+ "accepted_triangles":118804,"rejected_triangles":704,"heads":28,
+ "refine":{"triangles":70997,"kept":7159,"structural":46121,"near_walls":148,"outside":0,"small_pieces":38,
+  "thin_pieces":0,"erased":0,"walked":203,"tops":1896,"panel_triangles":12,"truncated":0,"walked_skipped":false,
+  "floor_y":-0.0051,"ceiling_y":2.6028,"boxes":2,"relabelled":1,"removed_boxes":0,"suggestions":0,
+  "plane_shifts":[{"kind":"wall","wall":0,"shift":-0.0004},...,{"kind":"ceiling","shift":-0.0021}],
+  "output_triangles":7171,"output_volumes":2},"warnings":[],
+ "timings_ms":{"read":0,"fusion":0,"model":0,"mesh":0,"refine":0,"total":0}}
+```
+
+The example above illustrates the schema; actual counts and timings depend on the input. Heights are absolute
+STAGE coordinates. `frames` includes skipped frames; `skipped_frames`, `far_vertices`, and
+`discontinuity_triangles` count input exclusions once, not once per pass. `walls` counts output polygon
+edges including synthesized edges; `detected_walls` counts fitted physical planes. Coverage means the percentage
+of the output perimeter supported by observed wall planes, **not camera coverage of all room surfaces**. Timings
+include parsing, fusion, structural/furniture modelling, mesh generation, refinement, and total time including
+output. The scanner fields describe the unrefined scan (`triangles`, `volumes`, `ceiling_y` are the raw files');
+`refine` is the refinement report (same keys as scan.json's `report`) plus the refined `output_triangles` and
+`output_volumes`. `heads` counts the head-path points kept for the walked-volume pass.
+
+All frame headers, timestamps/vertices/poses, approximately unit quaternions, counts, indices and EOF boundaries
+are checked before publication. A non-finite timestamp/pose/vertex or invalid tracking quaternion skips the entire
+frame after consuming and structurally validating its record, with a count and warning. A bad frame never erases
+usable frames elsewhere in the dump. Vertices outside the camera-relative range (default 4 m) and every triangle
+touching them are discarded. Triangles with a camera-depth jump over `--depth-jump + --depth-ratio * nearest_depth`
+are rejected before fusion; this complements long-edge and grazing rejection. Frame counts are capped at
+1 million vertices / 3 million indices;
+oversized records fail rather than allocating from untrusted counts. A header-only dump or one without usable
+triangles fails. Empty frames may accompany useful frames. Structural corruption (truncation, unsupported header,
+bad counts or indices) remains fatal, preserves any existing output byte for byte and creates no output directory.
+UUIDs come from `getrandom`, fresh per scan; mesh geometry is repeatable.
+
+All files are computed first, then each is written to an exclusive, randomly named temporary file and renamed, in
+the order `room-mesh-raw.bin`, `room-raw.txt`, `scan.json`, `room-mesh.bin`, `room.txt` (meshes before their room
+text, `room.txt` last). A write failure removes the temporary files. These are atomic **file** replacements, not a
+multi-file filesystem transaction: the installer should scan into a fresh staging directory
+and publish that directory/symlink after success. Do not run concurrent writers into the same output directory.
+There is no fsync-based power-loss durability promise. Neither scan nor build writes application data outside
+the worktree's `FRAMEPORT_HOME`; fixtures and test output use temporary directories.
+
+## Reconstruction
+
+1. The first streaming pass validates every frame, rotates its mesh by the supplied quaternion, and translates
+   it into STAGE. It rejects degenerate triangles, excessively long edges, out-of-range points, and grazing
+   surfaces. Winding is corrected toward the observing camera. A deterministic bounded reservoir of 32,768
+   accepted triangle centroids determines median position and padded bounds. No frames are retained across reads.
+2. The second pass rasterizes accepted triangles at 0.75 voxel spacing. Per-cell surfels average positions and
+   inward normals, weighted by area and squared incidence. A capped accumulated weight lets later views correct
+   earlier ones. The grid is sized from the sample bounds and capped at 8 x 8 x 4 metres about the data median.
+   Unobserved cells have zero weight. This implementation uses a bounded dense backing array for the sparse
+   observations, rather than a hash table; the 4.2-million-cell hard cap bounds all later work. Complete regular
+   fans are recognized from their index topology, without hardcoding a camera resolution. Their normals come from
+   12 x 12 neighbourhood covariance plane fits, rejecting patches above `--patch-residual` RMS; irregular meshes
+   retain triangle normals. Each cell counts contributing frames once and needs `--min-views` evidence, capped at
+   ten percent of usable frames (rounded down, at least one) for brief captures. This suppresses transient stereo
+   geometry without requiring a short scan to see each surface five times.
+3. Horizontal normal/height histograms select the dominant floor within the STAGE floor band and a ceiling above
+   the minimum ceiling height. Missing floor uses STAGE y=0 with a warning; missing ceiling uses floor plus
+   `--ceiling-default`, warning exactly `ceiling not seen`. A ceiling must also have at least 15% as many supported
+   cells as all upward-facing horizontal surfaces, so a few isolated down-facing patches do not invent a ceiling.
+4. RANSAC fits near-vertical planes using distance and normal agreement, then refines them by position covariance.
+   Minimum height, span, and area reject furniture faces. Wall directions within the snap tolerance of the
+   dominant wall's orthogonal directions are snapped, with offsets refitted. Directed wall segments are connected
+   by nearest endpoints and adjacent line intersections. This preserves the L-shaped fixture's re-entrant corner.
+   Parallel same-facing planes within 25 cm / approximately 14° merge, suppressing duplicate softened faces.
+   Planes below 20% of the strongest original plane's area are discarded. When at least 65% of candidate wall area
+   supports an orthogonal family, directions outside 12° of that family are discarded (`--snap-degrees 0` disables
+   this orthogonal consensus filter). Large gaps close along observed endpoints. Ambiguous endpoints with three
+   or four planes can use inward half-plane intersections; concave rooms retain segment ordering. Otherwise a
+   warned observed-bounds rectangle is used. Polygon checks reject crossing edges. The output follows the contract's positive
+   shoelace ordering in (x,z), with left-facing inward normals.
+5. Furniture tops are clustered separately from vertical faces, within supported horizontal height bands. A
+   softened edge connecting a tabletop to a wall can no longer absorb the whole room into one box. Top boxes use
+   a minimum-area horizontal orientation search and the median surface height; vertical screen candidates use
+   face-direction harmonics / PCA. Bounds trim the outer 2% to suppress stereo halos. Top boxes extend down to the
+   floor (the footprint and lower extent remain geometric estimates). Weak/sparse top patches are discarded.
+   Labels follow height, area, long-side (with two voxels of measurement tolerance),
+   thinness and near-wall rules, in order BED, COUCH, TABLE, SCREEN, STORAGE, OTHER. Only volumes are emitted;
+   optional table plane records are not required. Floor/ceiling/wall surfaces are excluded before clustering.
+6. Surfel splats form an incidence/area-weighted signed distance field within three voxels of each surface. The
+   sign is positive in observed free room space. Marching cubes traces zero crossings on cube faces, resolving
+   ambiguous faces from their centre sign. It fans closed contours and orients triangles toward the positive
+   gradient. Unknown corners suppress extraction rather than bridging unobserved space. If necessary, extraction
+   is repeated on a coarser lattice (strides 2–4) until at most 200,000 triangles remain, with a decimation warning;
+   excess beyond that fails. Vertices are unshared triangle vertices, so at most 600,000 vertices. Structural
+   planes are semantic anchors, not substituted for the observed global mesh.
+
+## Refinement
+
+After the mesh, the scanner cleans the room the way the owner tuned it in the room-scan cleanup page (2026-10-18);
+`native/roomscan/refine.c` and `rules.c` port that page's `refine()` and label rules pass for pass (local parity
+check on the owner's recording: identical counts and bit-identical refined meshes, see below). `--refine 0`
+switches it off: room.txt and room-mesh.bin are then byte-for-byte what the scanner wrote before refinement existed
+(the raw files and scan.json are still written, so refinement can be switched on later without a new scan).
+
+The input is exactly what the raw files hold: the raw room is written as text and read back (doubles parsed from the
+4-decimal text, like the page reads it), the head path is rounded the same way. Therefore `--refine-only <dir>`
+on the raw files reproduces the scan's refined files byte for byte. The mesh is welded at 1 mm (quantized, as the
+page does) for the passes that need topology; the output is again unshared triangle vertices.
+
+1. **Label rules** (`rules.c`, `--label-rules 0` off) on the scanner's volumes, using the raw room (walls, outline,
+   floor): a box that holds >= 60% of two boxes whose centres are >= 1 m apart covers several things (removed); a
+   box >= 75% inside a bigger box with a top no higher (+5 cm) is part of it (removed); a centre > 10 cm outside the
+   outline is behind a wall (removed). A tall thin slab from the floor (thinner than 22 cm, >= 1.8 m high, bottom
+   <= 0.3 m, at most 0.5 m behind the wall line) becomes a door (<= 1.1 m wide) or closet **suggestion** in
+   scan.json (box removed, nothing added: the GUI decides). Thin (< 22 cm) upright boxes are SCREEN only when
+   raised >= 0.3 m, top <= 2.2 m, width/height >= 1.2, within 15 degrees of the nearest wall (when closer than
+   0.35 m) and flat: the raw mesh's depth spread inside the box <= 3 cm (with >= 30 triangles; fewer = unknown,
+   accepted); otherwise removed. Then BED (top 0.25-0.65 m, area >= 2 m^2, long side 1.8-3 m), COUCH (top
+   0.35-0.6 m, long side >= 1.4 m), TABLE (top 0.6-1.1 m), STORAGE (>= 1.1 m high, >= 25 cm deep, within 0.35 m of a
+   wall); anything taller than 1.1 m otherwise is removed, the rest is OTHER. Every box gets a reason in scan.json.
+   These thresholds are constants in `rules.c` (the page's `RULES0`).
+2. **Furniture**: triangles within 10 cm of a ruled box (after the rules) are furniture; the passes below never
+   classify, clear or walk them away, and the tubes pass keeps pieces that are mostly furniture.
+3. **Planes**: seen walls (`WALL_FACE` records), floor and ceiling. Each plane's offset moves to the median signed
+   distance of the non-furniture triangles facing it (normal within `--facing-deg`) within `--band` of it (walls:
+   within their length + band), when there are more than 50. An unseen ceiling (floor + 2.5 m) moves to the real
+   one; the re-estimated ceiling is written to the refined room.txt (ceiling record and wall tops).
+4. **Structural triangles**: facing a plane, not furniture, behind it by less than `--band`, in front of it by less
+   than `--band-in` (walls), `--floor-in`, `--ceil-in`; in a wall's top `--top-strip` below the ceiling the full
+   band applies in front too (the depth bends where wall meets ceiling). The nearest qualifying plane owns it.
+5. **Erase spheres** (`--erase "x,y,z,r;..."`, from the GUI's eraser) drop every triangle whose centroid is inside.
+6. **Walked volume** (`--walked` = radius R, 0 off): where the user stood, nothing solid can be. Non-furniture
+   triangles from 0.2 m above the floor up to 0.25 m above a head position, within R horizontally of it, go.
+   Needs the head path (scan.json); without it the pass is skipped (`walked_skipped`).
+7. **Walls** (`--walls`): `panels` (default) removes the structural triangles, then non-furniture triangles closer
+   than `--near` to any plane (within the wall's extent), and adds flat panels: one quad per seen wall (moved by its
+   offset shift) from floor to ceiling, and the outline ear-clipped at the floor and the ceiling heights, all wound
+   counter-clockwise seen from inside. `snap` instead projects every vertex of a structural triangle onto its plane
+   (the last owner wins). `off` keeps them.
+8. **Furniture tops** (`--tops`, 0 off): upward-facing (normal y > 0.8) triangles within `--tops` of a box top and
+   inside its footprint are flattened onto it.
+9. **Clip**: centroids further than `--clip` outside the outline (`--clip` + `--clip-open` past an unseen wall), or
+   further than `--clip` above the ceiling / below the floor plane go. `--clip 1 --clip-open 2` switches it off.
+10. **Islands**: connected pieces smaller than `--island` m^2 go (`--protect 1` keeps furniture triangles).
+11. **Thin floating pieces** (`--tubes`, 0 off): pieces of >= 10 triangles, < 1 m^2, at most half furniture, whose
+    longest principal axis (vertex PCA, std) is >= `--tubes` times the second and the second <= `--tube-thick`.
+12. **Smoothing**: `--smooth` Taubin iterations (lambda 0.5, mu -0.53) over the kept triangles.
+
+Output: the kept scan triangles, then the panels (`refine.panel_triangles`), at most 200,000 triangles (more kept
+triangles would be cut, `truncated`, with a warning). The refinement adds about 20 ms on the host for the owner's
+64k-triangle scan; its buffers (welding hash, double positions, union-find, adjacency) stay below ~170 MiB for a
+200k-triangle mesh and the fusion grid is freed before it runs, so peak memory is still the fusion phase's.
+
+`--refine-only <room dir> [refinement options] [--json]` runs only steps 1-12 from `room-raw.txt` +
+`room-mesh-raw.bin` (+ the head path from `scan.json`) and rewrites scan.json, room-mesh.bin and room.txt. A folder
+from an older scanner without raw files: its room.txt + mesh become the raw files first (the room text is rewritten
+with the mesh record pointing at `room-mesh-raw.bin`), a warning says so, and there is no head path. Its JSON:
+`{"ok":true,"refine_only":true,"raw_triangles":..,"volumes":..,"floor_y":..,"ceiling_y":..,"heads":..,
+"refine":{...},"warnings":[...],"timings_ms":{"refine":..,"total":..}}`.
+
+Local parity (2026-10-18, private recording `room1.fprs`, not in the repository): the reference page's functions run
+under node on this scanner's raw output give the same per-pass counts, the same label decisions and reasons, and
+bit-identical refined meshes for the defaults, snap, off + protect, erase spheres + tubes 2, and a wide-band setting
+(one triangle differs there: a facing test exactly at the threshold), and the same on an older 128k-triangle room
+folder. Distance ties at outline corners decide which wall's clip allowance applies, so the corner distance uses
+V8's Math.hypot algorithm.
+
+Peak allocation stays below 260 MiB, including maximum frame buffers, the grid, model worklists and mesh buffers
+(the latter phases do not retain frame buffers). Default synthetic scenes use a much smaller grid. Thresholds
+are CLI options below or named constants next to their algorithms. No room-specific coordinates or dimensions are
+used; on-device quality and speed still need validation.
+
+## Tuning
+
+Distances are metres, areas m², volumes m³. `--universe` accepts the full unsigned 64-bit range; 0 means unknown.
+
+| Option | Default | Accepted range / meaning |
+| --- | ---: | --- |
+| `--voxel` | 0.05 | 0.04–0.20, spatial resolution; lower values cost more memory/work |
+| `--ceiling-default` | 2.5 | 1.8–3.8, height above floor when ceiling is unseen |
+| `--truncation` | 3 | 1–5, TSDF band in voxel units |
+| `--max-edge` | 0.6 | 0.05–1.5, reject longer triangle edges |
+| `--grazing` | 0.12 | 0.01–0.9, minimum absolute camera/normal cosine |
+| `--range` | 4 | 1–10, maximum camera-relative vertex distance; >4 m opts back into inpainted depth |
+| `--depth-jump` | 0.25 | 0.02–1, absolute part of a triangle's maximum depth discontinuity |
+| `--depth-ratio` | 0.12 | 0–0.5, additional fraction of nearest vertex depth |
+| `--min-views` | 5 | 1–16, temporal support target; brief scans cap it as described above |
+| `--patch-residual` | 0.03 | 0.005–0.1, maximum RMS residual of a regular-fan normal patch |
+| `--plane-distance` | 0.045 | 0.01–0.15, point-to-plane inlier tolerance |
+| `--min-plane-area` | 0.45 | 0.1–4, minimum occupied plane area estimate |
+| `--wall-height` | 1.5 | 0.5–3, minimum observed vertical wall span |
+| `--snap-degrees` | 5 | 0–15, orthogonal snap tolerance |
+| `--floor-band` | 0.35 | 0.05–1, floor search distance from STAGE y=0 |
+| `--ceiling-min` | 1.8 | 1.5–3, minimum absolute ceiling y |
+| `--min-volume` | 0.05 | 0.005–1, reject smaller furniture boxes |
+| `--cluster-gap` | 0.10 | 0.04–0.20, voxel neighbourhood gap (rounded up to cells) |
+| `--gap` | 0.65 | 0.1–1.5, maximum adjacent-wall endpoint extrapolation |
+| `--horizontal` | 0.85 | 0.6–0.99, minimum floor/ceiling/top normal cosine |
+
+Refinement (all distances metres; defaults = the owner's settings):
+
+| Option | Default | Accepted range / meaning |
+| --- | ---: | --- |
+| `--refine` | 1 | 0/1; 0 = the unrefined output in room.txt/room-mesh.bin |
+| `--walls` | panels | `off`, `snap` (project onto the planes) or `panels` (flat wall/floor/ceiling panels) |
+| `--band` | 0.35 | 0.02–1, structural band behind a surface; plane re-estimation window |
+| `--facing-deg` | 60 | 5–89, maximum angle between a triangle's normal and the surface's |
+| `--band-in` | 0.12 | 0–1, band in front of a wall (room side) |
+| `--floor-in` | 0.08 | 0–1, band above the floor |
+| `--ceil-in` | 0.25 | 0–1, band below the ceiling |
+| `--top-strip` | 0.5 | 0–2, top part of a wall where the full band applies in front too |
+| `--near` | 0.03 | 0–0.3, panels: also clear non-furniture scan this close to a plane |
+| `--clip` | 0.05 | 0–1, clip distance outside the outline / beyond floor and ceiling |
+| `--clip-open` | 0.10 | 0–2, extra allowance past unseen walls (`--clip 1 --clip-open 2` = no clipping) |
+| `--island` | 0.20 | 0–5 m^2, minimum connected piece area (0 off) |
+| `--smooth` | 8 | 0–50 integer, Taubin iterations |
+| `--tops` | 0.10 | 0–0.5, flatten upward scan this close to a box top (0 off) |
+| `--protect` | 0 | 0/1, islands never remove furniture triangles |
+| `--tubes` | 3 | 0–20, elongation (PCA axis ratio) of a thin floating piece (0 off) |
+| `--tube-thick` | 0.15 | 0.01–1, maximum second PCA axis (std) of a thin floating piece |
+| `--walked` | 0.40 | 0 or 0.05–1.5, walked-volume radius around the head path (0 off) |
+| `--label-rules` | 1 | 0/1, label rules on the scanner's volumes |
+| `--erase` | none | `"x,y,z,r;..."`, up to 64 spheres (r 0–5 m) whose scan is removed |
+
+Additional constants in `model.c` include RANSAC trials, normal agreement, wall span, furniture margins,
+label height/area thresholds, box trimming and circle recognition. Fusion sampling/weight limits are in
+`fusion.c`; mesh splat radii/decimation limits in `mesh.c`; hard resource limits in `scan.h`.
+
+`--hint outline.txt` accepts one `x z` point per line, decimal/scientific notation, optional `#` comments, either
+winding, at most 96 points / 8 KiB. At least eight points with radial coefficient of variation below 5% count as
+the default circle and are ignored. A non-circular hint is used only when walls are incomplete **and every
+observed wall has a compatible hint edge** within `--gap`. Complete scans are never constrained to chaperone.
+Incompatible inset play boundaries are ignored with a warning. Hint-completed edges retain synthesized status.
+
+## Limits for integration
+
+- Synthesized wall records now append `INVISIBLE_WALL_FACE` as their optional eighth field. Observed walls omit
+  the label and default to `WALL_FACE`; comments are no longer used to carry semantics. This matches upstream's
+  authorized contract change exactly; adapters need that same contract revision.
+- A private RoomView recording was used for offline robustness work. It, its derived geometry, and its results
+  stay outside committed files. Synthetic fixtures independently exercise the input characteristics. They are
+  regressions, not proof
+  of headset accuracy. Furniture labels are geometric heuristics; adjacent/touching objects can merge, occluded
+  objects may split, top-only clusters have inferred depth, and thin fragments can be screen candidates. Nearby
+  parallel walls and small wall jogs can merge under coarse depth uncertainty. Large disconnected coplanar wall segments are
+  currently fitted together; complicated rooms can fall back to a warned rectangle.
+- Cropped or sparse captures can produce an incomplete mesh and synthesized outline. Surfaces are not filled
+  through unseen regions. Furniture is not an accessibility/safety boundary. Rooms beyond the grid cap are
+  cropped with a warning. Default-circle recognition may also ignore an intentionally circular boundary.
+- Output paths are fixed by the contract. The plumbing stream should stage a new directory and switch `current`
+  after scanner success, preserving the previous room for rollback. Assign the recording's actual universe id;
+  this standalone scanner cannot query SteamVR or validate universe alignment.
+
+## Offline validation
+
+`tests/test_roomscan.py` builds with the host compiler (skips only if none exists). Its tests cover the noisy
+4 x 3 x 2.6 m room with table/couch, six-wall L, moving and rotated/translated mesh poses, ceiling fallback, a single
+frame, missing walls, circular/matching hints, correct UUIDs/wire layout, interior mesh winding, triangle budget,
+repeatable mesh bytes with fresh UUIDs, truncated/corrupt dumps, invalid counts/indices/poses and invalid CLI values.
+Refinement tests: a floating pole and a column in the walked path (`synth_scan.py` `TUBE`/`GHOST`, `extra=`)
+are meshed by the scanner and removed by the tubes / walked passes (each kept with its pass off, the table top kept);
+panels wind into the room on the re-estimated planes; `--refine-only` reproduces a scan's files byte for byte;
+`--refine 0` equals the raw output (and refining it later equals the default); scan.json settings/report/heads; head
+path decimation to <= 2000 points; erase spheres; the label rules on a hand-written older room folder (merged,
+nested, behind a wall, SCREEN from a flat panel, a door suggestion with wall and position, unknown records kept,
+idempotent, `--label-rules 0`); invalid refinement options.
+The test module takes about fourteen seconds including synthetic rendering and compilation (under the 60 s budget).
+New cases cover non-finite frames before/after usable frames, per-vertex far rejection, depth jumps below the edge
+limit, weak ceiling evidence, wall labels and a complete camera-fan scan. The deterministic stdlib renderer now
+defaults to a 132 x 128 full index fan (99,822 indices), +Z forward / -Y image up, with poses mapping to STAGE.
+It adds separable depth smoothing, spatially correlated noise, far inpainting, two initial NaN poses, 3 Hz timestamps
+and head-height drift from 0.9 to 1.7 m. `--profile legacy` retains the smaller 110° x 76° test cone. New CLI controls
+are `--profile`, `--invalid-start`, `--smoothing` and optional resolution overrides. Use `--invalid-start 0` for a
+usable one-frame fixture; default RoomView warm-up frames otherwise have no valid tracking.
+
+```sh
+UV_OFFLINE=1 UV_CACHE_DIR=/tmp/frameport-uv-cache uv run pytest -q tests/test_roomscan.py
+UV_OFFLINE=1 UV_CACHE_DIR=/tmp/frameport-uv-cache uv run ruff check scripts/mr/synth_scan.py tests/test_roomscan.py
+```
+
+The synthetic camera fan passes AddressSanitizer + UndefinedBehaviorSanitizer. Two consecutive final native builds
+produce identical SHA-256 `2cc16b90abcd3d359f1658c581172bd650017bf2725e24268915f50904c000ec` (97,808 bytes, with refinement),
+matching `artifacts/SHA256SUMS`. ELF inspection confirms aarch64, little-endian, no PT_INTERP / PT_DYNAMIC, and no
+embedded local build paths.
+
+The required full `uv run pytest -q` run completed with **1,788 passed, 40 skipped, 11 failed, 16 errors** in 79 s.
+All 27 failures/errors are the sandbox's `PermissionError: [Errno 1] Operation not permitted` on socket creation
+in existing HTTP/pairing/live-stream tests (`test_deeplink`, `test_devkit`, `test_install_links_extra`,
+`test_livestream`, `test_setup_url`, `test_ui_state`). This environment forbids sockets, including loopback.
+The unchanged baseline had the identical 27 failures/errors before the scanner tests were added (1,747 passed).
+Consequently the whole-suite-pass requirement cannot be satisfied here; rerun it outside that restriction at
+integration. No tests were changed/skipped to hide the restriction and no network/device access was attempted.
+No patch/settings/catalog/triage files were touched, so the conditional patch documentation regeneration is
+unnecessary.
+
+## Ten-minute capture budget (synthetic benchmark)
+
+The scanner is streaming and single-threaded. On an Intel Core i7-14700K host, a **synthetic-only** 1,800-frame
+132 x 128 dump (1,083,751,208 bytes, equivalent to ten minutes at 3 Hz) took **7.41 s elapsed / 7.08 s CPU**, with
+**27,208 KiB maximum RSS** at the default voxel size. The file repeats a 30-view synthetic sweep, including its
+warm-up frames; it tests parsing/fusion throughput rather than 1,800 independent viewpoints. Geometry-dependent
+model/mesh work and storage caches affect timing. No private recording or derived room data is in that benchmark.
+
+Reproduce with bounded copies rather than loading a gigabyte into Python:
+
+```sh
+python scripts/mr/synth_scan.py /tmp/roomview.fprs
+python - <<'PY'
+import shutil
+with open('/tmp/roomview.fprs', 'rb') as source, open('/tmp/roomscan-1800.fprs', 'wb') as out:
+    out.write(source.read(8))
+    for repeat in range(60):
+        source.seek(8)
+        shutil.copyfileobj(source, out, 1024 * 1024)
+PY
+/usr/bin/time -v /tmp/fp_roomscan --offline /tmp/roomscan-1800.fprs --out /tmp/roomscan-benchmark --json
+```
+
+For the Frame's Cortex-A720/X4-class cores, budgeting **3–5 times the host CPU time plus storage** gives roughly
+**23–38 s** for this workload, leaving headroom under the requested ~60 s. This is an estimate, not an ARM
+measurement or an 8-core speedup claim. Worst-case allocations are bounded below 260 MiB independently of frame
+count (48-byte cells, 4.2-million-cell cap, bounded frame buffers/worklists), below both the original 300 MB and
+follow-up 600 MB limits. A maximum-sized complex room can add model/mesh work beyond this small synthetic sweep.
+The maintainer must time a ten-minute real capture on the Frame and check CPU time, wall time and RSS before
+claiming the target is achieved on-device. Hardware square root instructions replace iterative division; neither
+build links libm. The build and host command both require `-fno-math-errno` for that intrinsic.
+
+## Exact device checks (maintainer only; none executed by this stream)
+
+1. On the development PC, build, then render the canonical fixtures:
+
+   ```sh
+   python native/build.py --only roomscan
+   python scripts/mr/synth_scan.py /tmp/box.fprs
+   python scripts/mr/synth_scan.py /tmp/l.fprs --shape l
+   python scripts/mr/synth_scan.py /tmp/down.fprs --no-ceiling
+   python scripts/mr/synth_scan.py /tmp/one.fprs --frames 1 --invalid-start 0
+   scp artifacts/linux-arm64-bin/fp_roomscan /tmp/box.fprs /tmp/l.fprs /tmp/down.fprs /tmp/one.fprs steamos@<FRAME>:~/Downloads/
+   ```
+
+2. In a terminal **on the Frame**, use an isolated directory; no game or current room is changed:
+
+   ```sh
+   mkdir -p "$HOME/.local/share/frameport/roomscan-test"
+   cd "$HOME/.local/share/frameport/roomscan-test"
+   cp "$HOME/Downloads/fp_roomscan" ./fp_roomscan
+   chmod 700 ./fp_roomscan
+   ./fp_roomscan --help
+   ./fp_roomscan --offline "$HOME/Downloads/box.fprs" --out box --universe 0 --json > box.json
+   cat box.json
+   ./fp_roomscan --offline "$HOME/Downloads/l.fprs" --out l --json > l.json
+   ./fp_roomscan --offline "$HOME/Downloads/down.fprs" --out down --ceiling-default 2.7 --json > down.json
+   ./fp_roomscan --offline "$HOME/Downloads/one.fprs" --out one --json > one.json
+   ```
+
+   Expected JSON: box has `ok:true`, `walls:4`, `detected_walls:4`, `volumes:2`, floor within 5 cm of 0,
+   ceiling within 5 cm of 2.6, coverage 100; the only expected box warnings concern skipped warm-up frames and
+   out-of-range vertices. `box/room.txt` includes TABLE and COUCH volume records.
+   L has six walls and the concave corner near (0,0), rather than a rectangle. Down includes exactly the warning
+   string `ceiling not seen` (other warnings are expected), with ceiling minus floor 2.7. One includes
+   `few frames; scan more viewpoints`. Every mesh should have at most 200,000 triangles. JSON is the scanner log;
+   there are no expected stderr status lines.
+
+3. Verify sidecars, wall labels and the corrupt-input exit status on the Frame:
+
+   ```sh
+   python3 - <<'PY'
+   import json, pathlib, struct
+   for name in ('box', 'l', 'down', 'one'):
+       report = json.loads(pathlib.Path(name + '.json').read_text())
+       data = pathlib.Path(name, 'room-mesh.bin').read_bytes()
+       magic, version, nv, ni = struct.unpack_from('<4sIII', data)
+       assert report['ok'] and magic == b'FPRM' and version == 1
+       assert ni % 3 == 0 and 0 < ni // 3 <= 200000
+       assert len(data) == 16 + nv * 12 + ni * 4
+       for line in pathlib.Path(name, 'room.txt').read_text().splitlines():
+           if line.startswith('wall '):
+               fields = line.split()
+               assert len(fields) in (8, 9)
+               if len(fields) == 9:
+                   assert fields[-1] == 'INVISIBLE_WALL_FACE'
+       print(name, nv, ni // 3, report['warnings'])
+   pathlib.Path('broken.fprs').write_bytes(b'FPRS\x01\0\0\0\0')
+   PY
+   ./fp_roomscan --offline broken.fprs --out broken --json
+   echo "$?"
+   test ! -e broken/room.txt
+   test ! -e broken/room-mesh.bin
+   ```
+
+   Expected: `{"ok":false,"error":"truncated frame header"}`, exit status 2, no `broken` outputs.
+
+4. Record actual RoomView dumps with the maintainer's recorder (FPRS v1, mesh-to-STAGE poses, stable universe).
+   Copy the recording to `~/Downloads/capture.fprs`. Look around slowly for about a minute, including floor,
+   ceiling, every wall, and furniture from several directions. With the **recorded universe id** assigned below:
+
+   ```sh
+   scan_universe=0  # replace 0 with the recorder's actual decimal universe id
+   /usr/bin/time -v ./fp_roomscan --offline "$HOME/Downloads/capture.fprs" --out real --universe "$scan_universe" --json > real.json 2> real-timing.log
+   cat real.json real-timing.log
+   cat real/room.txt
+   ```
+
+   Measure wall offsets/yaws, ceiling and table top physically and compare to the records (target 5 cm / 2°).
+   Check resident memory below 300 MB, sensible coverage/warnings, tabletop labels and no false wall/furniture
+   blobs from smeared edges. Repeat with `--max-edge 0.35 --grazing 0.2` into `real-stricter` if edges smear;
+   try `--voxel 0.08 --plane-distance 0.07` into `real-coarser` if depth is noisy. Keep both JSON logs and raw
+   dumps **outside git** for threshold calibration. These are proposed tuning probes, not established device fixes.
+
+5. Repeat the synthetic 1,800-frame benchmark from the preceding section on the Frame, using the same command
+   and `/usr/bin/time -v`. Then test a ten-minute independent real capture. Target: about 60 s elapsed or less,
+   less than 600 MB RSS, successful JSON and bounded mesh size. Record CPU time as well as wall time so storage
+   overhead is visible. With difficult stereo edges compare `--min-views 8 --patch-residual 0.02` in a fresh output
+   directory; short captures cap view support automatically. Include the JSON's exclusion counters in triage;
+   skipped frames may occur anywhere in the capture. Keep all personal results outside git.
+
+6. After merging plumbing/emulation, publish this staged room through that stream's room-install path and try
+   Demeter, then an MRUK discovery/mesh game. Check room loading, furniture alignment, and warning/fallback
+   behaviour in-headset; the scanner alone cannot verify the Meta API path. Do not replace `rooms/current` by hand
+   during these standalone checks.
+
+Undo standalone checks: remove only the isolated `~/.local/share/frameport/roomscan-test` directory and the five
+test files copied to `~/Downloads` (plus `capture.fprs` if no longer needed). No Steam settings, games, agent,
+room universe folder, or current-room symlink were changed by these steps.
@@ -108,3 +108,21 @@ shots:
    steps:
      - go: settings
      - wait_for: "Portal (OLED)"
+
+  - name: room             # experimental: the pretend Frame's made-up bedroom scan (fakes.fake_room), no real scan
+    docs: [README.md, docs/INSTALL.md]
+    viewport: [1280, 1690]
+    steps:
+      - hook: open_room
+      - wait_for: "Furniture & screens"
+      - park: true
+
+  - name: room-editing     # a box picked in the list (its type, place and size) next to the clean-up's labels
+    docs: [docs/INSTALL.md]
+    viewport: [1280, 2000]  # (tall enough that nothing scrolls)
+    steps:
+      - hook: open_room
+      - wait_for: "Furniture & screens"
+      - hook: {name: room_editing, args: [box]}
+      - park: true
+    crop: {anchor: "Furniture & screens", left: -26, top: -28, width: 670, height: 1262}
@@ -149,6 +149,9 @@ static int flip_quads = 0;
 static int flip_emul_setting = 1;
 static int cylinder_strips_on = 1;  // show cylinder layers as flat quad strips (cylinder_strips)
 static int scene_emul;  // scene emulation setting (per game)
+static int scene_scan_request = 1;
+static int scene_hide_bounds;  // per game: the app's STAGE bounds query answers "no play area" (Demeter)
+static int scene_events_via_shim;  // the shim delivers room events: the layer's xrPollEvent leaves them alone
 static float scene_height = 2.5f;  // scene emulation ceiling height (m)
 static float scene_width, scene_depth;  // optional room size override (m)
 static int64_t xr_time_offset;  // XrTime minus CLOCK_MONOTONIC ns, measured at xrWaitFrame
@@ -228,6 +231,8 @@ static void read_settings(const char *path) {
        if (sscanf(line, "flip_emul=%f", &value) == 1) flip_emul_setting = value != 0;
        if (sscanf(line, "cylinder_strips=%f", &value) == 1) cylinder_strips_on = value != 0;
        if (sscanf(line, "scene_emul=%f", &value) == 1) scene_emul = value != 0;
+        if (sscanf(line, "scene_scan_request=%f", &value) == 1) scene_scan_request = value != 0;
+        if (sscanf(line, "scene_hide_bounds=%f", &value) == 1) scene_hide_bounds = value != 0;
        if (sscanf(line, "scene_height=%f", &value) == 1 && value > 1.5f && value < 5.0f) scene_height = value;
        if (sscanf(line, "scene_width=%f", &value) == 1 && value > 0.5f && value < 20.0f) scene_width = value;
        if (sscanf(line, "scene_depth=%f", &value) == 1 && value > 0.5f && value < 20.0f) scene_depth = value;
@@ -393,8 +398,9 @@ XRAPI_ATTR XrResult XRAPI_CALL xrCreateInstance(const XrInstanceCreateInfo *info
        else if (!strcmp(ext, XR_FB_COLOR_SPACE_EXTENSION_NAME)) {
            requested_color_space = 1;
        } else if (scene_emul && is_scene_extension(ext)) {
-            if (!emulate_scene) LOG("emulating Meta scene/spatial-entity extensions from the guardian bounds");
+            if (!emulate_scene) LOG("emulating Meta scene/spatial-entity extensions from room file or guardian bounds");
            emulate_scene = 1;
+            if (!strcmp(ext, "XR_META_spatial_entity_mesh")) scene_app_mesh = 1;
        } else if (controller_models && render_models_available && !strcmp(ext, XR_FB_RENDER_MODEL_EXTENSION_NAME)) {
            emulate_render_model = 1;
            LOG("emulating XR_FB_render_model with Steam Frame controller models");
@@ -898,8 +904,12 @@ static int layer_usable(const XrCompositionLayerBaseHeader *layer) {
            if (!runtime_swapchain(p->views[v].subImage.swapchain)) return 0;
        return 1;
    }
-    case XR_TYPE_COMPOSITION_LAYER_QUAD:
-        return runtime_swapchain(((const XrCompositionLayerQuad *)layer)->subImage.swapchain);
+    case XR_TYPE_COMPOSITION_LAYER_QUAD: {
+        const XrCompositionLayerQuad *q = (const XrCompositionLayerQuad *)layer;
+        if (q->size.width <= 0.0f || q->size.height <= 0.0f) return 0;
+        if (q->subImage.imageRect.extent.width <= 0 || q->subImage.imageRect.extent.height <= 0) return 0;
+        return runtime_swapchain(q->subImage.swapchain);
+    }
    case XR_TYPE_COMPOSITION_LAYER_CYLINDER_KHR:
        if (no_cylinder) return 0;
        return runtime_swapchain(((const XrCompositionLayerCylinderKHR *)layer)->subImage.swapchain);
@@ -921,15 +931,44 @@ static int layer_usable(const XrCompositionLayerBaseHeader *layer) {
 static uint64_t next_fake_handle = 0x7f000001;
 #define FAKE_HANDLE(type) ((type)(uintptr_t)__atomic_fetch_add(&next_fake_handle, 1, __ATOMIC_RELAXED))

+// The app's passthrough calls, logged (each kind at most 8 times) to see where an MR game stops (NOPE: black).
+static void passthrough_log(const char *what, uint64_t handle, uint32_t flags, int purpose) {
+    static int counts[8];
+    static const char *const kinds[8] = {"create", "start", "pause", "destroy", "layer create", "layer resume",
+                                         "layer pause", "layer destroy"};
+    for (int k = 0; k < 8; ++k)
+        if (!strcmp(what, kinds[k]) && counts[k]++ < 8)
+            LOG("passthrough: %s 0x%llx flags=0x%x purpose=%d", what, (unsigned long long)handle, flags, purpose);
+}
 static XRAPI_ATTR XrResult XRAPI_CALL emu_create_passthrough(XrSession s, const XrPassthroughCreateInfoFB *i, XrPassthroughFB *out) {
-    (void)s; (void)i; if (!out) return XR_ERROR_VALIDATION_FAILURE; *out = FAKE_HANDLE(XrPassthroughFB); return XR_SUCCESS;
+    (void)s; if (!out) return XR_ERROR_VALIDATION_FAILURE; *out = FAKE_HANDLE(XrPassthroughFB);
+    passthrough_log("create", (uint64_t)(uintptr_t)*out, i ? (uint32_t)i->flags : 0, -1);
+    return XR_SUCCESS;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_passthrough_start(XrPassthroughFB p) {
+    passthrough_log("start", (uint64_t)(uintptr_t)p, 0, -1); return XR_SUCCESS;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_passthrough_pause(XrPassthroughFB p) {
+    passthrough_log("pause", (uint64_t)(uintptr_t)p, 0, -1); return XR_SUCCESS;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_passthrough_handle(XrPassthroughFB p) {
+    passthrough_log("destroy", (uint64_t)(uintptr_t)p, 0, -1); return XR_SUCCESS;
 }
-static XRAPI_ATTR XrResult XRAPI_CALL emu_passthrough_handle(XrPassthroughFB p) { (void)p; return XR_SUCCESS; }
 static XRAPI_ATTR XrResult XRAPI_CALL emu_create_passthrough_layer(XrSession s, const XrPassthroughLayerCreateInfoFB *i,
        XrPassthroughLayerFB *out) {
-    (void)s; (void)i; if (!out) return XR_ERROR_VALIDATION_FAILURE; *out = FAKE_HANDLE(XrPassthroughLayerFB); return XR_SUCCESS;
+    (void)s; if (!out) return XR_ERROR_VALIDATION_FAILURE; *out = FAKE_HANDLE(XrPassthroughLayerFB);
+    passthrough_log("layer create", (uint64_t)(uintptr_t)*out, i ? (uint32_t)i->flags : 0, i ? (int)i->purpose : -1);
+    return XR_SUCCESS;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_passthrough_layer_resume(XrPassthroughLayerFB l) {
+    passthrough_log("layer resume", (uint64_t)(uintptr_t)l, 0, -1); return XR_SUCCESS;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_passthrough_layer_pause(XrPassthroughLayerFB l) {
+    passthrough_log("layer pause", (uint64_t)(uintptr_t)l, 0, -1); return XR_SUCCESS;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_passthrough_layer_handle(XrPassthroughLayerFB l) {
+    passthrough_log("layer destroy", (uint64_t)(uintptr_t)l, 0, -1); return XR_SUCCESS;
 }
-static XRAPI_ATTR XrResult XRAPI_CALL emu_passthrough_layer_handle(XrPassthroughLayerFB l) { (void)l; return XR_SUCCESS; }
 static XRAPI_ATTR XrResult XRAPI_CALL emu_passthrough_layer_style(XrPassthroughLayerFB l, const XrPassthroughStyleFB *st) {
    (void)l; (void)st; return XR_SUCCESS;
 }
@@ -965,12 +1004,12 @@ static PFN_xrVoidFunction passthrough_emulation(const char *name) {
    static const struct { const char *name; PFN_xrVoidFunction fn; } table[] = {
        {"xrCreatePassthroughFB", (PFN_xrVoidFunction)emu_create_passthrough},
        {"xrDestroyPassthroughFB", (PFN_xrVoidFunction)emu_passthrough_handle},
-        {"xrPassthroughStartFB", (PFN_xrVoidFunction)emu_passthrough_handle},
-        {"xrPassthroughPauseFB", (PFN_xrVoidFunction)emu_passthrough_handle},
+        {"xrPassthroughStartFB", (PFN_xrVoidFunction)emu_passthrough_start},
+        {"xrPassthroughPauseFB", (PFN_xrVoidFunction)emu_passthrough_pause},
        {"xrCreatePassthroughLayerFB", (PFN_xrVoidFunction)emu_create_passthrough_layer},
        {"xrDestroyPassthroughLayerFB", (PFN_xrVoidFunction)emu_passthrough_layer_handle},
-        {"xrPassthroughLayerPauseFB", (PFN_xrVoidFunction)emu_passthrough_layer_handle},
-        {"xrPassthroughLayerResumeFB", (PFN_xrVoidFunction)emu_passthrough_layer_handle},
+        {"xrPassthroughLayerPauseFB", (PFN_xrVoidFunction)emu_passthrough_layer_pause},
+        {"xrPassthroughLayerResumeFB", (PFN_xrVoidFunction)emu_passthrough_layer_resume},
        {"xrPassthroughLayerSetStyleFB", (PFN_xrVoidFunction)emu_passthrough_layer_style},
        {"xrCreateGeometryInstanceFB", (PFN_xrVoidFunction)emu_create_geometry},
        {"xrDestroyGeometryInstanceFB", (PFN_xrVoidFunction)emu_geometry_handle},
@@ -1008,6 +1047,13 @@ XRAPI_ATTR XrResult XRAPI_CALL xrGetSystemProperties(XrInstance instance, XrSyst
                ((XrSystemPassthroughPropertiesFB *)p)->supportsPassthrough = XR_TRUE;
            if (p->type == XR_TYPE_SYSTEM_SPATIAL_ENTITY_PROPERTIES_FB && emulate_scene)
                ((XrSystemSpatialEntityPropertiesFB *)p)->supportsSpatialEntity = XR_TRUE;
+            // META scene capability chains used by current MRUK.
+            if (p->type == XR_TYPE_SYSTEM_SPACE_DISCOVERY_PROPERTIES_META && emulate_scene)
+                ((XrSystemSpaceDiscoveryPropertiesMETA *)p)->supportsSpaceDiscovery = XR_TRUE;
+            if (p->type == XR_TYPE_SYSTEM_SPACE_PERSISTENCE_PROPERTIES_META && emulate_scene)
+                ((XrSystemSpacePersistencePropertiesMETA *)p)->supportsSpacePersistence = XR_TRUE;
+            if (p->type == XR_TYPE_SYSTEM_BOUNDARY_VISIBILITY_PROPERTIES_META && emulate_scene)
+                ((XrSystemBoundaryVisibilityPropertiesMETA *)p)->supportsBoundaryVisibility = XR_TRUE;
            if (p->type == XR_TYPE_SYSTEM_PASSTHROUGH_PROPERTIES2_FB)
                ((XrSystemPassthroughProperties2FB *)p)->capabilities = XR_PASSTHROUGH_CAPABILITY_BIT_FB;
            if (p->type == XR_TYPE_SYSTEM_RENDER_MODEL_PROPERTIES_FB && emulate_render_model)
@@ -1055,7 +1101,22 @@ XRAPI_ATTR XrResult XRAPI_CALL xrLocateSpace(XrSpace space, XrSpace baseSpace, X
    pose_time_note("xrLocateSpace", (uint64_t)(uintptr_t)space, (uint64_t)(uintptr_t)baseSpace, time);
    if (emulate_scene && location) {
        XrPosef pose; XrSpaceLocationFlags flags;
-        if (locate_fake(space, baseSpace, time, &pose, &flags)) {
+        pthread_mutex_lock(&scene_lock);
+        int fake = locate_fake(space, baseSpace, time, &pose, &flags);
+        int entity = fake ? fake_space_index(space) : -1, base_entity = fake ? fake_space_index(baseSpace) : -1;
+        pthread_mutex_unlock(&scene_lock);
+        if (fake) {
+            // MRUK keeps an anchor pending (no load Success, ever) unless both valid bits are set (Pinball FX)
+            static int logged, logged_invalid;
+            const XrSpaceLocationFlags need = XR_SPACE_LOCATION_ORIENTATION_VALID_BIT | XR_SPACE_LOCATION_POSITION_VALID_BIT;
+            int invalid = (flags & need) != need;
+            if (logged < 30 || (invalid && logged_invalid < 60)) {
+                LOG("scene: locate entity %d in %s %d (space 0x%llx) at %lld: flags 0x%llx%s", entity,
+                    base_entity >= 0 ? "entity" : "real space", base_entity, (unsigned long long)(uintptr_t)baseSpace,
+                    (long long)time, (unsigned long long)flags, invalid ? " NOT VALID" : "");
+                ++logged;
+                if (invalid) ++logged_invalid;
+            }
            location->pose = pose;
            location->locationFlags = flags;
            return XR_SUCCESS;
@@ -1077,8 +1138,8 @@ static XrResult locate_spaces_common(const char *name, XrSession session, const
    if (info) pose_time_note(name, info->spaceCount ? (uint64_t)(uintptr_t)info->spaces[0] : 0,
                             (uint64_t)(uintptr_t)info->baseSpace, info->time);
    if (emulate_scene && info && locations) {
-        any_fake = fake_space_index(info->baseSpace) >= 0;
-        for (uint32_t i = 0; i < info->spaceCount && !any_fake; ++i) any_fake = fake_space_index(info->spaces[i]) >= 0;
+        any_fake = is_fake_space(info->baseSpace);
+        for (uint32_t i = 0; i < info->spaceCount && !any_fake; ++i) any_fake = is_fake_space(info->spaces[i]);
    }
    if (!any_fake) {
        PFN_xrLocateSpaces fn = (PFN_xrLocateSpaces)lookup(active_instance, name);
@@ -1101,7 +1162,12 @@ static XRAPI_ATTR XrResult XRAPI_CALL emu_locate_spaces_khr(XrSession session, c
 }

 XRAPI_ATTR XrResult XRAPI_CALL xrDestroySpace(XrSpace space) {
-    if (fake_space_index(space) >= 0) return XR_SUCCESS;  // entity spaces live for the whole session
+    if (is_fake_space(space)) {
+        pthread_mutex_lock(&scene_lock);
+        int valid = fake_space_index(space) >= 0;
+        pthread_mutex_unlock(&scene_lock);
+        return valid ? XR_SUCCESS : XR_ERROR_HANDLE_INVALID;  // entity spaces live for the whole session
+    }
    PFN_xrDestroySpace fn = (PFN_xrDestroySpace)lookup(active_instance, "xrDestroySpace");
    return fn ? fn(space) : XR_ERROR_FUNCTION_UNSUPPORTED;
 }
@@ -1486,7 +1552,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrPollEvent(XrInstance instance, XrEventDataBuffe
    mx_audio_initialize(); mx_batman_geometry_initialize();
    PFN_xrPollEvent fn = (PFN_xrPollEvent)lookup(instance, "xrPollEvent");
    if (!fn) return XR_ERROR_FUNCTION_UNSUPPORTED;
-    if (emulate_scene && event) {
+    if (emulate_scene && event && !scene_events_via_shim) {
        pthread_mutex_lock(&scene_lock);
        int got = pop_event(event);
        pthread_mutex_unlock(&scene_lock);
@@ -1825,6 +1891,7 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
    XrCompositionLayerQuad quads[64];
    XrCompositionLayerQuad fade_out;  // fade_quad: at most one fade layer per frame
    int faded = 0;
+    const XrCompositionLayerBaseHeader *own_fade = NULL;  // fade_quad's black quad (FrameBridge's own)
    cube_outputs_begin();
    uint32_t count = 0, dropped = 0, swapped = 0, passthrough = 0;
    const XrCompositionLayerBaseHeader *surface_projections[SURF_MAX];
@@ -2130,7 +2197,32 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
        // the app's own layer: fade_quad=2 removed it from the copy submitted)
        int level = fade_quad && !faded && count < 64 ? fade_level(info->layers[i]) : 0;
        const XrCompositionLayerBaseHeader *fade_l = level ? fade_layer(session, level, count, &fade_out) : NULL;
-        if (fade_l) { kept[count++] = fade_l; faded = 1; ++swapped; }
+        if (fade_l) { kept[count++] = fade_l; own_fade = fade_l; faded = 1; ++swapped; }
+    }
+    // The runtime refuses frames with more layers than maxLayerCount (XR_ERROR_LAYER_LIMIT_EXCEEDED: Punch Fit sends
+    // 21+). Keep every projection layer and FrameBridge's own fade quad, then the app's other layers in submission
+    // order until the limit (from PR #246; the earliest app layers were what Punch Fit needed).
+    uint32_t max_layers = runtime_max_layers ? runtime_max_layers : 16, trimmed_layers = 0;
+    if (count > max_layers) {
+        const XrCompositionLayerBaseHeader *trimmed[64];
+        uint32_t tcount = 0, reserved = 0, res_kept = 0, other_kept = 0;
+        for (uint32_t i = 0; i < count; ++i)
+            if (kept[i]->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION || kept[i] == own_fade) ++reserved;
+        if (reserved > max_layers) reserved = max_layers;
+        uint32_t budget = max_layers - reserved;
+        for (uint32_t i = 0; i < count; ++i) {
+            int keep_always = kept[i]->type == XR_TYPE_COMPOSITION_LAYER_PROJECTION || kept[i] == own_fade;
+            uint32_t *n = keep_always ? &res_kept : &other_kept;
+            if (*n < (keep_always ? reserved : budget)) { trimmed[tcount++] = kept[i]; ++*n; }
+            else ++trimmed_layers;
+        }
+        static int layer_limit_logged;
+        if (layer_limit_logged++ < 5)
+            LOG("xrEndFrame: %u layers exceed the runtime limit %u: left out %u of the app's other layers "
+                "(kept %u projection/fade layers and %u others)", count, max_layers, trimmed_layers, res_kept,
+                other_kept);
+        for (uint32_t i = 0; i < tcount; ++i) kept[i] = trimmed[i];
+        count = tcount;
    }
    PoolFrame pool_frame;
    if (swapchain_pool && session == pool_session) {
@@ -2168,11 +2260,11 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
            }
        }
    }
-    static int views_logged;
-    if (views_logged < 3) {  // describe the stereo layer layout a few times to debug eye/stereo problems
-        for (uint32_t i = 0; i < info->layerCount; ++i) {
-            const XrCompositionLayerBaseHeader *l = info->layers[i];
-            if (l && l->type == XR_TYPE_COMPOSITION_LAYER_QUAD) {
+    static int views_logged, quads_logged;
+    if (views_logged < 3 || quads_logged < 10) {  // describe the stereo layer layout and quads
+        for (uint32_t i = 0; i < fixed.layerCount; ++i) {
+            const XrCompositionLayerBaseHeader *l = fixed.layers[i];
+            if (l && l->type == XR_TYPE_COMPOSITION_LAYER_QUAD && quads_logged < 10) {
                const XrCompositionLayerQuad *qd = (const XrCompositionLayerQuad *)l;
                char chain[160] = "";
                size_t used = 0;
@@ -2183,10 +2275,12 @@ XRAPI_ATTR XrResult XRAPI_CALL xrEndFrame(XrSession session, const XrFrameEndInf
                                      (unsigned long long)((const XrCompositionLayerImageLayoutFB *)n)->flags);
                    used += w;
                }
-                LOG("quad layer: flags=0x%llx size=%.2fx%.2f next:%s", (unsigned long long)qd->layerFlags,
-                    qd->size.width, qd->size.height, chain);
+                LOG("quad layer %u: swapchain=%p flags=0x%llx size=%.2fx%.2f pos=%.2f,%.2f,%.2f next:%s", i,
+                    (void *)(uintptr_t)qd->subImage.swapchain, (unsigned long long)qd->layerFlags,
+                    qd->size.width, qd->size.height, qd->pose.position.x, qd->pose.position.y, qd->pose.position.z, chain);
+                ++quads_logged;
            }
-            if (!l || l->type != XR_TYPE_COMPOSITION_LAYER_PROJECTION) continue;
+            if (!l || l->type != XR_TYPE_COMPOSITION_LAYER_PROJECTION || views_logged >= 3) continue;
            const XrCompositionLayerProjection *p = (const XrCompositionLayerProjection *)l;
            for (uint32_t v = 0; v < p->viewCount; ++v) {
                const XrCompositionLayerProjectionView *pv = &p->views[v];
@@ -2351,30 +2445,94 @@ static XRAPI_ATTR XrResult XRAPI_CALL fb_hide_update_swapchain(XrSwapchain swapc
    return fn ? fn(swapchain, state) : XR_ERROR_FUNCTION_UNSUPPORTED;
 }

+// Generic calls the shim routes here for the emulated room (OVRPort's dispatcher refuses fake handles' functions):
+// only fake room spaces and FramePort's own room events are handled locally; every real call goes on to OVRPort's
+// dispatcher, whose own work (headset identity, events, controller spaces) was skipped for every scene game before.
+static PFN_xrVoidFunction dispatcher_proc(const char *name) {
+    static PFN_xrGetInstanceProcAddr gipa;
+    static int tried;
+    if (!tried) {
+        tried = 1;
+        void *h = dlopen("libopenxr_loader.so", RTLD_NOW | RTLD_NOLOAD);  // OVRPort's dispatcher (xrshim's next)
+        if (h) gipa = (PFN_xrGetInstanceProcAddr)dlsym(h, "xrGetInstanceProcAddr");
+        LOG("scene: shim calls for real handles go to OVRPort's dispatcher (%s)", gipa ? "found" : "MISSING");
+    }
+    PFN_xrVoidFunction fn = NULL;
+    if (gipa && active_instance) gipa(active_instance, name, &fn);
+    return fn;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL shim_locate_space(XrSpace space, XrSpace base, XrTime time, XrSpaceLocation *loc) {
+    PFN_xrLocateSpace next = is_fake_space(space) || is_fake_space(base) ? NULL
+                             : (PFN_xrLocateSpace)dispatcher_proc("xrLocateSpace");
+    return next ? next(space, base, time, loc) : xrLocateSpace(space, base, time, loc);
+}
+static XrResult shim_locate_spaces_common(const char *name, XrSession session, const XrSpacesLocateInfo *info,
+                                          XrSpaceLocations *locations) {
+    int any_fake = info && is_fake_space(info->baseSpace);
+    for (uint32_t i = 0; info && i < info->spaceCount && !any_fake; ++i) any_fake = is_fake_space(info->spaces[i]);
+    PFN_xrLocateSpaces next = any_fake ? NULL : (PFN_xrLocateSpaces)dispatcher_proc(name);
+    return next ? next(session, info, locations) : locate_spaces_common(name, session, info, locations);
+}
+static XRAPI_ATTR XrResult XRAPI_CALL shim_locate_spaces(XrSession s, const XrSpacesLocateInfo *i, XrSpaceLocations *l) {
+    return shim_locate_spaces_common("xrLocateSpaces", s, i, l);
+}
+static XRAPI_ATTR XrResult XRAPI_CALL shim_locate_spaces_khr(XrSession s, const XrSpacesLocateInfo *i, XrSpaceLocations *l) {
+    return shim_locate_spaces_common("xrLocateSpacesKHR", s, i, l);
+}
+static XRAPI_ATTR XrResult XRAPI_CALL shim_destroy_space(XrSpace space) {
+    PFN_xrDestroySpace next = is_fake_space(space) ? NULL : (PFN_xrDestroySpace)dispatcher_proc("xrDestroySpace");
+    return next ? next(space) : xrDestroySpace(space);
+}
+static XRAPI_ATTR XrResult XRAPI_CALL shim_poll_event(XrInstance instance, XrEventDataBuffer *event) {
+    scene_events_via_shim = 1;
+    if (event) {  // room events first: OVRPort's dispatcher might drop event types it doesn't know
+        pthread_mutex_lock(&scene_lock);
+        int got = pop_event(event);
+        pthread_mutex_unlock(&scene_lock);
+        if (got) return XR_SUCCESS;
+    }
+    PFN_xrPollEvent next = (PFN_xrPollEvent)dispatcher_proc("xrPollEvent");
+    return next ? next(instance, event) : xrPollEvent(instance, event);
+}
+
 // For native/xrshim: emulated functions that overport's dispatcher doesn't know (it never asks us for them).
 __attribute__((visibility("default"))) PFN_xrVoidFunction framebridge_extension_proc(const char *name) {
    pthread_once(&init_once, initialize);
-    if (fixed_resolution && name && !strcmp(name, "xrGetRecommendedLayerResolutionMETA"))
+    if (!name) return NULL;
+    if (fixed_resolution && !strcmp(name, "xrGetRecommendedLayerResolutionMETA"))
        return (PFN_xrVoidFunction)fixed_recommended_resolution;
-    if (name && !strcmp(name, "framebridge_hide_fb_foveation"))
+    if (!strcmp(name, "framebridge_hide_fb_foveation"))
        return (PFN_xrVoidFunction)framebridge_hide_fb_foveation;
-    if (hide_fb_foveation_vulkan && name) {
+    if (hide_fb_foveation_vulkan) {
        if (!strcmp(name, "xrCreateFoveationProfileFB")) return (PFN_xrVoidFunction)xrCreateFoveationProfileFB;
        if (!strcmp(name, "xrUpdateSwapchainFB")) return (PFN_xrVoidFunction)fb_hide_update_swapchain;
    }
-    if (name && !foveation_fix && (foveation_storage_fix || foveation_eye)) {
+    if (!foveation_fix && (foveation_storage_fix || foveation_eye)) {
        if (!strcmp(name, "xrCreateFoveationProfileFB")) return (PFN_xrVoidFunction)xrCreateFoveationProfileFB;
        if (!strcmp(name, "xrGetFoveationEyeTrackedStateMETA")) return (PFN_xrVoidFunction)xrGetFoveationEyeTrackedStateMETA;
        if (!strcmp(name, "xrDestroyFoveationProfileFB") || !strcmp(name, "xrUpdateSwapchainFB") ||
            !strcmp(name, "xrGetSwapchainStateFB")) return lookup(active_instance, name);
    }
-    if(surface_native && name){
+    if (surface_native) {
 #define NATIVE_PROC(fn) if(!strcmp(name,#fn))return (PFN_xrVoidFunction)fn;
        NATIVE_PROC(xrGetVulkanGraphicsDeviceKHR)
        NATIVE_PROC(xrGetVulkanDeviceExtensionsKHR)
        NATIVE_PROC(xrCreateVulkanDeviceKHR)
        NATIVE_PROC(xrCreateVulkanInstanceKHR)
 #undef NATIVE_PROC
+    }
+    // The shim bypasses OVRPort's fixed dispatch table for all scene calls, including consumers of fake spaces.
+    if (name && emulate_scene) {
+        PFN_xrVoidFunction scene = scene_emulation(name);
+        if (scene) return scene;
+        // xrGetSystemProperties stays with OVRPort (its headset identity; it calls down to our hook for the scene flags)
+#define SCENE_PROC(fn, impl) if (!strcmp(name, #fn)) return (PFN_xrVoidFunction)impl;
+        SCENE_PROC(xrPollEvent, shim_poll_event)
+        SCENE_PROC(xrLocateSpace, shim_locate_space)
+        SCENE_PROC(xrLocateSpaces, shim_locate_spaces)
+        SCENE_PROC(xrLocateSpacesKHR, shim_locate_spaces_khr)
+        SCENE_PROC(xrDestroySpace, shim_destroy_space)
+#undef SCENE_PROC
    }
    PFN_xrVoidFunction color = name ? color_space_emulation(name) : NULL;
    return color ? color : (name ? render_model_emulation(name) : NULL);
@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Included by scene_emu.c. Persist only application anchors; scanned entities remain owned by the room file.
+#include <sys/random.h>
+#include <sys/stat.h>
+#include <unistd.h>
+#ifndef SCENE_EXTERNAL_ROOT
+#define SCENE_EXTERNAL_ROOT "/sdcard/Android/data"
+#endif
+
+static int anchor_path(char *path, size_t size) {
+    char process[256] = {0};
+    FILE *f = fopen("/proc/self/cmdline", "r");
+    if (!f) return 0;
+    size_t n = fread(process, 1, sizeof(process)-1, f);
+    fclose(f);
+    if (!n) return 0;
+    char *colon = strchr(process, ':');
+    if (colon) *colon = 0;
+    // Only package-like process names: never let a command line become a path traversal.
+    if (!strchr(process, '.') || !strcmp(process, ".") || !strcmp(process, "..")) return 0;
+    for (const char *p = process; *p; ++p)
+        if (!((*p >= 'a' && *p <= 'z') || (*p >= 'A' && *p <= 'Z') || (*p >= '0' && *p <= '9') || *p == '.' || *p == '_')) return 0;
+    int len = snprintf(path, size, "%s/%s/files/framebridge-anchors.txt", SCENE_EXTERNAL_ROOT, process);
+    return len > 0 && (size_t)len < size;
+}
+static int anchor_uuid(XrUuidEXT *u) {
+    size_t have = 0;
+    while (have < sizeof(u->data)) {
+        ssize_t n = getrandom(u->data + have, sizeof(u->data) - have, 0);
+        if (n < 0 && errno == EINTR) continue;
+        if (n <= 0) break;
+        have += (size_t)n;
+    }
+    if (have < sizeof(u->data)) {
+        FILE *f = fopen("/dev/urandom", "rb");
+        if (!f) return 0;
+        have = fread(u->data, 1, sizeof(u->data), f);
+        fclose(f);
+        if (have != sizeof(u->data)) return 0;
+    }
+    u->data[6] = (uint8_t)((u->data[6] & 15) | 0x40);
+    u->data[8] = (uint8_t)((u->data[8] & 63) | 0x80);
+    for (int i = 0; i < entity_count; ++i) if (uuid_equal(u, &entities[i].uuid)) return 0;
+    return 1;
+}
+static int write_anchors(void) {
+    char path[4096], tmp[4128];
+    if (!anchor_path(path, sizeof(path))) return 0;
+    snprintf(tmp, sizeof(tmp), "%s.tmp-XXXXXX", path);
+    int fd = mkstemp(tmp);
+    if (fd < 0) return 0;
+    FILE *f = fdopen(fd, "w");
+    if (!f) { close(fd); unlink(tmp); return 0; }
+    int ok = 1;
+    for (int i = 0; i < entity_count; ++i) {
+        const scene_entity *e = &entities[i];
+        if (!e->is_anchor || !e->saved || e->erased) continue;
+        char uuid[33];
+        for (int k = 0; k < 16; ++k) snprintf(uuid + k*2, 3, "%02x", e->uuid.data[k]);
+        const XrPosef p = e->pose_in_stage;
+        if (fprintf(f, "anchor %s %.9g %.9g %.9g %.9g %.9g %.9g %.9g\n", uuid,
+                    p.position.x, p.position.y, p.position.z, p.orientation.x, p.orientation.y, p.orientation.z, p.orientation.w) < 0) ok = 0;
+    }
+    if (fflush(f) || fsync(fd)) ok = 0;
+    if (fclose(f)) ok = 0;
+    if (ok && rename(tmp, path)) ok = 0;
+    if (!ok) { LOG("scene: anchor write failed (%d)", errno); unlink(tmp); }
+    return ok;
+}
+static void load_anchors(void) {
+    char path[4096];
+    if (!anchor_path(path, sizeof(path))) return;
+    FILE *f = fopen(path, "r");
+    if (!f) return;
+    char line[1024], *t[10];
+    unsigned loaded = 0;
+    while (fgets(line, sizeof(line), f)) {
+        if (!strchr(line, '\n') && !feof(f)) { int c; while ((c=fgetc(f)) != EOF && c != '\n') {} continue; }
+        XrUuidEXT uuid; float v[7];
+        int n = room_tokens(line, t, 10);
+        if (n != 9 || strcmp(t[0], "anchor") || !room_uuid(t[1], &uuid) || !room_values(t, 2, 7, v)) continue;
+        float norm = sqrtf(v[3]*v[3]+v[4]*v[4]+v[5]*v[5]+v[6]*v[6]);
+        if (norm < 0.0001f) continue;
+        int duplicate = 0;
+        for (int i = 0; i < entity_count; ++i) duplicate |= uuid_equal(&uuid, &entities[i].uuid);
+        if (duplicate) continue;
+        int i = add_entity((XrPosef){{v[3]/norm,v[4]/norm,v[5]/norm,v[6]/norm},{v[0],v[1],v[2]}}, NULL, 0, 0, 0, 1);
+        if (i < 0) break;
+        entities[i].uuid = uuid; entities[i].saved = 1; ++loaded;
+    }
+    fclose(f);
+    LOG("scene: loaded %u saved anchors", loaded);
+}
+// Batch writes are atomic both on disk and in memory. Failure never silently destroys the old anchor set.
+static XrResult persist_spaces(uint32_t count, const XrSpace *spaces, uint32_t uuid_count, const XrUuidEXT *uuids, int erase) {
+    unsigned char selected[MAX_ENTITIES] = {0}, old_saved[MAX_ENTITIES], old_erased[MAX_ENTITIES];
+    for (uint32_t k = 0; k < count; ++k) {
+        int i = fake_space_index(spaces[k]);
+        if (i < 0) return XR_ERROR_HANDLE_INVALID;
+        if (entities[i].is_anchor) selected[i] = 1;
+    }
+    if (erase) for (int i = 0; i < entity_count; ++i)
+        if (entities[i].is_anchor && !entities[i].erased && uuid_matches(uuid_count, uuids, &entities[i])) selected[i] = 1;
+    int changed = 0;
+    for (int i = 0; i < entity_count; ++i) {
+        old_saved[i] = (unsigned char)entities[i].saved; old_erased[i] = (unsigned char)entities[i].erased;
+        if (selected[i]) { entities[i].saved = !erase; entities[i].erased = erase; changed = 1; }
+    }
+    if (changed && !write_anchors()) {
+        for (int i = 0; i < entity_count; ++i) { entities[i].saved = old_saved[i]; entities[i].erased = old_erased[i]; }
+        return XR_ERROR_RUNTIME_FAILURE;
+    }
+    if (changed) LOG("scene: anchors %s", erase ? "erased" : "saved");
+    return XR_SUCCESS;
+}
@@ -1,16 +1,19 @@
 // SPDX-License-Identifier: GPL-3.0-only
 // Included by frame_adapter.c. Emulates Meta's scene / spatial-entity extensions (XR_FB_spatial_entity,
 // _query, _storage, _container, XR_FB_scene, XR_FB_scene_capture) for mixed-reality apps on runtimes that
-// lack them (Steam Frame). The "room" is a box built from the runtime's STAGE bounds (the guardian /
-// chaperone rectangle): floor, ceiling and four walls, reported as one room anchor with a layout.
+// lack them (Steam Frame). Room files use STAGE coordinates; absent/invalid files retain the guardian box.
 // Entity spaces are fake handles; every function that consumes a space is intercepted for them.

 static float scene_min_size = 1.5f;  // smallest room edge if the guardian is tiny or unavailable
 static int emulate_scene;            // app requested the scene extensions and the runtime lacks them
+static int scene_app_mesh;           // app enabled XR_META_spatial_entity_mesh: only then is the global mesh an entity
+                                     // (an older SDK's scene loader fails on an anchor it can't place)

 static const char *const scene_extensions[] = {
    "XR_FB_spatial_entity", "XR_FB_spatial_entity_query", "XR_FB_spatial_entity_storage",
    "XR_FB_spatial_entity_container", "XR_FB_scene", "XR_FB_scene_capture",
+    "XR_META_spatial_entity_mesh", "XR_META_spatial_entity_discovery", "XR_META_spatial_entity_persistence",
+    "XR_META_boundary_visibility",  // MR games hide the guardian before starting (NOPE asks every frame)
 };
 #define SCENE_EXTENSION_COUNT (sizeof(scene_extensions) / sizeof(scene_extensions[0]))

@@ -42,38 +45,58 @@ static XrPosef pose_inv(XrPosef a) {

 // ---------------------------------------------------------------- entities
 enum { ENT_ROOM, ENT_FLOOR, ENT_CEILING, ENT_WALL0, ENT_WALL1, ENT_WALL2, ENT_WALL3, ENT_FIXED_COUNT };
-#define MAX_ENTITIES 64
+#define MAX_ENTITIES 2048
+#define MAX_OUTLINE 1024

 typedef struct {
    XrSpace handle;       // fake handle given to the app
    XrUuidEXT uuid;
    XrPosef pose_in_stage;
-    const char *label;    // semantic label, NULL if none
+    char label[256];      // comma-separated Meta semantic labels
    XrRect2Df bounds;     // 2D bounds in the entity's local XY plane
-    int has_bounds, is_room, is_anchor;
+    XrRect3DfFB bounds3;
+    XrVector2f *boundary;
+    uint32_t boundary_count;
+    XrVector3f *vertices;
+    uint32_t *indices, vertex_count, index_count;
+    int has_bounds, has_bounds3, is_room, is_anchor, is_wall, erased, saved;
 } scene_entity;

 static pthread_mutex_t scene_lock = PTHREAD_MUTEX_INITIALIZER;
 static scene_entity entities[MAX_ENTITIES];
-static int entity_count;
+static int entity_count, room_entity_count, wall_count, room_from_file;
+static char room_source[32];
+static uint64_t room_universe;
 static XrSpace scene_stage = XR_NULL_HANDLE;  // real STAGE space used to anchor everything
 static XrSession scene_session = XR_NULL_HANDLE;
 static uint64_t next_request = 0x5ce0000001ull;

-#define FAKE_SPACE_TAG 0x5ce0000000000000ull
+// Fit the tag in uintptr_t as the adapter is also built for AArch32. Session generations prevent stale
+// handles from aliasing new room entities when an engine recreates its session in the same process.
+#if UINTPTR_MAX > 0xffffffffu
+#define FAKE_SPACE_TAG ((uintptr_t)0x5ce0000000000000ull)
+#define FAKE_SPACE_MASK ((uintptr_t)0xfff0000000000000ull)
+#else
+#define FAKE_SPACE_TAG ((uintptr_t)0x5ce00000u)
+#define FAKE_SPACE_MASK ((uintptr_t)0xfff00000u)
+#endif
+static unsigned scene_generation;
+
+static int is_fake_space(XrSpace space) { return ((uintptr_t)space & FAKE_SPACE_MASK) == FAKE_SPACE_TAG; }
 static int fake_space_index(XrSpace space) {
-    uint64_t v = (uint64_t)(uintptr_t)space;
-    if ((v & 0xfff0000000000000ull) != FAKE_SPACE_TAG) return -1;
-    int i = (int)(v & 0xffff);
-    return i < entity_count ? i : -1;
+    uintptr_t v = (uintptr_t)space;
+    if ((v & FAKE_SPACE_MASK) != FAKE_SPACE_TAG || ((v >> 12) & 255) != scene_generation) return -1;
+    int i = (int)(v & 4095);
+    return i < entity_count && !entities[i].erased ? i : -1;
 }
-static XrSpace fake_space(int index) { return (XrSpace)(uintptr_t)(FAKE_SPACE_TAG | (uint64_t)index); }
+static XrSpace fake_space(int index) { return (XrSpace)(FAKE_SPACE_TAG | ((uintptr_t)scene_generation << 12) | (uintptr_t)index); }

 static XrUuidEXT make_uuid(int index) {
    XrUuidEXT u;
    for (int i = 0; i < XR_UUID_SIZE_EXT; ++i) u.data[i] = (uint8_t)(0x5c ^ (i * 37) ^ (index * 101));
    u.data[6] = (uint8_t)((u.data[6] & 0x0f) | 0x40);  // version 4 style
    u.data[15] = (uint8_t)index;
+    u.data[14] ^= (uint8_t)((unsigned)index >> 8);
    return u;
 }
 static int uuid_equal(const XrUuidEXT *a, const XrUuidEXT *b) { return !memcmp(a->data, b->data, XR_UUID_SIZE_EXT); }
@@ -86,7 +109,7 @@ static int add_entity(XrPosef pose, const char *label, float w, float h, int is_
    e->handle = fake_space(i);
    e->uuid = make_uuid(i);
    e->pose_in_stage = pose;
-    e->label = label;
+    if (label) snprintf(e->label, sizeof(e->label), "%s", label);
    e->has_bounds = w > 0 && h > 0;
    e->bounds = (XrRect2Df){{-w / 2, -h / 2}, {w, h}};
    e->is_room = is_room;
@@ -94,9 +117,23 @@ static int add_entity(XrPosef pose, const char *label, float w, float h, int is_
    return i;
 }

+static void reset_room(void) {
+    for (int i = 0; i < entity_count; ++i) {
+        free(entities[i].boundary);
+        free(entities[i].vertices);
+        free(entities[i].indices);
+    }
+    memset(entities, 0, sizeof(entities));
+    entity_count = room_entity_count = wall_count = room_from_file = 0;
+    room_universe = 0;
+}
+
+#include "scene_room.c"
+
 // Build the room once the session exists: guardian rectangle -> floor/ceiling/walls.
 static void build_room(void) {
    if (entity_count) return;
+    if (load_room_file()) return;
    float width = 0, depth = 0;
    PFN_xrGetReferenceSpaceBoundsRect bounds_fn =
        (PFN_xrGetReferenceSpaceBoundsRect)lookup(active_instance, "xrGetReferenceSpaceBoundsRect");
@@ -117,10 +154,14 @@ static void build_room(void) {
    add_entity((XrPosef){{0, 0, 0, 1}, {0, 0, 0}}, NULL, 0, 0, 1, 0);                         // ENT_ROOM
    add_entity((XrPosef){{-s, 0, 0, s}, {0, 0, 0}}, "FLOOR", width, depth, 0, 0);             // +Z (normal) -> +Y
    add_entity((XrPosef){{s, 0, 0, s}, {0, h, 0}}, "CEILING", width, depth, 0, 0);            // +Z -> -Y
+    // Walls in loop order around the floor, as Meta's ROOM_LAYOUT lists them (Demeter walks them as an outline).
    add_entity((XrPosef){{0, 0, 0, 1}, {0, h / 2, -depth / 2}}, "WALL_FACE", width, h, 0, 0); // faces +Z
+    add_entity((XrPosef){{0, -s, 0, s}, {width / 2, h / 2, 0}}, "WALL_FACE", depth, h, 0, 0); // faces -X
    add_entity((XrPosef){{0, 1, 0, 0}, {0, h / 2, depth / 2}}, "WALL_FACE", width, h, 0, 0);  // faces -Z
    add_entity((XrPosef){{0, s, 0, s}, {-width / 2, h / 2, 0}}, "WALL_FACE", depth, h, 0, 0); // faces +X
-    add_entity((XrPosef){{0, -s, 0, s}, {width / 2, h / 2, 0}}, "WALL_FACE", depth, h, 0, 0); // faces -X
+    wall_count = 4;
+    room_entity_count = entity_count;
+    for (int i = ENT_WALL0; i < entity_count; ++i) entities[i].is_wall = 1;
 }

 // Supported components per entity.
@@ -128,12 +169,17 @@ static int entity_components(const scene_entity *e, XrSpaceComponentTypeFB *out)
    int n = 0;
    out[n++] = XR_SPACE_COMPONENT_TYPE_LOCATABLE_FB;
    out[n++] = XR_SPACE_COMPONENT_TYPE_STORABLE_FB;
+    out[n++] = XR_SPACE_COMPONENT_TYPE_SHARABLE_FB;  // Meta's runtime lists it; nothing is shared from here
    if (e->is_room) {
        out[n++] = XR_SPACE_COMPONENT_TYPE_ROOM_LAYOUT_FB;
        out[n++] = XR_SPACE_COMPONENT_TYPE_SPACE_CONTAINER_FB;
    } else if (!e->is_anchor) {
-        out[n++] = XR_SPACE_COMPONENT_TYPE_BOUNDED_2D_FB;
-        out[n++] = XR_SPACE_COMPONENT_TYPE_SEMANTIC_LABELS_FB;
+        if (e->has_bounds) {
+            out[n++] = XR_SPACE_COMPONENT_TYPE_BOUNDED_2D_FB;
+        }
+        if (e->has_bounds3) out[n++] = XR_SPACE_COMPONENT_TYPE_BOUNDED_3D_FB;
+        if (e->vertex_count) out[n++] = XR_SPACE_COMPONENT_TYPE_TRIANGLE_MESH_META;
+        if (e->label[0]) out[n++] = XR_SPACE_COMPONENT_TYPE_SEMANTIC_LABELS_FB;
    }
    return n;
 }
@@ -148,13 +194,37 @@ static int entity_has_component(const scene_entity *e, XrSpaceComponentTypeFB ty
 #define MAX_EVENTS 64
 static XrEventDataBuffer scene_events[MAX_EVENTS];
 static int event_head, event_tail;
+static int event_free(void) { return (event_head - event_tail - 1 + MAX_EVENTS) % MAX_EVENTS; }
 static void push_event(const void *event, size_t size) {
    if ((event_tail + 1) % MAX_EVENTS == event_head) return;
    memset(&scene_events[event_tail], 0, sizeof(XrEventDataBuffer));
    memcpy(&scene_events[event_tail], event, size);
    event_tail = (event_tail + 1) % MAX_EVENTS;
 }
+// A real scan takes a while; an answer in the same frame may be missed by a game's prompt logic (Pinball FX asked
+// again at once). The completion waits this long in its own slot. Caller of both holds scene_lock.
+static int scene_capture_delay_ms = 1500;
+static XrEventDataSceneCaptureCompleteFB pending_capture;
+static uint64_t pending_capture_at;  // CLOCK_MONOTONIC ns, 0 = none
+static uint64_t scene_now_ns(void) {
+    struct timespec ts;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    return (uint64_t)ts.tv_sec * 1000000000ull + (uint64_t)ts.tv_nsec;
+}
+static int scan_waiting;
+static uint64_t scan_started_at, scan_poll_at;
+static int scan_acked;
+static void poll_scan(uint64_t now);
 static int pop_event(XrEventDataBuffer *out) {  // caller holds scene_lock
+    uint64_t now = scene_now_ns();
+    if (scan_waiting) poll_scan(now);
+    if (!scan_waiting && pending_capture_at && now >= pending_capture_at) {
+        memset(out, 0, sizeof(*out));
+        memcpy(out, &pending_capture, sizeof(pending_capture));
+        pending_capture_at = 0;
+        LOG("scene: capture complete delivered (request %llu)", (unsigned long long)pending_capture.requestId);
+        return 1;
+    }
    if (event_head == event_tail) return 0;
    memcpy(out, &scene_events[event_head], sizeof(XrEventDataBuffer));
    event_head = (event_head + 1) % MAX_EVENTS;
@@ -171,6 +241,7 @@ static int stage_pose(XrSpace space, XrTime time, XrPosef *pose, XrSpaceLocation
                 XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT | XR_SPACE_LOCATION_POSITION_TRACKED_BIT;
        return 1;
    }
+    if (is_fake_space(space)) return 0;  // erased or from a prior session: never pass a fake handle to SteamVR
    PFN_xrLocateSpace locate = (PFN_xrLocateSpace)lookup(active_instance, "xrLocateSpace");
    if (!locate || !scene_stage) return 0;
    XrSpaceLocation loc = {XR_TYPE_SPACE_LOCATION, NULL, 0, {{0, 0, 0, 1}, {0, 0, 0}}};
@@ -181,7 +252,7 @@ static int stage_pose(XrSpace space, XrTime time, XrPosef *pose, XrSpaceLocation
 }
 // Locate `space` in `base` when either is fake. Returns 0 if neither is fake (caller forwards).
 static int locate_fake(XrSpace space, XrSpace base, XrTime time, XrPosef *pose, XrSpaceLocationFlags *flags) {
-    if (fake_space_index(space) < 0 && fake_space_index(base) < 0) return 0;
+    if (!is_fake_space(space) && !is_fake_space(base)) return 0;
    XrPosef s, b;
    XrSpaceLocationFlags fs = 0, fb = 0;
    if (!stage_pose(space, time, &s, &fs) || !stage_pose(base, time, &b, &fb)) {
@@ -195,99 +266,99 @@ static int locate_fake(XrSpace space, XrSpace base, XrTime time, XrPosef *pose,
 }

 // ---------------------------------------------------------------- emulated entry points
-static XRAPI_ATTR XrResult XRAPI_CALL emu_query_spaces(XrSession session, const XrSpaceQueryInfoBaseHeaderFB *info,
-                                                       XrAsyncRequestIdFB *request) {
-    if (!info || !request) return XR_ERROR_VALIDATION_FAILURE;
-    pthread_mutex_lock(&scene_lock);
-    scene_session = session;
-    build_room();
-    *request = next_request++;
-    XrEventDataSpaceQueryResultsAvailableFB avail = {XR_TYPE_EVENT_DATA_SPACE_QUERY_RESULTS_AVAILABLE_FB, NULL, *request};
-    XrEventDataSpaceQueryCompleteFB done = {XR_TYPE_EVENT_DATA_SPACE_QUERY_COMPLETE_FB, NULL, *request, XR_SUCCESS};
-    push_event(&avail, sizeof(avail));
-    push_event(&done, sizeof(done));
-    pthread_mutex_unlock(&scene_lock);
-    return XR_SUCCESS;
-}
-
-// Query filters are kept per request so retrieve can apply them.
+// Results are snapshotted before their available event is queued, so callers on another thread cannot
+// observe a half-stored filter. A bounded request history supports the count/data calls independently.
+#define MAX_QUERIES 64
 typedef struct {
    XrAsyncRequestIdFB id;
-    int has_component;
-    XrSpaceComponentTypeFB component;
-    uint32_t uuid_count;
-    XrUuidEXT uuids[64];
-} query_filter;
-static query_filter filters[16];
-static int filter_next;
-
-static void store_filter(XrAsyncRequestIdFB id, const XrSpaceQueryInfoFB *q) {
-    query_filter *f = &filters[filter_next++ % 16];
-    memset(f, 0, sizeof(*f));
-    f->id = id;
-    const XrSpaceFilterInfoBaseHeaderFB *flt = q->filter;
-    if (flt && flt->type == XR_TYPE_SPACE_COMPONENT_FILTER_INFO_FB) {
-        f->has_component = 1;
-        f->component = ((const XrSpaceComponentFilterInfoFB *)flt)->componentType;
-    } else if (flt && flt->type == XR_TYPE_SPACE_UUID_FILTER_INFO_FB) {
-        const XrSpaceUuidFilterInfoFB *u = (const XrSpaceUuidFilterInfoFB *)flt;
-        f->uuid_count = u->uuidCount < 64 ? u->uuidCount : 64;
-        for (uint32_t i = 0; i < f->uuid_count; ++i) f->uuids[i] = u->uuids[i];
-    }
+    uint32_t count;
+    XrSpaceQueryResultFB *results;
+} scene_query;
+static scene_query queries[MAX_QUERIES];
+static unsigned query_next;
+static scene_query *new_query(void) {
+    scene_query *q = &queries[query_next % MAX_QUERIES];
+    XrSpaceQueryResultFB *results = malloc((size_t)entity_count * sizeof(*results));
+    if (!results) return NULL;
+    ++query_next;
+    free(q->results);
+    *q = (scene_query){next_request++, 0, results};
+    return q;
 }
-
-static XRAPI_ATTR XrResult XRAPI_CALL emu_query_spaces_filtered(XrSession session, const XrSpaceQueryInfoBaseHeaderFB *info,
-                                                                XrAsyncRequestIdFB *request) {
-    XrResult r = emu_query_spaces(session, info, request);
-    if (XR_SUCCEEDED(r) && info->type == XR_TYPE_SPACE_QUERY_INFO_FB) {
-        pthread_mutex_lock(&scene_lock);
-        store_filter(*request, (const XrSpaceQueryInfoFB *)info);
-        const XrSpaceQueryInfoFB *q = (const XrSpaceQueryInfoFB *)info;
-        LOG("scene: query request=%llu filter=%d", (unsigned long long)*request, q->filter ? q->filter->type : 0);
-        pthread_mutex_unlock(&scene_lock);
-    }
-    return r;
+static scene_query *find_query(XrAsyncRequestIdFB id) {
+    for (int i = 0; i < MAX_QUERIES; ++i) if (queries[i].id == id) return &queries[i];
+    return NULL;
 }
+static int uuid_matches(uint32_t n, const XrUuidEXT *uuids, const scene_entity *e) {
+    for (uint32_t i = 0; i < n; ++i) if (uuid_equal(&uuids[i], &e->uuid)) return 1;
+    return 0;
+}
+#include "scene_anchors.c"
+#include "scene_scan.c"

-static int filter_matches(const query_filter *f, const scene_entity *e) {
+static int fb_filter_matches(const XrSpaceFilterInfoBaseHeaderFB *f, const scene_entity *e) {
    if (!f) return 1;
-    if (f->has_component) return entity_has_component(e, f->component);
-    if (f->uuid_count) {
-        for (uint32_t i = 0; i < f->uuid_count; ++i) if (uuid_equal(&f->uuids[i], &e->uuid)) return 1;
-        return 0;
+    if (f->type == XR_TYPE_SPACE_COMPONENT_FILTER_INFO_FB)
+        return entity_has_component(e, ((const XrSpaceComponentFilterInfoFB *)f)->componentType);
+    if (f->type == XR_TYPE_SPACE_UUID_FILTER_INFO_FB) {
+        const XrSpaceUuidFilterInfoFB *u = (const XrSpaceUuidFilterInfoFB *)f;
+        return u->uuids && uuid_matches(u->uuidCount, u->uuids, e);
    }
    return 1;
 }
-
+static void log_head_in_room(void);  // scene_meta.c
+static XRAPI_ATTR XrResult XRAPI_CALL emu_query_spaces_filtered(XrSession session, const XrSpaceQueryInfoBaseHeaderFB *info,
+                                                                XrAsyncRequestIdFB *request) {
+    if (!info || !request || info->type != XR_TYPE_SPACE_QUERY_INFO_FB) return XR_ERROR_VALIDATION_FAILURE;
+    const XrSpaceQueryInfoFB *info_fb = (const XrSpaceQueryInfoFB *)info;
+    pthread_mutex_lock(&scene_lock);
+    scene_session = session;
+    build_room();
+    if (event_free() < 2) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_LIMIT_REACHED; }
+    scene_query *q = new_query();
+    if (!q) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_OUT_OF_MEMORY; }
+    for (int i = 0; i < entity_count && q->count < info_fb->maxResultCount; ++i) {
+        scene_entity *e = &entities[i];
+        if (!e->erased && fb_filter_matches(info_fb->filter, e))
+            q->results[q->count++] = (XrSpaceQueryResultFB){e->handle, e->uuid};
+    }
+    *request = q->id;
+    XrEventDataSpaceQueryResultsAvailableFB avail = {XR_TYPE_EVENT_DATA_SPACE_QUERY_RESULTS_AVAILABLE_FB, NULL, *request};
+    XrEventDataSpaceQueryCompleteFB done = {XR_TYPE_EVENT_DATA_SPACE_QUERY_COMPLETE_FB, NULL, *request, XR_SUCCESS};
+    push_event(&avail, sizeof(avail)); push_event(&done, sizeof(done));
+    LOG("scene: query request=%llu results=%u", (unsigned long long)*request, q->count);
+    log_head_in_room();
+    pthread_mutex_unlock(&scene_lock);
+    return XR_SUCCESS;
+}
 static XRAPI_ATTR XrResult XRAPI_CALL emu_retrieve_results(XrSession session, XrAsyncRequestIdFB request,
                                                           XrSpaceQueryResultsFB *results) {
    (void)session;
    if (!results) return XR_ERROR_VALIDATION_FAILURE;
    pthread_mutex_lock(&scene_lock);
-    const query_filter *f = NULL;
-    for (int i = 0; i < 16; ++i) if (filters[i].id == request) f = &filters[i];
-    uint32_t n = 0;
-    for (int i = 0; i < entity_count; ++i) {
-        if (!filter_matches(f, &entities[i])) continue;
-        if (results->resultCapacityInput && n < results->resultCapacityInput && results->results) {
-            results->results[n].space = entities[i].handle;
-            results->results[n].uuid = entities[i].uuid;
+    scene_query *q = find_query(request);
+    XrResult r = XR_SUCCESS;
+    if (!q) r = XR_ERROR_VALIDATION_FAILURE;
+    else {
+        results->resultCountOutput = q->count;
+        if (results->resultCapacityInput && results->resultCapacityInput < q->count) r = XR_ERROR_SIZE_INSUFFICIENT;
+        else if (results->resultCapacityInput) {
+            if (!results->results) r = XR_ERROR_VALIDATION_FAILURE;
+            else memcpy(results->results, q->results, q->count * sizeof(*q->results));
        }
-        ++n;
    }
-    results->resultCountOutput = n;
    pthread_mutex_unlock(&scene_lock);
-    return (results->resultCapacityInput && results->resultCapacityInput < n) ? XR_ERROR_SIZE_INSUFFICIENT : XR_SUCCESS;
+    return r;
 }

-static XRAPI_ATTR XrResult XRAPI_CALL emu_get_uuid(XrSpace space, XrUuidEXT *uuid) {
+static XRAPI_ATTR XrResult XRAPI_CALL scene_get_uuid(XrSpace space, XrUuidEXT *uuid) {
    int i = fake_space_index(space);
    if (i < 0 || !uuid) return XR_ERROR_HANDLE_INVALID;
    *uuid = entities[i].uuid;
    return XR_SUCCESS;
 }

-static XRAPI_ATTR XrResult XRAPI_CALL emu_enumerate_components(XrSpace space, uint32_t capacity, uint32_t *count,
+static XRAPI_ATTR XrResult XRAPI_CALL scene_enumerate_components(XrSpace space, uint32_t capacity, uint32_t *count,
                                                               XrSpaceComponentTypeFB *types) {
    int i = fake_space_index(space);
    if (i < 0 || !count) return XR_ERROR_HANDLE_INVALID;
@@ -296,16 +367,33 @@ static XRAPI_ATTR XrResult XRAPI_CALL emu_enumerate_components(XrSpace space, ui
    *count = (uint32_t)n;
    if (!capacity) return XR_SUCCESS;
    if (capacity < (uint32_t)n) return XR_ERROR_SIZE_INSUFFICIENT;
+    if (!types) return XR_ERROR_VALIDATION_FAILURE;
    for (int k = 0; k < n; ++k) types[k] = list[k];
    return XR_SUCCESS;
 }

+// Which entity refused which component (the first ones only): an app's scene loader gives up on the whole room over
+// one of these, and OVRPlugin's own error line doesn't name the component (Demeter, 2026-10-16).
+static void log_refused_component(const char *op, int i, XrSpaceComponentTypeFB type) {
+    static int logged;
+    if (logged >= 20) return;
+    ++logged;
+    const scene_entity *e = &entities[i];
+    LOG("scene: %s component %d refused on %s (entity %d)", op, (int)type,
+        e->is_room ? "room" : e->is_anchor ? "app anchor" : e->label[0] ? e->label : "unlabelled", i);
+}
+
 static XRAPI_ATTR XrResult XRAPI_CALL emu_set_component_status(XrSpace space, const XrSpaceComponentStatusSetInfoFB *info,
                                                               XrAsyncRequestIdFB *request) {
-    int i = fake_space_index(space);
-    if (i < 0 || !info || !request) return XR_ERROR_HANDLE_INVALID;
-    if (!entity_has_component(&entities[i], info->componentType)) return XR_ERROR_SPACE_COMPONENT_NOT_SUPPORTED_FB;
    pthread_mutex_lock(&scene_lock);
+    int i = fake_space_index(space);
+    if (i < 0 || !info || !request) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_HANDLE_INVALID; }
+    if (!entity_has_component(&entities[i], info->componentType)) {
+        log_refused_component("set", i, info->componentType);
+        pthread_mutex_unlock(&scene_lock);
+        return XR_ERROR_SPACE_COMPONENT_NOT_SUPPORTED_FB;
+    }
+    if (!event_free()) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_LIMIT_REACHED; }
    *request = next_request++;
    XrEventDataSpaceSetStatusCompleteFB e = {XR_TYPE_EVENT_DATA_SPACE_SET_STATUS_COMPLETE_FB, NULL, *request, XR_SUCCESS,
                                             space, entities[i].uuid, info->componentType, info->enabled};
@@ -314,44 +402,49 @@ static XRAPI_ATTR XrResult XRAPI_CALL emu_set_component_status(XrSpace space, co
    return XR_SUCCESS;
 }

-static XRAPI_ATTR XrResult XRAPI_CALL emu_get_component_status(XrSpace space, XrSpaceComponentTypeFB type,
+static XRAPI_ATTR XrResult XRAPI_CALL scene_get_component_status(XrSpace space, XrSpaceComponentTypeFB type,
                                                               XrSpaceComponentStatusFB *status) {
    int i = fake_space_index(space);
    if (i < 0 || !status) return XR_ERROR_HANDLE_INVALID;
-    if (!entity_has_component(&entities[i], type)) return XR_ERROR_SPACE_COMPONENT_NOT_SUPPORTED_FB;
+    if (!entity_has_component(&entities[i], type)) {
+        log_refused_component("get", i, type);
+        return XR_ERROR_SPACE_COMPONENT_NOT_SUPPORTED_FB;
+    }
    status->enabled = XR_TRUE;
    status->changePending = XR_FALSE;
    return XR_SUCCESS;
 }

-static XRAPI_ATTR XrResult XRAPI_CALL emu_get_container(XrSession session, XrSpace space, XrSpaceContainerFB *container) {
+static XRAPI_ATTR XrResult XRAPI_CALL scene_get_container(XrSession session, XrSpace space, XrSpaceContainerFB *container) {
    (void)session;
    int i = fake_space_index(space);
    if (i < 0 || !container) return XR_ERROR_HANDLE_INVALID;
    if (!entities[i].is_room) return XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB;
-    uint32_t n = ENT_FIXED_COUNT - 1;  // everything except the room itself
+    uint32_t n = room_entity_count - 1;  // everything except the room itself
    container->uuidCountOutput = n;
    if (!container->uuidCapacityInput) return XR_SUCCESS;
    if (container->uuidCapacityInput < n) return XR_ERROR_SIZE_INSUFFICIENT;
+    if (!container->uuids) return XR_ERROR_VALIDATION_FAILURE;
    for (uint32_t k = 0; k < n; ++k) container->uuids[k] = entities[ENT_FLOOR + k].uuid;
    return XR_SUCCESS;
 }

-static XRAPI_ATTR XrResult XRAPI_CALL emu_get_room_layout(XrSession session, XrSpace space, XrRoomLayoutFB *layout) {
+static XRAPI_ATTR XrResult XRAPI_CALL scene_get_room_layout(XrSession session, XrSpace space, XrRoomLayoutFB *layout) {
    (void)session;
    int i = fake_space_index(space);
    if (i < 0 || !layout) return XR_ERROR_HANDLE_INVALID;
    if (!entities[i].is_room) return XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB;
    layout->floorUuid = entities[ENT_FLOOR].uuid;
    layout->ceilingUuid = entities[ENT_CEILING].uuid;
-    layout->wallUuidCountOutput = 4;
+    layout->wallUuidCountOutput = (uint32_t)wall_count;
    if (!layout->wallUuidCapacityInput) return XR_SUCCESS;
-    if (layout->wallUuidCapacityInput < 4) return XR_ERROR_SIZE_INSUFFICIENT;
-    for (int k = 0; k < 4; ++k) layout->wallUuids[k] = entities[ENT_WALL0 + k].uuid;
+    if (layout->wallUuidCapacityInput < (uint32_t)wall_count) return XR_ERROR_SIZE_INSUFFICIENT;
+    if (!layout->wallUuids) return XR_ERROR_VALIDATION_FAILURE;
+    for (int k = 0; k < wall_count; ++k) layout->wallUuids[k] = entities[ENT_WALL0 + k].uuid;
    return XR_SUCCESS;
 }

-static XRAPI_ATTR XrResult XRAPI_CALL emu_get_bounding_box_2d(XrSession session, XrSpace space, XrRect2Df *rect) {
+static XRAPI_ATTR XrResult XRAPI_CALL scene_get_bounding_box_2d(XrSession session, XrSpace space, XrRect2Df *rect) {
    (void)session;
    int i = fake_space_index(space);
    if (i < 0 || !rect) return XR_ERROR_HANDLE_INVALID;
@@ -360,19 +453,29 @@ static XRAPI_ATTR XrResult XRAPI_CALL emu_get_bounding_box_2d(XrSession session,
    return XR_SUCCESS;
 }

-static XRAPI_ATTR XrResult XRAPI_CALL emu_get_bounding_box_3d(XrSession session, XrSpace space, XrRect3DfFB *box) {
-    (void)session; (void)space; (void)box;
-    return XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB;
+static XRAPI_ATTR XrResult XRAPI_CALL scene_get_bounding_box_3d(XrSession session, XrSpace space, XrRect3DfFB *box) {
+    (void)session;
+    int i = fake_space_index(space);
+    if (i < 0 || !box) return XR_ERROR_HANDLE_INVALID;
+    if (!entities[i].has_bounds3) return XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB;
+    *box = entities[i].bounds3;
+    return XR_SUCCESS;
 }

-static XRAPI_ATTR XrResult XRAPI_CALL emu_get_boundary_2d(XrSession session, XrSpace space, XrBoundary2DFB *boundary) {
+static XRAPI_ATTR XrResult XRAPI_CALL scene_get_boundary_2d(XrSession session, XrSpace space, XrBoundary2DFB *boundary) {
    (void)session;
    int i = fake_space_index(space);
    if (i < 0 || !boundary) return XR_ERROR_HANDLE_INVALID;
    if (!entities[i].has_bounds) return XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB;
-    boundary->vertexCountOutput = 4;
+    uint32_t n = entities[i].boundary_count ? entities[i].boundary_count : 4;
+    boundary->vertexCountOutput = n;
    if (!boundary->vertexCapacityInput) return XR_SUCCESS;
-    if (boundary->vertexCapacityInput < 4) return XR_ERROR_SIZE_INSUFFICIENT;
+    if (boundary->vertexCapacityInput < n) return XR_ERROR_SIZE_INSUFFICIENT;
+    if (!boundary->vertices) return XR_ERROR_VALIDATION_FAILURE;
+    if (entities[i].boundary_count) {
+        memcpy(boundary->vertices, entities[i].boundary, n * sizeof(*boundary->vertices));
+        return XR_SUCCESS;
+    }
    const XrRect2Df b = entities[i].bounds;
    boundary->vertices[0] = (XrVector2f){b.offset.x, b.offset.y};
    boundary->vertices[1] = (XrVector2f){b.offset.x + b.extent.width, b.offset.y};
@@ -381,16 +484,86 @@ static XRAPI_ATTR XrResult XRAPI_CALL emu_get_boundary_2d(XrSession session, XrS
    return XR_SUCCESS;
 }

-static XRAPI_ATTR XrResult XRAPI_CALL emu_get_semantic_labels(XrSession session, XrSpace space, XrSemanticLabelsFB *labels) {
+static XRAPI_ATTR XrResult XRAPI_CALL scene_get_triangle_mesh(XrSpace space, const XrSpaceTriangleMeshGetInfoMETA *info,
+                                                          XrSpaceTriangleMeshMETA *mesh) {
+    (void)info;
+    int i = fake_space_index(space);
+    if (i < 0 || !mesh) return XR_ERROR_HANDLE_INVALID;
+    const scene_entity *e = &entities[i];
+    if (!e->vertex_count) return XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB;
+    mesh->vertexCountOutput = e->vertex_count;
+    mesh->indexCountOutput = e->index_count;
+    if ((mesh->vertexCapacityInput && mesh->vertexCapacityInput < e->vertex_count) ||
+        (mesh->indexCapacityInput && mesh->indexCapacityInput < e->index_count)) return XR_ERROR_SIZE_INSUFFICIENT;
+    if ((mesh->vertexCapacityInput && !mesh->vertices) || (mesh->indexCapacityInput && !mesh->indices))
+        return XR_ERROR_VALIDATION_FAILURE;
+    if (mesh->vertexCapacityInput) memcpy(mesh->vertices, e->vertices, e->vertex_count * sizeof(*e->vertices));
+    if (mesh->indexCapacityInput) memcpy(mesh->indices, e->indices, e->index_count * sizeof(*e->indices));
+    return XR_SUCCESS;
+}
+
+// Labels as Meta's runtime hands them to an app (XR_FB_scene): an app that sends no XrSemanticLabelsSupportInfoFB
+// knows only the first label set; one that does gets "OTHER" for labels missing from its recognizedLabels, WALL_FACE
+// for invisible walls unless it accepts them, and DESK for TABLE unless it accepts that migration. Older Meta SDKs
+// (Demeter, 2026-10-16) rejected a whole scanned room over one INVISIBLE_WALL_FACE and kept asking for Space Setup.
+static const char *const scene_legacy_labels = "DESK,COUCH,FLOOR,CEILING,WALL_FACE,DOOR_FRAME,WINDOW_FRAME,OTHER";
+
+static int label_listed(const char *list, const char *label, size_t len) {
+    for (const char *p = list; p && *p;) {
+        const char *end = strchr(p, ',');
+        size_t n = end ? (size_t)(end - p) : strlen(p);
+        if (n == len && !strncmp(p, label, len)) return 1;
+        p = end ? end + 1 : NULL;
+    }
+    return 0;
+}
+
+static void scene_app_labels(const char *label, const XrSemanticLabelsFB *labels, char *out, size_t size) {
+    const XrSemanticLabelsSupportInfoFB *support = NULL;
+    for (const XrBaseInStructure *n = labels->next; n; n = n->next)
+        if (n->type == XR_TYPE_SEMANTIC_LABELS_SUPPORT_INFO_FB) support = (const XrSemanticLabelsSupportInfoFB *)n;
+    const char *known = support ? support->recognizedLabels : scene_legacy_labels;
+    XrSemanticLabelsSupportFlagsFB flags = support ? support->flags : 0;
+    out[0] = 0;
+    for (const char *p = label; *p;) {
+        const char *end = strchr(p, ',');
+        size_t len = end ? (size_t)(end - p) : strlen(p);
+        char one[64];
+        snprintf(one, sizeof(one), "%.*s", (int)len, p);
+        if (!strcmp(one, "INVISIBLE_WALL_FACE") && !(flags & XR_SEMANTIC_LABELS_SUPPORT_ACCEPT_INVISIBLE_WALL_FACE_BIT_FB))
+            snprintf(one, sizeof(one), "WALL_FACE");
+        if (!strcmp(one, "TABLE") && !(flags & XR_SEMANTIC_LABELS_SUPPORT_ACCEPT_DESK_TO_TABLE_MIGRATION_BIT_FB))
+            snprintf(one, sizeof(one), "DESK");
+        if (known && *known && !label_listed(known, one, strlen(one))) snprintf(one, sizeof(one), "OTHER");
+        if (!label_listed(out, one, strlen(one)))
+            snprintf(out + strlen(out), size - strlen(out), "%s%s", out[0] ? "," : "", one);
+        p = end ? end + 1 : p + len;
+    }
+}
+
+static XRAPI_ATTR XrResult XRAPI_CALL scene_get_semantic_labels(XrSession session, XrSpace space, XrSemanticLabelsFB *labels) {
    (void)session;
    int i = fake_space_index(space);
    if (i < 0 || !labels) return XR_ERROR_HANDLE_INVALID;
-    if (!entities[i].label) return XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB;
-    uint32_t n = (uint32_t)strlen(entities[i].label) + 1;
+    if (!entities[i].label[0]) return XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB;
+    char text[sizeof(entities[0].label)];
+    scene_app_labels(entities[i].label, labels, text, sizeof(text));
+    uint32_t n = (uint32_t)strlen(text) + 1;
    labels->bufferCountOutput = n;
    if (!labels->bufferCapacityInput) return XR_SUCCESS;
    if (labels->bufferCapacityInput < n) return XR_ERROR_SIZE_INSUFFICIENT;
-    memcpy(labels->buffer, entities[i].label, n);
+    if (!labels->buffer) return XR_ERROR_VALIDATION_FAILURE;
+    memcpy(labels->buffer, text, n);
+    static unsigned char logged[MAX_ENTITIES];  // diagnostics: what each entity is called for this app, once
+    if (!logged[i]) {
+        logged[i] = 1;
+        const XrSemanticLabelsSupportInfoFB *support = NULL;
+        for (const XrBaseInStructure *s = labels->next; s; s = s->next)
+            if (s->type == XR_TYPE_SEMANTIC_LABELS_SUPPORT_INFO_FB) support = (const XrSemanticLabelsSupportInfoFB *)s;
+        LOG("scene: labels of entity %d: %s -> \"%s\" (app's labels: %s, flags 0x%llx)", i, entities[i].label, text,
+            support && support->recognizedLabels ? support->recognizedLabels : "none sent, legacy set",
+            support ? (unsigned long long)support->flags : 0ULL);
+    }
    return XR_SUCCESS;
 }

@@ -401,11 +574,22 @@ static XRAPI_ATTR XrResult XRAPI_CALL emu_request_scene_capture(XrSession sessio
    pthread_mutex_lock(&scene_lock);
    scene_session = session;
    build_room();
+    if (!event_free() || pending_capture_at) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_LIMIT_REACHED; }
    *request = next_request++;
    XrEventDataSceneCaptureCompleteFB e = {XR_TYPE_EVENT_DATA_SCENE_CAPTURE_COMPLETE_FB, NULL, *request, XR_SUCCESS};
-    push_event(&e, sizeof(e));
+    if (scene_scan_request && start_scan(*request)) {
+        pending_capture = e;
+        pending_capture_at = scan_started_at + (uint64_t)scene_capture_delay_ms * 1000000ull;
+    } else if (scene_capture_delay_ms > 0) {
+        pending_capture = e;
+        pending_capture_at = scene_now_ns() + (uint64_t)scene_capture_delay_ms * 1000000ull;
+    } else {
+        push_event(&e, sizeof(e));
+    }
+    if (scan_waiting) LOG("scene: capture requested -> waiting for FramePort");
+    else LOG("scene: capture requested -> %s (complete in %d ms)", room_from_file ? "scanned room" : "guardian box",
+             scene_capture_delay_ms);
    pthread_mutex_unlock(&scene_lock);
-    LOG("scene: capture requested -> using guardian room");
    return XR_SUCCESS;
 }

@@ -417,9 +601,16 @@ static XRAPI_ATTR XrResult XRAPI_CALL emu_create_anchor(XrSession session, const
    build_room();
    XrPosef base = {{0, 0, 0, 1}, {0, 0, 0}};
    XrSpaceLocationFlags flags = 0;
-    stage_pose(info->space, info->time, &base, &flags);
+    if (event_free() < 1) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_LIMIT_REACHED; }
+    if (!stage_pose(info->space, info->time, &base, &flags) ||
+        !(flags & XR_SPACE_LOCATION_POSITION_VALID_BIT) || !(flags & XR_SPACE_LOCATION_ORIENTATION_VALID_BIT)) {
+        pthread_mutex_unlock(&scene_lock); return XR_ERROR_POSE_INVALID;
+    }
+    XrUuidEXT uuid;
+    if (!anchor_uuid(&uuid)) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_RUNTIME_FAILURE; }
    int i = add_entity(pose_mul(base, info->poseInSpace), NULL, 0, 0, 0, 1);
    *request = next_request++;
+    if (i >= 0) entities[i].uuid = uuid;
    XrEventDataSpatialAnchorCreateCompleteFB e = {XR_TYPE_EVENT_DATA_SPATIAL_ANCHOR_CREATE_COMPLETE_FB, NULL, *request,
        i >= 0 ? XR_SUCCESS : XR_ERROR_LIMIT_REACHED, i >= 0 ? entities[i].handle : XR_NULL_HANDLE,
        i >= 0 ? entities[i].uuid : (XrUuidEXT){{0}}};
@@ -431,31 +622,136 @@ static XRAPI_ATTR XrResult XRAPI_CALL emu_create_anchor(XrSession session, const
 static XRAPI_ATTR XrResult XRAPI_CALL emu_save_space(XrSession session, const XrSpaceSaveInfoFB *info, XrAsyncRequestIdFB *request) {
    (void)session;
    if (!info || !request) return XR_ERROR_VALIDATION_FAILURE;
-    int i = fake_space_index(info->space);
    pthread_mutex_lock(&scene_lock);
+    int i = fake_space_index(info->space);
+    if (i < 0) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_HANDLE_INVALID; }
+    if (!event_free()) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_LIMIT_REACHED; }
+    XrResult r = persist_spaces(1, &info->space, 0, NULL, 0);
    *request = next_request++;
-    XrEventDataSpaceSaveCompleteFB e = {XR_TYPE_EVENT_DATA_SPACE_SAVE_COMPLETE_FB, NULL, *request, XR_SUCCESS, info->space,
-                                        i >= 0 ? entities[i].uuid : (XrUuidEXT){{0}}, info->location};
+    XrEventDataSpaceSaveCompleteFB e = {XR_TYPE_EVENT_DATA_SPACE_SAVE_COMPLETE_FB, NULL, *request, r, info->space,
+                                        entities[i].uuid, info->location};
    push_event(&e, sizeof(e));
    pthread_mutex_unlock(&scene_lock);
    return XR_SUCCESS;
 }
-
 static XRAPI_ATTR XrResult XRAPI_CALL emu_erase_space(XrSession session, const XrSpaceEraseInfoFB *info, XrAsyncRequestIdFB *request) {
    (void)session;
    if (!info || !request) return XR_ERROR_VALIDATION_FAILURE;
-    int i = fake_space_index(info->space);
    pthread_mutex_lock(&scene_lock);
+    int i = fake_space_index(info->space);
+    if (i < 0) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_HANDLE_INVALID; }
+    if (!event_free()) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_LIMIT_REACHED; }
+    XrResult r = persist_spaces(1, &info->space, 0, NULL, 1);
    *request = next_request++;
-    XrEventDataSpaceEraseCompleteFB e = {XR_TYPE_EVENT_DATA_SPACE_ERASE_COMPLETE_FB, NULL, *request, XR_SUCCESS, info->space,
-                                         i >= 0 ? entities[i].uuid : (XrUuidEXT){{0}}, info->location};
+    XrEventDataSpaceEraseCompleteFB e = {XR_TYPE_EVENT_DATA_SPACE_ERASE_COMPLETE_FB, NULL, *request, r, info->space,
+                                         entities[i].uuid, info->location};
    push_event(&e, sizeof(e));
    pthread_mutex_unlock(&scene_lock);
    return XR_SUCCESS;
 }

+// Reads share the mutation lock: engine worker threads may retrieve geometry while anchors are saved.
+static XRAPI_ATTR XrResult XRAPI_CALL emu_get_uuid(XrSpace space, XrUuidEXT *uuid) {
+    pthread_mutex_lock(&scene_lock);
+    XrResult r = scene_get_uuid(space, uuid);
+    pthread_mutex_unlock(&scene_lock);
+    return r;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_enumerate_components(XrSpace space, uint32_t capacity, uint32_t *count, XrSpaceComponentTypeFB *types) {
+    pthread_mutex_lock(&scene_lock);
+    XrResult r = scene_enumerate_components(space, capacity, count, types);
+    pthread_mutex_unlock(&scene_lock);
+    return r;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_get_component_status(XrSpace space, XrSpaceComponentTypeFB type, XrSpaceComponentStatusFB *status) {
+    pthread_mutex_lock(&scene_lock);
+    XrResult r = scene_get_component_status(space, type, status);
+    pthread_mutex_unlock(&scene_lock);
+    return r;
+}
+// Diagnostics for MR games that reject the room (Pinball FX asks for a scan again and again): every kind of room
+// query is logged once per entity with its result. Caller holds scene_lock.
+enum { TR_CONTAINER, TR_LAYOUT, TR_BOX2D, TR_BOX3D, TR_BOUNDARY, TR_MESH, TR_COUNT };
+static void trace_call(XrSpace space, int kind, XrResult r) {
+    static const char *const names[TR_COUNT] = {"container", "room layout", "2D box", "3D box", "2D outline", "mesh"};
+    static unsigned char seen[MAX_ENTITIES];
+    int i = fake_space_index(space);
+    if (i < 0 || (seen[i] & (1u << kind))) return;
+    seen[i] |= (unsigned char)(1u << kind);
+    LOG("scene: %s of entity %d (%s): result %d", names[kind], i,
+        entities[i].is_room ? "ROOM" : entities[i].label[0] ? entities[i].label : "anchor", r);
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_get_container(XrSession session, XrSpace space, XrSpaceContainerFB *container) {
+    pthread_mutex_lock(&scene_lock);
+    XrResult r = scene_get_container(session, space, container);
+    trace_call(space, TR_CONTAINER, r);
+    pthread_mutex_unlock(&scene_lock);
+    return r;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_get_room_layout(XrSession session, XrSpace space, XrRoomLayoutFB *layout) {
+    pthread_mutex_lock(&scene_lock);
+    XrResult r = scene_get_room_layout(session, space, layout);
+    trace_call(space, TR_LAYOUT, r);
+    pthread_mutex_unlock(&scene_lock);
+    return r;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_get_bounding_box_2d(XrSession session, XrSpace space, XrRect2Df *rect) {
+    pthread_mutex_lock(&scene_lock);
+    XrResult r = scene_get_bounding_box_2d(session, space, rect);
+    trace_call(space, TR_BOX2D, r);
+    pthread_mutex_unlock(&scene_lock);
+    return r;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_get_bounding_box_3d(XrSession session, XrSpace space, XrRect3DfFB *box) {
+    pthread_mutex_lock(&scene_lock);
+    XrResult r = scene_get_bounding_box_3d(session, space, box);
+    trace_call(space, TR_BOX3D, r);
+    pthread_mutex_unlock(&scene_lock);
+    return r;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_get_boundary_2d(XrSession session, XrSpace space, XrBoundary2DFB *boundary) {
+    pthread_mutex_lock(&scene_lock);
+    XrResult r = scene_get_boundary_2d(session, space, boundary);
+    trace_call(space, TR_BOUNDARY, r);
+    pthread_mutex_unlock(&scene_lock);
+    return r;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_get_triangle_mesh(XrSpace space, const XrSpaceTriangleMeshGetInfoMETA *info, XrSpaceTriangleMeshMETA *mesh) {
+    pthread_mutex_lock(&scene_lock);
+    XrResult r = scene_get_triangle_mesh(space, info, mesh);
+    trace_call(space, TR_MESH, r);
+    pthread_mutex_unlock(&scene_lock);
+    return r;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_get_semantic_labels(XrSession session, XrSpace space, XrSemanticLabelsFB *labels) {
+    pthread_mutex_lock(&scene_lock);
+    XrResult r = scene_get_semantic_labels(session, space, labels);
+    pthread_mutex_unlock(&scene_lock);
+    return r;
+}
+
+// The app's STAGE bounds: the Frame reports a 1x1 m rect but OVRPlugin can't give its outline ("ovrpBoundary_Outer
+// is not supported"), so Unity games that trust a configured boundary index an empty array (Demeter's
+// RemoveObjectNotInGuardian). With an emulated room there is no play area for the app; build_room asks the runtime.
+static XRAPI_ATTR XrResult XRAPI_CALL emu_stage_bounds(XrSession session, XrReferenceSpaceType type, XrExtent2Df *bounds) {
+    if (type == XR_REFERENCE_SPACE_TYPE_STAGE) {
+        if (!bounds) return XR_ERROR_VALIDATION_FAILURE;
+        static int logged;
+        if (!logged++) LOG("scene: STAGE bounds hidden from the app (no play-area outline on this runtime)");
+        *bounds = (XrExtent2Df){0, 0};
+        return XR_SPACE_BOUNDS_UNAVAILABLE;
+    }
+    PFN_xrGetReferenceSpaceBoundsRect fn =
+        (PFN_xrGetReferenceSpaceBoundsRect)lookup(active_instance, "xrGetReferenceSpaceBoundsRect");
+    return fn ? fn(session, type, bounds) : XR_ERROR_FUNCTION_UNSUPPORTED;
+}
+
+#include "scene_meta.c"
+
 static PFN_xrVoidFunction scene_emulation(const char *name) {
    if (!emulate_scene) return NULL;
+    if (!strcmp(name, "xrGetReferenceSpaceBoundsRect"))  // only for games that trust the 1x1 m rect (NOPE stalled)
+        return scene_hide_bounds ? (PFN_xrVoidFunction)emu_stage_bounds : NULL;
    static const struct { const char *name; PFN_xrVoidFunction fn; } table[] = {
        {"xrQuerySpacesFB", (PFN_xrVoidFunction)emu_query_spaces_filtered},
        {"xrRetrieveSpaceQueryResultsFB", (PFN_xrVoidFunction)emu_retrieve_results},
@@ -468,11 +764,17 @@ static PFN_xrVoidFunction scene_emulation(const char *name) {
        {"xrGetSpaceBoundingBox2DFB", (PFN_xrVoidFunction)emu_get_bounding_box_2d},
        {"xrGetSpaceBoundingBox3DFB", (PFN_xrVoidFunction)emu_get_bounding_box_3d},
        {"xrGetSpaceBoundary2DFB", (PFN_xrVoidFunction)emu_get_boundary_2d},
+        {"xrGetSpaceTriangleMeshMETA", (PFN_xrVoidFunction)emu_get_triangle_mesh},
        {"xrGetSpaceSemanticLabelsFB", (PFN_xrVoidFunction)emu_get_semantic_labels},
        {"xrRequestSceneCaptureFB", (PFN_xrVoidFunction)emu_request_scene_capture},
        {"xrCreateSpatialAnchorFB", (PFN_xrVoidFunction)emu_create_anchor},
        {"xrSaveSpaceFB", (PFN_xrVoidFunction)emu_save_space},
        {"xrEraseSpaceFB", (PFN_xrVoidFunction)emu_erase_space},
+        {"xrDiscoverSpacesMETA", (PFN_xrVoidFunction)emu_discover_spaces},
+        {"xrRetrieveSpaceDiscoveryResultsMETA", (PFN_xrVoidFunction)emu_retrieve_discovery},
+        {"xrSaveSpacesMETA", (PFN_xrVoidFunction)emu_save_spaces},
+        {"xrEraseSpacesMETA", (PFN_xrVoidFunction)emu_erase_spaces},
+        {"xrRequestBoundaryVisibilityMETA", (PFN_xrVoidFunction)emu_request_boundary_visibility},
    };
    for (size_t i = 0; i < sizeof(table) / sizeof(table[0]); ++i)
        if (!strcmp(name, table[i].name)) return table[i].fn;
@@ -485,6 +787,19 @@ static void scene_on_create_session(XrSession session) {
    PFN_xrCreateReferenceSpace create = (PFN_xrCreateReferenceSpace)lookup(active_instance, "xrCreateReferenceSpace");
    XrReferenceSpaceCreateInfo ci = {XR_TYPE_REFERENCE_SPACE_CREATE_INFO, NULL, XR_REFERENCE_SPACE_TYPE_STAGE,
                                     {{0, 0, 0, 1}, {0, 0, 0}}};
+    pthread_mutex_lock(&scene_lock);
+    if (scan_waiting) clean_scan_files();
+    scan_waiting = 0;
+    pending_capture_at = 0;
+    reset_room();
+    scene_generation = (scene_generation + 1) & 255;
+    event_head = event_tail = 0;
+    for (int i = 0; i < MAX_QUERIES; ++i) { free(queries[i].results); memset(&queries[i], 0, sizeof(queries[i])); }
+    query_next = 0;
    scene_session = session;
+    scene_stage = XR_NULL_HANDLE;
    if (create && XR_SUCCEEDED(create(session, &ci, &scene_stage))) LOG("scene: emulation active (anchored to STAGE)");
+    build_room();
+    load_anchors();
+    pthread_mutex_unlock(&scene_lock);
 }
@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Included by scene_emu.c, using the cached OpenXR registry declarations (no private ABI copies).
+static int meta_filter_matches(const XrSpaceDiscoveryInfoMETA *info, const scene_entity *e) {
+    for (uint32_t k = 0; k < info->filterCount; ++k) {
+        const XrSpaceFilterBaseHeaderMETA *f = info->filters[k];
+        if (!f) continue;
+        if (f->type == XR_TYPE_SPACE_FILTER_COMPONENT_META &&
+            !entity_has_component(e, ((const XrSpaceFilterComponentMETA *)f)->componentType)) return 0;
+        if (f->type == XR_TYPE_SPACE_FILTER_UUID_META) {
+            const XrSpaceFilterUuidMETA *u = (const XrSpaceFilterUuidMETA *)f;
+            if (!u->uuids || !uuid_matches(u->uuidCount, u->uuids, e)) return 0;
+        }
+    }
+    return 1;
+}
+// Diagnostics: MRUK takes the room whose floor outline contains the head as the "current room"; outside it, a game
+// can ask for a room scan again and again (Pinball FX). Logs the head against the floor outline (3 times per session).
+static void log_head_in_room(void) {
+    static int logged;
+    static XrSpace view = XR_NULL_HANDLE;
+    const scene_entity *f = &entities[ENT_FLOOR];
+    if (logged >= 3 || !scene_session || !scene_stage || !last_predicted_time || entity_count <= ENT_FLOOR ||
+        !f->has_bounds) return;
+    if (!view) {
+        PFN_xrCreateReferenceSpace create = (PFN_xrCreateReferenceSpace)lookup(active_instance, "xrCreateReferenceSpace");
+        XrReferenceSpaceCreateInfo ci = {XR_TYPE_REFERENCE_SPACE_CREATE_INFO, NULL, XR_REFERENCE_SPACE_TYPE_VIEW,
+                                         {{0, 0, 0, 1}, {0, 0, 0}}};
+        if (!create || XR_FAILED(create(scene_session, &ci, &view))) return;
+    }
+    XrPosef head;
+    XrSpaceLocationFlags flags = 0;
+    if (!stage_pose(view, last_predicted_time, &head, &flags)) return;
+    XrVector3f p = pose_mul(pose_inv(f->pose_in_stage), head).position;  // floor plane: x, y; its normal: z
+    XrVector2f rect[4], *v = f->boundary;
+    uint32_t n = f->boundary_count;
+    if (!n) {
+        const XrRect2Df b = f->bounds;
+        rect[0] = (XrVector2f){b.offset.x, b.offset.y};
+        rect[1] = (XrVector2f){b.offset.x + b.extent.width, b.offset.y};
+        rect[2] = (XrVector2f){b.offset.x + b.extent.width, b.offset.y + b.extent.height};
+        rect[3] = (XrVector2f){b.offset.x, b.offset.y + b.extent.height};
+        v = rect;
+        n = 4;
+    }
+    int inside = 0;
+    for (uint32_t a = 0, b = n - 1; a < n; b = a++)
+        if ((v[a].y > p.y) != (v[b].y > p.y) && p.x < (v[b].x - v[a].x) * (p.y - v[a].y) / (v[b].y - v[a].y) + v[a].x)
+            inside = !inside;
+    LOG("scene: head in STAGE %.2f,%.2f,%.2f (flags 0x%llx), floor-local %.2f,%.2f: %s the floor outline (%u points)",
+        head.position.x, head.position.y, head.position.z, (unsigned long long)flags, p.x, p.y,
+        inside ? "inside" : "OUTSIDE", n);
+    ++logged;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_discover_spaces(XrSession session, const XrSpaceDiscoveryInfoMETA *info,
+                                                         XrAsyncRequestIdFB *request) {
+    if (!info || !request || (info->filterCount && !info->filters)) return XR_ERROR_VALIDATION_FAILURE;
+    pthread_mutex_lock(&scene_lock);
+    scene_session = session;
+    build_room();
+    if (event_free() < 2) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_LIMIT_REACHED; }
+    scene_query *q = new_query();
+    if (!q) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_OUT_OF_MEMORY; }
+    for (int i = 0; i < entity_count; ++i) {
+        scene_entity *e = &entities[i];
+        if (!e->erased && meta_filter_matches(info, e))
+            q->results[q->count++] = (XrSpaceQueryResultFB){e->handle, e->uuid};
+    }
+    *request = q->id;
+    XrEventDataSpaceDiscoveryResultsAvailableMETA avail = {XR_TYPE_EVENT_DATA_SPACE_DISCOVERY_RESULTS_AVAILABLE_META, NULL, *request};
+    XrEventDataSpaceDiscoveryCompleteMETA done = {XR_TYPE_EVENT_DATA_SPACE_DISCOVERY_COMPLETE_META, NULL, *request, XR_SUCCESS};
+    push_event(&avail, sizeof(avail)); push_event(&done, sizeof(done));
+    LOG("scene: discovery request=%llu results=%u", (unsigned long long)*request, q->count);
+    log_head_in_room();
+    pthread_mutex_unlock(&scene_lock);
+    return XR_SUCCESS;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_retrieve_discovery(XrSession session, XrAsyncRequestIdFB request,
+                                                           XrSpaceDiscoveryResultsMETA *results) {
+    (void)session;
+    if (!results) return XR_ERROR_VALIDATION_FAILURE;
+    pthread_mutex_lock(&scene_lock);
+    scene_query *q = find_query(request);
+    XrResult r = XR_SUCCESS;
+    if (!q) r = XR_ERROR_VALIDATION_FAILURE;
+    else {
+        results->resultCountOutput = q->count;
+        if (results->resultCapacityInput && results->resultCapacityInput < q->count) r = XR_ERROR_SIZE_INSUFFICIENT;
+        else if (results->resultCapacityInput) {
+            if (!results->results) r = XR_ERROR_VALIDATION_FAILURE;
+            else for (uint32_t i = 0; i < q->count; ++i)
+                results->results[i] = (XrSpaceDiscoveryResultMETA){q->results[i].space, q->results[i].uuid};
+        }
+    }
+    pthread_mutex_unlock(&scene_lock);
+    return r;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_save_spaces(XrSession session, const XrSpacesSaveInfoMETA *info,
+                                                     XrAsyncRequestIdFB *request) {
+    (void)session;
+    if (!info || !request || !info->spaceCount || !info->spaces) return XR_ERROR_VALIDATION_FAILURE;
+    pthread_mutex_lock(&scene_lock);
+    if (!event_free()) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_LIMIT_REACHED; }
+    XrResult r = persist_spaces(info->spaceCount, info->spaces, 0, NULL, 0);
+    *request = next_request++;
+    XrEventDataSpacesSaveResultMETA done = {XR_TYPE_EVENT_DATA_SPACES_SAVE_RESULT_META, NULL, *request, r};
+    push_event(&done, sizeof(done));
+    pthread_mutex_unlock(&scene_lock);
+    return XR_SUCCESS;
+}
+// XR_META_boundary_visibility: the Frame shows no guardian over an app anyway, so a request always succeeds; the
+// change event (once per new state, like Meta's runtime) is what MR games wait for before they start.
+static XrBoundaryVisibilityMETA boundary_visibility = XR_BOUNDARY_VISIBILITY_NOT_SUPPRESSED_META;
+static XRAPI_ATTR XrResult XRAPI_CALL emu_request_boundary_visibility(XrSession session, XrBoundaryVisibilityMETA v) {
+    (void)session;
+    if (v != XR_BOUNDARY_VISIBILITY_SUPPRESSED_META && v != XR_BOUNDARY_VISIBILITY_NOT_SUPPRESSED_META)
+        return XR_ERROR_VALIDATION_FAILURE;
+    pthread_mutex_lock(&scene_lock);
+    if (v != boundary_visibility) {
+        boundary_visibility = v;
+        XrEventDataBoundaryVisibilityChangedMETA e = {XR_TYPE_EVENT_DATA_BOUNDARY_VISIBILITY_CHANGED_META, NULL, v};
+        push_event(&e, sizeof(e));
+        LOG("scene: boundary %s", v == XR_BOUNDARY_VISIBILITY_SUPPRESSED_META ? "suppressed" : "shown");
+    }
+    pthread_mutex_unlock(&scene_lock);
+    return XR_SUCCESS;
+}
+static XRAPI_ATTR XrResult XRAPI_CALL emu_erase_spaces(XrSession session, const XrSpacesEraseInfoMETA *info,
+                                                      XrAsyncRequestIdFB *request) {
+    (void)session;
+    if (!info || !request || (info->spaceCount && !info->spaces) || (info->uuidCount && !info->uuids))
+        return XR_ERROR_VALIDATION_FAILURE;
+    pthread_mutex_lock(&scene_lock);
+    if (!event_free()) { pthread_mutex_unlock(&scene_lock); return XR_ERROR_LIMIT_REACHED; }
+    XrResult r = persist_spaces(info->spaceCount, info->spaces, info->uuidCount, info->uuids, 1);
+    *request = next_request++;
+    XrEventDataSpacesEraseResultMETA done = {XR_TYPE_EVENT_DATA_SPACES_ERASE_RESULT_META, NULL, *request, r};
+    push_event(&done, sizeof(done));
+    pthread_mutex_unlock(&scene_lock);
+    return XR_SUCCESS;
+}
@@ -0,0 +1,268 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Included by scene_emu.c. Bounded parsing keeps corrupt scan files from exhausting an Android game.
+#include <errno.h>
+#include <stdint.h>
+
+static int room_uuid(const char *s, XrUuidEXT *u) {
+    if (strlen(s) != 32) return 0;
+    for (int i = 0; i < 16; ++i) {
+        unsigned n = 0;
+        for (int k = 0; k < 2; ++k) {
+            char c = s[i * 2 + k];
+            if (c >= '0' && c <= '9') n = n * 16 + (unsigned)(c - '0');
+            else if (c >= 'a' && c <= 'f') n = n * 16 + (unsigned)(c - 'a' + 10);
+            else return 0;
+        }
+        u->data[i] = (uint8_t)n;
+    }
+    return 1;
+}
+static int room_float(const char *s, float *v) {
+    char *end;
+    errno = 0;
+    *v = strtof(s, &end);
+    return *s && !*end && !errno && isfinite(*v) && fabsf(*v) <= 100000;
+}
+static int room_uint(const char *s, uint64_t *v) {
+    char *end;
+    if (*s < '0' || *s > '9') return 0;
+    errno = 0;
+    *v = strtoull(s, &end, 10);
+    return !*end && !errno;
+}
+static int room_tokens(char *s, char **t, int cap) {
+    char *comment = strchr(s, '#');
+    if (comment) *comment = 0;
+    int n = 0;
+    char *save;
+    for (char *p = strtok_r(s, " \t\r\n", &save); p; p = strtok_r(NULL, " \t\r\n", &save)) {
+        if (n == cap) return -1;
+        t[n++] = p;
+    }
+    return n;
+}
+static int room_values(char **t, int start, int count, float *v) {
+    for (int i = 0; i < count; ++i) if (!room_float(t[start + i], &v[i])) return 0;
+    return 1;
+}
+static int room_path(char *out, size_t size, const char *name) {
+    const char *config = getenv("FRAMEBRIDGE_CONFIG");
+    if (!config || !*config || strchr(name, '/') || strchr(name, '\\') || !strcmp(name, "..")) return 0;
+    const char *slash = strrchr(config, '/');
+    int n = slash ? snprintf(out, size, "%.*s/%s", (int)(slash - config), config, name)
+                  : snprintf(out, size, "%s", name);
+    return n >= 0 && (size_t)n < size;
+}
+static uint32_t room_u32(const unsigned char *p) {
+    return (uint32_t)p[0] | (uint32_t)p[1] << 8 | (uint32_t)p[2] << 16 | (uint32_t)p[3] << 24;
+}
+static int room_mesh(scene_entity *e, const char *name, uint64_t nv, uint64_t ni) {
+    // At most 200k triangles and 16 MiB of payload; validate every index before publishing the mesh.
+    if (!nv || nv > 600000 || !ni || ni > 600000 || ni % 3 || nv * 12 + ni * 4 > 16 * 1024 * 1024) return 0;
+    char path[4096];
+    if (!room_path(path, sizeof(path), name)) return 0;
+    FILE *f = fopen(path, "rb");
+    if (!f) return 0;
+    unsigned char header[16], word[4];
+    int ok = fread(header, 1, 16, f) == 16 && !memcmp(header, "FPRM", 4) && room_u32(header + 4) == 1 &&
+             room_u32(header + 8) == nv && room_u32(header + 12) == ni;
+    XrVector3f *verts = ok ? malloc((size_t)nv * sizeof(*verts)) : NULL;
+    uint32_t *indices = ok ? malloc((size_t)ni * sizeof(*indices)) : NULL;
+    ok = ok && verts && indices;
+    for (uint64_t i = 0; ok && i < nv; ++i) {
+        float xyz[3];
+        for (int k = 0; ok && k < 3; ++k) {
+            ok = fread(word, 1, 4, f) == 4;
+            uint32_t bits = ok ? room_u32(word) : 0;
+            memcpy(&xyz[k], &bits, 4);
+            ok = ok && isfinite(xyz[k]) && fabsf(xyz[k]) <= 100000;
+        }
+        if (ok) verts[i] = (XrVector3f){xyz[0], xyz[1], xyz[2]};
+    }
+    for (uint64_t i = 0; ok && i < ni; ++i) {
+        ok = fread(word, 1, 4, f) == 4;
+        indices[i] = ok ? room_u32(word) : 0;
+        ok = ok && indices[i] < nv;
+    }
+    ok = ok && fgetc(f) == EOF && !ferror(f);
+    fclose(f);
+    if (!ok) { free(verts); free(indices); return 0; }
+    e->vertices = verts; e->indices = indices;
+    e->vertex_count = (uint32_t)nv; e->index_count = (uint32_t)ni;
+    return 1;
+}
+static int room_set_uuid(int i, XrUuidEXT uuid) {
+    for (int k = 0; k < entity_count; ++k)
+        if (k != i && uuid_equal(&entities[k].uuid, &uuid)) return 0;
+    entities[i].uuid = uuid;
+    return 1;
+}
+static int room_wall(XrUuidEXT uuid, const float *v, const char *label) {
+    float dx = v[2] - v[0], dz = v[3] - v[1], length = hypotf(dx, dz);
+    if (length < 0.001f || v[5] <= v[4]) return 0;
+    float angle = atan2f(-dz, dx) / 2;
+    int i = add_entity((XrPosef){{0, sinf(angle), 0, cosf(angle)},
+                       {(v[0] + v[2]) / 2, (v[4] + v[5]) / 2, (v[1] + v[3]) / 2}},
+                       label, length, v[5] - v[4], 0, 0);
+    if (i < 0) return 0;
+    if (!room_set_uuid(i, uuid)) { --entity_count; return 0; }
+    entities[i].is_wall = 1;
+    return 1;
+}
+static int room_outline(scene_entity *e, const XrVector2f *points, int n, float cx, float cz, int ceiling) {
+    e->boundary = malloc((size_t)n * sizeof(*e->boundary));
+    if (!e->boundary) return 0;
+    e->boundary_count = (uint32_t)n;
+    float xmin = INFINITY, ymin = INFINITY, xmax = -INFINITY, ymax = -INFINITY;
+    for (int i = 0; i < n; ++i) {
+        XrVector2f p = {points[i].x - cx, (points[i].y - cz) * (ceiling ? 1 : -1)};
+        e->boundary[i] = p;
+        xmin = fminf(xmin, p.x); xmax = fmaxf(xmax, p.x);
+        ymin = fminf(ymin, p.y); ymax = fmaxf(ymax, p.y);
+    }
+    e->has_bounds = 1;
+    e->bounds = (XrRect2Df){{xmin, ymin}, {xmax - xmin, ymax - ymin}};
+    return 1;
+}
+static int load_room_file(void) {
+    char path[4096];
+    if (!room_path(path, sizeof(path), "room.txt")) return 0;
+    FILE *f = fopen(path, "r");
+    if (!f) return 0;
+    // Long enough for a 1024-point outline. Reject whole overlong lines, never interpret their tails.
+    char *line = malloc(65536);
+    char **t = malloc((2 * MAX_OUTLINE + 4) * sizeof(*t));
+    if (!line || !t) { free(line); free(t); fclose(f); return 0; }
+    int ok = fgets(line, 65536, f) != NULL;
+    int n = ok ? room_tokens(line, t, 2 * MAX_OUTLINE + 4) : 0;
+    if (n != 2 || strcmp(t[0], "frameport-room") || strcmp(t[1], "1")) {
+        LOG("scene: bad room magic/version -> guardian box");
+        free(line); free(t); fclose(f); return 0;
+    }
+    const float s = 0.70710678f;
+    add_entity((XrPosef){{0, 0, 0, 1}, {0, 0, 0}}, NULL, 0, 0, 1, 0);
+    add_entity((XrPosef){{-s, 0, 0, s}, {0, 0, 0}}, "FLOOR", 0, 0, 0, 0);
+    add_entity((XrPosef){{s, 0, 0, s}, {0, 2.5f, 0}}, "CEILING", 0, 0, 0, 0);
+    XrVector2f outline[MAX_OUTLINE];
+    int outline_n = 0, ceiling_set = 0, volumes = 0, planes = 0, triangles = 0;
+    unsigned lineno = 1;
+    snprintf(room_source, sizeof(room_source), "manual");
+    while (fgets(line, 65536, f)) {
+        ++lineno;
+        if (!strchr(line, '\n') && !feof(f)) {
+            int c; while ((c = fgetc(f)) != EOF && c != '\n') {}
+            LOG("scene: bad room line %u (too long)", lineno); continue;
+        }
+        n = room_tokens(line, t, 2 * MAX_OUTLINE + 4);
+        if (!n) continue;
+        ok = n > 0;
+        float v[10]; XrUuidEXT uuid; uint64_t a, b;
+        if (n < 0) ok = 0;
+        else if (!strcmp(t[0], "source")) {
+            ok = n == 2 && (!strcmp(t[1], "scan") || !strcmp(t[1], "boundary") || !strcmp(t[1], "box") || !strcmp(t[1], "manual"));
+            if (ok) snprintf(room_source, sizeof(room_source), "%s", t[1]);
+        } else if (!strcmp(t[0], "universe")) {
+            ok = n == 2 && room_uint(t[1], &a);
+            if (ok) room_universe = a;
+        } else if (!strcmp(t[0], "room") || !strcmp(t[0], "floor") || !strcmp(t[0], "ceiling")) {
+            int i = !strcmp(t[0], "room") ? ENT_ROOM : !strcmp(t[0], "floor") ? ENT_FLOOR : ENT_CEILING;
+            ok = n == (i == ENT_ROOM ? 2 : 3) && room_uuid(t[1], &uuid) &&
+                 (i == ENT_ROOM || room_float(t[2], v)) && room_set_uuid(i, uuid);
+            if (ok && i != ENT_ROOM) entities[i].pose_in_stage.position.y = v[0];
+            if (ok && i == ENT_CEILING) ceiling_set = 1;
+        } else if (!strcmp(t[0], "outline")) {
+            ok = n >= 2 && room_uint(t[1], &a) && a >= 3 && a <= MAX_OUTLINE && n == 2 + 2 * (int)a;
+            XrVector2f parsed[MAX_OUTLINE];
+            for (uint64_t k = 0; ok && k < a; ++k) ok = room_float(t[2 + k * 2], &parsed[k].x) && room_float(t[3 + k * 2], &parsed[k].y);
+            if (ok) { memcpy(outline, parsed, (size_t)a * sizeof(*outline)); outline_n = (int)a; }
+        } else if (!strcmp(t[0], "wall")) {
+            // optional 8th field: WALL_FACE (default) or INVISIBLE_WALL_FACE for an edge the scanner closed itself
+            const char *label = n == 9 ? t[8] : "WALL_FACE";
+            ok = (n == 8 || (n == 9 && (!strcmp(label, "WALL_FACE") || !strcmp(label, "INVISIBLE_WALL_FACE")))) &&
+                 room_uuid(t[1], &uuid) && room_values(t, 2, 6, v) && room_wall(uuid, v, label);
+        } else if (!strcmp(t[0], "volume") || !strcmp(t[0], "plane")) {
+            int volume = !strcmp(t[0], "volume");
+            ok = n == (volume ? 10 : 12) && room_uuid(t[1], &uuid) && strlen(t[2]) < sizeof(entities[0].label) && room_values(t, 3, volume ? 7 : 9, v);
+            XrPosef pose = {{0, 0, 0, 1}, {0, 0, 0}};
+            float w = 0, h = 0;
+            if (ok && volume) {
+                float yaw = v[3] * 0.00872664626f;
+                pose = (XrPosef){quat_mul((XrQuaternionf){0, sinf(yaw), 0, cosf(yaw)}, (XrQuaternionf){-s, 0, 0, s}), {v[0], v[2], v[1]}};
+                w = v[4]; h = v[5]; ok = v[6] > 0;
+            } else if (ok) {
+                float norm = sqrtf(v[3]*v[3]+v[4]*v[4]+v[5]*v[5]+v[6]*v[6]);
+                ok = norm > 0.0001f;
+                if (ok) pose = (XrPosef){{v[3]/norm,v[4]/norm,v[5]/norm,v[6]/norm}, {v[0],v[1],v[2]}};
+                w = v[7]; h = v[8];
+            }
+            int i = ok && w > 0 && h > 0 ? add_entity(pose, t[2], w, h, 0, 0) : -1;
+            ok = i >= 0;
+            if (ok && !room_set_uuid(i, uuid)) { --entity_count; ok = 0; }
+            if (ok && volume) {
+                entities[i].has_bounds3 = 1;
+                entities[i].bounds3 = (XrRect3DfFB){{-w/2, -h/2, -v[6]}, {w, h, v[6]}};
+                ++volumes;
+            } else if (ok) ++planes;
+        } else if (!strcmp(t[0], "mesh")) {
+            if (!scene_app_mesh) continue;  // the app didn't enable XR_META_spatial_entity_mesh
+            ok = n == 5 && room_uuid(t[1], &uuid) && room_uint(t[3], &a) && room_uint(t[4], &b) && !triangles;
+            int i = ok ? add_entity((XrPosef){{0,0,0,1},{0,0,0}}, "GLOBAL_MESH", 0, 0, 0, 0) : -1;
+            ok = i >= 0 && room_set_uuid(i, uuid) && room_mesh(&entities[i], t[2], a, b);
+            if (ok) triangles = (int)b / 3;
+            else if (i >= 0) --entity_count;
+        }
+        if (!ok) LOG("scene: bad room line %u (skipped)", lineno);
+    }
+    ok = !ferror(f);
+    free(line); free(t); fclose(f);
+    // Layout walls must be contiguous and in file order, regardless of where other records occurred.
+    for (int i = ENT_WALL0; i < entity_count; ++i) if (entities[i].is_wall) {
+        scene_entity wall = entities[i];
+        memmove(&entities[ENT_WALL0 + wall_count + 1], &entities[ENT_WALL0 + wall_count],
+                (size_t)(i - ENT_WALL0 - wall_count) * sizeof(wall));
+        entities[ENT_WALL0 + wall_count++] = wall;
+    }
+    if (!outline_n && wall_count) {
+        float xmin = INFINITY, zmin = INFINITY, xmax = -INFINITY, zmax = -INFINITY;
+        for (int i = ENT_WALL0; i < ENT_WALL0 + wall_count; ++i) {
+            scene_entity *e = &entities[i];
+            XrVector3f d = quat_rotate(e->pose_in_stage.orientation, (XrVector3f){e->bounds.extent.width/2,0,0});
+            xmin = fminf(xmin, e->pose_in_stage.position.x - fabsf(d.x)); xmax = fmaxf(xmax, e->pose_in_stage.position.x + fabsf(d.x));
+            zmin = fminf(zmin, e->pose_in_stage.position.z - fabsf(d.z)); zmax = fmaxf(zmax, e->pose_in_stage.position.z + fabsf(d.z));
+        }
+        outline[0]=(XrVector2f){xmin,zmin}; outline[1]=(XrVector2f){xmax,zmin};
+        outline[2]=(XrVector2f){xmax,zmax}; outline[3]=(XrVector2f){xmin,zmax}; outline_n=4;
+    }
+    double area = 0, cx = 0, cz = 0;
+    for (int i = 0; i < outline_n; ++i) {
+        XrVector2f a = outline[i], b = outline[(i+1)%outline_n];
+        double cross = (double)a.x*b.y-(double)b.x*a.y;
+        area += cross; cx += (a.x+b.x)*cross; cz += (a.y+b.y)*cross;
+    }
+    if (!ok || outline_n < 3 || fabs(area) < 0.00001) { reset_room(); return 0; }
+    cx /= 3*area; cz /= 3*area;
+    if (!ceiling_set) entities[ENT_CEILING].pose_in_stage.position.y = entities[ENT_FLOOR].pose_in_stage.position.y + 2.5f;
+    for (int i = ENT_FLOOR; i <= ENT_CEILING; ++i) {
+        entities[i].pose_in_stage.position.x = (float)cx; entities[i].pose_in_stage.position.z = (float)cz;
+        if (!room_outline(&entities[i], outline, outline_n, (float)cx, (float)cz, i == ENT_CEILING)) { reset_room(); return 0; }
+    }
+    if (!wall_count) for (int i = 0; i < outline_n; ++i) {
+        XrVector2f a = outline[i], b = outline[(i+1)%outline_n];
+        float v[] = {a.x,a.y,b.x,b.y,entities[ENT_FLOOR].pose_in_stage.position.y,entities[ENT_CEILING].pose_in_stage.position.y};
+        if (!room_wall(make_uuid(entity_count), v, "WALL_FACE")) { reset_room(); return 0; }
+        ++wall_count;
+    }
+    // Move generated walls ahead of furniture as well.
+    if (wall_count && !entities[ENT_WALL0].is_wall) {
+        scene_entity *walls = malloc((size_t)wall_count * sizeof(*walls));
+        if (!walls) { reset_room(); return 0; }
+        memcpy(walls, &entities[entity_count-wall_count], (size_t)wall_count*sizeof(*walls));
+        memmove(&entities[ENT_WALL0+wall_count], &entities[ENT_WALL0], (size_t)(entity_count-wall_count-ENT_WALL0)*sizeof(*walls));
+        memcpy(&entities[ENT_WALL0], walls, (size_t)wall_count*sizeof(*walls)); free(walls);
+    }
+    for (int i = 0; i < entity_count; ++i) entities[i].handle = fake_space(i);
+    room_entity_count = entity_count; room_from_file = 1;
+    LOG("scene: room from %s file (%d walls, %d volumes, %d planes, %d mesh triangles, universe %llu)",
+        room_source, wall_count, volumes, planes, triangles, (unsigned long long)room_universe);
+    return 1;
+}
@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Included by scene_emu.c; all scan state is protected by scene_lock.
+static int scan_path(char *path, size_t size, const char *kind) {
+    char anchor[4096];
+    if (!anchor_path(anchor, sizeof(anchor))) return 0;
+    char *slash = strrchr(anchor, '/');
+    if (!slash) return 0;
+    *slash = 0;
+    int n = snprintf(path, size, "%s/framebridge-scan-%s", anchor, kind);
+    return n > 0 && (size_t)n < size;
+}
+static void clean_scan_files(void) {
+    const char *kinds[] = {"request", "ack", "result"};
+    char path[4096];
+    for (unsigned i = 0; i < 3; ++i) if (scan_path(path, sizeof(path), kinds[i])) unlink(path);
+}
+static int start_scan(XrAsyncRequestIdFB id) {
+    char path[4096], tmp[4128];
+    if (!scan_path(path, sizeof(path), "request")) return 0;
+    clean_scan_files();
+    snprintf(tmp, sizeof(tmp), "%s.tmp-XXXXXX", path);
+    int fd = mkstemp(tmp);
+    if (fd < 0) { LOG("scene: scan request write failed (%d), using the stored room", errno); return 0; }
+    FILE *f = fdopen(fd, "w");
+    if (!f) { close(fd); unlink(tmp); return 0; }
+    int ok = fprintf(f, "request %llu %llu\n", (unsigned long long)id, (unsigned long long)time(NULL)) > 0;
+    if (fflush(f) || fsync(fd)) ok = 0;
+    if (fclose(f)) ok = 0;
+    if (ok && rename(tmp, path)) ok = 0;
+    if (!ok) { unlink(tmp); LOG("scene: scan request write failed (%d), using the stored room", errno); return 0; }
+    scan_started_at = scene_now_ns();
+    scan_poll_at = 0;
+    scan_waiting = 1;
+    scan_acked = 0;
+    LOG("scene: scan requested from FramePort (request %llu)", (unsigned long long)id);
+    return 1;
+}
+static int scan_message(const char *kind, char *status, char *reason, size_t size) {
+    char path[4096], line[512];
+    struct stat st;
+    if (!scan_path(path, sizeof(path), kind) || stat(path, &st)) return 0;
+    FILE *f = fopen(path, "r");
+    if (!f) return 0;
+    int ok = fgets(line, sizeof(line), f) != NULL;
+    fclose(f);
+    unsigned long long id;
+    int used = 0;
+    if (!ok || sscanf(line, "%15s %llu %n", status, &id, &used) < 2 || id != pending_capture.requestId) return 0;
+    snprintf(reason, size, "%s", line + used);
+    reason[strcspn(reason, "\r\n")] = 0;
+    return 1;
+}
+static int reload_scanned_room(void) {
+    scene_entity *old = malloc(sizeof(entities));
+    if (!old) return 0;
+    memcpy(old, entities, sizeof(entities));
+    int old_count = entity_count, old_room_count = room_entity_count, old_walls = wall_count, old_file = room_from_file;
+    uint64_t old_universe = room_universe;
+    unsigned old_generation = scene_generation;
+    char old_source[sizeof(room_source)];
+    memcpy(old_source, room_source, sizeof(room_source));
+    memset(entities, 0, sizeof(entities));
+    entity_count = room_entity_count = wall_count = room_from_file = 0;
+    room_universe = 0;
+    scene_generation = (scene_generation + 1) & 255;
+    if (!load_room_file()) {
+        reset_room();
+        memcpy(entities, old, sizeof(entities));
+        entity_count = old_count; room_entity_count = old_room_count; wall_count = old_walls; room_from_file = old_file;
+        room_universe = old_universe; scene_generation = old_generation;
+        memcpy(room_source, old_source, sizeof(room_source));
+        free(old);
+        return 0;
+    }
+    for (int i = 0; i < old_count; ++i) {
+        free(old[i].boundary); free(old[i].vertices); free(old[i].indices);
+    }
+    free(old);
+    load_anchors();
+    return 1;
+}
+static void poll_scan(uint64_t now) {
+    if (now < scan_poll_at) return;
+    scan_poll_at = now + 250000000ull;
+    char status[16], reason[512];
+    if (!scan_acked && scan_message("ack", status, reason, sizeof(reason)) && !strcmp(status, "ack")) {
+        scan_acked = 1;
+        scan_started_at = now;  // allow the scanner a full six minutes after acknowledging
+        LOG("scene: scan started by FramePort");
+    }
+    if (scan_message("result", status, reason, sizeof(reason)) &&
+        (!strcmp(status, "ok") || !strcmp(status, "failed"))) {
+        int ok = !strcmp(status, "ok") && reload_scanned_room();
+        pending_capture_at = now;
+        pending_capture.result = ok ? XR_SUCCESS : XR_ERROR_RUNTIME_FAILURE;
+        if (ok) LOG("scene: scanned room loaded (%d entities)", entity_count);
+        else LOG("scene: scan failed (%s)", !strcmp(status, "failed") ? reason : "could not load scanned room");
+    } else if (!scan_acked && now - scan_started_at >= 5000000000ull) {
+        LOG("scene: no scanner answered, using the stored room");
+    } else if (scan_acked && now - scan_started_at >= 360000000000ull) {
+        pending_capture_at = now;
+        pending_capture.result = XR_ERROR_RUNTIME_FAILURE;
+        LOG("scene: scan failed (timeout)");
+    } else return;
+    scan_waiting = 0;
+    clean_scan_files();
+}
@@ -201,6 +201,18 @@ def build_venc(tc: Path):
         f"-ffile-prefix-map={HERE}=native", "fp_venc.c", "convert.c", "sys.c", "-o", out / "fp_venc"], cwd=src)


+def build_roomscan(tc: Path):
+    """Offline room reconstruction (Linux aarch64). No libc, headers, generated tables or fetched dependencies."""
+    src = HERE / "roomscan"
+    out = ART / "linux-arm64-bin"
+    out.mkdir(parents=True, exist_ok=True)
+    run([tc / "bin/clang", "--target=aarch64-linux-gnu", "-ffreestanding", "-nostdlib", "-nostdlibinc", "-static",
+         "-fno-stack-protector", "-fno-builtin", "-ffp-contract=off", "-fno-math-errno", "-O2", "-Wall", "-Wextra", "-Werror",
+         "-fuse-ld=lld", "-Wl,--build-id=none", "-Wl,-z,max-page-size=65536", "-e", "_start",
+         f"-ffile-prefix-map={HERE}=native", "main.c", "fusion.c", "model.c", "mesh.c", "refine.c", "rules.c",
+         "roomio.c", "platform.c", "-o", out / "fp_roomscan"], cwd=src)
+
+
 OCULUSHMD_IMPORTS = ("CreateEventW", "CreateJobObjectW", "AssignProcessToJobObject", "QueryInformationJobObject",
                     "CreateProcessW", "ResumeThread", "WaitForSingleObject", "GetExitCodeProcess", "CloseHandle",
                     "Sleep", "GetCommandLineW", "GetLastError", "GetStdHandle", "WriteFile", "ExitProcess")
@@ -449,7 +461,7 @@ def write_sums():

 def main():
    ap = argparse.ArgumentParser()
-    ap.add_argument("--only", default="adapter,bridge,compat,langpack,glshim,eglfmt,glmv,ovrtrace,dex,xrlayer,oculushmd,xrruntime,xrshim,vkshim,zinkfix,foveation,ovrpshim,tlskeys,luajit,vrsettings,venc,a32")
+    ap.add_argument("--only", default="adapter,bridge,compat,langpack,glshim,eglfmt,glmv,ovrtrace,dex,xrlayer,oculushmd,xrruntime,xrshim,vkshim,zinkfix,foveation,ovrpshim,tlskeys,luajit,vrsettings,venc,roomscan,a32")
    ap.add_argument("--ndk")
    args = ap.parse_args()
    parts = set(args.only.split(","))
@@ -465,9 +477,10 @@ def main():
             "ovrpshim": lambda: build_ovrpshim(tc), "tlskeys": lambda: build_tlskeys(tc),
             "luajit": lambda: build_luajit(tc),
             "vrsettings": lambda: build_vrsettings(tc), "venc": lambda: build_venc(tc),
+             "roomscan": lambda: build_roomscan(tc),
             "vroverlay_probe": lambda: build_vroverlay_probe(tc), "a32": lambda: build_a32(tc)}
    for name in ("adapter", "bridge", "compat", "langpack", "glshim", "eglfmt", "glmv", "ovrtrace", "xrruntime", "xrshim", "vkshim", "zinkfix", "foveation", "ovrpshim", "tlskeys", "luajit", "dex", "xrlayer", "oculushmd", "vrsettings", "venc",
-                 "vroverlay_probe", "a32"):
+                 "roomscan", "vroverlay_probe", "a32"):
        if name in parts:
            log(f"build {name}")
            steps[name]()
@@ -0,0 +1,339 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+#include "scan.h"
+
+#define MIN_TRIANGLE_TWICE_AREA 1e-8f
+#define MIN_RANGE .1f
+#define MAX_COORDINATE 10000.f
+#define QUATERNION_NORM_TOLERANCE .1f
+#define SAMPLE_SPACING_VOXELS .75f
+#define MAX_SURFEL_WEIGHT 10.f
+#define FEW_FRAMES 8
+#define MAX_GRID_XZ 8.f
+#define MAX_GRID_Y 4.f
+#define GRID_PADDING_VOXELS 5.f
+#define NORMAL_PATCH_SIZE 12
+#define MIN_PATCH_POINTS 24
+
+float root(float x)
+{
+    if (x <= 0) return 0;
+    /* -fno-math-errno makes this one hardware sqrt, with no libc/libm symbol on either build. */
+    return __builtin_sqrtf(x);
+}
+Vec unit(Vec p) { float n = root(dot(p,p)); return n > 1e-12f ? mul(p,1/n) : vec(0,0,0); }
+int flo(float x) { int i = (int)x; return x < (float)i ? i-1 : i; }
+float sine(float x)
+{
+    while (x > PI) x -= 2*PI;
+    while (x < -PI) x += 2*PI;
+    if (x > PI/2) x = PI-x;
+    if (x < -PI/2) x = -PI-x;
+    float q = x*x;
+    return x*(1-q/6+q*q/120-q*q*q/5040+q*q*q*q/362880);
+}
+float cosine(float x) { return sine(x+PI/2); }
+float angle(float y, float x)
+{
+    /* atan approximation, maximum error < .012 degrees. */
+    float a = mn(ab(x),ab(y)) / mx(mx(ab(x),ab(y)),1e-20f), q = a*a;
+    float r = a*(.999866f+q*(-.3302995f+q*(.180141f+q*(-.085133f+q*.0208351f))));
+    if (ab(y) > ab(x)) r = PI/2-r;
+    if (x < 0) r = PI-r;
+    return y < 0 ? -r : r;
+}
+int same(const char *a, const char *b)
+{
+    while (*a && *a == *b) a++,b++;
+    return *a == *b;
+}
+u32 random_next(Scan *s) { s->rng ^= s->rng<<13; s->rng ^= s->rng>>17; s->rng ^= s->rng<<5; return s->rng; }
+void warn(Scan *s, const char *m)
+{
+    for (int i = 0; i < s->nwarnings; i++) if (same(s->warnings[i],m)) return;
+    if (s->nwarnings < 24) s->warnings[s->nwarnings++] = m;
+}
+/* The head path (where the user stood and walked) for the refinement's walked-volume pass. Bounded: every
+ * head_stride-th tracked frame, halving the kept points and doubling the stride when the buffer is full. */
+static void record_head(Scan *s, Vec eye)
+{
+    if(!s->head_stride) s->head_stride=1;
+    if(s->head_frames++%s->head_stride) return;
+    if(s->nheads==MAX_HEADS) {
+        for(int i=0;i<MAX_HEADS/2;i++) s->heads[i]=s->heads[2*i];
+        s->nheads=MAX_HEADS/2;s->head_stride*=2;
+        if((s->head_frames-1)%s->head_stride) return;
+    }
+    s->heads[s->nheads++]=eye;
+}
+static u32 u32le(const u8 *p) { return (u32)p[0]|(u32)p[1]<<8|(u32)p[2]<<16|(u32)p[3]<<24; }
+static float f32le(const u8 *p) { union { u32 u; float f; } v = {u32le(p)}; return v.f; }
+/* 1 = complete, 0 = clean EOF, -1 = I/O error or partial record. */
+static int exact(int fd, void *p, usize n)
+{
+    usize done = 0;
+    while (done < n) {
+        long r = io_read(fd,(u8 *)p+done,n-done);
+        if (r < 0 || (!r && done)) return -1;
+        if (!r) return 0;
+        done += (usize)r;
+    }
+    return 1;
+}
+Vec grid_point(Scan *s, int x, int y, int z)
+{
+    return add(s->origin,vec(x*s->opt.voxel,y*s->opt.voxel,z*s->opt.voxel));
+}
+int cell_index(Scan *s, Vec p)
+{
+    Vec q = mul(sub(p,s->origin),1/s->opt.voxel);
+    int x = flo(q.x+.5f), y = flo(q.y+.5f), z = flo(q.z+.5f);
+    if (x < 0 || y < 0 || z < 0 || x >= s->nx || y >= s->ny || z >= s->nz) return -1;
+    return (y*s->nz+z)*s->nx+x;
+}
+static void sample(Scan *s, Vec p, Vec n, float w)
+{
+    int i = cell_index(s,p);
+    if (i < 0) { s->clipped++; return; }
+    Cell *c = &s->cells[i];
+    /* Cap repeated views' influence without throwing away later measurements. */
+    float scale = c->weight > MAX_SURFEL_WEIGHT ? MAX_SURFEL_WEIGHT/c->weight : 1;
+    c->p = add(mul(c->p,scale),mul(p,w));
+    c->n = add(mul(c->n,scale),mul(n,w));
+    c->weight = c->weight*scale+w;
+    if(c->last_frame!=s->fuse_frame) { c->last_frame=s->fuse_frame;c->views++; }
+}
+static void triangle(Scan *s, Vec a, Vec b, Vec c, Vec eye, Vec patch_normal, int fuse)
+{
+    Vec abv = sub(b,a), ac = sub(c,a), bc = sub(c,b);
+    float longest = root(mx(dot(abv,abv),mx(dot(ac,ac),dot(bc,bc))));
+    Vec p = mul(add(a,add(b,c)),1.f/3), n = cross(abv,ac);
+    float twice_area = root(dot(n,n));
+    Vec view = sub(eye,p);
+    float distance = root(dot(view,view));
+    if (twice_area < MIN_TRIANGLE_TWICE_AREA || longest > s->opt.max_edge || distance > s->opt.range || distance < MIN_RANGE) {
+        if (!fuse) s->rejected++;
+        return;
+    }
+    n = mul(n,1/twice_area);
+    if(dot(patch_normal,patch_normal)>.5f) n=patch_normal;
+    float facing = dot(n,view)/distance;
+    if (ab(facing) < s->opt.grazing) { if (!fuse) s->rejected++; return; }
+    if (facing < 0) n = mul(n,-1);
+    if (!fuse) {
+        s->accepted++;
+        s->seen++;
+        int slot = s->seen <= MAX_SAMPLES ? (int)s->seen-1 : (int)(random_next(s)%s->seen);
+        if (slot < MAX_SAMPLES) s->samples[slot] = p;
+        s->nsamples = (int)mn((float)s->seen,MAX_SAMPLES);
+    } else {
+        int steps = (int)(longest/(s->opt.voxel*SAMPLE_SPACING_VOXELS))+1;
+        float weight = twice_area*facing*facing / ((steps+1)*(steps+2)*.5f);
+        for (int j = 0; j <= steps; j++) for (int k = 0; k <= steps-j; k++) {
+            Vec q = add(a,add(mul(abv,(float)j/steps),mul(ac,(float)k/steps)));
+            sample(s,q,n,weight);
+        }
+    }
+}
+static Vec patch_normal(Vec *points, float *depths, int width, int x0, int y0, int x1, int y1,
+                        float tolerance)
+{
+    Vec mean=vec(0,0,0);int count=0;
+    /* Shift before accumulating the covariance: room positions can be large relative to patch residuals. */
+    Vec origin=points[y0*width+x0];
+    for(int y=y0;y<y1;y++) for(int x=x0;x<x1;x++) if(depths[y*width+x]>0) {
+        mean=add(mean,sub(points[y*width+x],origin));count++;
+    }
+    if(count<MIN_PATCH_POINTS) return vec(0,0,0);
+    mean=mul(mean,1.f/count);
+    float cov[3][3]={{0}},basis[3][3]={{1,0,0},{0,1,0},{0,0,1}};
+    for(int y=y0;y<y1;y++) for(int x=x0;x<x1;x++) if(depths[y*width+x]>0) {
+        Vec p=sub(sub(points[y*width+x],origin),mean);float a[3]={p.x,p.y,p.z};
+        for(int i=0;i<3;i++) for(int j=0;j<3;j++) cov[i][j]+=a[i]*a[j];
+    }
+    for(int sweep=0;sweep<8;sweep++) {
+        int p=0,q=1;
+        if(ab(cov[0][2])>ab(cov[p][q])) { p=0;q=2; }
+        if(ab(cov[1][2])>ab(cov[p][q])) { p=1;q=2; }
+        if(ab(cov[p][q])<1e-10f) break;
+        float phi=.5f*angle(2*cov[p][q],cov[q][q]-cov[p][p]),co=cosine(phi),si=sine(phi);
+        float aa=cov[p][p],bb=cov[q][q],abv=cov[p][q];
+        for(int k=0;k<3;k++) if(k!=p && k!=q) {
+            float a=cov[k][p],b=cov[k][q];
+            cov[k][p]=cov[p][k]=co*a-si*b;cov[k][q]=cov[q][k]=si*a+co*b;
+        }
+        cov[p][p]=co*co*aa-2*si*co*abv+si*si*bb;
+        cov[q][q]=si*si*aa+2*si*co*abv+co*co*bb;cov[p][q]=cov[q][p]=0;
+        for(int k=0;k<3;k++) {
+            float a=basis[k][p],b=basis[k][q];basis[k][p]=co*a-si*b;basis[k][q]=si*a+co*b;
+        }
+    }
+    int least=0;
+    for(int i=1;i<3;i++) if(cov[i][i]<cov[least][least]) least=i;
+    if(cov[least][least]/count>tolerance*tolerance) return vec(0,0,0);
+    return unit(vec(basis[0][least],basis[1][least],basis[2][least]));
+}
+static int grid_normals(Scan *s, Vec *points, float *depths, Vec *normals, u32 nv, u32 ni, const u8 *indices)
+{
+    if(ni<6 || u32le(indices)!=0 || u32le(indices+8)!=1) return 0;
+    u32 width=u32le(indices+4);
+    if(width<3 || width>nv || nv%width || ni!=6*(width-1)*(nv/width-1)) return 0;
+    /* Only a complete regular fan uses patch normals. Other meshes retain ordinary triangle normals. */
+    u32 at=0;
+    for(u32 row=0;row+1<nv/width;row++) for(u32 col=0;col+1<width;col++) {
+        u32 a=row*width+col,expected[6]={a,a+width,a+1,a+1,a+width,a+width+1};
+        for(int k=0;k<6;k++) if(u32le(indices+4*at++)!=expected[k]) return 0;
+    }
+    int height=(int)(nv/width);
+    for(int y=0;y<height;y+=NORMAL_PATCH_SIZE) for(int x=0;x<(int)width;x+=NORMAL_PATCH_SIZE) {
+        int x1=(int)mn(x+NORMAL_PATCH_SIZE,(float)width),y1=(int)mn(y+NORMAL_PATCH_SIZE,height);
+        Vec n=patch_normal(points,depths,(int)width,x,y,x1,y1,s->opt.patch_residual);
+        for(int yy=y;yy<y1;yy++) for(int xx=x;xx<x1;xx++) normals[yy*width+xx]=n;
+    }
+    return 1;
+}
+const char *read_dump(Scan *s, int fuse)
+{
+    int fd = io_open(s->opt.input,0);
+    if (fd < 0) return "cannot open scan dump";
+    u8 header[44];
+    const char *error = 0;
+    Vec *vertices = 0,*normals=0;
+    float *depths = 0;
+    u8 *indices = 0;
+    usize vs = 0, is = 0, ds = 0;
+    if (exact(fd,header,8) != 1 || header[0]!='F' || header[1]!='P' || header[2]!='R' || header[3]!='S' ||
+        u32le(header+4) != 1) { error = "invalid FPRS header"; goto done; }
+    unsigned frames = 0;
+    for (;;) {
+        int r = exact(fd,header,44);
+        if (r == 0) break;
+        if (r < 0) { error = "truncated frame header"; break; }
+        /* Tracking can start before poses are available. Consume the entire bounded record before skipping,
+         * so one NaN cannot hide a truncated payload or desynchronize the next frame. */
+        int invalid=(u32le(header+4)&0x7ff00000u) == 0x7ff00000u;
+        float pose[7];
+        for (int i = 0; i < 7; i++) {
+            pose[i] = f32le(header+8+i*4);
+            if (!finite(pose[i]) || ab(pose[i]) > MAX_COORDINATE) invalid=1;
+        }
+        float norm = 0;
+        for (int i = 3; i < 7; i++) norm += pose[i]*pose[i];
+        if (!finite(norm) || ab(norm-1) > QUATERNION_NORM_TOLERANCE) invalid=1;
+        if(!invalid) for (int i = 3; i < 7; i++) pose[i] /= root(norm);
+        if(!fuse && !invalid) record_head(s,vec(pose[0],pose[1],pose[2]));
+        u32 nv = u32le(header+36), ni = u32le(header+40);
+        if (nv > MAX_FRAME_VERTICES || ni > MAX_FRAME_INDICES || ni%3 || (!nv && ni)) {
+            error = "invalid frame counts"; break;
+        }
+        usize needv = (usize)nv*12, needi = (usize)ni*4;
+        if (needv > vs) {
+            io_free(vertices,vs);io_free(normals,vs);vs=needv;vertices=io_alloc(vs);normals=io_alloc(vs);
+        }
+        if (needi > is) { io_free(indices,is); is=needi; indices=io_alloc(is); }
+        if((usize)nv*4>ds) { io_free(depths,ds);ds=(usize)nv*4;depths=io_alloc(ds); }
+        if ((nv && (!vertices || !depths || !normals)) || (ni && !indices)) { error = "frame allocation failed"; break; }
+        if ((needv && exact(fd,vertices,needv)!=1) || (needi && exact(fd,indices,needi)!=1)) {
+            error = "truncated frame data"; break;
+        }
+        Vec eye = vec(pose[0],pose[1],pose[2]), q = vec(pose[3],pose[4],pose[5]);
+        u64 far=0;
+        for (u32 i = 0; i < nv; i++) {
+            u8 *p = (u8 *)&vertices[i];
+            Vec v = vec(f32le(p),f32le(p+4),f32le(p+8));
+            if (!finite(v.x) || !finite(v.y) || !finite(v.z) ||
+                ab(v.x)>MAX_COORDINATE || ab(v.y)>MAX_COORDINATE || ab(v.z)>MAX_COORDINATE) {
+                invalid=1;break;
+            }
+            depths[i]=root(dot(v,v));
+            if(depths[i]>s->opt.range || depths[i]<MIN_RANGE) { depths[i]=-1;far++;continue; }
+            Vec t = mul(cross(q,v),2);
+            vertices[i] = add(eye,add(v,add(mul(t,pose[6]),cross(q,t))));
+        }
+        int regular=!invalid && grid_normals(s,vertices,depths,normals,nv,ni,indices);
+        /* Structural errors are fatal even in a frame whose tracking/depth is unusable. */
+        s->fuse_frame=frames+1;
+        for (u32 i = 0; i < ni; i+=3) {
+            u32 a=u32le(indices+4*i), b=u32le(indices+4*(i+1)), c=u32le(indices+4*(i+2));
+            if (a>=nv || b>=nv || c>=nv) { error = "index outside vertex array"; break; }
+            if(invalid) continue;
+            if(depths[a]<0 || depths[b]<0 || depths[c]<0) { if(!fuse) s->rejected++;continue; }
+            float near=mn(depths[a],mn(depths[b],depths[c])),far_depth=mx(depths[a],mx(depths[b],depths[c]));
+            if(far_depth-near>s->opt.depth_jump+s->opt.depth_ratio*near) {
+                if(!fuse) { s->rejected++;s->discontinuities++; }continue;
+            }
+            Vec normal=regular ? normals[a] : vec(0,0,0);
+            if(regular && dot(normal,normal)<.5f) { if(!fuse) s->rejected++;continue; }
+            triangle(s,vertices[a],vertices[b],vertices[c],eye,normal,fuse);
+        }
+        if (error) break;
+        if(!fuse) { if(invalid) s->skipped_frames++;else s->far_vertices+=far; }
+        frames++;
+    }
+    if (!error && !frames) error = "scan contains no frames";
+    if (!error && !fuse) s->frames = frames;
+done:
+    io_free(vertices,vs);
+    io_free(normals,vs);
+    io_free(indices,is);
+    io_free(depths,ds);
+    io_close(fd);
+    return error;
+}
+static float median(Scan *s, int axis)
+{
+    /* In-place quickselect on the bounded reservoir; no dump-sized allocations. */
+    int lo=0, hi=s->nsamples-1, mid=s->nsamples/2;
+    while (lo < hi) {
+        float pivot = ((float *)&s->samples[(lo+hi)/2])[axis];
+        int i=lo,j=hi;
+        while (i<=j) {
+            while (((float *)&s->samples[i])[axis] < pivot) i++;
+            while (((float *)&s->samples[j])[axis] > pivot) j--;
+            if (i<=j) { Vec t=s->samples[i]; s->samples[i++]=s->samples[j]; s->samples[j--]=t; }
+        }
+        if (mid<=j) hi=j;
+        else if (mid>=i) lo=i;
+        else break;
+    }
+    return ((float *)&s->samples[mid])[axis];
+}
+const char *init_grid(Scan *s)
+{
+    if (!s->nsamples) return "scan contains no usable triangles";
+    float x=median(s,0), y=median(s,1), z=median(s,2), v=s->opt.voxel;
+    Vec low=s->samples[0],high=low;
+    for(int i=1;i<s->nsamples;i++) {
+        Vec p=s->samples[i];
+        low=vec(mn(low.x,p.x),mn(low.y,p.y),mn(low.z,p.z));
+        high=vec(mx(high.x,p.x),mx(high.y,p.y),mx(high.z,p.z));
+    }
+    float pad=v*mx(GRID_PADDING_VOXELS,s->opt.truncation+2);
+    low=sub(low,vec(pad,pad,pad));high=add(high,vec(pad,pad,pad));
+    s->origin=vec(mx(flo(low.x/v)*v,flo((x-MAX_GRID_XZ/2)/v)*v),
+                  mx(flo(low.y/v)*v,flo((y-MAX_GRID_Y/2)/v)*v),
+                  mx(flo(low.z/v)*v,flo((z-MAX_GRID_XZ/2)/v)*v));
+    s->nx=(int)mn(-flo(-(high.x-s->origin.x)/v)+1,(int)(MAX_GRID_XZ/v)+1);
+    s->ny=(int)mn(-flo(-(high.y-s->origin.y)/v)+1,(int)(MAX_GRID_Y/v)+1);
+    s->nz=(int)mn(-flo(-(high.z-s->origin.z)/v)+1,(int)(MAX_GRID_XZ/v)+1);
+    usize count = (usize)s->nx*s->ny*s->nz;
+    if (count > MAX_CELLS) return "voxel grid exceeds memory budget; increase --voxel";
+    s->count = (int)count;
+    s->cells = io_alloc(count*sizeof(Cell));
+    return s->cells ? 0 : "grid allocation failed";
+}
+void finish_fusion(Scan *s)
+{
+    /* A short look-around cannot expose each surface in many frames. Cap the target at ten percent of usable
+     * views (at least one); long recordings still require repeated evidence rather than transient depth. */
+    unsigned required=(unsigned)mn(s->opt.min_views,mx(1,(s->frames-s->skipped_frames)/10.f));
+    for (int i=0; i<s->count; i++) {
+        Cell *c=&s->cells[i];
+        if(c->views<required) { c->weight=0;continue; }
+        if (c->weight) { c->p=mul(c->p,1/c->weight); c->n=unit(c->n); }
+    }
+    if (s->clipped) warn(s,"scan clipped to 8 x 8 x 4 metre grid");
+    if (s->frames < FEW_FRAMES) warn(s,"few frames; scan more viewpoints");
+    if(s->skipped_frames) warn(s,"non-finite or invalid frames skipped");
+    if(s->far_vertices) warn(s,"out-of-range depth vertices skipped");
+    if (s->accepted < s->rejected) warn(s,"many triangles rejected; check depth quality");
+}
@@ -0,0 +1,395 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+#include "refine.h"
+
+static int error_json(const char *error)
+{
+    Buf t;buf_init(&t,4096);put(&t,"{\"ok\":false,\"error\":\"");put(&t,error);put(&t,"\"}\n");
+    io_write(1,t.data,t.n);buf_free(&t);return 2;
+}
+static int parse_float(const char *p,float *out)
+{
+    int digits=0;float n=0,scale=1;
+    while(*p>='0' && *p<='9') { n=n*10+*p++-'0';digits++;if(n>10000) return 0; }
+    if(*p=='.') { p++;while(*p>='0' && *p<='9') { scale*=.1f;n+=(*p++-'0')*scale;digits++; } }
+    if(!digits || *p || !finite(n)) return 0;
+    *out=n;return 1;
+}
+static int parse_universe(const char *p,u64 *out)
+{
+    u64 n=0;if(!*p) return 0;
+    for(;*p;p++) {
+        if(*p<'0' || *p>'9') return 0;
+        unsigned digit=(unsigned)(*p-'0');
+        if(n>(~(u64)0-digit)/10) return 0;
+        n=n*10+digit;
+    }
+    *out=n;return 1;
+}
+/* "x,y,z,r;x,y,z,r;..." (metres, STAGE space) */
+static int parse_erase(const char *value, Refine *o)
+{
+    char *p=(char *)value;o->nerase=0;
+    while(*p) {
+        if(o->nerase==MAX_ERASE) return 0;
+        float v[4];
+        for(int i=0;i<4;i++) {
+            if(!parse_number(&p,&v[i])) return 0;
+            if(i<3) { if(*p!=',') return 0;p++; }
+        }
+        if(v[3]<=0 || v[3]>5) return 0;
+        o->erase[o->nerase++]=(Sphere){v[0],v[1],v[2],v[3]};
+        while(*p==' ') p++;
+        if(*p==';') p++;
+        else if(*p) return 0;
+    }
+    return 1;
+}
+static const char *options(Options *o,int argc,char **argv)
+{
+    *o=(Options){.voxel=.05f,.ceiling_default=2.5f,.truncation=3,.max_edge=.6f,.grazing=.12f,.range=4.f,
+        .depth_jump=.25f,.depth_ratio=.12f,.min_views=5,.patch_residual=.03f,
+        .plane_distance=.045f,.min_plane_area=.45f,.wall_height=1.5f,.snap_degrees=5,.floor_band=.35f,
+        .ceiling_min=1.8f,.min_volume=.05f,.cluster_gap=.10f,.gap=.65f,.horizontal=.85f,
+        /* The owner's refinement settings (room-scan cleanup page, 2026-10-18). */
+        .rf={.refine=1,.walls=2,.protect=0,.label_rules=1,.smooth=8,.band=.35f,.facing_deg=60,.band_in=.12f,
+             .floor_in=.08f,.ceil_in=.25f,.top_strip=.5f,.near=.03f,.clip=.05f,.clip_open=.10f,.island=.20f,
+             .tops=.10f,.tubes=3,.tube_thick=.15f,.walked=.40f}};
+    for(int i=1;i<argc;i++) {
+        const char *arg=argv[i];
+        if(same(arg,"--json")) continue;
+        if(i+1==argc) return "option requires a value";
+        const char *value=argv[++i];
+        float number=0;
+        if(same(arg,"--offline")) o->input=value;
+        else if(same(arg,"--out")) o->out=value;
+        else if(same(arg,"--hint")) o->hint=value;
+        else if(same(arg,"--refine-only")) o->refine_only=value;
+        else if(same(arg,"--universe")) { if(!parse_universe(value,&o->universe)) return "invalid universe"; }
+        else if(same(arg,"--walls")) {
+            if(same(value,"off")) o->rf.walls=0;
+            else if(same(value,"snap")) o->rf.walls=1;
+            else if(same(value,"panels")) o->rf.walls=2;
+            else return "option outside supported range";
+        }
+        else if(same(arg,"--erase")) { if(!parse_erase(value,&o->rf)) return "invalid erase spheres"; }
+        else if(same(arg,"--refine") || same(arg,"--protect") || same(arg,"--label-rules") || same(arg,"--smooth")) {
+            int high=same(arg,"--smooth") ? 50 : 1;
+            if(!parse_float(value,&number) || number!=(float)(int)number || number>high) return "option outside supported range";
+            int *dest=same(arg,"--refine") ? &o->rf.refine : same(arg,"--protect") ? &o->rf.protect :
+                      same(arg,"--label-rules") ? &o->rf.label_rules : &o->rf.smooth;
+            *dest=(int)number;
+        }
+        else {
+            float *dest=0,low=0,high=100;
+            if(same(arg,"--voxel")) { dest=&o->voxel;low=.04f;high=.2f; }
+            else if(same(arg,"--ceiling-default")) { dest=&o->ceiling_default;low=1.8f;high=3.8f; }
+            else if(same(arg,"--truncation")) { dest=&o->truncation;low=1;high=5; }
+            else if(same(arg,"--max-edge")) { dest=&o->max_edge;low=.05f;high=1.5f; }
+            else if(same(arg,"--grazing")) { dest=&o->grazing;low=.01f;high=.9f; }
+            else if(same(arg,"--range")) { dest=&o->range;low=1;high=10; }
+            else if(same(arg,"--depth-jump")) { dest=&o->depth_jump;low=.02f;high=1; }
+            else if(same(arg,"--depth-ratio")) { dest=&o->depth_ratio;high=.5f; }
+            else if(same(arg,"--min-views")) { dest=&o->min_views;low=1;high=16; }
+            else if(same(arg,"--patch-residual")) { dest=&o->patch_residual;low=.005f;high=.1f; }
+            else if(same(arg,"--plane-distance")) { dest=&o->plane_distance;low=.01f;high=.15f; }
+            else if(same(arg,"--min-plane-area")) { dest=&o->min_plane_area;low=.1f;high=4; }
+            else if(same(arg,"--wall-height")) { dest=&o->wall_height;low=.5f;high=3; }
+            else if(same(arg,"--snap-degrees")) { dest=&o->snap_degrees;high=15; }
+            else if(same(arg,"--floor-band")) { dest=&o->floor_band;low=.05f;high=1; }
+            else if(same(arg,"--ceiling-min")) { dest=&o->ceiling_min;low=1.5f;high=3; }
+            else if(same(arg,"--min-volume")) { dest=&o->min_volume;low=.005f;high=1; }
+            else if(same(arg,"--cluster-gap")) { dest=&o->cluster_gap;low=.04f;high=.2f; }
+            else if(same(arg,"--gap")) { dest=&o->gap;low=.1f;high=1.5f; }
+            else if(same(arg,"--horizontal")) { dest=&o->horizontal;low=.6f;high=.99f; }
+            else if(same(arg,"--band")) { dest=&o->rf.band;low=.02f;high=1; }
+            else if(same(arg,"--facing-deg")) { dest=&o->rf.facing_deg;low=5;high=89; }
+            else if(same(arg,"--band-in")) { dest=&o->rf.band_in;high=1; }
+            else if(same(arg,"--floor-in")) { dest=&o->rf.floor_in;high=1; }
+            else if(same(arg,"--ceil-in")) { dest=&o->rf.ceil_in;high=1; }
+            else if(same(arg,"--top-strip")) { dest=&o->rf.top_strip;high=2; }
+            else if(same(arg,"--near")) { dest=&o->rf.near;high=.3f; }
+            else if(same(arg,"--clip")) { dest=&o->rf.clip;high=1; }
+            else if(same(arg,"--clip-open")) { dest=&o->rf.clip_open;high=2; }
+            else if(same(arg,"--island")) { dest=&o->rf.island;high=5; }
+            else if(same(arg,"--tops")) { dest=&o->rf.tops;high=.5f; }
+            else if(same(arg,"--tubes")) { dest=&o->rf.tubes;high=20; }
+            else if(same(arg,"--tube-thick")) { dest=&o->rf.tube_thick;low=.01f;high=1; }
+            else if(same(arg,"--walked")) { dest=&o->rf.walked;high=1.5f; }
+            else return "unknown option";
+            if(!parse_float(value,dest) || *dest<low || *dest>high) return "option outside supported range";
+        }
+    }
+    if(o->rf.walked>0 && o->rf.walked<.05f) return "option outside supported range";
+    if(o->refine_only) return o->input ? "--refine-only takes no --offline dump" : 0;
+    return o->input && o->out ? 0 : "required: --offline dump.fprs --out directory";
+}
+
+/* ------------------------------------------------------------------------------------------------ refinement */
+typedef struct {
+    Report rep;
+    Label labels[MAX_VOLUMES];
+    int nlabels, changed, removed, nsuggest, out_triangles, out_volumes;
+    float ceiling_y;
+    i64 ms;
+} Outcome;
+static const char *copy_name(char *dst, const char *src, usize cap)
+{
+    usize i=0;while(src[i] && i+1<cap) { dst[i]=src[i];i++; }
+    dst[i]=0;return dst;
+}
+static void box_json(Buf *b, const RVol *v)
+{
+    put(b,"{\"cx\":");put_dec(b,v->cx);put(b,",\"cz\":");put_dec(b,v->cz);put(b,",\"top_y\":");put_dec(b,v->top);
+    put(b,",\"yaw_deg\":");put_dec(b,v->yaw);put(b,",\"w\":");put_dec(b,v->w);put(b,",\"d\":");put_dec(b,v->d);
+    put(b,",\"h\":");put_dec(b,v->h);put(b,"}");
+}
+static void scan_json(Buf *b, const Refine *o, const Vec *heads, int nheads, const Outcome *r)
+{
+    put(b,"{\"version\":1,\"heads\":");heads_json(b,heads,nheads);
+    put(b,",\"refine\":");settings_json(b,o);
+    put(b,",\"report\":");report_json(b,&r->rep,r->nlabels,r->changed,r->removed,r->nsuggest);
+    put(b,",\"labels\":[");
+    for(int i=0;i<r->nlabels;i++) {
+        const Label *l=&r->labels[i];
+        if(i) put(b,",");
+        put(b,"{\"from\":\"");put(b,l->from);put(b,"\",\"to\":");
+        if(l->to[0]) { put(b,"\"");put(b,l->to);put(b,"\""); } else put(b,"null");
+        put(b,",\"reason\":\"");put(b,l->reason);put(b,"\"");
+        if(l->suggest[0]) { put(b,",\"suggest\":\"");put(b,l->suggest);put(b,"\""); }
+        put(b,",\"id\":\"");put(b,l->box.id);put(b,"\",\"box\":");box_json(b,&l->box);put(b,"}");
+    }
+    put(b,"],\"suggestions\":[");
+    int first=1;
+    for(int i=0;i<r->nlabels;i++) {
+        const Label *l=&r->labels[i];
+        if(!l->suggest[0]) continue;
+        if(!first) put(b,",");
+        first=0;
+        put(b,"{\"kind\":\"");put(b,l->suggest);put(b,"\",\"box\":");box_json(b,&l->box);
+        put(b,",\"wall\":");put_int(b,l->wall);put(b,",\"along\":");put_dec(b,l->along);
+        put(b,",\"reason\":\"");put(b,l->reason);put(b,"\"}");
+    }
+    put(b,"]}\n");
+}
+/* Refines `raw` (as read back from its own text) and publishes: [raw mesh, raw text,] scan.json, room-mesh.bin,
+ * room.txt. Everything is computed before the first file is written, so a failure leaves the old files. */
+static const char *refine_publish(const char *dir, const Room *raw, const Vec *v, const u32 *idx, int nv, int ni,
+                                  const Vec *heads, int nheads, const Refine *o, int write_raw, Outcome *res)
+{
+    static Room refined;
+    static RVol ruled[MAX_VOLUMES];
+    const char *error=0;
+    Prep prep={0};
+    Vec *rv=0;u32 *ri=0;int rn=0;
+    u8 *raw_mesh=0,*mesh=0;usize raw_size=0,mesh_size=0;
+    Buf raw_text,text,json;
+    buf_init(&raw_text,1u<<20);buf_init(&text,1u<<20);buf_init(&json,MAX_JSON_FILE);
+    i64 t0=io_time(1);
+    memset(res,0,sizeof(*res));
+    refined=*raw;
+    copy_name(refined.mesh_name,"room-mesh.bin",sizeof(refined.mesh_name));
+    if(o->refine) {
+        error=prep_mesh(&prep,v,idx,nv,ni);
+        int nruled=raw->nvols;
+        if(!error) {
+            if(o->label_rules) res->nlabels=rules_apply(raw,&prep,ruled,&nruled,res->labels);
+            else memcpy(ruled,raw->vols,sizeof(RVol)*(usize)raw->nvols);
+        }
+        if(!error) error=refine_run(o,raw,&prep,ruled,nruled,heads,nheads,&rv,&ri,&rn,&res->rep);
+        if(!error) {
+            refined.ceiling=res->rep.ceiling_y;
+            for(int i=0;i<refined.nwalls;i++) if(refined.walls[i].y1==raw->ceiling) refined.walls[i].y1=refined.ceiling;
+            memcpy(refined.vols,ruled,sizeof(RVol)*(usize)nruled);refined.nvols=nruled;
+            refined.mesh_nv=refined.mesh_ni=(u32)rn;refined.has_mesh=1;
+            for(int i=0;i<res->nlabels;i++) {
+                Label *l=&res->labels[i];
+                if(l->suggest[0]) res->nsuggest++;
+                if(!l->to[0]) res->removed++;
+                else if(!same(l->to,l->from)) res->changed++;
+            }
+        }
+    }
+    if(!error) error=mesh_bytes(rv ? rv : v,rv ? ri : idx,rv ? rn : nv,rv ? rn : ni,&mesh,&mesh_size);
+    if(!error && write_raw) error=mesh_bytes(v,idx,nv,ni,&raw_mesh,&raw_size);
+    if(!error && write_raw && !room_text(raw,&raw_text)) error="room text exceeds output budget";
+    if(!error && !room_text(&refined,&text)) error="room text exceeds output budget";
+    if(!error) { scan_json(&json,o,heads,nheads,res);if(!json.ok) error="scan.json exceeds output budget"; }
+    res->ms=io_time(1)-t0;
+    res->out_triangles=(int)refined.mesh_ni/3;res->out_volumes=refined.nvols;res->ceiling_y=refined.ceiling;
+    if(!error && !io_mkdir(dir)) error="cannot create output directory";
+    if(!error && write_raw) error=publish(dir,"room-mesh-raw.bin",raw_mesh,raw_size);
+    if(!error && write_raw) error=publish(dir,"room-raw.txt",raw_text.data,raw_text.n);
+    if(!error) error=publish(dir,"scan.json",json.data,json.n);
+    if(!error) error=publish(dir,"room-mesh.bin",mesh,mesh_size);
+    if(!error) error=publish(dir,"room.txt",text.data,text.n);
+    prep_free(&prep);
+    io_free(rv,(usize)MAX_MESH_VERTICES*sizeof(Vec));io_free(ri,(usize)MAX_TRIANGLES*3*sizeof(u32));
+    io_free(raw_mesh,raw_size);io_free(mesh,mesh_size);
+    buf_free(&raw_text);buf_free(&text);buf_free(&json);
+    return error;
+}
+static void refine_summary(Buf *t, const Outcome *r)
+{
+    put(t,"\"refine\":");report_json(t,&r->rep,r->nlabels,r->changed,r->removed,r->nsuggest);
+    if(t->ok && t->n) t->n--;  /* reopen the object for the output counts */
+    put(t,",\"output_triangles\":");put_int(t,r->out_triangles);
+    put(t,",\"output_volumes\":");put_int(t,r->out_volumes);put(t,"}");
+}
+
+/* ------------------------------------------------------------------------------------------------ summaries */
+static void duration(Buf *t,i64 a,i64 b) { put_dec(t,(float)(b-a)/1000000); }
+static void warnings_json(Buf *t, const char **w, int n)
+{
+    put(t,",\"warnings\":[");
+    for(int i=0;i<n;i++) { if(i) put(t,",");put(t,"\"");put(t,w[i]);put(t,"\""); }
+    put(t,"]");
+}
+static void summary(Scan *s, const Outcome *r)
+{
+    Buf t;buf_init(&t,1u<<16);put(&t,"{\"ok\":true,\"frames\":");put_u64(&t,s->frames);
+    put(&t,",\"skipped_frames\":");put_u64(&t,s->skipped_frames);
+    put(&t,",\"far_vertices\":");put_u64(&t,s->far_vertices);
+    put(&t,",\"discontinuity_triangles\":");put_u64(&t,s->discontinuities);
+    put(&t,",\"walls\":");put_u64(&t,(u64)s->noutline);
+    put(&t,",\"detected_walls\":");put_u64(&t,(u64)s->nplanes);
+    put(&t,",\"volumes\":");put_u64(&t,(u64)s->nvolumes);
+    put(&t,",\"floor_y\":");put_dec(&t,s->floor);put(&t,",\"ceiling_y\":");put_dec(&t,s->ceiling);
+    put(&t,",\"coverage_percent\":");put_dec(&t,s->coverage);
+    put(&t,",\"hint_used\":");put(&t,s->hint_used ? "true" : "false");
+    put(&t,",\"triangles\":");put_u64(&t,(u64)s->ni/3);
+    put(&t,",\"accepted_triangles\":");put_u64(&t,s->accepted);
+    put(&t,",\"rejected_triangles\":");put_u64(&t,s->rejected);
+    put(&t,",\"heads\":");put_int(&t,s->nheads);put(&t,",");
+    refine_summary(&t,r);
+    warnings_json(&t,s->warnings,s->nwarnings);
+    put(&t,",\"timings_ms\":{\"read\":");duration(&t,s->t0,s->tread);
+    put(&t,",\"fusion\":");duration(&t,s->tread,s->tfuse);
+    put(&t,",\"model\":");duration(&t,s->tfuse,s->tmodel);
+    put(&t,",\"mesh\":");duration(&t,s->tmodel,s->tmesh);
+    put(&t,",\"refine\":");duration(&t,s->tmesh,s->trefine);
+    put(&t,",\"total\":");duration(&t,s->t0,io_time(1));put(&t,"}}\n");io_write(1,t.data,t.n);buf_free(&t);
+}
+
+/* ------------------------------------------------------------------------------------------------ scan path */
+static const char *scan_outputs(Scan *s, Outcome *out)
+{
+    static Room built,raw;
+    static Vec heads[MAX_HEADS];
+    const char *error=room_from_scan(s,&built);
+    if(error) return error;
+    copy_name(built.mesh_name,"room-mesh-raw.bin",sizeof(built.mesh_name));
+    /* Refine what the raw files will hold, so --refine-only on them gives the same refined files. */
+    Buf t;buf_init(&t,1u<<20);
+    if(!room_text(&built,&t)) { buf_free(&t);return "room text exceeds output budget"; }
+    error=room_parse(t.data,t.n,&raw);
+    buf_free(&t);
+    if(error) return error;
+    Buf h;buf_init(&h,1u<<20);heads_json(&h,s->heads,s->nheads);put(&h,"}");
+    Buf wrap;buf_init(&wrap,1u<<20);put(&wrap,"{\"heads\":");put_n(&wrap,h.data,h.n);
+    int nheads=wrap.ok ? heads_parse(wrap.data,wrap.n,heads) : 0;
+    buf_free(&h);buf_free(&wrap);
+    return refine_publish(s->opt.out,&raw,s->vertices,s->indices,s->nv,s->ni,heads,nheads,&s->opt.rf,1,out);
+}
+
+/* ------------------------------------------------------------------------------------------------ --refine-only */
+static int refine_only(Options *o)
+{
+    static Room raw;
+    static Vec heads[MAX_HEADS];
+    static Outcome res;
+    const char *warns[4];int nwarn=0;
+    i64 t0=io_time(1);
+    const char *dir=o->refine_only,*error=0;
+    char path[4096];
+    u8 *text=0,*bin=0,*json=0;usize text_n=0,bin_n=0,json_n=0;
+    Vec *v=0;u32 *idx=0;int nv=0,ni=0,nheads=0,write_raw=0;
+    if(!join_path(path,dir,"room-raw.txt")) return error_json("output path too long");
+    error=read_file(path,1u<<20,&text,&text_n);
+    if(error) {
+        /* An older room folder: its room.txt + mesh are the unrefined scan. */
+        write_raw=1;
+        if(!join_path(path,dir,"room.txt")) return error_json("output path too long");
+        error=read_file(path,1u<<20,&text,&text_n);
+        if(error) return error_json("room folder has neither room-raw.txt nor room.txt");
+    }
+    error=room_parse((const char *)text,text_n,&raw);
+    io_free(text,(1u<<20)+1);
+    if(error) return error_json(error);
+    if(!raw.has_mesh) return error_json("room has no mesh to refine");
+    if(!join_path(path,dir,write_raw ? raw.mesh_name : "room-mesh-raw.bin")) return error_json("output path too long");
+    error=read_file(path,MAX_RAW_FILE,&bin,&bin_n);
+    if(!error) error=mesh_parse(bin,bin_n,&v,&idx,&nv,&ni);
+    io_free(bin,MAX_RAW_FILE+1);
+    if(error) return error_json(error);
+    if((u32)nv!=raw.mesh_nv || (u32)ni!=raw.mesh_ni) {
+        io_free(v,(usize)MAX_MESH_VERTICES*sizeof(Vec));io_free(idx,(usize)MAX_TRIANGLES*3*sizeof(u32));
+        return error_json("mesh record does not match the mesh file");
+    }
+    copy_name(raw.mesh_name,"room-mesh-raw.bin",sizeof(raw.mesh_name));
+    if(join_path(path,dir,"scan.json") && !read_file(path,MAX_JSON_FILE,&json,&json_n)) {
+        nheads=heads_parse((const char *)json,json_n,heads);
+        io_free(json,MAX_JSON_FILE+1);
+    }
+    if(!nheads && o->rf.walked>0) warns[nwarn++]="no head path; walked volume skipped";
+    if(write_raw) warns[nwarn++]="no raw files; the current room was taken as the unrefined scan";
+    error=refine_publish(dir,&raw,v,idx,nv,ni,heads,nheads,&o->rf,write_raw,&res);
+    io_free(v,(usize)MAX_MESH_VERTICES*sizeof(Vec));io_free(idx,(usize)MAX_TRIANGLES*3*sizeof(u32));
+    if(error) return error_json(error);
+    if(res.rep.truncated) warns[nwarn++]="refined mesh truncated to the triangle budget";
+    Buf t;buf_init(&t,1u<<16);
+    put(&t,"{\"ok\":true,\"refine_only\":true,\"raw_triangles\":");put_int(&t,ni/3);
+    put(&t,",\"volumes\":");put_int(&t,raw.nvols);put(&t,",\"floor_y\":");put_dec(&t,raw.floor);
+    put(&t,",\"ceiling_y\":");put_dec(&t,res.ceiling_y);put(&t,",\"heads\":");put_int(&t,nheads);put(&t,",");
+    refine_summary(&t,&res);
+    warnings_json(&t,warns,nwarn);
+    put(&t,",\"timings_ms\":{\"refine\":");put_dec(&t,(float)res.ms/1000000);
+    put(&t,",\"total\":");duration(&t,t0,io_time(1));put(&t,"}}\n");
+    io_write(1,t.data,t.n);buf_free(&t);
+    return 0;
+}
+
+int main(int argc,char **argv)
+{
+    if(argc==2 && same(argv[1],"--help")) {
+        const char usage[]="fp_roomscan --offline dump.fprs --out directory [--universe N] [--voxel 0.05]\n"
+            "  [--ceiling-default 2.5] [--hint outline.txt] [--json]\n"
+            "fp_roomscan --refine-only room-directory [refinement options] [--json]\n"
+            "Tuning: --truncation --max-edge --grazing --range --depth-jump --depth-ratio --plane-distance --min-plane-area\n"
+            "  --min-views --patch-residual --wall-height --snap-degrees --floor-band --ceiling-min\n"
+            "  --min-volume --cluster-gap --gap --horizontal\n"
+            "Refinement: --refine 0|1 --walls off|snap|panels --band --facing-deg --band-in --floor-in --ceil-in\n"
+            "  --top-strip --near --clip --clip-open --island --smooth --tops --protect 0|1 --tubes --tube-thick\n"
+            "  --walked --label-rules 0|1 --erase \"x,y,z,r;...\"\n"
+            "Always prints one JSON summary; errors exit 2. See docs/mr/scan.md for units and ranges.\n";
+        io_write(1,usage,sizeof(usage)-1);return 0;
+    }
+    Scan *s=io_alloc(sizeof(Scan));
+    if(!s) return error_json("scan allocation failed");
+    s->rng=0x714ce3u;s->t0=io_time(1);
+    const char *error=options(&s->opt,argc,argv);
+    if(!error && s->opt.refine_only) {
+        int result=refine_only(&s->opt);
+        io_free(s,sizeof(Scan));return result;
+    }
+    static Outcome outcome;
+    if(!error) error=read_dump(s,0);
+    s->tread=io_time(1);
+    if(!error) error=init_grid(s);
+    if(!error) error=read_dump(s,1);
+    if(!error) finish_fusion(s);
+    s->tfuse=io_time(1);
+    if(!error) error=make_model(s);
+    s->tmodel=io_time(1);
+    if(!error) error=make_mesh(s);
+    s->tmesh=io_time(1);
+    /* The grid is not needed after the mesh: freeing it keeps the refinement inside the same memory budget. */
+    io_free(s->cells,(usize)s->count*sizeof(Cell));s->cells=0;
+    if(!error) error=scan_outputs(s,&outcome);
+    s->trefine=io_time(1);
+    if(!error && outcome.rep.truncated) warn(s,"refined mesh truncated to the triangle budget");
+    int result=0;
+    if(error) result=error_json(error);else summary(s,&outcome);
+    io_free(s->vertices,(usize)MAX_MESH_VERTICES*sizeof(Vec));
+    io_free(s->indices,(usize)MAX_TRIANGLES*3*sizeof(u32));
+    io_free(s,sizeof(Scan));return result;
+}
@@ -0,0 +1,112 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+#include "scan.h"
+
+#define TANGENT_RADIUS_SQUARED 2.25f
+#define TANGENT_WEIGHT_RADIUS_SQUARED 2.5f
+#define MAX_EXTRACTION_STRIDE 4
+/* Marching cubes without a 256-case table: trace the zero contour on the six faces, then fan each closed loop.
+ * Ambiguous faces choose their diagonal from the face centre. Adjacent cubes therefore make the same choice. */
+static const int corners[8][3]={{0,0,0},{1,0,0},{1,0,1},{0,0,1},{0,1,0},{1,1,0},{1,1,1},{0,1,1}};
+static const int edges[12][2]={{0,1},{1,2},{2,3},{3,0},{4,5},{5,6},{6,7},{7,4},{0,4},{1,5},{2,6},{3,7}};
+static const int faces[6][4]={{0,1,2,3},{4,5,6,7},{0,9,4,8},{1,10,5,9},{2,11,6,10},{3,8,7,11}};
+
+static void tsdf(Scan *s)
+{
+    float v=s->opt.voxel,trunc=v*s->opt.truncation;
+    int radius=(int)s->opt.truncation+2;
+    for (int i=0;i<s->count;i++) {
+        Cell *c=&s->cells[i];
+        if (!c->weight) continue;
+        int x=i%s->nx,z=(i/s->nx)%s->nz,y=i/(s->nx*s->nz);
+        for (int dy=-radius;dy<=radius;dy++) for (int dz=-radius;dz<=radius;dz++) for (int dx=-radius;dx<=radius;dx++) {
+            int xx=x+dx,yy=y+dy,zz=z+dz;
+            if (xx<0 || yy<0 || zz<0 || xx>=s->nx || yy>=s->ny || zz>=s->nz) continue;
+            Vec delta=sub(grid_point(s,xx,yy,zz),c->p);
+            float d=dot(delta,c->n),tangent=dot(delta,delta)-d*d;
+            if (ab(d)>trunc || tangent>v*v*TANGENT_RADIUS_SQUARED) continue;
+            Cell *dest=&s->cells[(yy*s->nz+zz)*s->nx+xx];
+            float w=(1-tangent/(v*v*TANGENT_WEIGHT_RADIUS_SQUARED))*mn(c->weight/(v*v),1.f);
+            dest->sdf+=d*w;dest->sw+=w;
+        }
+    }
+    for (int i=0;i<s->count;i++) if(s->cells[i].sw) s->cells[i].sdf/=s->cells[i].sw;
+}
+static void connect(int links[12][2], int a, int b)
+{
+    if(links[a][0]<0) links[a][0]=b;else links[a][1]=b;
+    if(links[b][0]<0) links[b][0]=a;else links[b][1]=a;
+}
+static int cube(Scan *s, int x, int y, int z, int stride)
+{
+    float f[8];Vec p[8],normal=vec(0,0,0);
+    for(int k=0;k<8;k++) {
+        int xx=x+corners[k][0]*stride,yy=y+corners[k][1]*stride,zz=z+corners[k][2]*stride;
+        Cell *c=&s->cells[(yy*s->nz+zz)*s->nx+xx];
+        if (c->sw<=0) return 1; /* Unknown space never creates an invented surface. */
+        f[k]=c->sdf;p[k]=grid_point(s,xx,yy,zz);
+    }
+    Vec cuts[12];int crossing[12],links[12][2],visited[12]={0};
+    for(int e=0;e<12;e++) {
+        int a=edges[e][0],b=edges[e][1];
+        crossing[e]=(f[a]<0)!=(f[b]<0);links[e][0]=links[e][1]=-1;
+        if(crossing[e]) cuts[e]=add(p[a],mul(sub(p[b],p[a]),f[a]/(f[a]-f[b])));
+    }
+    /* Gradient points to positive TSDF: toward the observed free room, including furniture's exterior. */
+    normal.x=f[1]+f[2]+f[5]+f[6]-f[0]-f[3]-f[4]-f[7];
+    normal.y=f[4]+f[5]+f[6]+f[7]-f[0]-f[1]-f[2]-f[3];
+    normal.z=f[2]+f[3]+f[6]+f[7]-f[0]-f[1]-f[4]-f[5];
+    for(int face=0;face<6;face++) {
+        int hit[4],n=0;float centre=0;
+        for(int j=0;j<4;j++) {
+            int e=faces[face][j];
+            if(crossing[e]) hit[n++]=e;
+            centre+=f[edges[e][0]]+f[edges[e][1]];
+        }
+        if(n==2) connect(links,hit[0],hit[1]);
+        else if(n==4) {
+            /* The shared first edge's first corner fixes the phase on this face. */
+            int first=edges[hit[0]][0],second=edges[hit[0]][1];
+            int common=(edges[hit[1]][0]==second || edges[hit[1]][1]==second) ? second : first;
+            if((centre<0)==(f[common]<0)) {
+                connect(links,hit[0],hit[3]);connect(links,hit[1],hit[2]);
+            } else { connect(links,hit[0],hit[1]);connect(links,hit[2],hit[3]); }
+        }
+    }
+    for(int e=0;e<12;e++) if(crossing[e] && !visited[e]) {
+        int loop[12],n=0,prev=-1,cur=e;
+        while(cur>=0 && !visited[cur] && n<12) {
+            visited[cur]=1;loop[n++]=cur;
+            int next=links[cur][0]==prev ? links[cur][1] : links[cur][0];prev=cur;cur=next;
+        }
+        if(cur!=e) continue;
+        for(int k=1;k+1<n;k++) {
+            Vec a=cuts[loop[0]],b=cuts[loop[k]],c=cuts[loop[k+1]];
+            Vec norm=cross(sub(b,a),sub(c,a));
+            if(dot(norm,norm)<1e-14f) continue;
+            if(s->ni/3>=MAX_TRIANGLES) return 0;
+            if(dot(norm,normal)<0) { Vec t=b;b=c;c=t; }
+            s->vertices[s->nv]=a;s->vertices[s->nv+1]=b;s->vertices[s->nv+2]=c;
+            for(int j=0;j<3;j++) s->indices[s->ni++]=(u32)s->nv++;
+        }
+    }
+    return 1;
+}
+const char *make_mesh(Scan *s)
+{
+    s->vertices=io_alloc((usize)MAX_MESH_VERTICES*sizeof(Vec));
+    s->indices=io_alloc((usize)MAX_TRIANGLES*3*sizeof(u32));
+    if(!s->vertices || !s->indices) return "mesh allocation failed";
+    tsdf(s);
+    for(int stride=1;stride<=MAX_EXTRACTION_STRIDE;stride++) {
+        s->nv=s->ni=0;int ok=1;
+        for(int y=0;y+stride<s->ny && ok;y+=stride)
+            for(int z=0;z+stride<s->nz && ok;z+=stride)
+                for(int x=0;x+stride<s->nx && ok;x+=stride) ok=cube(s,x,y,z,stride);
+        if(ok) {
+            if(stride>1) warn(s,"mesh decimated by coarsening extraction grid");
+            if(!s->ni) warn(s,"no mesh surface; scan denser views");
+            return 0;
+        }
+    }
+    return "mesh exceeds triangle budget";
+}
@@ -0,0 +1,672 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+#include "scan.h"
+
+#define RANSAC_TRIALS 96
+#define NORMAL_AGREEMENT .90f
+#define MIN_WALL_SPAN .60f
+#define FURNITURE_MARGIN .12f
+#define NEAR_WALL .35f
+#define MIN_TOP_AREA .25f
+#define BOX_TRIM .02f
+#define VERTICAL_NORMAL_Y .35f
+#define BOX_SIDE_NORMAL_Y .30f
+#define BOX_EDGE_STRENGTH .40f
+#define MIN_CLUSTER_SURFELS 12
+#define MIN_BOX_EDGE_VOTES 12
+#define MIN_OUTLINE_EXTENT 1.f
+#define MIN_OUTLINE_TWICE_AREA .5f
+#define FLOOR_INFER_DISTANCE .3f
+#define TABLE_MIN_HEIGHT .55f
+#define TABLE_MAX_HEIGHT 1.1f
+#define COUCH_MIN_HEIGHT .35f
+#define COUCH_MAX_HEIGHT .9f
+#define COUCH_MIN_LENGTH 1.4f
+#define BED_MIN_HEIGHT .3f
+#define BED_MAX_HEIGHT .8f
+#define BED_MIN_AREA 2.f
+#define STORAGE_MIN_HEIGHT 1.1f
+#define SCREEN_MAX_DEPTH .22f
+#define SCREEN_MIN_WIDTH .4f
+#define SCREEN_MAX_WIDTH 2.f
+#define DEFAULT_CIRCLE_MIN_POINTS 8
+#define DEFAULT_CIRCLE_RADIAL_CV .05f
+#define LOW_COVERAGE_PERCENT 80.f
+#define WALL_MERGE_DISTANCE .25f
+#define WALL_MERGE_COSINE .97f
+#define RELATIVE_WALL_AREA .20f
+#define DOMINANT_WALL_TOLERANCE 12.f
+#define ORTHOGONAL_SUPPORT_FRACTION .65f
+#define CEILING_MIN_AREA .08f    /* m^2 of fused down-facing cells at one height (fused surfaces are sparse: the
+                                  * owner's floor was 0.7 m^2 of cells, the ceiling 0.11 m^2 after a 2 s look up) */
+#define CEILING_MIN_HEIGHT 2.0f  /* m above the floor: lower ones are shelves, door frames, table undersides */
+#define CEILING_MAX_HEIGHT 4.0f
+#define BOX_AXIS_COS .96f        /* walls within ~16 deg of the two room axes (smeared depth tilted a real
+                                  * wall 12 deg in the owner's scan) */
+#define BOX_SNAP .5f             /* m: a rectangle side snaps to a detected wall this close */
+#define BOX_LOW_SHARE .02f       /* surfaces beyond the 2nd/98th percentile along an axis are outliers */
+#define WALL_BAND_TOP 2.4f       /* m above the floor: walls are fitted below this (and below the ceiling) */
+#define MIN_FURNITURE_TOP .25f
+#define WALL_FURNITURE_CLEARANCE .15f
+#define MIN_TOP_DENSITY .30f
+
+static void consolidate_walls(Scan *s)
+{
+    if(!s->nplanes) return;
+    Plane result[MAX_PLANES]={0};int count=0;
+    float largest=0;
+    for(int i=0;i<s->nplanes;i++) {
+        Plane p=s->planes[i];int merge=-1;
+        largest=mx(largest,p.area);
+        for(int j=0;j<count;j++) if(dot(p.n,result[j].n)>WALL_MERGE_COSINE &&
+            ab(p.d-result[j].d)<WALL_MERGE_DISTANCE) { merge=j;break; }
+        if(merge<0) result[count++]=p;
+        else {
+            Plane *r=&result[merge];
+            r->area+=p.area;r->bottom=mn(r->bottom,p.bottom);r->top=mx(r->top,p.top);
+            r->lo=mn(r->lo,p.lo);r->hi=mx(r->hi,p.hi);
+        }
+    }
+    float base=angle(result[0].n.z,result[0].n.x),aligned=0,total=0;
+    for(int i=0;i<count;i++) {
+        Plane *p=&result[i];float a=angle(p->n.z,p->n.x)-base;
+        float delta=ab(a-flo(a/(PI/2)+.5f)*(PI/2));
+        total+=p->area;
+        if(delta<DOMINANT_WALL_TOLERANCE*PI/180) aligned+=p->area;
+    }
+    int orthogonal=aligned>total*ORTHOGONAL_SUPPORT_FRACTION && s->opt.snap_degrees>0;
+    s->nplanes=0;
+    for(int i=0;i<count;i++) {
+        Plane p=result[i];float a=angle(p.n.z,p.n.x)-base;
+        float delta=ab(a-flo(a/(PI/2)+.5f)*(PI/2));
+        if(p.area<largest*RELATIVE_WALL_AREA) continue;
+        if(orthogonal && delta>DOMINANT_WALL_TOLERANCE*PI/180) continue;
+        s->planes[s->nplanes++]=p;
+    }
+}
+
+static float plane_height(Scan *s, int ceiling, int *found)
+{
+    float hist[512]={0}, step=s->opt.voxel*.5f;
+    int bins=(int)(4/step)+2;
+    if (bins>512) bins=512;
+    for (int i=0;i<s->count;i++) {
+        Cell *c=&s->cells[i];
+        if (!c->weight || (ceiling ? c->n.y > -s->opt.horizontal : c->n.y < s->opt.horizontal)) continue;
+        if (ceiling ? c->p.y<s->opt.ceiling_min : ab(c->p.y)>s->opt.floor_band) continue;
+        int b=flo((c->p.y-s->origin.y)/step);
+        if (b>=0 && b<bins) hist[b]+=1;
+    }
+    int best=0;
+    float score=0;
+    for (int b=1;b<bins-1;b++) {
+        float h=hist[b-1]+hist[b]+hist[b+1];
+        if (h>score) { score=h; best=b; }
+    }
+    float y=s->origin.y+(best+.5f)*step, total=0, sum=0,upward=0;
+    for (int i=0;i<s->count;i++) {
+        Cell *c=&s->cells[i];
+        if(c->weight && c->n.y>s->opt.horizontal) upward++;
+        if (!c->weight || ab(c->p.y-y)>s->opt.plane_distance) continue;
+        if (ceiling ? c->n.y > -s->opt.horizontal : c->n.y < s->opt.horizontal) continue;
+        total++; sum+=c->p.y;
+    }
+    *found=(ceiling || score* s->opt.voxel*s->opt.voxel >= s->opt.min_plane_area) && total>0;
+    /* A ceiling is judged on its own area and height, not against the floor: players glance up for a second and look
+     * at the floor all the time, so a share-of-upward-surfaces rule rejected every real ceiling (owner's scans,
+     * 2026-10-16: down-facing surfaces at ~2.9 m in both recordings, "ceiling not seen"). */
+    (void)upward;
+    if(ceiling && (total*s->opt.voxel*s->opt.voxel<CEILING_MIN_AREA || y-s->floor<CEILING_MIN_HEIGHT ||
+                   y-s->floor>CEILING_MAX_HEIGHT)) *found=0;
+    return *found ? sum/total : (ceiling ? s->floor+s->opt.ceiling_default : 0);
+}
+static int on_plane(Scan *s, Cell *c, Plane *p)
+{
+    return ab(dot(c->p,p->n)-p->d)<s->opt.plane_distance && dot(c->n,p->n)>NORMAL_AGREEMENT;
+}
+static void refine(Scan *s, int *ids, int n, Plane *p)
+{
+    Vec avg=vec(0,0,0), normal=vec(0,0,0);
+    float count=0;
+    for (int i=0;i<n;i++) {
+        Cell *c=&s->cells[ids[i]];
+        if (!c->mark && on_plane(s,c,p)) { avg=add(avg,c->p); normal=add(normal,c->n); count++; }
+    }
+    if (!count) return;
+    avg=mul(avg,1/count);
+    /* Fit positions, rather than averaging noisy per-triangle normals. */
+    float xx=0,zz=0,xz=0;
+    for (int i=0;i<n;i++) {
+        Cell *c=&s->cells[ids[i]];
+        if (!c->mark && on_plane(s,c,p)) {
+            float x=c->p.x-avg.x,z=c->p.z-avg.z;
+            xx+=x*x; zz+=z*z; xz+=x*z;
+        }
+    }
+    float yaw=.5f*angle(2*xz,xx-zz);
+    Vec nn=vec(-sine(yaw),0,cosine(yaw));
+    if (dot(nn,normal)<0) nn=mul(nn,-1);
+    p->n=nn; p->d=dot(nn,avg);
+    p->lo=1e10f; p->hi=-1e10f; p->bottom=1e10f; p->top=-1e10f;
+    count=0;
+    for (int i=0;i<n;i++) {
+        Cell *c=&s->cells[ids[i]];
+        if (!c->mark && on_plane(s,c,p)) {
+            float t=c->p.x*p->n.z-c->p.z*p->n.x;
+            p->lo=mn(p->lo,t); p->hi=mx(p->hi,t);
+            p->bottom=mn(p->bottom,c->p.y); p->top=mx(p->top,c->p.y); count++;
+        }
+    }
+    p->area=count*s->opt.voxel*s->opt.voxel;
+}
+static void walls(Scan *s, int *ids, int n)
+{
+    /* Walls are fitted in a fixed band above the floor whatever the ceiling: Valve's smoothed depth bends where wall
+     * meets ceiling, and with a detected 2.9 m ceiling that band confused the fit (owner's scan, 2026-10-16). */
+    float top=mn(s->ceiling,s->floor+WALL_BAND_TOP)-FURNITURE_MARGIN;
+    for (int i=0;i<n;i++) {
+        Cell *c=&s->cells[ids[i]];
+        c->mark=ab(c->n.y)>VERTICAL_NORMAL_Y || c->p.y<s->floor+FURNITURE_MARGIN || c->p.y>top;
+    }
+    for (int attempt=0;attempt<MAX_PLANES*2 && s->nplanes<MAX_PLANES;attempt++) {
+        Plane best={0}; int best_count=0;
+        for (int trial=0;trial<RANSAC_TRIALS;trial++) {
+            Cell *seed=&s->cells[ids[random_next(s)%(unsigned)n]];
+            if (seed->mark) continue;
+            Plane p={0}; p.n=unit(vec(seed->n.x,0,seed->n.z)); p.d=dot(seed->p,p.n);
+            int count=0;
+            for (int j=0;j<n;j++) {
+                Cell *c=&s->cells[ids[j]];
+                if (!c->mark && on_plane(s,c,&p)) count++;
+            }
+            if (count>best_count) { best_count=count; best=p; }
+        }
+        if (best_count*s->opt.voxel*s->opt.voxel<s->opt.min_plane_area) break;
+        refine(s,ids,n,&best);
+        /* Height separates large furniture faces from room walls. */
+        int wall=best.area>=s->opt.min_plane_area && best.top-best.bottom>=s->opt.wall_height &&
+                 best.hi-best.lo>=MIN_WALL_SPAN;
+        for (int j=0;j<n;j++) {
+            Cell *c=&s->cells[ids[j]];
+            if (!c->mark && on_plane(s,c,&best)) c->mark=wall ? 2 : 3;
+        }
+        if (wall) s->planes[s->nplanes++]=best;
+        /* Rejected candidates are consumed too, ensuring bounded progress. */
+    }
+    if (s->nplanes==MAX_PLANES) warn(s,"wall limit reached");
+    if (s->nplanes) {
+        float base=angle(s->planes[0].n.z,s->planes[0].n.x);
+        for (int k=0;k<s->nplanes;k++) {
+            Plane *p=&s->planes[k];
+            float a=angle(p->n.z,p->n.x), diff=a-base;
+            int quarter=flo(diff/(PI/2)+.5f);
+            float target=base+quarter*(PI/2);
+            if (ab(a-target)<s->opt.snap_degrees*PI/180) {
+                Vec nn=vec(cosine(target),0,sine(target));
+                float sum=0,count=0,lo=1e10f,hi=-1e10f;
+                for (int j=0;j<n;j++) {
+                    Cell *c=&s->cells[ids[j]];
+                    if (on_plane(s,c,p)) {
+                        sum+=dot(c->p,nn); count++;
+                        float t=c->p.x*nn.z-c->p.z*nn.x;
+                        lo=mn(lo,t); hi=mx(hi,t);
+                    }
+                }
+                if (count) { p->n=nn; p->d=sum/count; p->lo=lo; p->hi=hi; }
+            }
+        }
+    }
+    consolidate_walls(s);
+}
+static Pt endpoint(Plane *p, int end)
+{
+    float t=end ? p->hi : p->lo;
+    return (Pt){p->n.x*p->d+p->n.z*t,p->n.z*p->d-p->n.x*t};
+}
+static float distance2(Pt a, Pt b) { float x=a.x-b.x,z=a.z-b.z; return x*x+z*z; }
+static int intersect(Plane *a, Plane *b, Pt *p)
+{
+    float det=a->n.x*b->n.z-a->n.z*b->n.x;
+    if (ab(det)<.1f) return 0;
+    p->x=(a->d*b->n.z-a->n.z*b->d)/det;
+    p->z=(a->n.x*b->d-a->d*b->n.x)/det;
+    return 1;
+}
+static void push_outline(Scan *s, Pt p, int invisible)
+{
+    if (s->noutline && distance2(s->outline[s->noutline-1],p)<.0001f) return;
+    if (s->noutline<MAX_OUTLINE) {
+        s->outline[s->noutline]=p;
+        s->invisible[s->noutline++]=invisible;
+    }
+}
+static void rectangle(Scan *s, int *ids, int n)
+{
+    float x0=1e10f,x1=-1e10f,z0=1e10f,z1=-1e10f;
+    for (int i=0;i<n;i++) {
+        Vec p=s->cells[ids[i]].p;
+        x0=mn(x0,p.x);x1=mx(x1,p.x);z0=mn(z0,p.z);z1=mx(z1,p.z);
+    }
+    if (x1-x0<MIN_OUTLINE_EXTENT) { float m=(x0+x1)*.5f; x0=m-MIN_OUTLINE_EXTENT/2; x1=m+MIN_OUTLINE_EXTENT/2; }
+    if (z1-z0<MIN_OUTLINE_EXTENT) { float m=(z0+z1)*.5f; z0=m-MIN_OUTLINE_EXTENT/2; z1=m+MIN_OUTLINE_EXTENT/2; }
+    push_outline(s,(Pt){x0,z0},1);push_outline(s,(Pt){x1,z0},1);
+    push_outline(s,(Pt){x1,z1},1);push_outline(s,(Pt){x0,z1},1);
+    warn(s,"incomplete walls; synthesized outline");
+}
+static int segment_cross(Pt a, Pt b, Pt c, Pt d)
+{
+    float p=(b.x-a.x)*(c.z-a.z)-(b.z-a.z)*(c.x-a.x);
+    float q=(b.x-a.x)*(d.z-a.z)-(b.z-a.z)*(d.x-a.x);
+    float r=(d.x-c.x)*(a.z-c.z)-(d.z-c.z)*(a.x-c.x);
+    float t=(d.x-c.x)*(b.z-c.z)-(d.z-c.z)*(b.x-c.x);
+    return p*q<-.000001f && r*t<-.000001f;
+}
+static int valid_polygon(Scan *s)
+{
+    float area=0;
+    for (int i=0;i<s->noutline;i++) {
+        Pt a=s->outline[i], b=s->outline[(i+1)%s->noutline];
+        area+=a.x*b.z-b.x*a.z;
+        for (int j=i+2;j<s->noutline;j++) {
+            if ((j+1)%s->noutline==i) continue;
+            if (segment_cross(a,b,s->outline[j],s->outline[(j+1)%s->noutline])) return 0;
+        }
+    }
+    return s->noutline>=3 && area>MIN_OUTLINE_TWICE_AREA;
+}
+static int convex_fallback(Scan *s)
+{
+    if(s->nplanes<3 || s->nplanes>4) return 0;
+    /* A concave multi-wall room must use directed segments. A small set of enclosure planes can instead be
+     * clipped as inward half-planes when smeared endpoints prevent reliable corner ordering. */
+    Pt a[MAX_OUTLINE],b[MAX_OUTLINE];float x0=1e10f,x1=-1e10f,z0=1e10f,z1=-1e10f;
+    for(int i=0;i<s->nplanes;i++) for(int end=0;end<2;end++) {
+        Pt p=endpoint(&s->planes[i],end);x0=mn(x0,p.x);x1=mx(x1,p.x);z0=mn(z0,p.z);z1=mx(z1,p.z);
+    }
+    int n=4;a[0]=(Pt){x0,z0};a[1]=(Pt){x1,z0};a[2]=(Pt){x1,z1};a[3]=(Pt){x0,z1};
+    for(int i=0;i<s->nplanes;i++) {
+        Plane *p=&s->planes[i];int count=0;
+        for(int j=0;j<n;j++) {
+            Pt u=a[j],v=a[(j+1)%n];float du=p->n.x*u.x+p->n.z*u.z-p->d,dv=p->n.x*v.x+p->n.z*v.z-p->d;
+            if(du>=0) b[count++]=u;
+            if((du>=0)!=(dv>=0)) {
+                float t=du/(du-dv);b[count++]=(Pt){u.x+t*(v.x-u.x),u.z+t*(v.z-u.z)};
+            }
+        }
+        if(count<3 || count>=MAX_OUTLINE) return 0;
+        n=count;memcpy(a,b,(usize)n*sizeof(Pt));
+    }
+    s->noutline=n;
+    for(int j=0;j<n;j++) {
+        s->outline[j]=a[j];s->invisible[j]=1;Pt v=a[(j+1)%n];
+        for(int i=0;i<s->nplanes;i++) {
+            Plane *p=&s->planes[i];
+            if(ab(p->n.x*a[j].x+p->n.z*a[j].z-p->d)<s->opt.plane_distance &&
+               ab(p->n.x*v.x+p->n.z*v.z-p->d)<s->opt.plane_distance) s->invisible[j]=0;
+        }
+    }
+    if(!valid_polygon(s)) { s->noutline=0;return 0; }
+    warn(s,"wall endpoints uncertain; using plane intersections");return 1;
+}
+/* Value below which `share` of the projections fall (2 cm bins over +-8 m around the data). */
+static float projection_percentile(Scan *s, int *ids, int n, Pt axis, float share)
+{
+    static u32 hist[800];
+    memset(hist,0,sizeof(hist));
+    for (int i=0;i<n;i++) {
+        Vec p=s->cells[ids[i]].p;
+        int b=(int)((p.x*axis.x+p.z*axis.z+8)/.02f);
+        if (b>=0 && b<800) hist[b]++;
+    }
+    u64 total=0,run=0;
+    for (int b=0;b<800;b++) total+=hist[b];
+    for (int b=0;b<800;b++) { run+=hist[b]; if (run>=share*total) return b*.02f-8+.01f; }
+    return 8;
+}
+/* Most rooms are rectangles. When every detected wall runs along one of two perpendicular axes (2-4 walls), the
+ * outline is that rectangle: its sides at the 2nd/98th percentile of the surfaces along each axis, each snapped to a
+ * detected wall when one lies within BOX_SNAP. Directed wall chaining made a skewed quadrilateral of the owner's
+ * room from three smeared walls (2026-10-16). L-shaped rooms have more walls and keep the chaining below. */
+static int orthogonal_box(Scan *s, int *ids, int n)
+{
+    if (s->nplanes<2 || s->nplanes>4) return 0;
+    Vec u=s->planes[0].n; float len=root(u.x*u.x+u.z*u.z);
+    if (len<.5f) return 0;
+    Pt axis[2]={{u.x/len,u.z/len},{-u.z/len,u.x/len}};
+    float side[2][2]; int wall[2][2]={{0,0},{0,0}}, snapped=0;
+    for (int k=0;k<2;k++) {
+        side[k][0]=projection_percentile(s,ids,n,axis[k],BOX_LOW_SHARE);
+        side[k][1]=projection_percentile(s,ids,n,axis[k],1-BOX_LOW_SHARE);
+    }
+    for (int i=0;i<s->nplanes;i++) {
+        Plane *p=&s->planes[i];
+        float c0=p->n.x*axis[0].x+p->n.z*axis[0].z, c1=p->n.x*axis[1].x+p->n.z*axis[1].z;
+        int k=ab(c0)>=BOX_AXIS_COS ? 0 : ab(c1)>=BOX_AXIS_COS ? 1 : -1;
+        if (k<0) return 0;  // a wall off both axes: not a rectangle
+        float offset=p->d*(k ? c1 : c0)/ab(k ? c1 : c0);
+        int end=ab(offset-side[k][0])<ab(offset-side[k][1]) ? 0 : 1;
+        if (ab(offset-side[k][end])<BOX_SNAP) { side[k][end]=offset; snapped+=!wall[k][end]; wall[k][end]=1; }
+    }
+    if (snapped<2 || side[0][1]-side[0][0]<MIN_OUTLINE_EXTENT || side[1][1]-side[1][0]<MIN_OUTLINE_EXTENT) return 0;
+    /* corners (s,t) -> world x = a0.x s + a1.x t, z = a0.z s + a1.z t; edge flags = whether its side is a wall */
+    int order[4][2]={{0,0},{1,0},{1,1},{0,1}}, edge[4][2]={{1,0},{0,1},{1,1},{0,0}};  // edge k lies on side[a][e]
+    float twice=0;
+    Pt c[4];
+    for (int j=0;j<4;j++) {
+        float a=side[0][order[j][0]], b=side[1][order[j][1]];
+        c[j]=(Pt){axis[0].x*a+axis[1].x*b, axis[0].z*a+axis[1].z*b};
+    }
+    for (int j=0;j<4;j++) twice+=c[j].x*c[(j+1)%4].z-c[(j+1)%4].x*c[j].z;
+    s->noutline=0;
+    if (twice>0) for (int j=0;j<4;j++) push_outline(s,c[j],!wall[edge[j][0]][edge[j][1]]);
+    else for (int j=0;j<4;j++) {  // reversed: corner 0,3,2,1; edge from corner k to k-1 is the old edge k-1
+        int k=(4-j)%4, e=(k+3)%4;
+        push_outline(s,c[k],!wall[edge[e][0]][edge[e][1]]);
+    }
+    if (!valid_polygon(s)) { s->noutline=0; return 0; }
+    if (snapped<4) warn(s,"gaps closed with invisible walls");
+    return 1;
+}
+static void outline(Scan *s, int *ids, int n)
+{
+    if (orthogonal_box(s,ids,n)) return;
+    if (s->nplanes<3) { rectangle(s,ids,n); return; }
+    int order[MAX_PLANES]={0};
+    s->planes[0].used=1;
+    for (int k=1;k<s->nplanes;k++) {
+        Pt end=endpoint(&s->planes[order[k-1]],1);
+        float best=1e10f; int which=-1;
+        for (int j=0;j<s->nplanes;j++) if (!s->planes[j].used) {
+            float d=distance2(end,endpoint(&s->planes[j],0));
+            if (d<best) { best=d;which=j; }
+        }
+        order[k]=which;s->planes[which].used=1;
+    }
+    Pt starts[MAX_PLANES], ends[MAX_PLANES];
+    for (int k=0;k<s->nplanes;k++) {
+        Plane *p=&s->planes[order[k]], *next=&s->planes[order[(k+1)%s->nplanes]];
+        ends[k]=endpoint(p,1); starts[(k+1)%s->nplanes]=endpoint(next,0);
+        Pt corner;
+        if (intersect(p,next,&corner) && distance2(corner,ends[k])<s->opt.gap*s->opt.gap &&
+            distance2(corner,starts[(k+1)%s->nplanes])<s->opt.gap*s->opt.gap)
+            ends[k]=starts[(k+1)%s->nplanes]=corner;
+    }
+    for (int k=0;k<s->nplanes;k++) {
+        push_outline(s,starts[k],0);
+        if (distance2(ends[k],starts[(k+1)%s->nplanes])>.0001f) {
+            push_outline(s,ends[k],1);warn(s,"gaps closed with invisible walls");
+        }
+    }
+    if (!valid_polygon(s)) {
+        s->noutline=0;
+        if(!convex_fallback(s)) { rectangle(s,ids,n);warn(s,"wall ordering ambiguous"); }
+    }
+}
+static float wall_distance(Scan *s, Vec p)
+{
+    float best=1e10f;
+    for (int i=0;i<s->nplanes;i++) best=mn(best,ab(dot(s->planes[i].n,p)-s->planes[i].d));
+    return best;
+}
+static void trimmed_bounds(Scan *s, int *queue, int n, Vec axis, float *lo, float *hi)
+{
+    int hist[512]={0};float start=*lo,range=*hi-start;
+    if(range<.001f) return;
+    for(int i=0;i<n;i++) {
+        float value=dot(s->cells[queue[i]].p,axis);
+        int bin=(int)clamp((value-start)/range*511,0,511);hist[bin]++;
+    }
+    int count=0,target=(int)(n*BOX_TRIM);
+    for(int b=0;b<512;b++) { count+=hist[b];if(count>target) { *lo=start+range*b/511;break; } }
+    count=0;
+    for(int b=511;b>=0;b--) { count+=hist[b];if(count>target) { *hi=start+range*(b+1)/511;break; } }
+}
+static float top_height(Scan *s, int *queue, int n, float low, float high)
+{
+    int histogram[512]={0},bins=(int)mn((high-low)/(s->opt.voxel*.25f)+2,512);
+    float step=s->opt.voxel*.25f;
+    for(int i=0;i<n;i++) {
+        int bin=flo((s->cells[queue[i]].p.y-low)/step);
+        if(bin>=0 && bin<bins) histogram[bin]++;
+    }
+    int count=0;
+    for(int bin=0;bin<bins;bin++) {
+        count+=histogram[bin];
+        /* The median resists a softened lip without selecting one of several noisy sub-peaks as a new top. */
+        if(count>=n/2) return low+(bin+.5f)*step;
+    }
+    return (low+high)*.5f;
+}
+static void furniture(Scan *s, int *ids, int n, int *queue)
+{
+    /* Tops remain separable when a softened sofa/table edge blends into its neighbouring wall. Vertical-only
+     * components are considered separately for screens; they cannot turn a whole wall into an OTHER volume. */
+    for(int mode=0;mode<2;mode++) {
+    float histogram[256]={0},levels[32];int nlevels=0;
+    if(!mode) {
+        for(int j=0;j<n;j++) {
+            Cell *c=&s->cells[ids[j]];
+            if(c->n.y>s->opt.horizontal && c->p.y>s->floor+MIN_FURNITURE_TOP &&
+               c->p.y<s->ceiling-FURNITURE_MARGIN && wall_distance(s,c->p)>WALL_FURNITURE_CLEARANCE) {
+                int bin=flo((c->p.y-s->floor)/s->opt.voxel);
+                if(bin>=0 && bin<256) histogram[bin]++;
+            }
+        }
+        for(int k=0;k<32;k++) {
+            int best=0;float score=0;
+            for(int bin=1;bin<255;bin++) {
+                float count=histogram[bin-1]+histogram[bin]+histogram[bin+1];
+                if(count>score) { score=count;best=bin; }
+            }
+            if(score*s->opt.voxel*s->opt.voxel<MIN_TOP_AREA) break;
+            levels[nlevels++]=s->floor+(best+.5f)*s->opt.voxel;
+            int radius=(int)(s->opt.plane_distance*2/s->opt.voxel)+1;
+            for(int bin=best-radius;bin<=best+radius;bin++) if(bin>=0 && bin<256) histogram[bin]=0;
+        }
+    }
+    for (int j=0;j<n;j++) {
+        Cell *c=&s->cells[ids[j]];
+        int normal=mode ? ab(c->n.y)<BOX_SIDE_NORMAL_Y : c->n.y>s->opt.horizontal;
+        c->mark=(normal && c->p.y>s->floor+MIN_FURNITURE_TOP && c->p.y<s->ceiling-FURNITURE_MARGIN &&
+                 wall_distance(s,c->p)>WALL_FURNITURE_CLEARANCE) ? 1 : 0;
+        if(c->mark && !mode) {
+            c->mark=0;float best=s->opt.plane_distance*2;
+            for(int k=0;k<nlevels;k++) if(ab(c->p.y-levels[k])<best) {
+                best=ab(c->p.y-levels[k]);c->mark=k+1;
+            }
+        }
+    }
+    int radius=(int)(s->opt.cluster_gap/s->opt.voxel)+1;
+    for (int j=0;j<n;j++) {
+        int seed=ids[j];
+        if (s->cells[seed].mark<=0) continue;
+        int group=s->cells[seed].mark;
+        int head=0,tail=1;queue[0]=seed;s->cells[seed].mark=-1;
+        while (head<tail) {
+            int id=queue[head++],x=id%s->nx,z=(id/s->nx)%s->nz,y=id/(s->nx*s->nz);
+            for (int dy=-radius;dy<=radius;dy++) for (int dz=-radius;dz<=radius;dz++) for (int dx=-radius;dx<=radius;dx++) {
+                if (dx*dx+dy*dy+dz*dz>radius*radius) continue;
+                int xx=x+dx,yy=y+dy,zz=z+dz;
+                if (xx<0 || yy<0 || zz<0 || xx>=s->nx || yy>=s->ny || zz>=s->nz) continue;
+                int next=(yy*s->nz+zz)*s->nx+xx;
+                Cell *c=&s->cells[next];
+                if (c->mark==group) { c->mark=-1;queue[tail++]=next; }
+            }
+        }
+        if (tail<MIN_CLUSTER_SURFELS) continue;
+        Vec avg=vec(0,0,0);float top=-1e10f,bottom=1e10f;
+        for (int k=0;k<tail;k++) {
+            Vec p=s->cells[queue[k]].p;avg=add(avg,p);top=mx(top,p.y);bottom=mn(bottom,p.y);
+        }
+        avg=mul(avg,1.f/tail);
+        float xx=0,zz=0,xz=0,edge_x=0,edge_y=0,edge_count=0;
+        for (int k=0;k<tail;k++) {
+            Cell *c=&s->cells[queue[k]];
+            Vec p=sub(c->p,avg);xx+=p.x*p.x;zz+=p.z*p.z;xz+=p.x*p.z;
+            if(ab(c->n.y)<BOX_SIDE_NORMAL_Y) {
+                Vec norm=unit(vec(c->n.x,0,c->n.z));
+                float co2=norm.x*norm.x-norm.z*norm.z,si2=2*norm.x*norm.z;
+                edge_x+=co2*co2-si2*si2;edge_y+=2*co2*si2;edge_count++;
+            }
+        }
+        float yaw=.5f*angle(2*xz,xx-zz);
+        /* Opposing faces and perpendicular edges vote for the same fourth harmonic. Unlike PCA, this is not
+         * biased by one side being more visible. Non-box objects fall back to position covariance. */
+        if(edge_count>MIN_BOX_EDGE_VOTES && root(edge_x*edge_x+edge_y*edge_y)>edge_count*BOX_EDGE_STRENGTH)
+            yaw=.25f*angle(edge_y,edge_x);
+        if(!mode) {
+            float smallest=1e10f;
+            for(int degree=0;degree<90;degree++) {
+                float a=degree*PI/180,co=cosine(a),si=sine(a),u0=1e10f,u1=-1e10f,v0=1e10f,v1=-1e10f;
+                for(int k=0;k<tail;k++) {
+                    Vec p=s->cells[queue[k]].p;float u=p.x*co+p.z*si,v=-p.x*si+p.z*co;
+                    u0=mn(u0,u);u1=mx(u1,u);v0=mn(v0,v);v1=mx(v1,v);
+                }
+                float area=(u1-u0)*(v1-v0);
+                if(area<smallest) { smallest=area;yaw=a; }
+            }
+        }
+        float co=cosine(yaw),si=sine(yaw);
+        float u0=1e10f,u1=-1e10f,v0=1e10f,v1=-1e10f,top_count=0;
+        for (int k=0;k<tail;k++) {
+            Cell *c=&s->cells[queue[k]];Vec p=sub(c->p,avg);
+            float u=p.x*co+p.z*si,v=-p.x*si+p.z*co;
+            u0=mn(u0,u);u1=mx(u1,u);v0=mn(v0,v);v1=mx(v1,v);
+            if (c->n.y>s->opt.horizontal && c->p.y>top-s->opt.plane_distance*2) top_count++;
+        }
+        /* Stereo discontinuities leave a low-density halo even after long-edge rejection. Trim the outer
+         * two percent before measuring boxes; otherwise a table can become wide enough to look like a couch. */
+        float up=dot(avg,vec(co,0,si)),vp=dot(avg,vec(-si,0,co));
+        u0+=up;u1+=up;v0+=vp;v1+=vp;
+        trimmed_bounds(s,queue,tail,vec(co,0,si),&u0,&u1);
+        trimmed_bounds(s,queue,tail,vec(-si,0,co),&v0,&v1);
+        u0-=up;u1-=up;v0-=vp;v1-=vp;
+        trimmed_bounds(s,queue,tail,vec(0,1,0),&bottom,&top);
+        if(!mode) top=top_height(s,queue,tail,bottom,top);
+        float w=u1-u0,d=v1-v0,h=top-(bottom<s->floor+FLOOR_INFER_DISTANCE ? s->floor : mn(bottom,s->floor+FURNITURE_MARGIN));
+        if(d>w) { float t=w;w=d;d=t;yaw+=PI/2; }
+        while(yaw>PI/2) yaw-=PI;
+        if(!mode) h=top-s->floor;
+        if (w*d*h<s->opt.min_volume) continue;
+        float height=top-s->floor,area=w*d,top_area=(mode ? top_count : tail)*s->opt.voxel*s->opt.voxel;
+        if(!mode && (top_area<MIN_TOP_AREA || top_area<area*MIN_TOP_DENSITY)) continue;
+        const char *label="OTHER";
+        if (height>=BED_MIN_HEIGHT && height<=BED_MAX_HEIGHT && area>=BED_MIN_AREA) label="BED";
+        else if (height>=COUCH_MIN_HEIGHT && height<=COUCH_MAX_HEIGHT && mx(w,d)+2*s->opt.voxel>=COUCH_MIN_LENGTH) label="COUCH";
+        else if (height>=TABLE_MIN_HEIGHT && height<=TABLE_MAX_HEIGHT && top_area>=MIN_TOP_AREA) label="TABLE";
+        else if (mn(w,d)<SCREEN_MAX_DEPTH && mx(w,d)>=SCREEN_MIN_WIDTH && mx(w,d)<=SCREEN_MAX_WIDTH &&
+                 wall_distance(s,avg)<NEAR_WALL) label="SCREEN";
+        else if (h>=STORAGE_MIN_HEIGHT && wall_distance(s,avg)<NEAR_WALL) label="STORAGE";
+        if(mode && !same(label,"SCREEN")) continue;
+        if(!mode && same(label,"OTHER") && height>TABLE_MAX_HEIGHT) continue;
+        if (s->nvolumes>=MAX_VOLUMES) { warn(s,"furniture limit reached");break; }
+        Vec centre=vec(avg.x+co*(u0+u1)*.5f-si*(v0+v1)*.5f,top,
+                       avg.z+si*(u0+u1)*.5f+co*(v0+v1)*.5f);
+        /* ROOM_FORMAT yaw is an active right-handed rotation about +Y. */
+        s->volumes[s->nvolumes++]=(Volume){centre,-yaw*180/PI,w,d,h,label};
+    }
+    }
+}
+
+/* A hint is a fallback for missing walls, never a constraint on observed geometry. */
+static const char *hint(Scan *s);
+const char *make_model(Scan *s)
+{
+    int found;
+    s->floor=plane_height(s,0,&found);
+    if (!found) warn(s,"floor not seen; using STAGE floor");
+    s->ceiling=plane_height(s,1,&found);
+    if (!found) warn(s,"ceiling not seen");
+    usize bytes=(usize)s->count*sizeof(int);
+    int *ids=io_alloc(bytes),*queue=io_alloc(bytes);
+    if (!ids || !queue) { io_free(ids,bytes);io_free(queue,bytes);return "model allocation failed"; }
+    int n=0;
+    for (int i=0;i<s->count;i++) if (s->cells[i].weight) ids[n++]=i;
+    if (!n) { io_free(ids,bytes);io_free(queue,bytes);return "no surfaces in reconstruction bounds"; }
+    walls(s,ids,n);outline(s,ids,n);
+    const char *error=hint(s);
+    if (!error) furniture(s,ids,n,queue);
+    float perimeter=0,observed=0;
+    for (int i=0;i<s->noutline;i++) {
+        float d=root(distance2(s->outline[i],s->outline[(i+1)%s->noutline]));perimeter+=d;
+        if (!s->invisible[i]) observed+=d;
+    }
+    s->coverage=perimeter ? 100*observed/perimeter : 0;
+    if (s->coverage<LOW_COVERAGE_PERCENT) warn(s,"low wall coverage; scan all walls");
+    io_free(ids,bytes);io_free(queue,bytes);
+    return error;
+}
+
+int parse_number(char **cursor, float *value)
+{
+    char *p=*cursor;while (*p==' ' || *p=='\t' || *p=='\r') p++;
+    int sign=1,digits=0;if (*p=='-' || *p=='+') { if (*p=='-') sign=-1;p++; }
+    float v=0,scale=1;
+    while (*p>='0' && *p<='9') { v=v*10+*p++-'0';digits++;if(v>10000) return 0; }
+    if (*p=='.') { p++;while (*p>='0' && *p<='9') { scale*=.1f;v+=(*p++-'0')*scale;digits++; } }
+    if(*p=='e' || *p=='E') {
+        p++;int exponent=0,negative=0,edigits=0;
+        if(*p=='-' || *p=='+') { negative=*p=='-';p++; }
+        while(*p>='0' && *p<='9') { exponent=exponent*10+*p++-'0';edigits++;if(exponent>38) return 0; }
+        if(!edigits) return 0;
+        while(exponent--) v=negative ? v*.1f : v*10;
+    }
+    if (!digits || !finite(v) || v>10000) return 0;
+    *value=sign*v;*cursor=p;return 1;
+}
+static const char *hint(Scan *s)
+{
+    if (!s->opt.hint) return 0;
+    int fd=io_open(s->opt.hint,0);
+    if (fd<0) return "cannot open outline hint";
+    char data[8192];usize size=0;
+    for (;;) {
+        long r=io_read(fd,data+size,sizeof(data)-1-size);
+        if (r<0 || (r>0 && size+(usize)r==sizeof(data)-1)) { io_close(fd);return "outline hint too large or unreadable"; }
+        if (!r) break;
+        size+=(usize)r;
+    }
+    io_close(fd);data[size]=0;
+    Pt pts[MAX_OUTLINE];int n=0;char *p=data;
+    while (*p) {
+        while (*p==' ' || *p=='\t' || *p=='\r' || *p=='\n') p++;
+        if (!*p) break;
+        if (*p=='#') { while (*p && *p!='\n') p++;continue; }
+        if (n==MAX_OUTLINE || !parse_number(&p,&pts[n].x) || !parse_number(&p,&pts[n].z)) return "invalid outline hint";
+        n++;while (*p==' ' || *p=='\t' || *p=='\r') p++;
+        if (*p && *p!='\n' && *p!='#') return "invalid outline hint";
+        if (*p=='#') while (*p && *p!='\n') p++;
+    }
+    if (n<3) return "outline hint needs at least three points";
+    Pt centre={0};for (int i=0;i<n;i++) { centre.x+=pts[i].x/n;centre.z+=pts[i].z/n; }
+    float mean=0,variance=0;
+    for (int i=0;i<n;i++) mean+=root(distance2(pts[i],centre))/n;
+    for (int i=0;i<n;i++) { float r=root(distance2(pts[i],centre))-mean;variance+=r*r/n; }
+    if (n>=DEFAULT_CIRCLE_MIN_POINTS && root(variance)<mean*DEFAULT_CIRCLE_RADIAL_CV) {
+        warn(s,"default circle hint ignored");return 0;
+    }
+    int missing=0;for(int i=0;i<s->noutline;i++) missing+=s->invisible[i];
+    if (!missing) return 0;
+    Pt saved[MAX_OUTLINE];int inv[MAX_OUTLINE],old=s->noutline;
+    memcpy(saved,s->outline,sizeof(saved));memcpy(inv,s->invisible,sizeof(inv));
+    float area=0;for(int i=0;i<n;i++) area+=pts[i].x*pts[(i+1)%n].z-pts[(i+1)%n].x*pts[i].z;
+    s->noutline=n;
+    for(int i=0;i<n;i++) { s->outline[i]=pts[area>0 ? i : n-1-i];s->invisible[i]=1; }
+    if (!valid_polygon(s)) {
+        memcpy(s->outline,saved,sizeof(saved));memcpy(s->invisible,inv,sizeof(inv));s->noutline=old;
+        return "invalid outline hint polygon";
+    }
+    /* Only use a hint compatible with every observed wall. Chaperone can be an inset play area. */
+    for(int i=0;i<s->nplanes;i++) {
+        Plane *w=&s->planes[i];int match=0;
+        for(int k=0;k<n;k++) {
+            Pt a=s->outline[k],b=s->outline[(k+1)%n];
+            if(ab(a.x*w->n.x+a.z*w->n.z-w->d)<s->opt.gap &&
+               ab(b.x*w->n.x+b.z*w->n.z-w->d)<s->opt.gap) { match=1;s->invisible[k]=0; }
+        }
+        if (!match) {
+            memcpy(s->outline,saved,sizeof(saved));memcpy(s->invisible,inv,sizeof(inv));s->noutline=old;
+            warn(s,"hint disagrees with observed walls; ignored");return 0;
+        }
+    }
+    s->hint_used=1;warn(s,"incomplete walls closed using outline hint");return 0;
+}
@@ -0,0 +1,145 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+#include "platform.h"
+
+#ifdef FP_HOSTED
+#define _DEFAULT_SOURCE 1
+#include <errno.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <sys/mman.h>
+#include <sys/random.h>
+#include <sys/stat.h>
+#include <time.h>
+#include <unistd.h>
+
+int io_open(const char *p, int w) { return open(p, w ? O_WRONLY|O_CREAT|O_EXCL|O_NOFOLLOW : O_RDONLY, 0600); }
+long io_read(int fd, void *p, usize n)
+{
+    long r;
+    do r = read(fd, p, n); while (r < 0 && errno == EINTR);
+    return r;
+}
+static long put(int fd, const void *p, usize n)
+{
+    long r;
+    do r = write(fd, p, n); while (r < 0 && errno == EINTR);
+    return r;
+}
+int io_close(int fd) { return close(fd); }
+int io_rename(const char *a, const char *b) { return rename(a, b); }
+void io_remove(const char *p) { unlink(p); }
+int io_mkdir(const char *p) { return mkdir(p, 0700) == 0 || errno == EEXIST; }
+void *io_alloc(usize n)
+{
+    void *p = mmap(0, n, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0);
+    return p == MAP_FAILED ? 0 : p;
+}
+void io_free(void *p, usize n) { if (p) munmap(p, n); }
+int io_random(void *p, usize n)
+{
+    usize done = 0;
+    while (done < n) {
+        long r = getrandom((u8 *)p + done, n - done, 0);
+        if (r < 0 && errno == EINTR) continue;
+        if (r <= 0) return 0;
+        done += (usize)r;
+    }
+    return 1;
+}
+i64 io_time(int mono)
+{
+    struct timespec t;
+    if (clock_gettime(mono ? CLOCK_MONOTONIC : CLOCK_REALTIME, &t)) return 0;
+    return (i64)t.tv_sec * 1000000000 + t.tv_nsec;
+}
+#else
+/* asm-generic Linux syscall numbers: this target has no libc or UAPI dependency. */
+static long call(long n, long a, long b, long c, long d, long e, long f)
+{
+    register long x8 __asm__("x8") = n;
+    register long x0 __asm__("x0") = a;
+    register long x1 __asm__("x1") = b;
+    register long x2 __asm__("x2") = c;
+    register long x3 __asm__("x3") = d;
+    register long x4 __asm__("x4") = e;
+    register long x5 __asm__("x5") = f;
+    __asm__ volatile("svc #0" : "+r"(x0) : "r"(x8), "r"(x1), "r"(x2), "r"(x3), "r"(x4), "r"(x5) : "memory", "cc");
+    return x0;
+}
+int io_open(const char *p, int w) { return (int)call(56, -100, (long)p, w ? 1|64|128|131072 : 0, 0600, 0, 0); }
+long io_read(int fd, void *p, usize n)
+{
+    long r;
+    do r = call(63, fd, (long)p, (long)n, 0, 0, 0); while (r == -4);
+    return r;
+}
+static long put(int fd, const void *p, usize n)
+{
+    long r;
+    do r = call(64, fd, (long)p, (long)n, 0, 0, 0); while (r == -4);
+    return r;
+}
+int io_close(int fd) { return (int)call(57, fd, 0, 0, 0, 0, 0); }
+int io_rename(const char *a, const char *b) { return (int)call(38, -100, (long)a, -100, (long)b, 0, 0); }
+void io_remove(const char *p) { call(35, -100, (long)p, 0, 0, 0, 0); }
+int io_mkdir(const char *p)
+{
+    long r = call(34, -100, (long)p, 0700, 0, 0, 0);
+    return r == 0 || r == -17;
+}
+void *io_alloc(usize n)
+{
+    long p = call(222, 0, (long)n, 3, 0x22, -1, 0);
+    return (unsigned long)p > (unsigned long)-4096 ? 0 : (void *)p;
+}
+void io_free(void *p, usize n) { if (p) call(215, (long)p, (long)n, 0, 0, 0, 0); }
+int io_random(void *p, usize n)
+{
+    usize done = 0;
+    while (done < n) {
+        long r = call(278, (long)((u8 *)p + done), (long)(n - done), 0, 0, 0, 0);
+        if (r == -4) continue;
+        if (r <= 0) return 0;
+        done += (usize)r;
+    }
+    return 1;
+}
+i64 io_time(int mono)
+{
+    struct { long sec, ns; } t = {0, 0};
+    call(113, mono ? 1 : 0, (long)&t, 0, 0, 0, 0);
+    return (i64)t.sec * 1000000000 + t.ns;
+}
+void *memcpy(void *d, const void *s, usize n)
+{
+    u8 *a = d;
+    const u8 *b = s;
+    while (n--) *a++ = *b++;
+    return d;
+}
+void *memset(void *d, int c, usize n)
+{
+    u8 *a = d;
+    while (n--) *a++ = (u8)c;
+    return d;
+}
+extern int main(int argc, char **argv);
+__attribute__((used, noreturn)) void start_c(long *sp)
+{
+    int code = main((int)sp[0], (char **)(sp + 1));
+    for (;;) call(94, code, 0, 0, 0, 0, 0);
+}
+__asm__(".text\n.global _start\n.type _start,%function\n_start:\n"
+        "mov x29,#0\nmov x30,#0\nmov x0,sp\nbl start_c\nbrk #0\n");
+#endif
+
+int io_write(int fd, const void *p, usize n)
+{
+    while (n) {
+        long r = put(fd, p, n);
+        if (r <= 0) return 0;
+        p = (const u8 *)p + r;
+        n -= (usize)r;
+    }
+    return 1;
+}
@@ -0,0 +1,25 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+#ifndef FP_ROOMSCAN_PLATFORM_H
+#define FP_ROOMSCAN_PLATFORM_H
+
+/* The reconstruction sources use only this boundary, on Linux and in hosted tests. */
+typedef __SIZE_TYPE__ usize;
+typedef unsigned char u8;
+typedef unsigned int u32;
+typedef unsigned long long u64;
+typedef long long i64;
+int io_open(const char *path, int write);
+long io_read(int fd, void *data, usize size);
+int io_write(int fd, const void *data, usize size);
+int io_close(int fd);
+int io_rename(const char *old, const char *new);
+void io_remove(const char *path);
+int io_mkdir(const char *path);
+void *io_alloc(usize size);
+void io_free(void *data, usize size);
+int io_random(void *data, usize size);
+i64 io_time(int monotonic);
+void *memcpy(void *dst, const void *src, usize size);
+void *memset(void *dst, int value, usize size);
+
+#endif
@@ -0,0 +1,548 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+/* Mesh refinement: the passes of the owner's tuned cleanup page (2026-10-18), in its order and with its rules:
+ * plane offsets re-estimated from the scan, structural (wall/floor/ceiling) triangles classified with one-sided
+ * bands, erase spheres, the walked volume, flat panels or snapping, furniture tops, clipping outside the outline,
+ * small islands, thin floating pieces, Taubin smoothing. docs/mr/scan.md "Refinement" describes each pass. */
+#include "refine.h"
+
+#define WELD_MM 1000.0           /* vertices closer than 1 mm (quantized) are one vertex */
+#define WELD_BIAS 16384          /* key offset, as the reference: +-16 m */
+#define FURNITURE_PAD .1         /* m around a box that still counts as the box */
+#define MIN_SHIFT_SAMPLES 50     /* plane offsets move only with more facing triangles than this */
+#define WALKED_BELOW .2          /* m above the floor: the walked column starts here (feet, rugs stay) */
+#define WALKED_ABOVE .25         /* m above the head: the column ends here */
+#define TOP_NORMAL_Y .8          /* a triangle this upward-facing near a box top is part of the top */
+#define TUBE_MIN_TRIANGLES 10
+#define TUBE_MAX_AREA 1.0        /* m^2: bigger pieces are never thin floating pieces */
+#define TUBE_MAX_FURNITURE .5    /* share of a piece inside furniture boxes that keeps it */
+#define TAUBIN_LAMBDA .5
+#define TAUBIN_MU -.53
+
+double dfloor(double x) { i64 i=(i64)x; return x<(double)i ? (double)(i-1) : (double)i; }
+double droot(double x) { return x>0 ? __builtin_sqrt(x) : 0; }
+/* Double-precision sine (range reduction + Taylor series to x^19, error < 1e-15), as Math.sin. */
+double dsin(double x)
+{
+    const double pi=3.14159265358979323846;
+    x-=dfloor(x/(2*pi)+.5)*(2*pi);
+    if(x>pi/2) x=pi-x;
+    if(x<-pi/2) x=-pi-x;
+    double q=x*x,term=x,sum=x;
+    for(int k=1;k<10;k++) { term*=-q/((2*k)*(2*k+1));sum+=term; }
+    return sum;
+}
+double dcos(double x) { return dsin(x+3.14159265358979323846/2); }
+/* Math.hypot as V8 computes it (scaled, Kahan-compensated): distance ties at outline corners break the same way. */
+double dhypot(double a, double b)
+{
+    a=a<0 ? -a : a;b=b<0 ? -b : b;
+    double m=a>b ? a : b;
+    if(m==0) return 0;
+    double sum=0,comp=0,v[2]={a/m,b/m};
+    for(int i=0;i<2;i++) { double s=v[i]*v[i]-comp,p=sum+s;comp=(p-sum)-s;sum=p; }
+    return droot(sum)*m;
+}
+static double dab(double x) { return x<0 ? -x : x; }
+
+static void *alloc(usize n) { return n ? io_alloc(n) : 0; }
+
+/* ------------------------------------------------------------------------------------------------ welding */
+static u64 mix(u64 k) { k^=k>>33;k*=0xff51afd7ed558ccdull;k^=k>>33;k*=0xc4ceb9fe1a85ec53ull;k^=k>>33;return k; }
+static i64 quant(float v) { return (i64)dfloor((double)v*WELD_MM+.5)+WELD_BIAS; }
+const char *prep_mesh(Prep *p, const Vec *v, const u32 *idx, int nv, int ni)
+{
+    *p=(Prep){0};
+    int T=ni/3;
+    usize cap=1024;while(cap<(usize)nv*2) cap*=2;
+    i64 *keys=alloc(cap*sizeof(i64));
+    int *slot=alloc(cap*sizeof(int)),*wid=alloc((usize)(nv ? nv : 1)*sizeof(int));
+    double *sums=alloc((usize)(nv ? nv : 1)*4*sizeof(double));
+    const char *error=0;
+    if(!keys || !slot || !wid || !sums) { error="refine allocation failed";goto done; }
+    int W=0;
+    for(int i=0;i<nv;i++) {
+        i64 key=(quant(v[i].x)*32768+quant(v[i].y))*32768+quant(v[i].z);
+        usize h=(usize)mix((u64)key)&(cap-1);
+        while(slot[h] && keys[h]!=key) h=(h+1)&(cap-1);
+        if(!slot[h]) { keys[h]=key;slot[h]=++W; }
+        int w=slot[h]-1;wid[i]=w;
+        sums[4*w]+=v[i].x;sums[4*w+1]+=v[i].y;sums[4*w+2]+=v[i].z;sums[4*w+3]+=1;
+    }
+    p->T=T;p->W=W;
+    p->pos=alloc((usize)(W ? W : 1)*3*sizeof(double));
+    p->F=alloc((usize)(T ? T : 1)*3*sizeof(int));
+    p->fn=alloc((usize)(T ? T : 1)*3*sizeof(float));
+    p->cen=alloc((usize)(T ? T : 1)*3*sizeof(float));
+    p->area=alloc((usize)(T ? T : 1)*sizeof(float));
+    if(!p->pos || !p->F || !p->fn || !p->cen || !p->area) { error="refine allocation failed";goto done; }
+    for(int w=0;w<W;w++) for(int k=0;k<3;k++) p->pos[3*w+k]=sums[4*w+k]/sums[4*w+3];
+    for(int k=0;k<T*3;k++) p->F[k]=wid[idx[k]];
+    for(int t=0;t<T;t++) {
+        const double *a=p->pos+3*p->F[3*t],*b=p->pos+3*p->F[3*t+1],*c=p->pos+3*p->F[3*t+2];
+        double ux=b[0]-a[0],uy=b[1]-a[1],uz=b[2]-a[2],wx=c[0]-a[0],wy=c[1]-a[1],wz=c[2]-a[2];
+        double nx=uy*wz-uz*wy,ny=uz*wx-ux*wz,nz=ux*wy-uy*wx,l=droot(nx*nx+ny*ny+nz*nz);
+        if(!(l>0)) l=1e-12;
+        p->fn[3*t]=(float)(nx/l);p->fn[3*t+1]=(float)(ny/l);p->fn[3*t+2]=(float)(nz/l);p->area[t]=(float)(l/2);
+        for(int k=0;k<3;k++) p->cen[3*t+k]=(float)((a[k]+b[k]+c[k])/3);
+    }
+done:
+    io_free(keys,cap*sizeof(i64));io_free(slot,cap*sizeof(int));
+    io_free(wid,(usize)(nv ? nv : 1)*sizeof(int));io_free(sums,(usize)(nv ? nv : 1)*4*sizeof(double));
+    if(error) prep_free(p);
+    return error;
+}
+void prep_free(Prep *p)
+{
+    int T=p->T ? p->T : 1,W=p->W ? p->W : 1;
+    io_free(p->pos,(usize)W*3*sizeof(double));io_free(p->F,(usize)T*3*sizeof(int));
+    io_free(p->fn,(usize)T*3*sizeof(float));io_free(p->cen,(usize)T*3*sizeof(float));io_free(p->area,(usize)T*sizeof(float));
+    *p=(Prep){0};
+}
+
+/* ------------------------------------------------------------------------------------------------ helpers */
+typedef struct {
+    int kind, wall;       /* 0 wall (index into room->walls), 1 floor, 2 ceiling */
+    double n[3], off, shift;
+    double ox, oz, ux, uz, L;
+} RPlane;
+typedef struct { double cs, sn; const RVol *v; } Box;
+static void box_local(const Box *b, double x, double z, double *lx, double *lz)
+{
+    double dx=x-b->v->cx,dz=z-b->v->cz;
+    *lx=b->cs*dx-b->sn*dz;*lz=b->sn*dx+b->cs*dz;
+}
+static double s_dist(const RPlane *pl, const float *c) { return pl->n[0]*c[0]+pl->n[1]*c[1]+pl->n[2]*c[2]-pl->off; }
+static int in_ext(const RPlane *pl, const float *c, double m)
+{
+    if(pl->kind) return 1;
+    double s=(c[0]-pl->ox)*pl->ux+(c[2]-pl->oz)*pl->uz;
+    return s>-m && s<pl->L+m;
+}
+static int point_in_poly(double x, double z, const DPt *poly, int n)
+{
+    int inside=0;
+    for(int i=0,j=n-1;i<n;j=i++) {
+        double xi=poly[i].x,zi=poly[i].z,xj=poly[j].x,zj=poly[j].z;
+        if((zi>z)!=(zj>z) && x<(xj-xi)*(z-zi)/(zj-zi+1e-12)+xi) inside=!inside;
+    }
+    return inside;
+}
+/* Distance outside the outline (0 inside) and the extra allowance of the nearest wall (unseen walls). */
+static double outside_info(const Room *r, double x, double z, double open_extra, double *allow)
+{
+    double best=1e300;*allow=0;
+    for(int i=0;i<r->nwalls;i++) {
+        const RWall *w=&r->walls[i];
+        double abx=w->x1-w->x0,abz=w->z1-w->z0,l2=abx*abx+abz*abz;
+        double t=l2>0 ? ((x-w->x0)*abx+(z-w->z0)*abz)/l2 : 0;
+        t=t<0 ? 0 : t>1 ? 1 : t;
+        double dx=x-(w->x0+t*abx),dz=z-(w->z0+t*abz),d=dhypot(dx,dz);
+        if(d<best) { best=d;*allow=w->invisible ? open_extra : 0; }
+    }
+    return point_in_poly(x,z,r->outline,r->noutline) ? 0 : best;
+}
+static void nth(float *a, int n, int k)
+{
+    int lo=0,hi=n-1;
+    while(lo<hi) {
+        float pivot=a[(lo+hi)/2];int i=lo,j=hi;
+        while(i<=j) {
+            while(a[i]<pivot) i++;
+            while(a[j]>pivot) j--;
+            if(i<=j) { float t=a[i];a[i++]=a[j];a[j--]=t; }
+        }
+        if(k<=j) hi=j;else if(k>=i) lo=i;else break;
+    }
+}
+static int find(int *parent, int x)
+{
+    while(parent[x]!=x) { parent[x]=parent[parent[x]];x=parent[x]; }
+    return x;
+}
+static void unite(int *parent, const int *F, const u8 *keep, int T, int W)
+{
+    for(int i=0;i<W;i++) parent[i]=i;
+    for(int t=0;t<T;t++) if(keep[t]) {
+        int r=find(parent,F[3*t]);
+        parent[find(parent,F[3*t+1])]=r;parent[find(parent,F[3*t+2])]=r;
+    }
+}
+/* Eigenvalues of a symmetric 3x3 matrix by Jacobi rotations, as the reference's eigSym3. */
+static void eig3(double a[3][3], double out[3])
+{
+    static const int pairs[3][2]={{0,1},{0,2},{1,2}};
+    for(int sweep=0;sweep<20;sweep++) {
+        double off=dab(a[0][1])+dab(a[0][2])+dab(a[1][2]);
+        if(off<1e-14) break;
+        for(int k=0;k<3;k++) {
+            int p=pairs[k][0],q=pairs[k][1];
+            if(dab(a[p][q])<1e-18) continue;
+            double th=(a[q][q]-a[p][p])/(2*a[p][q]);
+            double t=(th<0 ? -1 : 1)/(dab(th)+droot(th*th+1)),c=1/droot(t*t+1),s=t*c;
+            for(int m=0;m<3;m++) { double akp=a[m][p],akq=a[m][q];a[m][p]=c*akp-s*akq;a[m][q]=s*akp+c*akq; }
+            for(int m=0;m<3;m++) { double apk=a[p][m],aqk=a[q][m];a[p][m]=c*apk-s*aqk;a[q][m]=s*apk+c*aqk; }
+        }
+    }
+    out[0]=a[0][0];out[1]=a[1][1];out[2]=a[2][2];
+}
+/* Ear clipping of the (positively wound) outline, exactly the reference's order. */
+static int ear_clip(const DPt *poly, int n, int tris[][3])
+{
+    int idx[MAX_OUTLINE],m=n,count=0,guard=0;
+    for(int i=0;i<n;i++) idx[i]=i;
+#define A2(a,b,c) ((poly[b].x-poly[a].x)*(poly[c].z-poly[a].z)-(poly[b].z-poly[a].z)*(poly[c].x-poly[a].x))
+    while(m>3 && guard++<10000) {
+        int cut=0;
+        for(int k=0;k<m;k++) {
+            int i0=idx[(k-1+m)%m],i1=idx[k],i2=idx[(k+1)%m];
+            if(A2(i0,i1,i2)<=0) continue;
+            int blocked=0;
+            for(int q=0;q<m && !blocked;q++) {
+                int j=idx[q];
+                if(j!=i0 && j!=i1 && j!=i2 && A2(i0,i1,j)>0 && A2(i1,i2,j)>0 && A2(i2,i0,j)>0) blocked=1;
+            }
+            if(blocked) continue;
+            tris[count][0]=i0;tris[count][1]=i1;tris[count][2]=i2;count++;
+            for(int q=k;q+1<m;q++) idx[q]=idx[q+1];
+            m--;cut=1;break;
+        }
+        if(!cut) break;
+    }
+#undef A2
+    if(m==3) { tris[count][0]=idx[0];tris[count][1]=idx[1];tris[count][2]=idx[2];count++; }
+    return count;
+}
+
+/* ------------------------------------------------------------------------------------------------ passes */
+typedef struct {
+    u8 *furn, *keep;
+    signed char *owner;
+    int *parent, *start, *nb, *fill, *comp, *stamp;
+    double *pos, *tmp, *acc;
+    float *ds;
+    int nb_n, comp_n;
+} Work;
+static void work_free(Work *w, int T, int W)
+{
+    usize t=(usize)(T ? T : 1),v=(usize)(W ? W : 1);
+    io_free(w->furn,t);io_free(w->keep,t);io_free(w->owner,t);io_free(w->parent,v*sizeof(int));
+    io_free(w->start,(v+1)*sizeof(int));io_free(w->nb,(usize)(w->nb_n ? w->nb_n : 1)*sizeof(int));
+    io_free(w->fill,v*sizeof(int));io_free(w->comp,v*sizeof(int));io_free(w->stamp,v*sizeof(int));
+    io_free(w->pos,v*3*sizeof(double));io_free(w->tmp,v*3*sizeof(double));
+    io_free(w->acc,(usize)(w->comp_n ? w->comp_n : 1)*12*sizeof(double));io_free(w->ds,t*sizeof(float));
+}
+
+/* Heads binned on a horizontal grid with cells of at least the walked radius: the 3 x 3 cells around a point hold
+ * every head within the radius, so this gives the same result as testing every head, with far fewer tests. */
+typedef struct { double x0, z0, cell; int nx, nz; int *start, *list; } HeadGrid;
+static int head_cell(const HeadGrid *g, double v, double v0) { return (int)dfloor((v-v0)/g->cell); }
+static int head_grid(HeadGrid *g, const Vec *heads, int n, double radius)
+{
+    double x0=1e300,x1=-1e300,z0=1e300,z1=-1e300;
+    for(int i=0;i<n;i++) { x0=heads[i].x<x0 ? heads[i].x : x0;x1=heads[i].x>x1 ? heads[i].x : x1;
+                           z0=heads[i].z<z0 ? heads[i].z : z0;z1=heads[i].z>z1 ? heads[i].z : z1; }
+    g->cell=radius;
+    if((x1-x0)/256>g->cell) g->cell=(x1-x0)/256;
+    if((z1-z0)/256>g->cell) g->cell=(z1-z0)/256;
+    g->x0=x0;g->z0=z0;g->nx=head_cell(g,x1,x0)+1;g->nz=head_cell(g,z1,z0)+1;
+    g->start=alloc((usize)(g->nx*g->nz+1)*sizeof(int));g->list=alloc((usize)n*sizeof(int));
+    int *fill=alloc((usize)(g->nx*g->nz)*sizeof(int));
+    if(!g->start || !g->list || !fill) { io_free(fill,(usize)(g->nx*g->nz)*sizeof(int));return 0; }
+    for(int i=0;i<n;i++) g->start[head_cell(g,heads[i].z,z0)*g->nx+head_cell(g,heads[i].x,x0)+1]++;
+    for(int c=0;c<g->nx*g->nz;c++) g->start[c+1]+=g->start[c];
+    for(int i=0;i<n;i++) {
+        int c=head_cell(g,heads[i].z,z0)*g->nx+head_cell(g,heads[i].x,x0);
+        g->list[g->start[c]+fill[c]++]=i;
+    }
+    io_free(fill,(usize)(g->nx*g->nz)*sizeof(int));
+    return 1;
+}
+static void head_grid_free(HeadGrid *g, int n)
+{
+    io_free(g->start,(usize)(g->nx*g->nz+1)*sizeof(int));io_free(g->list,(usize)n*sizeof(int));
+}
+static int walked_hit(const HeadGrid *g, const Vec *heads, double x, double y, double z, double r2)
+{
+    int cx=head_cell(g,x,g->x0),cz=head_cell(g,z,g->z0);
+    for(int v=cz-1;v<=cz+1;v++) for(int u=cx-1;u<=cx+1;u++) {
+        if(u<0 || v<0 || u>=g->nx || v>=g->nz) continue;
+        for(int k=g->start[v*g->nx+u];k<g->start[v*g->nx+u+1];k++) {
+            const Vec *h=&heads[g->list[k]];
+            if(y<h->y+WALKED_ABOVE && (x-h->x)*(x-h->x)+(z-h->z)*(z-h->z)<=r2) return 1;
+        }
+    }
+    return 0;
+}
+
+const char *refine_run(const Refine *o, const Room *room, const Prep *P, const RVol *vols, int nvols,
+                       const Vec *heads, int nheads, Vec **out_v, u32 **out_i, int *out_n, Report *rep)
+{
+    int T=P->T,W=P->W;
+    const float *cen=P->cen,*fn=P->fn,*area=P->area;
+    const int *F=P->F;
+    Work w={0};
+    const char *error=0;
+    *out_v=0;*out_i=0;*out_n=0;
+    memset(rep,0,sizeof(*rep));rep->triangles=T;
+    usize tb=(usize)(T ? T : 1),wb=(usize)(W ? W : 1);
+    w.furn=alloc(tb);w.keep=alloc(tb);w.owner=alloc(tb);w.ds=alloc(tb*sizeof(float));
+    w.parent=alloc(wb*sizeof(int));w.pos=alloc(wb*3*sizeof(double));w.stamp=alloc(wb*sizeof(int));
+    if(!w.furn || !w.keep || !w.owner || !w.ds || !w.parent || !w.pos || !w.stamp) { error="refine allocation failed";goto done; }
+    memcpy(w.pos,P->pos,(usize)W*3*sizeof(double));
+    double *pos=w.pos;
+
+    /* furniture flags: the ruled boxes (+10 cm) */
+    Box boxes[MAX_VOLUMES];
+    for(int i=0;i<nvols;i++) {
+        double a=vols[i].yaw*3.14159265358979323846/180;
+        boxes[i]=(Box){dcos(a),dsin(a),&vols[i]};
+    }
+    for(int i=0;i<nvols;i++) {
+        const RVol *v=&vols[i];
+        for(int t=0;t<T;t++) {
+            double lx,lz,y=cen[3*t+1];
+            box_local(&boxes[i],cen[3*t],cen[3*t+2],&lx,&lz);
+            if(dab(lx)<=v->w/2.+FURNITURE_PAD && dab(lz)<=v->d/2.+FURNITURE_PAD &&
+               y<=v->top+FURNITURE_PAD && y>=v->top-v->h-FURNITURE_PAD) w.furn[t]=1;
+        }
+    }
+
+    /* 1. planes: seen walls, floor, ceiling; offsets re-estimated (median of facing triangles within the band) */
+    RPlane planes[MAX_OUTLINE+2];int np=0;
+    for(int i=0;i<room->nwalls;i++) {
+        const RWall *wl=&room->walls[i];
+        if(wl->invisible) continue;
+        double dx=wl->x1-wl->x0,dz=wl->z1-wl->z0,L=dhypot(dx,dz);
+        if(!(L>0)) continue;
+        RPlane *pl=&planes[np++];
+        *pl=(RPlane){0,i,{-dz/L,0,dx/L},0,0,wl->x0,wl->z0,dx/L,dz/L,L};
+        pl->off=pl->n[0]*wl->x0+pl->n[2]*wl->z0;
+    }
+    planes[np++]=(RPlane){1,-1,{0,1,0},room->floor,0,0,0,0,0,0};
+    planes[np++]=(RPlane){2,-1,{0,-1,0},-(double)room->ceiling,0,0,0,0,0,0};
+    double cos_lim=dcos(o->facing_deg*3.14159265358979323846/180);
+#define FACING(pl,t) ((pl)->n[0]*fn[3*(t)]+(pl)->n[1]*fn[3*(t)+1]+(pl)->n[2]*fn[3*(t)+2]>cos_lim)
+    for(int k=0;k<np;k++) {
+        RPlane *pl=&planes[k];int n=0;
+        for(int t=0;t<T;t++) {
+            if(w.furn[t]) continue;
+            double d=s_dist(pl,cen+3*t);
+            if(dab(d)<o->band && FACING(pl,t) && in_ext(pl,cen+3*t,o->band)) w.ds[n++]=(float)d;
+        }
+        if(n>MIN_SHIFT_SAMPLES) { nth(w.ds,n,n>>1);pl->shift=w.ds[n>>1]; }
+        pl->off+=pl->shift;
+        rep->shifts[rep->nshifts++]=(Shift){pl->kind,pl->wall,(float)pl->shift};
+    }
+    double floor_y=planes[np-2].off,ceil_y=-planes[np-1].off;
+    rep->floor_y=(float)floor_y;rep->ceiling_y=(float)ceil_y;
+
+    /* 2. structural triangles: behind a surface = band; in front = band_in (walls; the full band in the wall's top
+     * strip), floor_in, ceil_in */
+    for(int t=0;t<T;t++) w.owner[t]=-1;
+    if(o->walls) for(int t=0;t<T;t++) {
+        if(w.furn[t]) continue;
+        double best=1e300;
+        for(int k=0;k<np;k++) {
+            const RPlane *pl=&planes[k];double d=s_dist(pl,cen+3*t);
+            double front=!pl->kind ? (cen[3*t+1]>ceil_y-o->top_strip ? o->band : o->band_in) :
+                         pl->kind==2 ? o->ceil_in : o->floor_in;
+            if(d>-o->band && d<front && dab(d)<best && FACING(pl,t) && in_ext(pl,cen+3*t,o->band)) {
+                best=dab(d);w.owner[t]=(signed char)k;
+            }
+        }
+    }
+#undef FACING
+    for(int t=0;t<T;t++) w.keep[t]=1;
+    /* erase spheres */
+    for(int e=0;e<o->nerase;e++) {
+        const Sphere *s=&o->erase[e];
+        for(int t=0;t<T;t++) {
+            double dx=cen[3*t]-s->x,dy=cen[3*t+1]-s->y,dz=cen[3*t+2]-s->z;
+            if(w.keep[t] && dx*dx+dy*dy+dz*dz<=(double)s->r*s->r) { w.keep[t]=0;rep->erased++; }
+        }
+    }
+    /* the walked volume: a column under each head position, never inside furniture */
+    if(o->walked>0 && nheads) {
+        HeadGrid g={0};
+        if(!head_grid(&g,heads,nheads,o->walked)) { head_grid_free(&g,nheads);error="refine allocation failed";goto done; }
+        double r2=(double)o->walked*o->walked;
+        for(int t=0;t<T;t++) {
+            if(!w.keep[t] || w.furn[t]) continue;
+            double y=cen[3*t+1];
+            if(y<room->floor+WALKED_BELOW) continue;
+            if(walked_hit(&g,heads,cen[3*t],y,cen[3*t+2],r2)) { w.keep[t]=0;rep->walked++; }
+        }
+        head_grid_free(&g,nheads);
+    } else if(o->walked>0) rep->walked_skipped=1;
+    for(int t=0;t<T;t++) if(w.owner[t]>=0) rep->structural++;
+    if(o->walls==2) {
+        for(int t=0;t<T;t++) if(w.owner[t]>=0) w.keep[t]=0;
+        if(o->near>0) for(int t=0;t<T;t++) {
+            if(!w.keep[t] || w.furn[t]) continue;
+            for(int k=0;k<np;k++) if(dab(s_dist(&planes[k],cen+3*t))<o->near && in_ext(&planes[k],cen+3*t,o->near)) {
+                w.keep[t]=0;rep->near++;break;
+            }
+        }
+    } else if(o->walls==1) {
+        /* snap: a vertex goes onto the plane of the last structural triangle that uses it */
+        int *vown=w.stamp;
+        for(int i=0;i<W;i++) vown[i]=-1;
+        for(int t=0;t<T;t++) if(w.owner[t]>=0) for(int j=0;j<3;j++) vown[F[3*t+j]]=w.owner[t];
+        for(int i=0;i<W;i++) {
+            if(vown[i]<0) continue;
+            const RPlane *pl=&planes[vown[i]];
+            double d=pl->n[0]*pos[3*i]+pl->n[1]*pos[3*i+1]+pl->n[2]*pos[3*i+2]-pl->off;
+            for(int k=0;k<3;k++) pos[3*i+k]-=d*pl->n[k];
+        }
+    }
+    /* 2b. furniture tops: upward scan near a box's top, inside its footprint, goes onto the top */
+    if(o->tops>0) {
+        for(int i=0;i<W;i++) w.stamp[i]=0;
+        for(int i=0;i<nvols;i++) {
+            const RVol *v=&vols[i];int mark=i+1;
+            for(int t=0;t<T;t++) {
+                if(!w.keep[t]) continue;
+                const double *a=pos+3*F[3*t],*b=pos+3*F[3*t+1],*c=pos+3*F[3*t+2];
+                double cy=(a[1]+b[1]+c[1])/3;
+                if(dab(cy-v->top)>=o->tops) continue;
+                double lx,lz;
+                box_local(&boxes[i],(a[0]+b[0]+c[0])/3,(a[2]+b[2]+c[2])/3,&lx,&lz);
+                if(dab(lx)>v->w/2. || dab(lz)>v->d/2.) continue;
+                double ux=b[0]-a[0],uy=b[1]-a[1],uz=b[2]-a[2],wx=c[0]-a[0],wy=c[1]-a[1],wz=c[2]-a[2];
+                double nx=uy*wz-uz*wy,ny=uz*wx-ux*wz,nz=ux*wy-uy*wx,l=droot(nx*nx+ny*ny+nz*nz);
+                if(ny/(l>0 ? l : 1)<=TOP_NORMAL_Y) continue;
+                for(int j=0;j<3;j++) w.stamp[F[3*t+j]]=mark;
+                rep->tops++;
+            }
+            for(int k=0;k<W;k++) if(w.stamp[k]==mark) pos[3*k+1]=v->top;
+        }
+    }
+    /* 3. clip outside the room (unseen walls allow clip_open more) and above/below the planes */
+    if(o->clip<1 || o->clip_open<2) for(int t=0;t<T;t++) {
+        if(!w.keep[t]) continue;
+        double allow,out=outside_info(room,cen[3*t],cen[3*t+2],o->clip_open,&allow),y=cen[3*t+1];
+        if(out>o->clip+allow || y>ceil_y+o->clip || y<floor_y-o->clip) { w.keep[t]=0;rep->outside++; }
+    }
+    /* 4. islands: connected pieces below the minimum area */
+    if(o->island>0) {
+        double *comp=w.tmp=alloc(wb*3*sizeof(double));
+        if(!comp) { error="refine allocation failed";goto done; }
+        unite(w.parent,F,w.keep,T,W);
+        for(int t=0;t<T;t++) if(w.keep[t]) comp[find(w.parent,F[3*t])]+=area[t];
+        for(int t=0;t<T;t++)
+            if(w.keep[t] && comp[find(w.parent,F[3*t])]<o->island && !(o->protect && w.furn[t])) { w.keep[t]=0;rep->islands++; }
+        io_free(w.tmp,wb*3*sizeof(double));w.tmp=0;
+    }
+    /* 4b. thin floating pieces: elongated (PCA), thin, small, not furniture */
+    if(o->tubes>0) {
+        unite(w.parent,F,w.keep,T,W);
+        w.comp=alloc(wb*sizeof(int));
+        if(!w.comp) { error="refine allocation failed";goto done; }
+        for(int i=0;i<W;i++) w.comp[i]=-1;
+        int nc=0;
+        for(int t=0;t<T;t++) if(w.keep[t]) { int r=find(w.parent,F[3*t]);if(w.comp[r]<0) w.comp[r]=nc++; }
+        w.comp_n=nc;
+        w.acc=alloc((usize)(nc ? nc : 1)*12*sizeof(double));
+        if(!w.acc) { error="refine allocation failed";goto done; }
+        for(int t=0;t<T;t++) {
+            if(!w.keep[t]) continue;
+            double *a=w.acc+12*w.comp[find(w.parent,F[3*t])];
+            for(int j=0;j<3;j++) {
+                const double *q=pos+3*F[3*t+j];double x=q[0],y=q[1],z=q[2];
+                a[0]++;a[1]+=x;a[2]+=y;a[3]+=z;a[4]+=x*x;a[5]+=x*y;a[6]+=x*z;a[7]+=y*y;a[8]+=y*z;a[9]+=z*z;
+            }
+            a[10]+=area[t];a[11]+=w.furn[t] ? 1 : 0;
+        }
+        u8 *drop=(u8 *)w.stamp;  /* nc <= T bytes fit in the W ints */
+        for(int c=0;c<nc;c++) {
+            double *a=w.acc+12*c,n=a[0],tris=n/3;drop[c]=0;
+            if(tris<TUBE_MIN_TRIANGLES || a[11]/tris>TUBE_MAX_FURNITURE || a[10]>=TUBE_MAX_AREA) continue;
+            double mx_=a[1]/n,my=a[2]/n,mz=a[3]/n;
+            double C[3][3]={{a[4]/n-mx_*mx_,a[5]/n-mx_*my,a[6]/n-mx_*mz},{0,a[7]/n-my*my,a[8]/n-my*mz},{0,0,a[9]/n-mz*mz}};
+            C[1][0]=C[0][1];C[2][0]=C[0][2];C[2][1]=C[1][2];
+            double ev[3];eig3(C,ev);
+            for(int k=0;k<3;k++) ev[k]=droot(ev[k]>1e-12 ? ev[k] : 1e-12);
+            for(int i=0;i<2;i++) for(int j=0;j<2-i;j++) if(ev[j]>ev[j+1]) { double s=ev[j];ev[j]=ev[j+1];ev[j+1]=s; }
+            if(ev[2]/(ev[1]>1e-6 ? ev[1] : 1e-6)>=o->tubes && ev[1]<=o->tube_thick) drop[c]=1;
+        }
+        for(int t=0;t<T;t++) if(w.keep[t] && drop[w.comp[find(w.parent,F[3*t])]]) { w.keep[t]=0;rep->tubes++; }
+    }
+    /* 5. Taubin smoothing over the kept triangles (lambda/mu pairs keep the volume) */
+    if(o->smooth>0) {
+        w.start=alloc((wb+1)*sizeof(int));w.fill=alloc(wb*sizeof(int));w.tmp=alloc(wb*3*sizeof(double));
+        if(!w.start || !w.fill || !w.tmp) { error="refine allocation failed";goto done; }
+        for(int t=0;t<T;t++) if(w.keep[t]) for(int j=0;j<3;j++) w.start[F[3*t+j]+1]+=2;
+        for(int i=0;i<W;i++) w.start[i+1]+=w.start[i];
+        w.nb_n=w.start[W];
+        w.nb=alloc((usize)(w.nb_n ? w.nb_n : 1)*sizeof(int));
+        if(!w.nb) { error="refine allocation failed";goto done; }
+        for(int i=0;i<W;i++) w.fill[i]=w.start[i];
+        for(int t=0;t<T;t++) if(w.keep[t]) for(int j=0;j<3;j++) {
+            int a=F[3*t+j],b=F[3*t+(j+1)%3],c=F[3*t+(j+2)%3];
+            w.nb[w.fill[a]++]=b;w.nb[w.fill[a]++]=c;
+        }
+        for(int it=0;it<o->smooth;it++) for(int pass=0;pass<2;pass++) {
+            double f=pass ? TAUBIN_MU : TAUBIN_LAMBDA;
+            for(int i=0;i<W;i++) {
+                int s0=w.start[i],e=w.start[i+1];
+                if(s0==e) { for(int k=0;k<3;k++) w.tmp[3*i+k]=pos[3*i+k];continue; }
+                double x=0,y=0,z=0;
+                for(int k=s0;k<e;k++) { const double *q=pos+3*w.nb[k];x+=q[0];y+=q[1];z+=q[2]; }
+                int n=e-s0;
+                w.tmp[3*i]=pos[3*i]+f*(x/n-pos[3*i]);w.tmp[3*i+1]=pos[3*i+1]+f*(y/n-pos[3*i+1]);
+                w.tmp[3*i+2]=pos[3*i+2]+f*(z/n-pos[3*i+2]);
+            }
+            memcpy(pos,w.tmp,(usize)W*3*sizeof(double));
+        }
+    }
+    /* 6. output: the kept scan, then flat panels for seen walls, the floor and the ceiling */
+    for(int t=0;t<T;t++) rep->kept+=w.keep[t];
+    Vec panel[(MAX_OUTLINE*2+MAX_OUTLINE*2)*3];int npanel=0;
+    if(o->walls==2) {
+        for(int k=0;k<np;k++) {
+            const RPlane *pl=&planes[k];
+            if(pl->kind) continue;
+            const RWall *wl=&room->walls[pl->wall];double sh=pl->shift;
+            double a0x=wl->x0+pl->n[0]*sh,a0z=wl->z0+pl->n[2]*sh,a1x=wl->x1+pl->n[0]*sh,a1z=wl->z1+pl->n[2]*sh;
+            Vec q[4]={vec((float)a0x,(float)floor_y,(float)a0z),vec((float)a1x,(float)floor_y,(float)a1z),
+                      vec((float)a1x,(float)ceil_y,(float)a1z),vec((float)a0x,(float)ceil_y,(float)a0z)};
+            double ux=a1x-a0x,uz=a1z-a0z,vy=ceil_y-floor_y;
+            int ok=(-uz*vy)*pl->n[0]+(ux*vy)*pl->n[2]>0;
+            int order[2][6]={{0,1,2,0,2,3},{1,0,3,1,3,2}};
+            for(int j=0;j<6;j++) panel[npanel*3+j]=q[order[!ok][j]];
+            npanel+=2;
+        }
+        int ears[MAX_OUTLINE][3];
+        int ne=ear_clip(room->outline,room->noutline,ears);
+        for(int e=0;e<ne;e++) {
+            DPt A=room->outline[ears[e][0]],B=room->outline[ears[e][1]],C=room->outline[ears[e][2]];
+            panel[npanel*3]=vec((float)A.x,(float)floor_y,(float)A.z);panel[npanel*3+1]=vec((float)C.x,(float)floor_y,(float)C.z);
+            panel[npanel*3+2]=vec((float)B.x,(float)floor_y,(float)B.z);npanel++;
+            panel[npanel*3]=vec((float)A.x,(float)ceil_y,(float)A.z);panel[npanel*3+1]=vec((float)B.x,(float)ceil_y,(float)B.z);
+            panel[npanel*3+2]=vec((float)C.x,(float)ceil_y,(float)C.z);npanel++;
+        }
+    }
+    rep->panels=npanel;
+    int room_left=MAX_TRIANGLES-npanel,kept_out=rep->kept<room_left ? rep->kept : room_left;
+    rep->truncated=rep->kept-kept_out;
+    *out_v=io_alloc((usize)MAX_MESH_VERTICES*sizeof(Vec));
+    *out_i=io_alloc((usize)MAX_TRIANGLES*3*sizeof(u32));
+    if(!*out_v || !*out_i) { error="refine allocation failed";goto done; }
+    int o_n=0;
+    for(int t=0;t<T && o_n<kept_out*3;t++) {
+        if(!w.keep[t]) continue;
+        for(int j=0;j<3;j++) {
+            const double *q=pos+3*F[3*t+j];
+            (*out_v)[o_n]=vec((float)q[0],(float)q[1],(float)q[2]);(*out_i)[o_n]=(u32)o_n;o_n++;
+        }
+    }
+    for(int k=0;k<npanel*3;k++) { (*out_v)[o_n]=panel[k];(*out_i)[o_n]=(u32)o_n;o_n++; }
+    *out_n=o_n;
+done:
+    if(error) {
+        io_free(*out_v,(usize)MAX_MESH_VERTICES*sizeof(Vec));io_free(*out_i,(usize)MAX_TRIANGLES*3*sizeof(u32));
+        *out_v=0;*out_i=0;*out_n=0;
+    }
+    work_free(&w,T,W);
+    return error;
+}
@@ -0,0 +1,101 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+#ifndef FP_ROOMSCAN_REFINE_H
+#define FP_ROOMSCAN_REFINE_H
+#include "scan.h"
+
+/* Room cleanup after the mesh (docs/mr/scan.md "Refinement"): the scanner's unrefined output is kept as
+ * room-raw.txt + room-mesh-raw.bin, the refined one replaces room.txt + room-mesh.bin, scan.json holds the head
+ * path, the settings used, the per-pass report, the label-rule decisions and door/closet suggestions. */
+
+#define MAX_EXTRA_TEXT 8192
+#define MAX_LABEL 24
+#define MAX_REASON 240
+#define MAX_RAW_FILE (16u+(usize)MAX_MESH_VERTICES*12u+(usize)MAX_TRIANGLES*12u)
+#define MAX_JSON_FILE (1u<<20)
+
+/* Growable text buffer (io_alloc backed). ok=0 after an allocation failure or the cap. */
+typedef struct { char *data; usize n, cap, limit; int ok; } Buf;
+void buf_init(Buf *b, usize limit);
+void buf_free(Buf *b);
+void put(Buf *b, const char *s);
+void put_n(Buf *b, const char *s, usize n);
+void put_int(Buf *b, i64 v);
+void put_u64(Buf *b, u64 v);
+void put_dec(Buf *b, float v);                 /* 4 decimals, the room.txt number format */
+void put_fixed(Buf *b, double v, int places);  /* JavaScript's toFixed */
+void put_round(Buf *b, double v);              /* JavaScript's Math.round */
+
+typedef struct { double x, z; } DPt;
+/* Room numbers are doubles parsed exactly from their decimal text, as the reference page reads them. */
+typedef struct { double x0, z0, x1, z1, y0, y1; int invisible; char id[33]; } RWall;
+typedef struct { double cx, cz, top, yaw, w, d, h; char label[MAX_LABEL]; char id[33]; } RVol;
+typedef struct {
+    u64 universe, time;
+    char source[16];
+    char room_id[33], floor_id[33], ceiling_id[33], mesh_id[33];
+    double floor, ceiling;
+    DPt outline[MAX_OUTLINE];
+    int noutline;
+    RWall walls[MAX_OUTLINE];
+    int nwalls;
+    RVol vols[MAX_VOLUMES];
+    int nvols;
+    char mesh_name[64];
+    u32 mesh_nv, mesh_ni;
+    int has_mesh;
+    char extra[MAX_EXTRA_TEXT];  /* records this scanner does not model (plane, ...), kept verbatim */
+    usize nextra;
+} Room;
+
+/* The mesh with its vertices welded at 1 mm (as the reference page does), per-triangle normals/centroids/areas. */
+typedef struct {
+    int T, W;
+    double *pos;
+    int *F;
+    float *fn, *cen, *area;
+} Prep;
+
+typedef struct { int kind, wall; float shift; } Shift;   /* kind: 0 wall, 1 floor, 2 ceiling */
+typedef struct {
+    int triangles, kept, structural, near, outside, islands, tubes, erased, walked, tops, panels, truncated;
+    int walked_skipped;
+    float floor_y, ceiling_y;
+    Shift shifts[MAX_OUTLINE+2];
+    int nshifts;
+} Report;
+typedef struct {
+    char from[MAX_LABEL], to[MAX_LABEL], suggest[8], reason[MAX_REASON];
+    RVol box;
+    int wall;
+    float along;
+} Label;
+
+/* roomio.c */
+const char *room_from_scan(Scan *s, Room *r);
+const char *room_parse(const char *text, usize n, Room *r);
+int room_text(const Room *r, Buf *b);
+const char *read_file(const char *path, usize limit, u8 **data, usize *size);
+const char *publish(const char *dir, const char *name, const void *data, usize size);
+int join_path(char *out, const char *dir, const char *name);
+const char *mesh_parse(const u8 *data, usize size, Vec **vertices, u32 **indices, int *nv, int *ni);
+const char *mesh_bytes(const Vec *vertices, const u32 *indices, int nv, int ni, u8 **data, usize *size);
+void heads_json(Buf *b, const Vec *heads, int n);
+int heads_parse(const char *text, usize n, Vec *heads);
+void settings_json(Buf *b, const Refine *o);
+void report_json(Buf *b, const Report *r, int nlabels, int changed, int removed, int nsuggest);
+
+/* refine.c */
+const char *prep_mesh(Prep *p, const Vec *vertices, const u32 *indices, int nv, int ni);
+void prep_free(Prep *p);
+const char *refine_run(const Refine *o, const Room *room, const Prep *p, const RVol *vols, int nvols,
+                       const Vec *heads, int nheads, Vec **out_v, u32 **out_i, int *out_n, Report *rep);
+double dfloor(double x);
+double droot(double x);
+double dsin(double x);
+double dcos(double x);
+double dhypot(double a, double b);
+
+/* rules.c */
+int rules_apply(const Room *room, const Prep *p, RVol *out, int *nout, Label *labels);
+
+#endif
@@ -0,0 +1,476 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+/* Room files: the room.txt writer/reader (docs/mr/ROOM_FORMAT.md), mesh sidecars, atomic publishing and the JSON
+ * pieces of scan.json. Every number goes through put_dec, so a room read back from its own text is bit-identical
+ * to the one the scan path refines (that is what makes --refine-only reproduce a scan's refined output). */
+#include "refine.h"
+
+void buf_init(Buf *b, usize limit) { *b=(Buf){0};b->limit=limit;b->ok=1; }
+void buf_free(Buf *b) { io_free(b->data,b->cap);*b=(Buf){0}; }
+void put_n(Buf *b, const char *s, usize n)
+{
+    if(!b->ok) return;
+    if(b->n+n+1>b->cap) {
+        usize cap=b->cap ? b->cap : 256;
+        while(cap<b->n+n+1) cap*=2;
+        if(cap>b->limit) cap=b->limit;
+        if(cap<b->n+n+1) { b->ok=0;return; }
+        char *data=io_alloc(cap);
+        if(!data) { b->ok=0;return; }
+        if(b->n) memcpy(data,b->data,b->n);
+        io_free(b->data,b->cap);b->data=data;b->cap=cap;
+    }
+    memcpy(b->data+b->n,s,n);b->n+=n;b->data[b->n]=0;
+}
+void put(Buf *b, const char *s) { usize n=0;while(s[n]) n++;put_n(b,s,n); }
+void put_u64(Buf *b, u64 value)
+{
+    char rev[24];int n=0;
+    do { rev[n++]=(char)('0'+value%10);value/=10; } while(value);
+    char out[24];for(int i=0;i<n;i++) out[i]=rev[n-1-i];
+    put_n(b,out,(usize)n);
+}
+void put_int(Buf *b, i64 v) { if(v<0) { put(b,"-");v=-v; } put_u64(b,(u64)v); }
+void put_dec(Buf *b, float value)
+{
+    /* Same arithmetic as the scanner's original writer: the --refine 0 output stays byte-for-byte unchanged. */
+    if(value<0) { put(b,"-");value=-value; }
+    u64 scaled=(u64)(value*10000.f+.5f);
+    put_u64(b,scaled/10000);put(b,".");
+    u64 fraction=scaled%10000;
+    if(fraction<1000) put(b,"0");
+    if(fraction<100) put(b,"0");
+    if(fraction<10) put(b,"0");
+    put_u64(b,fraction);
+}
+void put_fixed(Buf *b, double v, int places)
+{
+    /* Exact, like Number.prototype.toFixed: v*10^places from the double's bits in 128-bit integers, ties up. */
+    double scale=1;for(int i=0;i<places;i++) scale*=10;
+    int negative=v<0;if(negative) v=-v;
+    if(!(v<1e9)) v=0;
+    union { double d; u64 u; } bits={v};
+    int e=(int)((bits.u>>52)&0x7ff);
+    u64 m=bits.u&((1ull<<52)-1);
+    if(e) m|=1ull<<52;else e=1;
+    e-=1075;  /* v = m * 2^e */
+    unsigned __int128 big=(unsigned __int128)m*(u64)scale;
+    u64 scaled;
+    if(e>=0) scaled=(u64)(big<<e);
+    else if(e<=-127) scaled=0;
+    else {
+        unsigned __int128 half=(unsigned __int128)1<<(-e-1),rest=big&(((unsigned __int128)1<<-e)-1);
+        scaled=(u64)(big>>-e)+(rest>=half);
+    }
+    if(negative && scaled) put(b,"-");
+    put_u64(b,(u64)(scaled/(u64)scale));
+    if(places) {
+        put(b,".");u64 fraction=scaled%(u64)scale;
+        for(u64 d=(u64)scale/10;d>1 && fraction<d;d/=10) put(b,"0");
+        put_u64(b,fraction);
+    }
+}
+void put_round(Buf *b, double v) { put_int(b,(i64)dfloor(v+.5)); }
+
+static int uuid_hex(char out[33])
+{
+    u8 bytes[16];if(!io_random(bytes,sizeof(bytes))) return 0;
+    bytes[6]=(bytes[6]&15)|64;bytes[8]=(bytes[8]&63)|128;
+    const char *hex="0123456789abcdef";
+    for(int i=0;i<16;i++) { out[2*i]=hex[bytes[i]>>4];out[2*i+1]=hex[bytes[i]&15]; }
+    out[32]=0;return 1;
+}
+static void copy(char *dst, const char *src, usize cap)
+{
+    usize i=0;while(src[i] && i+1<cap) { dst[i]=src[i];i++; }
+    dst[i]=0;
+}
+const char *room_from_scan(Scan *s, Room *r)
+{
+    memset(r,0,sizeof(*r));
+    r->universe=s->opt.universe;r->time=(u64)(io_time(0)/1000000000);copy(r->source,"scan",sizeof(r->source));
+    if(!uuid_hex(r->room_id) || !uuid_hex(r->floor_id) || !uuid_hex(r->ceiling_id)) return "getrandom failed";
+    r->floor=s->floor;r->ceiling=s->ceiling;r->noutline=s->noutline;
+    for(int i=0;i<s->noutline;i++) {
+        Pt a=s->outline[i],b=s->outline[(i+1)%s->noutline];
+        r->outline[i]=(DPt){a.x,a.z};
+        r->walls[i]=(RWall){a.x,a.z,b.x,b.z,s->floor,s->ceiling,s->invisible[i],{0}};
+        if(!uuid_hex(r->walls[i].id)) return "getrandom failed";
+    }
+    r->nwalls=s->noutline;
+    for(int i=0;i<s->nvolumes;i++) {
+        Volume *v=&s->volumes[i];RVol *o=&r->vols[i];
+        *o=(RVol){v->p.x,v->p.z,v->p.y,v->yaw,v->w,v->d,v->h,{0},{0}};
+        copy(o->label,v->label,sizeof(o->label));
+        if(!uuid_hex(o->id)) return "getrandom failed";
+    }
+    r->nvols=s->nvolumes;
+    if(!uuid_hex(r->mesh_id)) return "getrandom failed";
+    copy(r->mesh_name,"room-mesh.bin",sizeof(r->mesh_name));
+    r->has_mesh=1;r->mesh_nv=(u32)s->nv;r->mesh_ni=(u32)s->ni;
+    return 0;
+}
+static void sp(Buf *b, double v) { put(b," ");put_dec(b,(float)v); }
+int room_text(const Room *r, Buf *b)
+{
+    put(b,"frameport-room 1\nuniverse ");put_u64(b,r->universe);
+    put(b,"\nsource ");put(b,r->source);put(b,"\ntime ");put_u64(b,r->time);
+    put(b,"\nroom ");put(b,r->room_id);
+    put(b,"\nfloor ");put(b,r->floor_id);sp(b,r->floor);
+    put(b,"\nceiling ");put(b,r->ceiling_id);sp(b,r->ceiling);
+    put(b,"\noutline ");put_u64(b,(u64)r->noutline);
+    for(int i=0;i<r->noutline;i++) { sp(b,r->outline[i].x);sp(b,r->outline[i].z); }
+    put(b,"\n");
+    for(int i=0;i<r->nwalls;i++) {
+        const RWall *w=&r->walls[i];
+        put(b,"wall ");put(b,w->id);sp(b,w->x0);sp(b,w->z0);sp(b,w->x1);sp(b,w->z1);sp(b,w->y0);sp(b,w->y1);
+        if(w->invisible) put(b," INVISIBLE_WALL_FACE");
+        put(b,"\n");
+    }
+    for(int i=0;i<r->nvols;i++) {
+        const RVol *v=&r->vols[i];
+        put(b,"volume ");put(b,v->id);put(b," ");put(b,v->label);
+        sp(b,v->cx);sp(b,v->cz);sp(b,v->top);sp(b,v->yaw);sp(b,v->w);sp(b,v->d);sp(b,v->h);put(b,"\n");
+    }
+    put_n(b,r->extra,r->nextra);
+    if(r->has_mesh) {
+        put(b,"mesh ");put(b,r->mesh_id);put(b," ");put(b,r->mesh_name);put(b," ");
+        put_u64(b,r->mesh_nv);put(b," ");put_u64(b,r->mesh_ni);put(b,"\n");
+    }
+    return b->ok;
+}
+
+/* ------------------------------------------------------------------------------------------------ reading */
+typedef struct { char *p[64]; int n; } Fields;
+static int is_space(char c) { return c==' ' || c=='\t' || c=='\r'; }
+/* Semantic labels are Meta's upper-case names; anything else would also be unsafe in scan.json strings. */
+static int field_label(const char *p)
+{
+    int n=0;
+    for(;p[n];n++) if(!((p[n]>='A' && p[n]<='Z') || (p[n]>='0' && p[n]<='9') || p[n]=='_')) return 0;
+    return n>0 && n<MAX_LABEL;
+}
+static int field_uuid(const char *p)
+{
+    int n=0;
+    for(;p[n];n++) if(!((p[n]>='0' && p[n]<='9') || (p[n]>='a' && p[n]<='f'))) return 0;
+    return n==32;
+}
+/* Decimal text to double, correctly rounded for the room format's numbers (<= 17 significant digits): the
+ * mantissa and the power of ten are exact doubles, so one division/multiplication rounds once, as parseFloat. */
+static int field_double(const char *p, double *out)
+{
+    int negative=0,digits=0,exponent=0;u64 mantissa=0;
+    if(*p=='-' || *p=='+') negative=*p++=='-';
+    for(;*p>='0' && *p<='9';p++,digits++) { if(mantissa<100000000000000000ull) mantissa=mantissa*10+(u64)(*p-'0');else exponent++; }
+    if(*p=='.') for(p++;*p>='0' && *p<='9';p++,digits++)
+        if(mantissa<100000000000000000ull) { mantissa=mantissa*10+(u64)(*p-'0');exponent--; }
+    if(!digits) return 0;
+    if(*p=='e' || *p=='E') {
+        p++;int sign=1,e=0,ed=0;
+        if(*p=='-' || *p=='+') sign=*p++=='-' ? -1 : 1;
+        for(;*p>='0' && *p<='9';p++,ed++) { e=e*10+*p-'0';if(e>400) return 0; }
+        if(!ed) return 0;
+        exponent+=sign*e;
+    }
+    if(*p) return 0;
+    double v=(double)mantissa,scale=1;
+    int e=exponent<0 ? -exponent : exponent;
+    for(int i=0;i<e && scale<1e300;i++) scale*=10;
+    v=exponent<0 ? v/scale : v*scale;
+    if(!(v<=1e7)) return 0;  /* also rejects NaN; room coordinates are metres */
+    *out=negative ? -v : v;return 1;
+}
+static int field_u64(const char *p, u64 *out)
+{
+    u64 n=0;if(!*p) return 0;
+    for(;*p;p++) {
+        if(*p<'0' || *p>'9') return 0;
+        unsigned digit=(unsigned)(*p-'0');
+        if(n>(~(u64)0-digit)/10) return 0;
+        n=n*10+digit;
+    }
+    *out=n;return 1;
+}
+static int floats(Fields *f, int from, double *out, int n)
+{
+    if(f->n<from+n) return 0;
+    for(int i=0;i<n;i++) if(!field_double(f->p[from+i],&out[i])) return 0;
+    return 1;
+}
+const char *room_parse(const char *text, usize n, Room *r)
+{
+    static char line[16384];
+    memset(r,0,sizeof(*r));
+    int have_floor=0,have_ceiling=0,first=1;
+    usize at=0;
+    while(at<n) {
+        usize start=at,len=0;
+        while(at<n && text[at]!='\n') at++;
+        len=at-start;at++;
+        if(len>=sizeof(line)) return "room line too long";
+        memcpy(line,text+start,len);line[len]=0;
+        usize raw_len=len;
+        for(usize i=0;i<len;i++) if(line[i]=='#') { line[i]=0;len=i;break; }
+        Fields f={{0},0};
+        char *p=line;
+        while(*p) {
+            while(is_space(*p)) *p++=0;
+            if(!*p) break;
+            if(f.n==64) return "room line has too many fields";
+            f.p[f.n++]=p;
+            while(*p && !is_space(*p)) p++;
+        }
+        if(first) {
+            if(f.n!=2 || !same(f.p[0],"frameport-room") || !same(f.p[1],"1")) return "not a frameport-room 1 file";
+            first=0;continue;
+        }
+        if(!f.n) continue;
+        const char *k=f.p[0];
+        if(same(k,"universe")) { if(f.n<2 || !field_u64(f.p[1],&r->universe)) return "invalid universe record"; }
+        else if(same(k,"time")) { if(f.n<2 || !field_u64(f.p[1],&r->time)) return "invalid time record"; }
+        else if(same(k,"source")) { if(f.n<2) return "invalid source record";copy(r->source,f.p[1],sizeof(r->source)); }
+        else if(same(k,"room")) { if(f.n<2 || !field_uuid(f.p[1])) return "invalid room record";copy(r->room_id,f.p[1],33); }
+        else if(same(k,"floor") || same(k,"ceiling")) {
+            int c=same(k,"ceiling");
+            if(f.n<3 || !field_uuid(f.p[1]) || !field_double(f.p[2],c ? &r->ceiling : &r->floor)) return "invalid floor/ceiling record";
+            copy(c ? r->ceiling_id : r->floor_id,f.p[1],33);
+            if(c) have_ceiling=1;else have_floor=1;
+        } else if(same(k,"outline")) {
+            u64 count;
+            if(f.n<2 || !field_u64(f.p[1],&count) || count<3 || count>MAX_OUTLINE || (u64)f.n!=2+2*count) return "invalid outline record";
+            for(int i=0;i<(int)count;i++)
+                if(!field_double(f.p[2+2*i],&r->outline[i].x) || !field_double(f.p[3+2*i],&r->outline[i].z)) return "invalid outline record";
+            r->noutline=(int)count;
+        } else if(same(k,"wall")) {
+            double v[6];
+            if(r->nwalls==MAX_OUTLINE) return "too many walls";
+            if(f.n<8 || !field_uuid(f.p[1]) || !floats(&f,2,v,6)) return "invalid wall record";
+            RWall *w=&r->walls[r->nwalls++];
+            *w=(RWall){v[0],v[1],v[2],v[3],v[4],v[5],f.n>8 && same(f.p[8],"INVISIBLE_WALL_FACE"),{0}};
+            copy(w->id,f.p[1],33);
+        } else if(same(k,"volume")) {
+            double v[7];
+            if(r->nvols==MAX_VOLUMES) return "too many volumes";
+            if(f.n<10 || !field_uuid(f.p[1]) || !field_label(f.p[2]) || !floats(&f,3,v,7)) return "invalid volume record";
+            RVol *o=&r->vols[r->nvols++];
+            *o=(RVol){v[0],v[1],v[2],v[3],v[4],v[5],v[6],{0},{0}};
+            copy(o->label,f.p[2],sizeof(o->label));copy(o->id,f.p[1],33);
+        } else if(same(k,"mesh")) {
+            u64 nv,ni;
+            if(f.n<5 || !field_uuid(f.p[1]) || !field_u64(f.p[3],&nv) || !field_u64(f.p[4],&ni) ||
+               nv>MAX_MESH_VERTICES || ni>(u64)MAX_TRIANGLES*3) return "invalid mesh record";
+            for(const char *c=f.p[2];*c;c++) if(*c=='/' || *c=='\\') return "invalid mesh file name";
+            copy(r->mesh_id,f.p[1],33);copy(r->mesh_name,f.p[2],sizeof(r->mesh_name));
+            r->mesh_nv=(u32)nv;r->mesh_ni=(u32)ni;r->has_mesh=1;
+        } else {
+            /* Forward compatibility: unknown records (plane, ...) are kept as they were written. */
+            if(r->nextra+raw_len+1>=MAX_EXTRA_TEXT) return "too many extra room records";
+            memcpy(r->extra+r->nextra,text+start,raw_len);r->nextra+=raw_len;r->extra[r->nextra++]='\n';
+        }
+    }
+    if(first) return "empty room file";
+    if(!r->source[0]) copy(r->source,"scan",sizeof(r->source));
+    if(!r->room_id[0] && !uuid_hex(r->room_id)) return "getrandom failed";
+    if(!have_floor && !uuid_hex(r->floor_id)) return "getrandom failed";
+    if(!have_ceiling) { if(!uuid_hex(r->ceiling_id)) return "getrandom failed";r->ceiling=r->floor+2.5; }
+    if(!r->noutline && r->nwalls>=3) {
+        double x0=1e10,x1=-1e10,z0=1e10,z1=-1e10;
+        for(int i=0;i<r->nwalls;i++) {
+            RWall *w=&r->walls[i];
+            double lx=w->x0<w->x1 ? w->x0 : w->x1,hx=w->x0<w->x1 ? w->x1 : w->x0;
+            double lz=w->z0<w->z1 ? w->z0 : w->z1,hz=w->z0<w->z1 ? w->z1 : w->z0;
+            x0=lx<x0 ? lx : x0;x1=hx>x1 ? hx : x1;z0=lz<z0 ? lz : z0;z1=hz>z1 ? hz : z1;
+        }
+        r->outline[0]=(DPt){x0,z0};r->outline[1]=(DPt){x1,z0};r->outline[2]=(DPt){x1,z1};r->outline[3]=(DPt){x0,z1};
+        r->noutline=4;
+    }
+    if(r->noutline<3) return "room has no outline";
+    double twice=0;
+    for(int i=0;i<r->noutline;i++) {
+        DPt a=r->outline[i],b=r->outline[(i+1)%r->noutline];twice+=a.x*b.z-b.x*a.z;
+    }
+    if(twice<0) for(int i=0;i<r->noutline/2;i++) {  /* readers reverse a negative outline (ROOM_FORMAT.md) */
+        DPt t=r->outline[i];r->outline[i]=r->outline[r->noutline-1-i];r->outline[r->noutline-1-i]=t;
+    }
+    if(!r->nwalls) {
+        for(int i=0;i<r->noutline;i++) {
+            DPt a=r->outline[i],b=r->outline[(i+1)%r->noutline];
+            r->walls[i]=(RWall){a.x,a.z,b.x,b.z,r->floor,r->ceiling,0,{0}};
+            if(!uuid_hex(r->walls[i].id)) return "getrandom failed";
+        }
+        r->nwalls=r->noutline;
+    }
+    return 0;
+}
+
+/* ------------------------------------------------------------------------------------------------ files */
+int join_path(char *out, const char *dir, const char *name)
+{
+    usize n=0;
+    while(*dir) { if(n>=3900) return 0;out[n++]=*dir++; }
+    if(n && out[n-1]!='/') out[n++]='/';
+    while(*name) { if(n>=4095) return 0;out[n++]=*name++; }
+    out[n]=0;return 1;
+}
+const char *read_file(const char *path, usize limit, u8 **data, usize *size)
+{
+    *data=0;*size=0;
+    int fd=io_open(path,0);
+    if(fd<0) return "cannot open file";
+    usize cap=limit+1;
+    u8 *buf=io_alloc(cap);
+    if(!buf) { io_close(fd);return "file allocation failed"; }
+    usize n=0;
+    for(;;) {
+        long r=io_read(fd,buf+n,cap-n);
+        if(r<0) { io_close(fd);io_free(buf,cap);return "cannot read file"; }
+        if(!r) break;
+        n+=(usize)r;
+        if(n>limit) { io_close(fd);io_free(buf,cap);return "file too large"; }
+    }
+    io_close(fd);
+    /* The caller frees with io_free(data, limit+1); the size is the buffer, not the content. */
+    *data=buf;*size=n;return 0;
+}
+const char *publish(const char *dir, const char *name, const void *data, usize size)
+{
+    char id[33],tmpname[256],final[4096],tmp[4096];
+    if(!uuid_hex(id)) return "getrandom failed";
+    usize n=0;
+    for(const char *p=name;*p && n<180;p++) tmpname[n++]=*p;
+    tmpname[n++]='.';
+    for(int i=0;i<32;i++) tmpname[n++]=id[i];
+    for(const char *p=".tmp";*p;p++) tmpname[n++]=*p;
+    tmpname[n]=0;
+    if(!join_path(final,dir,name) || !join_path(tmp,dir,tmpname)) return "output path too long";
+    int fd=io_open(tmp,1);
+    if(fd<0) return "cannot open temporary file";
+    int ok=io_write(fd,data,size);
+    if(io_close(fd)) ok=0;
+    if(!ok) { io_remove(tmp);return "cannot write temporary file"; }
+    if(io_rename(tmp,final)) { io_remove(tmp);return "cannot publish file"; }
+    return 0;
+}
+static u32 rd32(const u8 *p) { return (u32)p[0]|(u32)p[1]<<8|(u32)p[2]<<16|(u32)p[3]<<24; }
+static void wr32(u8 *p, u32 v) { for(int i=0;i<4;i++) p[i]=(u8)(v>>(8*i)); }
+const char *mesh_parse(const u8 *data, usize size, Vec **vertices, u32 **indices, int *nv, int *ni)
+{
+    *vertices=0;*indices=0;*nv=*ni=0;
+    if(size<16 || data[0]!='F' || data[1]!='P' || data[2]!='R' || data[3]!='M' || rd32(data+4)!=1) return "invalid mesh header";
+    u32 v=rd32(data+8),i=rd32(data+12);
+    if(v>MAX_MESH_VERTICES || i>(u32)MAX_TRIANGLES*3 || i%3 || size!=16+(usize)v*12+(usize)i*4) return "invalid mesh size";
+    Vec *pv=io_alloc((usize)MAX_MESH_VERTICES*sizeof(Vec));
+    u32 *pi=io_alloc((usize)MAX_TRIANGLES*3*sizeof(u32));
+    if(!pv || !pi) { io_free(pv,(usize)MAX_MESH_VERTICES*sizeof(Vec));io_free(pi,(usize)MAX_TRIANGLES*3*sizeof(u32));return "mesh allocation failed"; }
+    for(u32 k=0;k<v*3;k++) {
+        union { u32 u; float f; } c={rd32(data+16+4*(usize)k)};
+        if(!finite(c.f)) { io_free(pv,(usize)MAX_MESH_VERTICES*sizeof(Vec));io_free(pi,(usize)MAX_TRIANGLES*3*sizeof(u32));return "non-finite mesh vertex"; }
+        ((float *)pv)[k]=c.f;
+    }
+    for(u32 k=0;k<i;k++) {
+        pi[k]=rd32(data+16+(usize)v*12+4*(usize)k);
+        if(pi[k]>=v) { io_free(pv,(usize)MAX_MESH_VERTICES*sizeof(Vec));io_free(pi,(usize)MAX_TRIANGLES*3*sizeof(u32));return "mesh index outside vertex array"; }
+    }
+    *vertices=pv;*indices=pi;*nv=(int)v;*ni=(int)i;return 0;
+}
+const char *mesh_bytes(const Vec *vertices, const u32 *indices, int nv, int ni, u8 **data, usize *size)
+{
+    *size=16+(usize)nv*12+(usize)ni*4;
+    *data=io_alloc(*size);
+    if(!*data) return "mesh allocation failed";
+    u8 *p=*data;
+    p[0]='F';p[1]='P';p[2]='R';p[3]='M';wr32(p+4,1);wr32(p+8,(u32)nv);wr32(p+12,(u32)ni);
+    /* Both supported targets are little-endian IEEE float32, like the scanner's original writer. */
+    memcpy(p+16,vertices,(usize)nv*12);
+    memcpy(p+16+(usize)nv*12,indices,(usize)ni*4);
+    return 0;
+}
+
+/* ------------------------------------------------------------------------------------------------ scan.json */
+void heads_json(Buf *b, const Vec *heads, int n)
+{
+    put(b,"[");
+    for(int i=0;i<n;i++) {
+        if(i) put(b,",");
+        put(b,"[");put_dec(b,heads[i].x);put(b,",");put_dec(b,heads[i].y);put(b,",");put_dec(b,heads[i].z);put(b,"]");
+    }
+    put(b,"]");
+}
+int heads_parse(const char *text, usize n, Vec *heads)
+{
+    /* Finds "heads":[[x,y,z],...] in a scan.json written by heads_json; anything else gives no heads. */
+    const char *key="\"heads\"";
+    usize at=0;
+    for(;at+7<=n;at++) {
+        usize k=0;while(k<7 && text[at+k]==key[k]) k++;
+        if(k==7) break;
+    }
+    if(at+7>n) return 0;
+    char *p=(char *)text+at+7;const char *end=text+n;
+    while(p<end && (is_space(*p) || *p=='\n' || *p==':')) p++;
+    if(p>=end || *p!='[') return 0;
+    p++;
+    int count=0;
+    while(p<end && count<MAX_HEADS) {
+        while(p<end && (is_space(*p) || *p=='\n' || *p==',')) p++;
+        if(p>=end || *p==']') break;
+        if(*p!='[') return 0;
+        p++;
+        float v[3];
+        for(int i=0;i<3;i++) {
+            while(p<end && (is_space(*p) || *p==',')) p++;
+            if(!parse_number(&p,&v[i])) return 0;
+        }
+        while(p<end && is_space(*p)) p++;
+        if(p>=end || *p!=']') return 0;
+        p++;
+        heads[count++]=vec(v[0],v[1],v[2]);
+    }
+    return count;
+}
+static void key_float(Buf *b, const char *k, float v) { put(b,",\"");put(b,k);put(b,"\":");put_dec(b,v); }
+static void key_int(Buf *b, const char *k, i64 v, int first)
+{
+    if(!first) put(b,",");
+    put(b,"\"");put(b,k);put(b,"\":");put_int(b,v);
+}
+void settings_json(Buf *b, const Refine *o)
+{
+    static const char *walls[]={"off","snap","panels"};
+    put(b,"{");key_int(b,"refine",o->refine,1);
+    put(b,",\"walls\":\"");put(b,walls[o->walls]);put(b,"\"");
+    key_float(b,"band",o->band);key_float(b,"facing_deg",o->facing_deg);key_float(b,"band_in",o->band_in);
+    key_float(b,"floor_in",o->floor_in);key_float(b,"ceil_in",o->ceil_in);key_float(b,"top_strip",o->top_strip);
+    key_float(b,"near",o->near);key_float(b,"clip",o->clip);key_float(b,"clip_open",o->clip_open);
+    key_float(b,"island",o->island);key_int(b,"smooth",o->smooth,0);key_float(b,"tops",o->tops);
+    key_int(b,"protect",o->protect,0);key_float(b,"tubes",o->tubes);key_float(b,"tube_thick",o->tube_thick);
+    key_float(b,"walked",o->walked);key_int(b,"label_rules",o->label_rules,0);
+    put(b,",\"erase\":[");
+    for(int i=0;i<o->nerase;i++) {
+        const Sphere *e=&o->erase[i];
+        if(i) put(b,",");
+        put(b,"[");put_dec(b,e->x);put(b,",");put_dec(b,e->y);put(b,",");put_dec(b,e->z);put(b,",");put_dec(b,e->r);put(b,"]");
+    }
+    put(b,"]}");
+}
+void report_json(Buf *b, const Report *r, int nlabels, int changed, int removed, int nsuggest)
+{
+    static const char *kinds[]={"wall","floor","ceiling"};
+    put(b,"{");key_int(b,"triangles",r->triangles,1);key_int(b,"kept",r->kept,0);
+    key_int(b,"structural",r->structural,0);key_int(b,"near_walls",r->near,0);key_int(b,"outside",r->outside,0);
+    key_int(b,"small_pieces",r->islands,0);key_int(b,"thin_pieces",r->tubes,0);key_int(b,"erased",r->erased,0);
+    key_int(b,"walked",r->walked,0);key_int(b,"tops",r->tops,0);key_int(b,"panel_triangles",r->panels,0);
+    key_int(b,"truncated",r->truncated,0);
+    put(b,",\"walked_skipped\":");put(b,r->walked_skipped ? "true" : "false");
+    key_float(b,"floor_y",r->floor_y);key_float(b,"ceiling_y",r->ceiling_y);
+    key_int(b,"boxes",nlabels,0);key_int(b,"relabelled",changed,0);key_int(b,"removed_boxes",removed,0);
+    key_int(b,"suggestions",nsuggest,0);
+    put(b,",\"plane_shifts\":[");
+    for(int i=0;i<r->nshifts;i++) {
+        if(i) put(b,",");
+        put(b,"{\"kind\":\"");put(b,kinds[r->shifts[i].kind]);put(b,"\"");
+        if(!r->shifts[i].kind) { put(b,",\"wall\":");put_int(b,r->shifts[i].wall); }
+        key_float(b,"shift",r->shifts[i].shift);put(b,"}");
+    }
+    put(b,"]}");
+}
@@ -0,0 +1,255 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+/* Label rules on the scanner's furniture boxes (the owner's tuned rules, 2026-10-18): boxes outside the room,
+ * boxes that merged several things, boxes nested in a bigger one are removed; the rest are relabelled BED, COUCH,
+ * TABLE, STORAGE, SCREEN or OTHER by shape; tall thin slabs from the floor become door/closet suggestions (never
+ * applied automatically). Every decision is reported with a reason in scan.json. */
+#include "refine.h"
+
+#define R_INSIDE .1f         /* m: a centre further outside the outline is behind a wall */
+#define R_NEAR_WALL .35f
+#define R_BED_AREA 2.f
+#define R_BED_LONG 1.8f
+#define R_BED_MAX 3.f
+#define R_BED_TOP .65f
+#define R_BED_MIN_TOP .25f
+#define R_COUCH_MIN_TOP .35f
+#define R_COUCH_TOP .6f
+#define R_COUCH_LONG 1.4f
+#define R_TABLE_MIN .6f
+#define R_TABLE_MAX 1.1f
+#define R_STORAGE_H 1.1f
+#define R_STORAGE_D .25f
+#define R_SCREEN_BOTTOM .3f
+#define R_SCREEN_TOP 2.2f
+#define R_SCREEN_ASPECT 1.2f
+#define R_SCREEN_PARALLEL 15.f  /* degrees off the nearest wall */
+#define R_SCREEN_FLAT .03f      /* m: spread of the scan's depth inside the box */
+#define R_THIN .22f
+#define R_TALL_MIN 1.8f
+#define R_TALL_FLOOR .3f        /* m: a tall slab's bottom at most this far above the floor */
+#define R_TALL_BEHIND .5f
+#define R_DOOR_MAX 1.1f
+#define R_MERGE .6f             /* share of a box's footprint inside another that counts as held by it */
+#define R_MERGE_APART 1.f
+#define R_NESTED .75f
+#define FLAT_MIN_TRIANGLES 30
+#define FLAT_DEPTH_PAD .05f
+#define FOOTPRINT_STEP .05
+
+typedef struct { double cs, sn; } Rot;
+static Rot rot(const RVol *v) { double a=v->yaw*3.14159265358979323846/180; return (Rot){dcos(a),dsin(a)}; }
+static void local(const RVol *v, Rot r, double x, double z, double *lx, double *lz)
+{
+    double dx=x-v->cx,dz=z-v->cz;
+    *lx=r.cs*dx-r.sn*dz;*lz=r.sn*dx+r.cs*dz;
+}
+static double dabs(double x) { return x<0 ? -x : x; }
+static void corners(const RVol *v, Rot r, double out[4][2])
+{
+    static const int sg[4][2]={{-1,-1},{1,-1},{1,1},{-1,1}};
+    for(int k=0;k<4;k++) {
+        double x=sg[k][0]*v->w/2.,z=sg[k][1]*v->d/2.;
+        out[k][0]=v->cx+r.cs*x+r.sn*z;out[k][1]=v->cz-r.sn*x+r.cs*z;
+    }
+}
+static int point_in_poly(double x, double z, const DPt *poly, int n)
+{
+    int inside=0;
+    for(int i=0,j=n-1;i<n;j=i++) {
+        double xi=poly[i].x,zi=poly[i].z,xj=poly[j].x,zj=poly[j].z;
+        if((zi>z)!=(zj>z) && x<(xj-xi)*(z-zi)/(zj-zi+1e-12)+xi) inside=!inside;
+    }
+    return inside;
+}
+typedef struct { double dist, t, L, ux, uz; int i; } Near;
+static Near nearest_wall(const Room *r, double x, double z)
+{
+    Near best={1e300,0,0,1,0,-1};
+    for(int i=0;i<r->nwalls;i++) {
+        const RWall *w=&r->walls[i];
+        double abx=w->x1-w->x0,abz=w->z1-w->z0,l2=abx*abx+abz*abz,L=dhypot(abx,abz);
+        if(!(l2>0)) continue;
+        double t=((x-w->x0)*abx+(z-w->z0)*abz)/l2;
+        t=t<0 ? 0 : t>1 ? 1 : t;
+        double dx=x-(w->x0+t*abx),dz=z-(w->z0+t*abz),d=dhypot(dx,dz);
+        if(d<best.dist) best=(Near){d,t,L,abx/L,abz/L,i};
+    }
+    return best;
+}
+static double outside(const Room *r, double x, double z)
+{
+    return point_in_poly(x,z,r->outline,r->noutline) ? 0 : nearest_wall(r,x,z).dist;
+}
+/* Spread (std) of the scan's depth inside a thin upright box; <0 = too little scan to tell. */
+static double flatness(const Prep *p, const RVol *v)
+{
+    Rot r=rot(v);
+    double sum=0,sum2=0;int n=0;
+    for(int pass=0;pass<2;pass++) {
+        double mean=n ? sum/n : 0;
+        for(int t=0;t<p->T;t++) {
+            double y=p->cen[3*t+1];
+            if(y>v->top || y<v->top-v->h) continue;
+            double lx,lz;local(v,r,p->cen[3*t],p->cen[3*t+2],&lx,&lz);
+            double a=lx,b=lz,half=v->w/2.,depth=v->d/2.+FLAT_DEPTH_PAD;
+            if(v->d>v->w) { a=lz;b=lx;half=v->d/2.;depth=v->w/2.+FLAT_DEPTH_PAD; }
+            if(dabs(a)<=half && dabs(b)<=depth) {
+                if(!pass) { sum+=b;n++; } else sum2+=(b-mean)*(b-mean);
+            }
+        }
+        if(!pass && n<FLAT_MIN_TRIANGLES) return -1;
+    }
+    return droot(sum2/n);
+}
+static void cm(Buf *b, double x) { put_round(b,x*100);put(b," cm"); }
+static void lower(Buf *b, const char *s)
+{
+    char c[2]={0,0};
+    for(;*s;s++) { c[0]=*s>='A' && *s<='Z' ? (char)(*s+32) : *s;put(b,c); }
+}
+static void set_text(char *dst, usize cap, Buf *b)
+{
+    usize n=b->ok ? b->n : 0;
+    if(n>=cap) {  /* cut at a UTF-8 boundary */
+        n=cap-1;
+        while(n && ((u8)b->data[n]&0xc0)==0x80) n--;
+    }
+    if(n) memcpy(dst,b->data,n);
+    dst[n]=0;
+}
+static void copy(char *dst, const char *src, usize cap)
+{
+    usize i=0;while(src[i] && i+1<cap) { dst[i]=src[i];i++; }
+    dst[i]=0;
+}
+/* label "" = remove, suggest "door"/"closet" or "" */
+static void classify(const Room *room, const Prep *p, const RVol *v, char *label, char *suggest, Buf *why)
+{
+    double out=outside(room,v->cx,v->cz);
+    double top=v->top-room->floor,bottom=top-v->h,lng=v->w>v->d ? v->w : v->d,shrt=v->w<v->d ? v->w : v->d;
+    label[0]=suggest[0]=0;
+    if(shrt<R_THIN && v->h>=R_TALL_MIN && bottom<=R_TALL_FLOOR && out<=R_TALL_BEHIND) {
+        int door=lng<=R_DOOR_MAX;
+        copy(suggest,door ? "door" : "closet",8);
+        put(why,"tall thin slab from the floor (");put_fixed(why,v->h,2);put(why," m)");
+        if(out>0) { put(why,", ");cm(why,out);put(why," behind the wall line"); }
+        put(why,door ? ": a door or closet door?" : ": a closet front?");
+        return;
+    }
+    if(out>R_INSIDE) { put(why,"centre ");cm(why,out);put(why," outside the room (behind a wall)");return; }
+    Near wall=nearest_wall(room,v->cx,v->cz);
+    if(shrt<R_THIN) {
+        Rot r=rot(v);
+        double ax=v->w>=v->d ? r.cs : r.sn,az=v->w>=v->d ? -r.sn : r.cs;
+        double c=dabs(ax*wall.ux+az*wall.uz);c=c<1 ? c : 1;
+        double off=angle((float)droot(1-c*c),(float)c)*180/PI;
+        double fl=flatness(p,v);
+        Buf b;buf_init(&b,1024);int n=0;
+        if(bottom<R_SCREEN_BOTTOM) { put(&b,"starts ");cm(&b,bottom>0 ? bottom : 0);put(&b," off the floor");n++; }
+        if(top>R_SCREEN_TOP) { if(n++) put(&b,", ");put(&b,"top at ");put_fixed(&b,top,2);put(&b," m"); }
+        if(lng/v->h<R_SCREEN_ASPECT) { if(n++) put(&b,", ");put(&b,"taller than wide (");put_fixed(&b,lng/v->h,2);put(&b,")"); }
+        if(wall.dist<R_NEAR_WALL && off>R_SCREEN_PARALLEL) { if(n++) put(&b,", ");put_round(&b,off);put(&b,"\xc2\xb0 off the wall"); }
+        if(fl>=0 && fl>R_SCREEN_FLAT) { if(n++) put(&b,", ");put(&b,"not flat (");cm(&b,fl);put(&b," spread)"); }
+        if(!n) {
+            copy(label,"SCREEN",MAX_LABEL);put(why,"thin, raised, screen-shaped");
+            if(fl>=0) { put(why,", flat (");cm(why,fl);put(why,")"); }
+        } else { put(why,"thin upright slab: ");put_n(why,b.data,b.n); }
+        buf_free(&b);
+        return;
+    }
+    if(top<=R_BED_TOP && v->w*v->d>=R_BED_AREA && lng>=R_BED_LONG && lng<=R_BED_MAX && top>=R_BED_MIN_TOP) {
+        copy(label,"BED",MAX_LABEL);put_fixed(why,(double)v->w*v->d,1);put(why," m\xc2\xb2, ");put_fixed(why,lng,1);
+        put(why," m long, top ");put_fixed(why,top,2);put(why," m");return;
+    }
+    if(top>=R_COUCH_MIN_TOP && top<=R_COUCH_TOP && lng>=R_COUCH_LONG) {
+        copy(label,"COUCH",MAX_LABEL);put(why,"seat-height top ");put_fixed(why,top,2);put(why," m, ");
+        put_fixed(why,lng,1);put(why," m long");return;
+    }
+    if(top>=R_TABLE_MIN && top<=R_TABLE_MAX) { copy(label,"TABLE",MAX_LABEL);put(why,"top ");put_fixed(why,top,2);put(why," m");return; }
+    if(v->h>=R_STORAGE_H && shrt>=R_STORAGE_D && wall.dist<R_NEAR_WALL) {
+        copy(label,"STORAGE",MAX_LABEL);put_fixed(why,v->h,2);put(why," m tall by a wall");return;
+    }
+    if(top>R_TABLE_MAX) { put_fixed(why,top,2);put(why," m tall, matches nothing");return; }
+    copy(label,"OTHER",MAX_LABEL);put(why,"top ");put_fixed(why,top,2);put(why," m, ");put_fixed(why,lng,1);
+    put(why," \xc3\x97 ");put_fixed(why,shrt,1);put(why," m");
+}
+/* Share of a's and b's footprint they have in common, sampled on a 5 cm grid over both (as the reference). */
+static void footprint_overlap(const RVol *a, const RVol *b, double *fa, double *fb)
+{
+    Rot ra=rot(a),rb=rot(b);
+    double ca[4][2],cb[4][2],x0=1e300,x1=-1e300,z0=1e300,z1=-1e300;
+    corners(a,ra,ca);corners(b,rb,cb);
+    for(int k=0;k<4;k++) {
+        x0=ca[k][0]<x0 ? ca[k][0] : x0;x1=ca[k][0]>x1 ? ca[k][0] : x1;z0=ca[k][1]<z0 ? ca[k][1] : z0;z1=ca[k][1]>z1 ? ca[k][1] : z1;
+        x0=cb[k][0]<x0 ? cb[k][0] : x0;x1=cb[k][0]>x1 ? cb[k][0] : x1;z0=cb[k][1]<z0 ? cb[k][1] : z0;z1=cb[k][1]>z1 ? cb[k][1] : z1;
+    }
+    double na=0,nb=0,both=0;
+    for(double x=x0;x<=x1;x+=FOOTPRINT_STEP) for(double z=z0;z<=z1;z+=FOOTPRINT_STEP) {
+        double ax,az,bx,bz;local(a,ra,x,z,&ax,&az);local(b,rb,x,z,&bx,&bz);
+        int ia=dabs(ax)<=a->w/2. && dabs(az)<=a->d/2.,ib=dabs(bx)<=b->w/2. && dabs(bz)<=b->d/2.;
+        na+=ia;nb+=ib;both+=ia && ib;
+    }
+    *fa=both/(na>1 ? na : 1);*fb=both/(nb>1 ? nb : 1);
+}
+static int boxes_apart(const RVol *a, const RVol *b)
+{
+    /* footprints whose bounding circles don't touch share nothing (skips the sampling, same result) */
+    double ra=droot((double)a->w*a->w+(double)a->d*a->d)/2,rb=droot((double)b->w*b->w+(double)b->d*b->d)/2;
+    double dx=a->cx-b->cx,dz=a->cz-b->cz;
+    return dx*dx+dz*dz>(ra+rb+.1)*(ra+rb+.1);
+}
+int rules_apply(const Room *room, const Prep *p, RVol *out, int *nout, Label *labels)
+{
+    int n=room->nvols;const RVol *box=room->vols;
+    typedef struct { int i, j; double fa, fb; } Ov;
+    static Ov ov[MAX_VOLUMES*(MAX_VOLUMES-1)/2];
+    int nov=0,removed[MAX_VOLUMES]={0};
+    static char reason[MAX_VOLUMES][MAX_REASON];
+    for(int i=0;i<n;i++) for(int j=i+1;j<n;j++) {
+        if(boxes_apart(&box[i],&box[j])) continue;
+        double fa,fb;footprint_overlap(&box[i],&box[j],&fa,&fb);
+        if(fa>0 || fb>0) ov[nov++]=(Ov){i,j,fa,fb};
+    }
+    /* merged: a box that holds most of two boxes far apart covers several things */
+    for(int k=0;k<n;k++) {
+        int held[MAX_VOLUMES],nh=0;
+        for(int q=0;q<nov;q++) if(ov[q].i==k && ov[q].fb>=R_MERGE) held[nh++]=ov[q].j;
+        for(int q=0;q<nov;q++) if(ov[q].j==k && ov[q].fa>=R_MERGE) held[nh++]=ov[q].i;
+        for(int x=0;x<nh && !removed[k];x++) for(int y=0;y<nh && !removed[k];y++) {
+            const RVol *a=&box[held[x]],*b=&box[held[y]];
+            double dx=a->cx-b->cx,dz=a->cz-b->cz,d=dhypot(dx,dz);
+            if(held[x]<held[y] && d>=R_MERGE_APART) {
+                Buf t;buf_init(&t,1024);
+                put(&t,"holds a ");lower(&t,a->label);put(&t," and a ");lower(&t,b->label);put(&t," ");
+                put_fixed(&t,d,1);put(&t," m apart: several things merged");
+                set_text(reason[k],MAX_REASON,&t);buf_free(&t);removed[k]=1;
+            }
+        }
+    }
+    /* nested: mostly inside a bigger box with a lower top = part of it */
+    for(int q=0;q<nov;q++) for(int side=0;side<2;side++) {
+        int s=side ? ov[q].j : ov[q].i,g=side ? ov[q].i : ov[q].j;double f=side ? ov[q].fb : ov[q].fa;
+        const RVol *S=&box[s],*G=&box[g];
+        if(removed[s] || removed[g] || f<R_NESTED || (double)S->w*S->d>=(double)G->w*G->d || S->top>G->top+.05) continue;
+        Buf t;buf_init(&t,1024);
+        put_round(&t,f*100);put(&t,"% inside the bigger ");lower(&t,G->label);put(&t," box: part of it");
+        set_text(reason[s],MAX_REASON,&t);buf_free(&t);removed[s]=1;
+    }
+    int count=0;
+    for(int i=0;i<n;i++) {
+        Label *l=&labels[i];
+        memset(l,0,sizeof(*l));
+        copy(l->from,box[i].label,MAX_LABEL);l->box=box[i];l->wall=-1;
+        if(removed[i]) { copy(l->reason,reason[i],MAX_REASON);continue; }
+        Buf why;buf_init(&why,1024);
+        classify(room,p,&box[i],l->to,l->suggest,&why);
+        set_text(l->reason,MAX_REASON,&why);buf_free(&why);
+        if(l->suggest[0]) {
+            Near nw=nearest_wall(room,box[i].cx,box[i].cz);
+            l->wall=nw.i;l->along=(float)nw.t;
+        }
+        if(l->to[0]) { out[count]=box[i];copy(out[count].label,l->to,MAX_LABEL);count++; }
+    }
+    *nout=count;
+    return n;
+}
@@ -0,0 +1,108 @@
+/* SPDX-License-Identifier: GPL-3.0-only */
+#ifndef FP_ROOMSCAN_H
+#define FP_ROOMSCAN_H
+#include "platform.h"
+
+/* Resource limits are independent of dump length. Two passes avoid retaining frames. */
+#define MAX_FRAME_VERTICES 1000000u
+#define MAX_FRAME_INDICES 3000000u
+#define MAX_CELLS 4200000u
+#define MAX_SAMPLES 32768
+#define MAX_PLANES 32
+#define MAX_OUTLINE 96
+#define MAX_VOLUMES 128
+#define MAX_TRIANGLES 200000
+#define MAX_MESH_VERTICES 600000
+#define MAX_HEADS 2000
+#define MAX_ERASE 64
+#define PI 3.14159265358979323846f
+
+typedef struct { float x, y, z; } Vec;
+typedef struct { float x, z; } Pt;
+typedef struct {
+    Vec p, n;
+    float weight, sdf, sw;
+    int mark;
+    unsigned views, last_frame;
+} Cell;
+typedef struct {
+    Vec n;
+    float d, lo, hi, bottom, top, area;
+    int used;
+} Plane;
+typedef struct { Vec p; float yaw, w, d, h; const char *label; } Volume;
+typedef struct { float x, y, z, r; } Sphere;
+/* Refinement + label rules (refine.c, rules.c); defaults = the owner's tuned settings (2026-10-18). */
+typedef struct {
+    int refine, walls, protect, label_rules, smooth, nerase;  /* walls: 0 off, 1 snap, 2 panels */
+    float band, facing_deg, band_in, floor_in, ceil_in, top_strip, near, clip, clip_open, island, tops;
+    float tubes, tube_thick, walked;
+    Sphere erase[MAX_ERASE];
+} Refine;
+typedef struct {
+    const char *input, *out, *hint, *refine_only;
+    Refine rf;
+    u64 universe;
+    float voxel, ceiling_default, truncation, max_edge, grazing, range, depth_jump, depth_ratio, min_views;
+    float patch_residual;
+    float plane_distance, min_plane_area, wall_height, snap_degrees;
+    float floor_band, ceiling_min, min_volume, cluster_gap, gap, horizontal;
+} Options;
+typedef struct {
+    Options opt;
+    Cell *cells;
+    int nx, ny, nz, count;
+    Vec origin;
+    Vec samples[MAX_SAMPLES];
+    int nsamples;
+    u64 seen, accepted, rejected, clipped, far_vertices, discontinuities;
+    unsigned frames, skipped_frames, fuse_frame;
+    Plane planes[MAX_PLANES];
+    int nplanes;
+    Pt outline[MAX_OUTLINE];
+    int invisible[MAX_OUTLINE], noutline;
+    Volume volumes[MAX_VOLUMES];
+    int nvolumes;
+    float floor, ceiling, coverage;
+    const char *warnings[24];
+    int nwarnings, hint_used;
+    u32 rng;
+    Vec heads[MAX_HEADS];   /* head path of tracked frames; the stride doubles whenever the buffer is full */
+    int nheads;
+    unsigned head_stride, head_frames;
+    Vec *vertices;
+    u32 *indices;
+    int nv, ni;
+    i64 t0, tread, tfuse, tmodel, tmesh, trefine;
+} Scan;
+
+static inline float ab(float x) { return x < 0 ? -x : x; }
+static inline float mn(float a, float b) { return a < b ? a : b; }
+static inline float mx(float a, float b) { return a > b ? a : b; }
+static inline float clamp(float x, float a, float b) { return mn(mx(x, a), b); }
+static inline Vec vec(float x, float y, float z) { return (Vec){x,y,z}; }
+static inline Vec add(Vec a, Vec b) { return vec(a.x+b.x,a.y+b.y,a.z+b.z); }
+static inline Vec sub(Vec a, Vec b) { return vec(a.x-b.x,a.y-b.y,a.z-b.z); }
+static inline Vec mul(Vec a, float b) { return vec(a.x*b,a.y*b,a.z*b); }
+static inline float dot(Vec a, Vec b) { return a.x*b.x+a.y*b.y+a.z*b.z; }
+static inline Vec cross(Vec a, Vec b) { return vec(a.y*b.z-a.z*b.y,a.z*b.x-a.x*b.z,a.x*b.y-a.y*b.x); }
+static inline int finite(float x) { return x == x && ab(x) < 1e20f; }
+float root(float x);
+float sine(float x);
+float cosine(float x);
+float angle(float y, float x);
+Vec unit(Vec p);
+int flo(float x);
+u32 random_next(Scan *s);
+void warn(Scan *s, const char *message);
+int cell_index(Scan *s, Vec p);
+Vec grid_point(Scan *s, int x, int y, int z);
+const char *read_dump(Scan *s, int fuse);
+const char *init_grid(Scan *s);
+void finish_fusion(Scan *s);
+const char *make_model(Scan *s);
+const char *make_mesh(Scan *s);
+int same(const char *a, const char *b);
+int parse_number(char **cursor, float *value);
+
+#endif
@@ -7,6 +7,8 @@
 // Meta's OVRPlugin finds xrGetInstanceProcAddr with dlopen("libopenxr_loader.so") + dlsym, so FramePort points that
 // string in libOVRPlugin.so at this library instead (patches/frame/adapter.py). Names the adapter emulates are served
 // by the adapter (framebridge_extension_proc); everything else goes to overport's xrGetInstanceProcAddr unchanged.
+// The adapter also routes scene discovery/persistence/mesh and the core locate/event functions that consume
+// emulated spaces. Keep this name-agnostic: another fixed table here would repeat the dispatcher's limitation.
 //
 // Haptics (GitHub #9, found by Klownicle in Lucky's Tale): overport's dispatcher converts an
 // XrHapticAmplitudeEnvelopeVibrationFB with its nanosecond duration taken as seconds, so one vibration allocates an
@@ -149,7 +151,7 @@ EXPORT XRAPI_ATTR XrResult XRAPI_CALL xrGetInstanceProcAddr(XrInstance instance,
        }
        return r;
    }
-    if (name && function && instance != XR_NULL_HANDLE) {
+    if (name && function && instance != XR_NULL_HANDLE) {  // a null instance only serves the loader functions
        PFN_xrVoidFunction emulated = adapter_proc(name);
        if (emulated) {
            __android_log_print(ANDROID_LOG_INFO, TAG, "extension shim: %s -> FrameBridge", name);
@@ -61,6 +61,14 @@ def from_data() -> dict:
                texts[label] = ""
    for _, title in GROUPS:  # the Game settings dialog
        texts[title] = ""
+    from frameport.install.rooms import REFINE_DEFAULTS, REFINE_GROUPS
+
+    for meta in REFINE_DEFAULTS.values():  # the Room tab's scan clean-up settings
+        texts[meta["label"]] = ""
+        for _, label in meta.get("choices", ()):
+            texts[label] = ""
+    for _, title in REFINE_GROUPS:
+        texts[title] = ""
    for ui in [*UI.values(), *FOVEATION_UI.values()]:
        for t in (ui.get("label"), ui.get("help")):
            if t:
@@ -0,0 +1,111 @@
+"""Render the in-headset room-scan prompts (SteamVR overlay images) into artifacts/roomscan/.
+
+The Frame has no imaging library, so the agent shows pre-rendered PNGs through IVROverlay while it records the
+passthrough depth mesh (agent `room_capture`). One image per state; "look around" comes in 13 variants (0-12 of 12
+directions seen) so the progress ring can advance without drawing on the Frame. Colours = the Portal theme.
+
+    uv run python scripts/mr/render_prompts.py [--check]
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import io
+import sys
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+ROOT = Path(__file__).resolve().parents[2]
+OUT = ROOT / "artifacts" / "roomscan"
+W, H = 1024, 400
+BG, SURFACE, TEXT, TEXT_2 = (13, 14, 18, 235), (29, 31, 39, 255), (236, 238, 243, 255), (167, 172, 186, 255)
+ACCENT, SECONDARY, OK = (255, 138, 31, 255), (58, 168, 255, 255), (74, 222, 128, 255)
+DIRECTIONS = 12
+
+PROMPTS = {
+    "start": ("Turn on passthrough", "The scan runs while you can see your room:\n"
+              "open the quick access menu and switch passthrough on."),
+    "ceiling": ("Look up at the ceiling", "Hold it for a few seconds,\n"
+                "then look back down and keep turning."),
+    "floor": ("Look down at the floor", "Hold it for a few seconds,\nthen keep turning."),
+    "done": ("Room scanned", "You can take the headset off or start a mixed reality game."),
+    "failed": ("Scan stopped", "The headset's cameras sent no room view.\nStart the scan again from FramePort."),
+}
+
+
+def font(size: int, bold: bool = False) -> ImageFont.FreeTypeFont:
+    for name in ("DejaVuSans-Bold.ttf" if bold else "DejaVuSans.ttf",):
+        for base in ("/usr/share/fonts/truetype/dejavu", "C:/Windows/Fonts", "/Library/Fonts"):
+            p = Path(base) / name
+            if p.is_file():
+                return ImageFont.truetype(str(p), size)
+    return ImageFont.load_default(size=size)
+
+
+def panel(title: str, body: str, seen: int | None = None, accent=ACCENT, ring=SECONDARY,
+          label: str | None = None) -> Image.Image:
+    img = Image.new("RGBA", (W, H), (0, 0, 0, 0))
+    d = ImageDraw.Draw(img)
+    d.rounded_rectangle((4, 4, W - 4, H - 4), radius=48, fill=BG, outline=SURFACE, width=4)
+    d.rounded_rectangle((4, 4, 20, H - 4), radius=8, fill=accent)  # portal edge
+    x = 64
+    if seen is not None:  # progress ring: one segment per 30 degree direction seen
+        cx, cy, r = 150, H // 2, 92
+        for i in range(DIRECTIONS):
+            a0 = -90 + i * 360 / DIRECTIONS + 3
+            d.arc((cx - r, cy - r, cx + r, cy + r), a0, a0 + 360 / DIRECTIONS - 6,
+                  fill=(ring if i < seen else SURFACE), width=26)
+        d.text((cx, cy), label if label is not None else f"{seen}/{DIRECTIONS}", font=font(44, True), fill=TEXT,
+               anchor="mm")
+        x = 290
+    d.text((x, 108), title, font=font(54, True), fill=TEXT, anchor="lm")
+    y = 180
+    for line in body.split("\n"):
+        d.text((x, y), line, font=font(32), fill=TEXT_2, anchor="lm")
+        y += 48
+    return img
+
+
+def images() -> dict[str, bytes]:
+    out = {}
+    for key, (title, body) in PROMPTS.items():
+        out[key] = panel(title, body, accent=OK if key == "done" else ACCENT)
+    for n in range(DIRECTIONS + 1):
+        out[f"look_{n:02d}"] = panel("Look around the room", "Turn slowly until the ring is full:\n"
+                                     "every wall and your furniture.", seen=n, accent=SECONDARY)
+    for n in range(DIRECTIONS + 1):  # everything seen before the minimum scan time: the ring is the time left
+        out[f"finish_{n:02d}"] = panel("Almost done", "Walls, ceiling and floor are covered.\n"
+                                       "Look closely at your furniture\nuntil the ring fills.", seen=n, accent=OK,
+                                       ring=OK, label=f"{(DIRECTIONS - n) * 5}s")
+    data = {}
+    for key, img in out.items():
+        buf = io.BytesIO()
+        img.save(buf, "PNG", optimize=True)
+        data[f"{key}.png"] = buf.getvalue()
+    return data
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--check", action="store_true", help="fail if artifacts/roomscan is out of date")
+    args = ap.parse_args()
+    data = images()
+    if args.check:
+        stale = [n for n, b in data.items() if not (OUT / n).is_file() or (OUT / n).read_bytes() != b]
+        if stale:
+            print("out of date:", ", ".join(stale))
+            return 1
+        return 0
+    OUT.mkdir(parents=True, exist_ok=True)
+    for name, b in data.items():
+        p = OUT / name
+        if not p.is_file() or p.read_bytes() != b:
+            p.write_bytes(b)
+    print(f"{len(data)} prompts in {OUT.relative_to(ROOT)} "
+          f"({sum(map(len, data.values())) // 1024} KiB, {hashlib.sha256(b''.join(data.values())).hexdigest()[:12]})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""Render deterministic, noisy head-centred depth meshes into the FPRS v1 contract (stdlib only)."""
+from __future__ import annotations
+
+import argparse
+import math
+import random
+import struct
+from pathlib import Path
+
+BOX_OUTLINE = [(-2, -1.5), (2, -1.5), (2, 1.5), (-2, 1.5)]
+L_OUTLINE = [(-2, -2), (2, -2), (2, 0), (0, 0), (0, 2), (-2, 2)]
+TABLE = ((-.6, 0, -.25), (1.2, .75, .7))
+COUCH = ((.6, 0, .95), (1.6, .65, .65))
+# Clutter for the refinement tests: a thin pole floating in the air (a stereo streak) and a column where the user
+# stood (a "ghost" of the user's own body or a passer-by in the depth stream).
+TUBE = ((1.3, 1.35, -.5), (.12, .12, 1.4))
+GHOST = ((.35, .45, 0), (.3, .9, .3))
+ROOMVIEW_WIDTH, ROOMVIEW_HEIGHT = 132, 128
+ROOMVIEW_NEAR, ROOMVIEW_FAR = .3, 4.0
+
+
+def fan(width, height, roomview):
+    """RoomView camera axes are +Z forward / -Y image up; poses convert them to STAGE."""
+    sx, sy = (1.96, 1.94) if roomview else (math.tan(math.radians(55)), math.tan(math.radians(38)))
+    for row in range(height):
+        for col in range(width):
+            x = (2 * col / (width - 1) - 1) * sx
+            y = (2 * row / (height - 1) - 1) * sy
+            if not roomview:
+                y = -y
+            length = math.sqrt(x * x + y * y + 1)
+            yield x / length, y / length, (1 if roomview else -1) / length
+
+
+def smooth_depths(values, width, height, radius=3):
+    """Separable box smoothing models soft stereo boundaries, without a NumPy/scipy dependency."""
+    result = list(values)
+    for vertical in (False, True):
+        source, result = result, [0.0] * len(values)
+        lines, length, step = (width, height, width) if vertical else (height, width, 1)
+        for line in range(lines):
+            start = line if vertical else line * width
+            prefix = [0.0]
+            for i in range(length):
+                prefix.append(prefix[-1] + source[start + i * step])
+            for i in range(length):
+                lo, hi = max(0, i - radius), min(length, i + radius + 1)
+                result[start + i * step] = (prefix[hi] - prefix[lo]) / (hi - lo)
+    return result
+
+
+def inside(x, z, polygon):
+    odd = False
+    for (ax, az), (bx, bz) in zip(polygon, polygon[1:] + polygon[:1], strict=False):
+        if (az > z) != (bz > z) and x < (bx - ax) * (z - az) / (bz - az) + ax:
+            odd = not odd
+    return odd
+
+
+def rotate(v, q):
+    x, y, z = v
+    qx, qy, qz, qw = q
+    tx, ty, tz = 2 * (qy * z - qz * y), 2 * (qz * x - qx * z), 2 * (qx * y - qy * x)
+    return (x + qw * tx + qy * tz - qz * ty,
+            y + qw * ty + qz * tx - qx * tz,
+            z + qw * tz + qx * ty - qy * tx)
+
+
+def cast(eye, direction, polygon, ceiling, furniture, missing_wall):
+    ex, ey, ez = eye
+    dx, dy, dz = direction
+    nearest = 5.0
+    hit = False
+    for height in (0, ceiling):
+        if abs(dy) > 1e-8:
+            t = (height - ey) / dy
+            if .3 < t < nearest and inside(ex + t * dx, ez + t * dz, polygon):
+                nearest, hit = t, True
+    for index, ((ax, az), (bx, bz)) in enumerate(zip(polygon, polygon[1:] + polygon[:1], strict=False)):
+        if index == missing_wall:
+            continue
+        sx, sz = bx - ax, bz - az
+        det = dx * sz - dz * sx
+        if abs(det) < 1e-8:
+            continue
+        t = ((ax - ex) * sz - (az - ez) * sx) / det
+        u = ((ax - ex) * dz - (az - ez) * dx) / det
+        if .3 < t < nearest and 0 <= u <= 1 and 0 <= ey + t * dy <= ceiling:
+            nearest, hit = t, True
+    for (cx, bottom, cz), (width, height, depth) in furniture:
+        near, far = -1e20, 1e20
+        for pos, ray, lo, hi in zip(eye, direction,
+                                    (cx - width / 2, bottom, cz - depth / 2),
+                                    (cx + width / 2, bottom + height, cz + depth / 2), strict=False):
+            if abs(ray) < 1e-8:
+                if not lo <= pos <= hi:
+                    far = -1e20
+                    break
+            else:
+                a, b = (lo - pos) / ray, (hi - pos) / ray
+                near, far = max(near, min(a, b)), min(far, max(a, b))
+        if .3 < near < nearest and near <= far:
+            nearest, hit = near, True
+    return nearest if hit else None
+
+
+def render(path: Path, *, shape="box", frames=30, width=None, height=None, noise=.004,
+           holes=.025, smear=.012, floor_bias=.008, no_ceiling=False, seed=7,
+           yaw=0.0, offset=(0.0, 0.0, 0.0), missing_wall=-1, objects=True, profile="roomview",
+           invalid_start=None, smoothing=3, extra=()):
+    """Each frame has its own moving pose; no ground-truth room data is put in the dump."""
+    rng = random.Random(seed)
+    roomview = profile == "roomview"
+    width = width or (ROOMVIEW_WIDTH if roomview else 56)
+    height = height or (ROOMVIEW_HEIGHT if roomview else 40)
+    invalid_start = (2 if roomview else 0) if invalid_start is None else invalid_start
+    polygon = BOX_OUTLINE if shape == "box" else L_OUTLINE
+    ceiling = 2.6
+    furniture = ([TABLE, COUCH] if objects and shape == "box" else []) + list(extra)
+    rotation = (0, math.sin(yaw / 2), 0, math.cos(yaw / 2))
+    rays = list(fan(width, height, roomview))
+    with path.open("wb") as out:
+        out.write(struct.pack("<4sI", b"FPRS", 1))
+        for frame in range(frames):
+            heading = 2 * math.pi * frame / max(frames, 1)
+            pitch = -.85 if no_ceiling else (-.60, 0, .70)[frame % 3]
+            if roomview and no_ceiling:
+                pitch = -1.2
+            # The L's two arms need viewpoints on both sides of the re-entrant corner.
+            centre = (-.65, -.65) if shape == "l" else (0, 0)
+            eye = (centre[0] + .35 * math.cos(heading), 1.6 + .04 * math.sin(heading * 2),
+                   centre[1] + .35 * math.sin(heading))
+            if roomview:
+                eye = eye[0], 1.3 + .4 * math.sin(heading), eye[2]
+            sy, cy = math.sin(heading / 2), math.cos(heading / 2)
+            sp, cp = math.sin(pitch / 2), math.cos(pitch / 2)
+            q = (cy * sp, sy * cp, -sy * sp, cy * cp)
+            if roomview:
+                q = q[3], q[2], -q[1], -q[0]  # head rotation composed with camera's 180 degree X rotation
+            depths = [cast(eye, rotate(ray, q), polygon, ceiling, furniture, missing_wall) for ray in rays]
+            if roomview:
+                # Smooth both valid depth and inpainted far pixels. Low-frequency noise survives the filter,
+                # while isolated high-frequency speckle is small, as in a stereo patch fit.
+                coarse_width = (width + 11) // 12
+                coarse = [rng.gauss(0, .012) for _ in range(coarse_width * ((height + 11) // 12))]
+                depths = [(depth if depth is not None else 8 + rng.random() * 2)
+                          + coarse[(i // width // 12) * coarse_width + (i % width // 12)]
+                          for i, depth in enumerate(depths)]
+                depths = smooth_depths(depths, width, height, smoothing)
+            vertices, valid = [], []
+            for index, (ray, depth) in enumerate(zip(rays, depths, strict=False)):
+                keep = depth is not None and rng.random() >= holes
+                valid.append(keep or roomview)
+                if roomview and not keep:
+                    depth = 8 + rng.random() * 2
+                if depth is None:
+                    depth = 0
+                else:
+                    # Stereo edges blend two depths, producing stretched grazing triangles.
+                    other = depths[index + 1] if (index + 1) % width and index + 1 < len(depths) else depth
+                    if other is not None and abs(other - depth) > .3 and rng.random() < smear:
+                        depth = (depth + other) / 2
+                    world_ray = rotate(ray, q)
+                    if eye[1] + depth * world_ray[1] < .15:
+                        depth += floor_bias * rng.random()
+                    depth += rng.gauss(0, noise)
+                vertices.extend(c * depth for c in ray)
+            indices = []
+            for row in range(height - 1):
+                for col in range(width - 1):
+                    a = row * width + col
+                    for triangle in ((a, a + width, a + 1), (a + 1, a + width, a + width + 1)):
+                        if all(valid[i] for i in triangle):
+                            indices.extend(triangle)
+            # Compose the global room transform with each independent mesh -> room pose.
+            pose_eye = tuple(a + b for a, b in zip(rotate(eye, rotation), offset, strict=False))
+            ax, ay, az, aw = rotation
+            bx, by, bz, bw = q
+            pose_q = (aw * bx + ax * bw + ay * bz - az * by,
+                      aw * by - ax * bz + ay * bw + az * bx,
+                      aw * bz + ax * by - ay * bx + az * bw,
+                      aw * bw - ax * bx - ay * by - az * bz)
+            if frame < invalid_start:
+                pose_eye = (float("nan"),) * 3
+            out.write(struct.pack("<d7fII", frame / (3 if roomview else 15),
+                                  *pose_eye, *pose_q, len(rays), len(indices)))
+            out.write(struct.pack(f"<{len(vertices)}f", *vertices))
+            out.write(struct.pack(f"<{len(indices)}I", *indices))
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("out", type=Path)
+    ap.add_argument("--shape", choices=("box", "l"), default="box")
+    ap.add_argument("--frames", type=int, default=30)
+    ap.add_argument("--profile", choices=("roomview", "legacy"), default="roomview")
+    ap.add_argument("--width", type=int)
+    ap.add_argument("--height", type=int)
+    ap.add_argument("--invalid-start", type=int, help="untracked initial frames (RoomView default: 2)")
+    ap.add_argument("--smoothing", type=int, default=3, help="RoomView depth filter radius in pixels")
+    ap.add_argument("--noise", type=float, default=.004)
+    ap.add_argument("--holes", type=float, default=.025)
+    ap.add_argument("--smear", type=float, default=.012)
+    ap.add_argument("--floor-bias", type=float, default=.008)
+    ap.add_argument("--no-ceiling", action="store_true")
+    ap.add_argument("--no-objects", action="store_true")
+    ap.add_argument("--missing-wall", type=int, default=-1)
+    ap.add_argument("--yaw", type=float, default=0, help="global room yaw in degrees")
+    ap.add_argument("--seed", type=int, default=7)
+    args = ap.parse_args()
+    if args.frames < 1 or (args.width is not None and args.width < 3) or (args.height is not None and args.height < 3):
+        ap.error("positive frame count and a grid of at least 3 x 3 required")
+    render(args.out, shape=args.shape, frames=args.frames, width=args.width, height=args.height,
+           noise=args.noise, holes=args.holes, smear=args.smear, floor_bias=args.floor_bias,
+           no_ceiling=args.no_ceiling, seed=args.seed, yaw=math.radians(args.yaw),
+           missing_wall=args.missing_wall, objects=not args.no_objects, profile=args.profile,
+           invalid_start=args.invalid_start, smoothing=args.smoothing)
+
+
+if __name__ == "__main__":
+    main()
@@ -8,6 +8,7 @@ Quest builds are "installed" (the 8 largest).
 from __future__ import annotations

 import json
+import math
 import os
 import random
 import threading
@@ -18,6 +19,7 @@ from frameport.core.paths import user_data_dir
 from frameport.ui.app import FramePortApp

 FRAME_STATE = "showcase-frame.json"
+ROOM_DIR = None  # a folder with room.txt (+ its mesh) to serve as the pretend Frame's room instead of the made-up one
 SHOTS_AT = time.mktime((2026, 10, 4, 21, 40, 0, 0, 0, -1))  # the newest sample screenshot (local time)


@@ -29,6 +31,270 @@ def frame_state() -> dict:
        return {}


+def fake_room_mesh(room, cell: float = 0.2, seed: int = 7):
+    """A made-up scan of `room`: its floor, walls and furniture as noisy triangle grids, wound like a real scan's
+    (counter-clockwise seen from inside the room). Like a real scan it has holes where the headset sees nothing:
+    the floor under furniture that stands on it, and window glass."""
+    from frameport.mr.room import Mesh, plane_corners
+    from frameport.mr.view3d import box_corners
+
+    rnd = random.Random(seed)
+    verts, idx = [], []
+
+    def surface(o, u, v, noise=0.012, keep=None):  # o + s*u + t*v, normal = u x v; keep(point) False = a hole
+        lu = max(1, round((sum(c * c for c in u) ** 0.5) / cell))
+        lv = max(1, round((sum(c * c for c in v) ** 0.5) / cell))
+        base = len(verts)
+        for i in range(lv + 1):
+            for j in range(lu + 1):
+                n = noise if 0 < i < lv and 0 < j < lu else 0.0
+                verts.append(tuple(o[k] + u[k] * j / lu + v[k] * i / lv + rnd.uniform(-n, n) for k in range(3)))
+        for i in range(lv):
+            for j in range(lu):
+                mid = tuple(o[k] + u[k] * (j + 0.5) / lu + v[k] * (i + 0.5) / lv for k in range(3))
+                if keep is not None and not keep(mid):
+                    continue
+                a = base + i * (lu + 1) + j
+                b, c, d = a + 1, a + lu + 1, a + lu + 2
+                idx.extend((a, b, d, a, d, c))
+
+    def inside(vol, x, z):  # (x, z) on the box's footprint
+        a = math.radians(vol.yaw_deg)
+        dx, dz = x - vol.cx, z - vol.cz
+        lx, lz = math.cos(a) * dx - math.sin(a) * dz, math.sin(a) * dx + math.cos(a) * dz
+        return abs(lx) < vol.w / 2 and abs(lz) < vol.d / 2
+
+    y0 = room.floor
+    standing = [v for v in room.volumes if v.top_y - v.h - y0 < 0.05 and v.h > 0.3]  # on the floor, no gap below
+    windows = [plane_corners(p) for p in room.planes if p.label == "WINDOW_FRAME"]
+
+    def floor_seen(p):
+        return not any(inside(v, p[0], p[2]) for v in standing)
+
+    def wall_seen(p):  # not through a window's glass
+        for c in windows:
+            xs, ys, zs = [q[0] for q in c], [q[1] for q in c], [q[2] for q in c]
+            if (min(ys) + 0.05 < p[1] < max(ys) - 0.05 and min(xs) - 0.05 <= p[0] <= max(xs) + 0.05
+                    and min(zs) - 0.05 <= p[2] <= max(zs) + 0.05):
+                return False
+        return True
+
+    xs, zs = [x for x, _ in room.outline], [z for _, z in room.outline]
+    surface((min(xs), y0, max(zs)), (max(xs) - min(xs), 0, 0), (0, 0, min(zs) - max(zs)), 0.008,
+            floor_seen)  # floor, facing up
+    for w in room.walls:
+        if w.label == "INVISIBLE_WALL_FACE":
+            continue
+        surface((w.x0, w.y0, w.z0), (w.x1 - w.x0, 0, w.z1 - w.z0), (0, w.y1 - w.y0, 0), 0.012,
+                wall_seen)  # facing into the room
+    for vol in room.volumes:
+        c = box_corners(vol.cx, vol.cz, vol.yaw_deg, vol.w, vol.d)
+        top, bottom = vol.top_y, vol.top_y - vol.h
+        soft = 0.03 if vol.label in ("BED", "COUCH") else 0.015  # (a duvet isn't flat)
+        surface((c[0][0], top, c[0][1]), (c[3][0] - c[0][0], 0, c[3][1] - c[0][1]),
+                (c[1][0] - c[0][0], 0, c[1][1] - c[0][1]), soft)  # top, facing up
+        for i in range(4):
+            a, b = c[i], c[(i + 1) % 4]
+            surface((a[0], bottom, a[1]), (0, top - bottom, 0), (b[0] - a[0], 0, b[1] - a[1]), 0.012)  # facing out
+    return Mesh(vertices=verts, indices=idx)
+
+
+def fake_room():
+    """The pretend Frame's scanned room, made up from scratch (no real scan): a 3.6 x 3.2 m bedroom with a bed and a
+    nightstand under a wall-mounted TV, a closet, a desk with two monitors under the window, a door, a lamp and a
+    plant. Walls: 0 = the bed's (-Z, forward), 1 = right (+X), 2 = behind (+Z), 3 = the desk's and the door's (-X);
+    the 3D view looks at walls 0 and 3."""
+    from frameport.mr.room import Volume, box_room, plane_on_wall
+
+    room = box_room(3.6, 3.2, 2.5)
+    room.source, room.universe, room.time = "scan", 7, int(SHOTS_AT)
+    room.walls = [type(w)(f"{0xa0 + i:032x}", w.x0, w.z0, w.x1, w.z1, w.y0, w.y1, w.label)
+                  for i, w in enumerate(room.walls)]  # (fixed ids: the same room in every render)
+    room.uuid, room.floor_uuid, room.ceiling_uuid = (f"{0xf0 + i:032x}" for i in range(3))
+    vid = iter(f"{i:032x}" for i in range(1, 99))
+    room.volumes = [Volume(next(vid), "BED", 0.6, -0.58, 0.55, 0, 1.45, 2.05, 0.55),
+                    Volume(next(vid), "SCREEN", 0.6, -1.55, 1.78, 0, 1.12, 0.07, 0.66),      # TV above the bed
+                    Volume(next(vid), "TABLE", -1.44, -0.25, 0.75, 90, 1.4, 0.7, 0.75),      # desk
+                    Volume(next(vid), "SCREEN", -1.6, -0.56, 1.2, 82, 0.6, 0.06, 0.36),      # monitors on it
+                    Volume(next(vid), "SCREEN", -1.6, 0.06, 1.2, 98, 0.6, 0.06, 0.36),
+                    Volume(next(vid), "STORAGE", -1.25, -1.3, 2.1, 0, 1.0, 0.6, 2.1),        # closet
+                    Volume(next(vid), "TABLE", -0.42, -1.38, 0.52, 0, 0.45, 0.4, 0.52),      # nightstand
+                    Volume(next(vid), "LAMP", -0.42, -1.42, 0.9, 0, 0.2, 0.2, 0.38),
+                    Volume(next(vid), "PLANT", 1.56, -1.37, 0.95, 0, 0.36, 0.36, 0.95)]      # in the corner
+    room.planes = [plane_on_wall(room, 3, 0.17, 0.0, 0.85, 2.05, "DOOR_FRAME", f"{0xd0:032x}"),
+                   plane_on_wall(room, 3, 0.58, 1.22, 1.05, 1.05, "WINDOW_FRAME", f"{0xd1:032x}")]
+    return room
+
+
+class FakeRoom:
+    """The pretend Frame's room storage + scanner (agent room_* commands), files under its fake home like the real
+    agent's (rooms.export reads the mesh over the fake SFTP). A scan steps forward on every status poll and then
+    waits, so a screenshot finds it mid-scan; room_capture_stop cancels it."""
+
+    def __init__(self, home: str):
+        from frameport.mr.room import dumps, write_mesh
+
+        self.home = home
+        self.scan: dict = {"state": "none"}
+        self.polls = 0
+        self.mesh_triangles = 0
+        if ROOM_DIR:
+            from pathlib import Path
+
+            from frameport.mr.room import parse
+            src = Path(ROOM_DIR)
+            self.room = parse((src / "room.txt").read_text())
+            self.mesh = (src / self.room.mesh.filename).read_bytes() if self.room.mesh else None
+            if self.room.mesh:
+                self.mesh_triangles = self.room.mesh.index_count // 3
+        else:
+            from frameport.mr.room import Mesh
+
+            self.room = fake_room()
+            m = fake_room_mesh(self.room)
+            self.room.mesh = Mesh(uuid=f"{0xe0:032x}", filename="room-mesh.bin", vertex_count=len(m.vertices),
+                                  index_count=len(m.indices))
+            self.mesh = write_mesh(m)
+            self.mesh_triangles = len(m.indices) // 3
+        self.text = dumps(self.room)
+        self.refine: dict = {}  # the saved clean-up settings (non-defaults)
+        self.edited = False
+        self.last_report = self.report()
+        self._write()
+
+    def _folder(self):
+        return os.path.join(self.home, ".local/share/frameport/rooms", str(self.room.universe))
+
+    def _write(self) -> None:
+        os.makedirs(self._folder(), exist_ok=True)
+        with open(os.path.join(self._folder(), "room.txt"), "w") as f:
+            f.write(self.text)
+        if self.mesh is not None and self.room.mesh:
+            with open(os.path.join(self._folder(), self.room.mesh.filename), "wb") as f:
+                f.write(self.mesh)
+
+    # the scan clean-up (scan.json, docs/mr/ROOM_FORMAT.md): what the label rules decided for each of the scanner's
+    # boxes (in its order; to = None: removed), and the door / closet suggestions (never applied by the scanner)
+    LABELS = [
+        {"from": "BED", "to": "BED", "reason": "flat top at 0.55 m, 2.05 x 1.45 m against a wall: a bed",
+         "box": {"w": 1.45, "d": 2.05, "h": 0.55}},
+        {"from": "TABLE", "to": "SCREEN", "reason": "7 cm thin, flat on the wall, 1.1 m above the floor: a screen",
+         "box": {"w": 1.12, "d": 0.07, "h": 0.66}},
+        {"from": "TABLE", "to": "TABLE", "reason": "top at 0.75 m by a wall: a desk",
+         "box": {"w": 1.4, "d": 0.7, "h": 0.75}},
+        {"from": "OTHER", "to": "SCREEN", "reason": "6 cm thin and upright, standing on a table: a screen",
+         "box": {"w": 0.6, "d": 0.06, "h": 0.36}},
+        {"from": "SCREEN", "to": "SCREEN", "reason": "upright on a table, facing the room: a screen",
+         "box": {"w": 0.6, "d": 0.06, "h": 0.36}},
+        {"from": "STORAGE", "to": "STORAGE", "reason": "2.1 m high and 0.6 m deep in a corner: storage",
+         "box": {"w": 1.0, "d": 0.6, "h": 2.1}},
+        {"from": "STORAGE", "to": "TABLE", "reason": "top at 0.52 m, 0.45 m wide by the bed: a nightstand",
+         "box": {"w": 0.45, "d": 0.4, "h": 0.52}},
+        {"from": "LAMP", "to": "LAMP", "reason": "0.38 m high, standing on a table: a lamp",
+         "box": {"w": 0.2, "d": 0.2, "h": 0.38}},
+        {"from": "PLANT", "to": "PLANT", "reason": "0.95 m high and round from above: a plant",
+         "box": {"w": 0.36, "d": 0.36, "h": 0.95}},
+        {"from": "OTHER", "to": None, "reason": "0.5 m behind the wall: outside the room",
+         "box": {"w": 0.6, "d": 0.4, "h": 0.8}},
+        {"from": "TABLE", "to": None, "reason": "only 3 cm above the floor: a rug, not furniture",
+         "box": {"w": 1.6, "d": 1.1, "h": 0.03}},
+        {"from": "STORAGE", "to": None, "suggest": "door", "reason": "2.0 m high, 10 cm thin, flat on the wall",
+         "box": {"w": 0.8, "d": 0.1, "h": 2.0}}]
+    SUGGESTIONS = [{"kind": "door", "box": {"cx": 1.75, "cz": 1.0, "top_y": 2.0, "yaw_deg": 90, "w": 0.8, "d": 0.1,
+                                            "h": 2.0}, "wall": 1, "along": 0.81,
+                    "reason": "A tall, thin slab on the wall, 0.8 m wide: a door, or a closet's front"}]
+
+    def report(self, settings: dict | None = None) -> dict:
+        """scan.json's report (its keys: docs/mr/ROOM_FORMAT.md), consistent with the room's own mesh: `kept` is
+        the mesh's triangle count with the recommended settings, other settings remove more or less."""
+        s = {**{"walked": 0.4, "smooth": 8, "island": 0.2, "walls": "panels"}, **(settings or {})}
+
+        def removed(s):
+            return {"walked": int(1900 * s["walked"]), "small_pieces": int(3600 * s["island"]),
+                    "near_walls": 140 if s["walls"] == "panels" else 40}
+
+        now, default = removed(s), removed({"walked": 0.4, "island": 0.2, "walls": "panels"})
+        fixed = {"outside": 1260, "thin_pieces": 184, "erased": 0}
+        kept = self.mesh_triangles - (sum(now.values()) - sum(default.values()))
+        return {"triangles": self.mesh_triangles + sum(default.values()) + sum(fixed.values()), "kept": kept,
+                "structural": int(self.mesh_triangles * 0.62) if s["walls"] != "off" else 0, **now, **fixed,
+                "tops": 410, "panel_triangles": 64 if s["walls"] == "panels" else 0, "truncated": 0,
+                "walked_skipped": False, "floor_y": 0.0, "ceiling_y": 2.5,
+                "boxes": sum(1 for lb in self.LABELS if lb["to"]),
+                "relabelled": sum(1 for lb in self.LABELS if lb["to"] and lb["to"] != lb["from"]),
+                "removed_boxes": sum(1 for lb in self.LABELS if not lb["to"]),
+                "suggestions": len(self.SUGGESTIONS), "plane_shifts": [{"kind": "wall", "wall": 3, "shift": 0.02}]}
+
+    def status(self) -> dict:
+        from frameport.mr.room import summary
+
+        if self.text is None:
+            return {"rooms": [], "universe": self.room.universe, "room": None, "room_text": None, "aligned": False,
+                    "default_circle": False, "scanner_installed": True, "refine": self.refine, "labels": [],
+                    "suggestions": [], "report": None}
+        scanned = self.room.source == "scan"
+        return {"rooms": [], "universe": self.room.universe, "aligned": True, "default_circle": False,
+                "scanner_installed": True, "room_text": self.text,
+                "room": {"universe": self.room.universe, "source": self.room.source, "summary": summary(self.room)},
+                "refine": dict(self.refine), "report": self.last_report if scanned else None,
+                "labels": self.LABELS if scanned else [], "suggestions": self.SUGGESTIONS if scanned else [],
+                "raw": scanned, "edited": self.edited}
+
+    def agent(self, command, **args):
+        if command == "room_status":
+            return self.status()
+        if command == "room_delete":
+            self.text = None
+            return {"deleted": True}
+        if command == "room_from_boundary":
+            from frameport.mr.room import box_room, dumps
+            room = box_room(5, 4, 2.5)
+            room.source, room.universe = "boundary", self.room.universe
+            self.room, self.mesh, self.text = room, None, dumps(room)
+            self._write()
+            return {"room": {"source": "boundary"}}
+        if command == "room_capture":
+            self.scan, self.polls = {"state": "waiting", "started": time.time()}, 0
+            return {"started": True}
+        if command == "room_capture_status":
+            self.polls += 1
+            if self.scan.get("state") in ("waiting", "recording"):
+                steps = [{"state": "waiting"}, {"state": "recording", "directions": 3, "looked_up": 0},
+                         {"state": "recording", "directions": 7, "looked_up": 6, "looked_down": 2}]
+                self.scan.update(steps[min(self.polls - 1, len(steps) - 1)])
+            return dict(self.scan)
+        if command == "room_refine":  # a clean-up takes a moment; the room's mesh stays the made-up one
+            from frameport.mr.room import dumps
+
+            time.sleep(5)
+            if args.get("settings") is not None:
+                self.refine = dict(args["settings"])
+            if not args.get("keep_edits", True):
+                self.edited = False
+            self.last_report = self.report(self.refine)
+            self.room.time += 1
+            self.text = dumps(self.room)
+            self._write()
+            return {"summary": {"refine": self.last_report}, **self.status()}
+        if command == "room_put":  # the box editor's Save
+            from pathlib import Path
+
+            from frameport.mr.room import dumps, parse
+            path = Path(args["path"])
+            self.room = parse(path.read_text())
+            if self.room.mesh:
+                self.mesh = (path.parent / self.room.mesh.filename).read_bytes()
+            self.text = dumps(self.room)
+            self.edited = bool(args.get("edited"))
+            self._write()
+            return {"room": {"universe": self.room.universe}}
+        if command == "room_capture_stop":
+            if self.scan.get("state") in ("waiting", "recording", "building"):
+                self.scan.update(state="failed", error="cancelled", cancelled=True)
+            return {"stopped": [], "state": self.scan.get("state")}
+        raise RuntimeError(f"fake Frame: {command} not available")
+
+
 class FakeFS:
    """--fake-frame's file system for the Files tab: a temp folder with sample files, served like SFTP."""

@@ -54,6 +320,30 @@ class FakeFS:
                t = SHOTS_AT - 86400 * (2 + (i + j) % 5) - 3600 * ((i * 7 + j * 3) % 11)
                os.utime(os.path.join(root, name), (t, t))
        self.shots = self._screenshots()
+        self.room = FakeRoom(self.home)
+
+    def run(self, cmd: str):
+        """Only the room uploads' folder (rooms._upload_dir: mkdir -p / rm -rf below the room store)."""
+        import shlex
+        import shutil
+
+        rooms_dir = os.path.join(self.home, ".local/share/frameport/rooms")
+        words = shlex.split(cmd)
+        path = words[-1] if words else ""
+        if words[:2] == ["mkdir", "-p"] and path.startswith(rooms_dir):
+            os.makedirs(path, exist_ok=True)
+            return 0, "", ""
+        if words[:3] == ["rm", "-rf", "--"] and path.startswith(rooms_dir + "/.incoming-"):
+            shutil.rmtree(path, ignore_errors=True)
+            return 0, "", ""
+        raise AttributeError(f"fake Frame: no shell for {cmd!r}")
+
+    def put(self, local, remote, **kwargs):
+        import shutil
+
+        if not str(remote).startswith(os.path.join(self.home, ".local/share/frameport/rooms/.incoming-")):
+            raise AttributeError("fake Frame: uploads only for rooms")
+        shutil.copyfile(local, remote)

    def _screenshots(self) -> list[dict]:
        """Sample Steam screenshots for the Screenshots tab, two days, a few games + SteamVR. They are the games' own
@@ -135,6 +425,8 @@ class FakeFS:
            return {"shots": shots, "total": len(shots), "games": list(games.values())}
        if command == "take_screenshot":  # the Screenshots tab's button: a new shot of the running game
            return self.take_screenshot()
+        if command.startswith("room_"):
+            return self.room.agent(command, **args)
        if command == "saves_info":  # Restore saves…: what the Frame has now, and the copy from the last restore
            return {"package": args.get("package"), "files": 14, "bytes": 2_310_000, "skipped": [],
                    "running": False, "version": "1.0", "rollback": {"size": 812_000, "time": time.time() - 86400}}
@@ -160,6 +452,9 @@ class FakeFS:
                import shutil

                shutil.copyfile(remote, local)
+
+            def open(self, path, mode="r"):  # (rooms.export reads the room mesh)
+                return open(path, mode)  # noqa: SIM115
        return SFTP()


@@ -438,6 +733,104 @@ def open_monitor_details(app: FramePortApp) -> None:
        app.monitor_view.toggle_details()


+def open_room(app: FramePortApp) -> None:
+    """The Room tab, once its room has loaded and the canvas has drawn it."""
+    app.go("room")
+    for _ in range(40):
+        st = getattr(app, "_room_state", None) or {}
+        if st.get("model") is not None or st.get("model_error"):
+            break
+        time.sleep(0.25)
+    time.sleep(1.5)
+
+
+def start_fake_scan(app: FramePortApp) -> None:
+    """Scan room in the headset on the pretend Frame: it reaches 7 of 12 directions and waits there."""
+    from frameport.ui import room_state
+
+    app.go("room")
+    if app.room_view is not None and app.room_view.root is not None:  # (back to the top after the editing cards)
+        app.page.run_task(app.room_view.root.scroll_to, offset=0, duration=0)
+    room_state.operate(app, "capture")
+    time.sleep(5)  # rooms.scan polls every 2 s
+
+
+def cancel_fake_scan(app: FramePortApp) -> None:
+    from frameport.ui import room_state
+
+    room_state.operate(app, "cancel")
+    time.sleep(3)
+
+
+def show_room_editing(app: FramePortApp, which: str) -> None:
+    """The Room tab's editing cards (scrolled into view): cleanup (Clean-up with the key settings), more (+ More
+    settings), box (a box selected in the editor), doors (a door added on a wall), suggestion (the Labels card's door
+    suggestion taken), applied (other settings applied: the job runs, then the new counts)."""
+    view = app.room_view
+    if view is None or view.root is None:
+        open_room(app)
+        view = app.room_view
+    if which == "cleanup":
+        if view.cleanup.more.visible:
+            view.cleanup.toggle_more()
+    elif which == "more":
+        if not view.cleanup.more.visible:
+            view.cleanup.toggle_more()
+    elif which == "box":
+        if view.cleanup.more.visible:
+            view.cleanup.toggle_more()
+        view.editor.select(("box", 1))
+    elif which == "doors":
+        view.editor._add_plane("DOOR_FRAME")
+        view.editor._plane_value("along", 0.3)
+    elif which == "suggestion":
+        view.editor.accept(app.target.frame.room.SUGGESTIONS[0], "door")
+    elif which == "applied":
+        view.editor.discard()
+        view.cleanup.set("walls", "snap")
+        view.cleanup._slid("smooth", 4)
+        view.cleanup.apply()
+        time.sleep(0.6)
+        app.page.run_task(view.show_editing)
+        time.sleep(0.6)
+        return  # (the running clean-up: the next step shows its result)
+    elif which == "result":
+        time.sleep(6)
+    app.page.run_task(view.show_editing)
+    time.sleep(1.5)
+
+
+def show_room_state(app: FramePortApp, which: str) -> None:
+    """none: the Room tab without a saved room; disconnected: its not-connected page; frame: the Frame page's room card
+    (scrolled into view) with the room back."""
+    from frameport.ui import room_state
+
+    fs = app.target.frame if app.target else None
+    if which == "none":
+        fs.room.saved_text = fs.room.text
+        fs.room.text = None
+        room_state.state(app, force=True)
+        app.go("room")
+        time.sleep(2)
+    elif which == "disconnected":
+        app.frame_state = "none"
+        app.go("room")
+    elif which == "frame":
+        app.frame_state = "connected"
+        fs.room.text = getattr(fs.room, "saved_text", None) or fs.room.text
+        room_state.state(app, force=True)
+        app.go("frame")
+        time.sleep(2)
+        view = app.switcher.content.content
+        try:
+            app.page.run_task(view.scroll_to, offset=T_SCROLL_TO_ROOM, duration=0)
+        except Exception:  # noqa: BLE001 - only for the picture
+            pass
+
+
+T_SCROLL_TO_ROOM = 520  # the Frame page's room card, below the device card and the readiness checklist
+
+
 LINUX_APPIMAGE = "linux.venera"  # --linux's packages
 LINUX_FOLDER = "linux.matineevr"

@@ -471,7 +864,9 @@ def install_fakes(game: str | None, monitor_session=None) -> None:
    """--fake-frame: never reach a real Frame (start-up auto-connect, discovery, the 30 s poll); Type on Frame and
    the Monitor stream are fakes. `game` = the Monitor's game card (with its artwork)."""
    from frameport.frame import keyboard, monitor
+    from frameport.install import rooms

+    rooms.ensure_scanner = rooms.ensure_prompts = lambda frame: None  # (the pretend Frame has its own scanner)
    keyboard.KeyboardSession = FakeKeyboardSession
    monitor.MonitorSession = monitor_session or FakeMonitorSession
    FakeMonitorSession.GAME = game
@@ -399,6 +399,17 @@ def _long_upload(session, package: str, seconds: float = 30.0, after: float = 2.
    app.jobs.submit(Job(f"Install {app._title(package)} on Frame", run, package, "install"))


+def _open_room(session) -> None:
+    """The Room tab with the pretend Frame's scanned room loaded and drawn (3D view, cards)."""
+    fakes.open_room(session.app)
+
+
+def _room_editing(session, which: str = "box") -> None:
+    """The Room tab's editing cards scrolled into view (fakes.show_room_editing: cleanup, more, box = a box selected,
+    doors, suggestion = the door suggestion taken)."""
+    fakes.show_room_editing(session.app, which)
+
+
 def _press_keys(session, text: str, gap: float = 0.28) -> None:
    """Keys typed on the Type on Frame tab (the pretend keyboard), one by one."""
    view = session.app.keyboard_view
@@ -414,4 +425,4 @@ HOOKS = {"fake_install": _fake_install, "wait_jobs": _wait_jobs, "held_install":
         "frame_asks": _frame_asks,
         "easter_eggs": _easter_eggs, "fps_dip": _fps_dip, "perfect_pacing": _perfect_pacing,
         "battery": _battery, "long_upload": _long_upload, "press_keys": _press_keys,
-         "monitor_settled": _monitor_settled}
+         "monitor_settled": _monitor_settled, "open_room": _open_room, "room_editing": _room_editing}
@@ -26,12 +26,17 @@ from showcase.fakes import (  # noqa: E402,F401
    LINUX_FOLDER,
    add_fake_linux_apps,
    attach_fake_frame,
+    cancel_fake_scan,
    fake_live_stream,
    fake_save_backups,
    install_fakes,
    open_monitor_details,
+    open_room,
    open_type_tab,
+    show_room_editing,
+    show_room_state,
    start_fake_install,
+    start_fake_scan,
    stop_fake_live,
 )

@@ -138,6 +143,20 @@ def main() -> int:
             ("live", lambda a: a.go("live")), ("live-streaming", fake_live_stream),
             ("keyboard", lambda a: (stop_fake_live(a), a.go("keyboard"))),
             ("monitor", lambda a: a.go("monitor")), ("monitor-details", open_monitor_details),
+             # the Room tab (--fake-frame: a made-up scanned room; a scan steps forward and waits, then is cancelled)
+             ("room", open_room),
+             # its editing cards: the scan clean-up, the box editor, doors and windows, the label rules' suggestions
+             ("room-cleanup", lambda a: show_room_editing(a, "cleanup")),
+             ("room-cleanup-more", lambda a: show_room_editing(a, "more")),
+             ("room-box-selected", lambda a: show_room_editing(a, "box")),
+             ("room-doors", lambda a: show_room_editing(a, "doors")),
+             ("room-suggestion-door", lambda a: show_room_editing(a, "suggestion")),
+             ("room-cleanup-applying", lambda a: show_room_editing(a, "applied")),
+             ("room-cleanup-applied", lambda a: show_room_editing(a, "result")),
+             ("room-scanning", start_fake_scan), ("room-cancelled", cancel_fake_scan),
+             ("room-none", lambda a: show_room_state(a, "none")),
+             ("room-disconnected", lambda a: show_room_state(a, "disconnected")),
+             ("room-frame-card", lambda a: show_room_state(a, "frame")),
             ("tools", lambda a: a.go("settings")),
             # the index on the left: "This PC" scrolls the page there
             ("settings-index", lambda a: a.page.run_task(a.settings_view.show_section, "pc")),
@@ -546,6 +565,7 @@ def main() -> int:
            app = FramePortApp(page)
            if args.fake_frame:
                attach_fake_frame(app)
+
        except Exception:  # noqa: BLE001
            ERRORS.append("startup: " + traceback.format_exc())
            return
@@ -10,7 +10,7 @@ const site = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const repo = resolve(site, '..');

 const SHOTS = ['library.png', 'game.png', 'monitor.png', 'live-view.png', 'files.png', 'type-on-frame.png',
-  'screenshots.png', 'install-progress.png', 'patches.png'];
+  'screenshots.png', 'install-progress.png', 'patches.png', 'room.png'];
 const PUBLIC = {
  'docs/images': ['tour-teaser.webp'],
  'docs/media': ['frameport-tour.mp4', 'frameport-tour.jpg', 'frameport-install.mp4', 'frameport-install.jpg'],
@@ -13,6 +13,7 @@ import keys from '../assets/media/type-on-frame.png';
 import screenshots from '../assets/media/screenshots.png';
 import progress from '../assets/media/install-progress.png';
 import patches from '../assets/media/patches.png';
+import room from '../assets/media/room.png';
 import { url } from '../data/site';

 interface Props { games: MockGame[] }
@@ -21,6 +22,7 @@ const shots = [
  { img: library, title: 'Library', text: 'Your games with their artwork. Search, filter, install several at once.' },
  { img: game, title: 'Game page', text: 'One click to install or play. Patches under Customize.' },
  { img: progress, title: 'Installing', text: 'Each stage, with speed and time left.' },
+  { img: room, title: 'Room (experimental)', text: 'Your scanned room in 3D for mixed-reality games. Clean up the scan, fix the labels.' },
  { img: monitor, title: 'Monitor', text: "Frame rate, load, temperature and battery, live." },
  { img: live, title: 'Live view', text: 'What the headset shows, with sound, in your browser.' },
  { img: screenshots, title: 'Screenshots', text: 'Your headset screenshots, by game and day.' },
@@ -1,14 +1,32 @@
 {
- "updated": "2026-10-17",
+ "updated": "2026-10-19",
 "people": [
  {
   "login": "spoopyghosty0",
   "avatar": "https://avatars.githubusercontent.com/u/336754034?v=4",
   "url": "https://github.com/spoopyghosty0",
-   "commits": 707,
+   "commits": 783,
   "issues": 6,
-   "prs": 4,
-   "total": 745
+   "prs": 5,
+   "total": 826
+  },
+  {
+   "login": "Izimzizi",
+   "avatar": "https://avatars.githubusercontent.com/u/77581918?v=4",
+   "url": "https://github.com/Izimzizi",
+   "commits": 0,
+   "issues": 21,
+   "prs": 0,
+   "total": 63
+  },
+  {
+   "login": "tkp206093",
+   "avatar": "https://avatars.githubusercontent.com/u/29872453?v=4",
+   "url": "https://github.com/tkp206093",
+   "commits": 0,
+   "issues": 21,
+   "prs": 0,
+   "total": 63
  },
  {
   "login": "Klownicle",
@@ -19,15 +37,6 @@
   "prs": 0,
   "total": 60
  },
-  {
-   "login": "tkp206093",
-   "avatar": "https://avatars.githubusercontent.com/u/29872453?v=4",
-   "url": "https://github.com/tkp206093",
-   "commits": 0,
-   "issues": 18,
-   "prs": 0,
-   "total": 54
-  },
  {
   "login": "UnicronNL",
   "avatar": "https://avatars.githubusercontent.com/u/1267745?v=4",
@@ -46,6 +55,24 @@
   "prs": 0,
   "total": 45
  },
+  {
+   "login": "Genosystem",
+   "avatar": "https://avatars.githubusercontent.com/u/40860703?v=4",
+   "url": "https://github.com/Genosystem",
+   "commits": 0,
+   "issues": 13,
+   "prs": 0,
+   "total": 39
+  },
+  {
+   "login": "Lucas-Mathieu",
+   "avatar": "https://avatars.githubusercontent.com/u/184943223?v=4",
+   "url": "https://github.com/Lucas-Mathieu",
+   "commits": 12,
+   "issues": 0,
+   "prs": 5,
+   "total": 37
+  },
  {
   "login": "Sheebalove",
   "avatar": "https://avatars.githubusercontent.com/u/176067652?v=4",
@@ -91,24 +118,6 @@
   "prs": 0,
   "total": 30
  },
-  {
-   "login": "Lucas-Mathieu",
-   "avatar": "https://avatars.githubusercontent.com/u/184943223?v=4",
-   "url": "https://github.com/Lucas-Mathieu",
-   "commits": 9,
-   "issues": 0,
-   "prs": 4,
-   "total": 29
-  },
-  {
-   "login": "Genosystem",
-   "avatar": "https://avatars.githubusercontent.com/u/40860703?v=4",
-   "url": "https://github.com/Genosystem",
-   "commits": 0,
-   "issues": 9,
-   "prs": 0,
-   "total": 27
-  },
  {
   "login": "inseend",
   "avatar": "https://avatars.githubusercontent.com/u/11666993?v=4",
@@ -118,15 +127,6 @@
   "prs": 0,
   "total": 27
  },
-  {
-   "login": "Izimzizi",
-   "avatar": "https://avatars.githubusercontent.com/u/77581918?v=4",
-   "url": "https://github.com/Izimzizi",
-   "commits": 0,
-   "issues": 9,
-   "prs": 0,
-   "total": 27
-  },
  {
   "login": "jim2011",
   "avatar": "https://avatars.githubusercontent.com/u/15848374?v=4",
@@ -136,6 +136,15 @@
   "prs": 0,
   "total": 24
  },
+  {
+   "login": "Jmckenzie84",
+   "avatar": "https://avatars.githubusercontent.com/u/71196491?v=4",
+   "url": "https://github.com/Jmckenzie84",
+   "commits": 0,
+   "issues": 8,
+   "prs": 0,
+   "total": 24
+  },
  {
   "login": "coah80",
   "avatar": "https://avatars.githubusercontent.com/u/100182500?v=4",
@@ -145,23 +154,14 @@
   "prs": 2,
   "total": 20
  },
-  {
-   "login": "Jmckenzie84",
-   "avatar": "https://avatars.githubusercontent.com/u/71196491?v=4",
-   "url": "https://github.com/Jmckenzie84",
-   "commits": 0,
-   "issues": 6,
-   "prs": 0,
-   "total": 18
-  },
  {
   "login": "broli95",
   "avatar": "https://avatars.githubusercontent.com/u/22918304?v=4",
   "url": "https://github.com/broli95",
   "commits": 0,
-   "issues": 5,
+   "issues": 6,
   "prs": 0,
-   "total": 15
+   "total": 18
  },
  {
   "login": "buildmine10",
@@ -199,6 +199,15 @@
   "prs": 0,
   "total": 15
  },
+  {
+   "login": "jeliastam",
+   "avatar": "https://avatars.githubusercontent.com/u/2113009?v=4",
+   "url": "https://github.com/jeliastam",
+   "commits": 0,
+   "issues": 5,
+   "prs": 0,
+   "total": 15
+  },
  {
   "login": "Scoota23",
   "avatar": "https://avatars.githubusercontent.com/u/27732436?v=4",
@@ -226,15 +235,6 @@
   "prs": 0,
   "total": 15
  },
-  {
-   "login": "jeliastam",
-   "avatar": "https://avatars.githubusercontent.com/u/2113009?v=4",
-   "url": "https://github.com/jeliastam",
-   "commits": 0,
-   "issues": 4,
-   "prs": 0,
-   "total": 12
-  },
  {
   "login": "Loafmeister",
   "avatar": "https://avatars.githubusercontent.com/u/60628625?v=4",
@@ -253,6 +253,15 @@
   "prs": 1,
   "total": 12
  },
+  {
+   "login": "Natouille04",
+   "avatar": "https://avatars.githubusercontent.com/u/60348431?v=4",
+   "url": "https://github.com/Natouille04",
+   "commits": 0,
+   "issues": 4,
+   "prs": 0,
+   "total": 12
+  },
  {
   "login": "nickwilde77555",
   "avatar": "https://avatars.githubusercontent.com/u/180547421?v=4",
@@ -352,6 +361,15 @@
   "prs": 0,
   "total": 9
  },
+  {
+   "login": "wanwanwanwano",
+   "avatar": "https://avatars.githubusercontent.com/u/341975109?v=4",
+   "url": "https://github.com/wanwanwanwano",
+   "commits": 0,
+   "issues": 3,
+   "prs": 0,
+   "total": 9
+  },
  {
   "login": "Akimya49",
   "avatar": "https://avatars.githubusercontent.com/u/46827872?v=4",
@@ -361,6 +379,33 @@
   "prs": 0,
   "total": 6
  },
+  {
+   "login": "crointer",
+   "avatar": "https://avatars.githubusercontent.com/u/165038970?v=4",
+   "url": "https://github.com/crointer",
+   "commits": 0,
+   "issues": 2,
+   "prs": 0,
+   "total": 6
+  },
+  {
+   "login": "DerMueller",
+   "avatar": "https://avatars.githubusercontent.com/u/82468245?v=4",
+   "url": "https://github.com/DerMueller",
+   "commits": 0,
+   "issues": 2,
+   "prs": 0,
+   "total": 6
+  },
+  {
+   "login": "DexgamingX",
+   "avatar": "https://avatars.githubusercontent.com/u/85261590?v=4",
+   "url": "https://github.com/DexgamingX",
+   "commits": 0,
+   "issues": 2,
+   "prs": 0,
+   "total": 6
+  },
  {
   "login": "DJ3thenew23",
   "avatar": "https://avatars.githubusercontent.com/u/3744521?v=4",
@@ -388,6 +433,15 @@
   "prs": 0,
   "total": 6
  },
+  {
+   "login": "Gabiga71",
+   "avatar": "https://avatars.githubusercontent.com/u/20774946?v=4",
+   "url": "https://github.com/Gabiga71",
+   "commits": 0,
+   "issues": 2,
+   "prs": 0,
+   "total": 6
+  },
  {
   "login": "ganona",
   "avatar": "https://avatars.githubusercontent.com/u/112239200?v=4",
@@ -424,6 +478,15 @@
   "prs": 0,
   "total": 6
  },
+  {
+   "login": "mamasboi2000",
+   "avatar": "https://avatars.githubusercontent.com/u/344123932?v=4",
+   "url": "https://github.com/mamasboi2000",
+   "commits": 0,
+   "issues": 2,
+   "prs": 0,
+   "total": 6
+  },
  {
   "login": "marcoszaballos",
   "avatar": "https://avatars.githubusercontent.com/u/44778619?v=4",
@@ -460,15 +523,6 @@
   "prs": 0,
   "total": 6
  },
-  {
-   "login": "Natouille04",
-   "avatar": "https://avatars.githubusercontent.com/u/60348431?v=4",
-   "url": "https://github.com/Natouille04",
-   "commits": 0,
-   "issues": 2,
-   "prs": 0,
-   "total": 6
-  },
  {
   "login": "peetzweg",
   "avatar": "https://avatars.githubusercontent.com/u/839848?v=4",
@@ -496,15 +550,6 @@
   "prs": 0,
   "total": 6
  },
-  {
-   "login": "wanwanwanwano",
-   "avatar": "https://avatars.githubusercontent.com/u/341975109?v=4",
-   "url": "https://github.com/wanwanwanwano",
-   "commits": 0,
-   "issues": 2,
-   "prs": 0,
-   "total": 6
-  },
  {
   "login": "yzfsoldier",
   "avatar": "https://avatars.githubusercontent.com/u/35410319?v=4",
@@ -640,24 +685,6 @@
   "prs": 0,
   "total": 3
  },
-  {
-   "login": "DerMueller",
-   "avatar": "https://avatars.githubusercontent.com/u/82468245?v=4",
-   "url": "https://github.com/DerMueller",
-   "commits": 0,
-   "issues": 1,
-   "prs": 0,
-   "total": 3
-  },
-  {
-   "login": "DexgamingX",
-   "avatar": "https://avatars.githubusercontent.com/u/85261590?v=4",
-   "url": "https://github.com/DexgamingX",
-   "commits": 0,
-   "issues": 1,
-   "prs": 0,
-   "total": 3
-  },
  {
   "login": "DolphinOfficial",
   "avatar": "https://avatars.githubusercontent.com/u/92276540?v=4",
@@ -685,6 +712,15 @@
   "prs": 0,
   "total": 3
  },
+  {
+   "login": "ehnobigdeal0",
+   "avatar": "https://avatars.githubusercontent.com/u/344167176?v=4",
+   "url": "https://github.com/ehnobigdeal0",
+   "commits": 0,
+   "issues": 1,
+   "prs": 0,
+   "total": 3
+  },
  {
   "login": "felis-lynx",
   "avatar": "https://avatars.githubusercontent.com/u/106830854?v=4",
@@ -712,6 +748,15 @@
   "prs": 0,
   "total": 3
  },
+  {
+   "login": "Haseo-sudo",
+   "avatar": "https://avatars.githubusercontent.com/u/344139069?v=4",
+   "url": "https://github.com/Haseo-sudo",
+   "commits": 0,
+   "issues": 1,
+   "prs": 0,
+   "total": 3
+  },
  {
   "login": "hokey1981",
   "avatar": "https://avatars.githubusercontent.com/u/42741984?v=4",
@@ -811,6 +856,24 @@
   "prs": 0,
   "total": 3
  },
+  {
+   "login": "MThomason122",
+   "avatar": "https://avatars.githubusercontent.com/u/25598648?v=4",
+   "url": "https://github.com/MThomason122",
+   "commits": 0,
+   "issues": 1,
+   "prs": 0,
+   "total": 3
+  },
+  {
+   "login": "Nikoroq",
+   "avatar": "https://avatars.githubusercontent.com/u/135438574?v=4",
+   "url": "https://github.com/Nikoroq",
+   "commits": 0,
+   "issues": 1,
+   "prs": 0,
+   "total": 3
+  },
  {
   "login": "njorbie",
   "avatar": "https://avatars.githubusercontent.com/u/340724129?v=4",
@@ -829,6 +892,15 @@
   "prs": 0,
   "total": 3
  },
+  {
+   "login": "persuaded9041",
+   "avatar": "https://avatars.githubusercontent.com/u/464398?v=4",
+   "url": "https://github.com/persuaded9041",
+   "commits": 0,
+   "issues": 1,
+   "prs": 0,
+   "total": 3
+  },
  {
   "login": "pinbear-creator",
   "avatar": "https://avatars.githubusercontent.com/u/194687704?v=4",
@@ -946,6 +1018,15 @@
   "prs": 0,
   "total": 3
  },
+  {
+   "login": "Zomby2D",
+   "avatar": "https://avatars.githubusercontent.com/u/5513720?v=4",
+   "url": "https://github.com/Zomby2D",
+   "commits": 0,
+   "issues": 1,
+   "prs": 0,
+   "total": 3
+  },
  {
   "login": "zoomiti",
   "avatar": "https://avatars.githubusercontent.com/u/34012653?v=4",
@@ -954,6 +1035,15 @@
   "issues": 1,
   "prs": 0,
   "total": 3
+  },
+  {
+   "login": "codex",
+   "avatar": "https://avatars.githubusercontent.com/u/267193182?v=4",
+   "url": "https://github.com/codex",
+   "commits": 2,
+   "issues": 0,
+   "prs": 0,
+   "total": 2
  }
 ]
 }
@@ -276,7 +276,7 @@
 },
 "adapter.scene_emul": {
  "anchor": "adapter-scene_emul",
-  "title": "Pretend room layout",
+  "title": "Use room layout",
  "group": "Game settings"
 },
 "adapter.scene_height": {
@@ -284,6 +284,16 @@
  "title": "Room height",
  "group": "Game settings"
 },
+ "adapter.scene_hide_bounds": {
+  "anchor": "adapter-scene_hide_bounds",
+  "title": "Hide play-area size",
+  "group": "Game settings"
+ },
+ "adapter.scene_scan_request": {
+  "anchor": "adapter-scene_scan_request",
+  "title": "Scan when requested",
+  "group": "Game settings"
+ },
 "adapter.scene_width": {
  "anchor": "adapter-scene_width",
  "title": "Room width",
@@ -539,6 +549,11 @@
  "title": "Start the game in the app's main process",
  "group": "Steam Frame patches"
 },
+ "frame.meta_depth_occlusion": {
+  "anchor": "frame-meta_depth_occlusion",
+  "title": "Unity: disable Meta depth occlusion",
+  "group": "Steam Frame patches"
+ },
 "frame.meta_permissions": {
  "anchor": "frame-meta_permissions",
  "title": "Declare Meta-only permissions",
@@ -659,6 +674,11 @@
  "title": "Unity: keep MSAA off at runtime (OVRManager)",
  "group": "Steam Frame patches"
 },
+ "frame.unity_scene_active_rooms": {
+  "anchor": "frame-unity_scene_active_rooms",
+  "title": "Unity: skip Meta's player-in-room check",
+  "group": "Steam Frame patches"
+ },
 "frame.unity_text_input": {
  "anchor": "frame-unity_text_input",
  "title": "Make Unity text fields work",