webspatial-avp-iwdp

name

webspatial-avp-iwdp

description

Programmatic WebSpatial debugging on the Apple Vision Pro simulator via ios-webkit-debug-proxy and tools/scripts/iwdp-sim.py. Use when automating AVP simulator tests, driving SpatialDiv WKWebViews without Safari clicks, reading DOM/CSS from portal webviews, or debugging any WebSpatial app (not only test-server). Triggers on iwdp, ios-webkit-debug-proxy, visionOS simulator automation, data-name inspector targets, SpatialDiv webview eval, or AVP screenshot gates.

WebSpatial AVP — iwdp automation

Read first

Full guide: tools/scripts/IWDP-SIM.md

Script: python3 tools/scripts/iwdp-sim.py

Core model (must internalize)

• Each enable-xr SpatialDiv = separate WKWebView in Safari Develop / iwdp.
• data-name → inspector title (use unique stable names).
• WebSpatial title = host app webview (often sidebar shell); portal DOM lives in SpatialDiv titles.
• No simctl tap on visionOS; no iwdp console.log — use dom / probe / page-log mirrors.

Standard agent workflow

# 1. Dev server running (adjust origin for other apps)
npm run dev

# 2. Launch app + route + wait for SpatialDiv
python3 tools/scripts/iwdp-sim.py launch --terminate --route <route> \
  --wait-title "<SpatialDiv data-name>"

# 3. Discover targets
python3 tools/scripts/iwdp-sim.py list

# 4. Drive UI in the correct webview (SpatialDiv title, not WebSpatial)
python3 tools/scripts/iwdp-sim.py click "<data-name>" "<css-selector>" --wait-ms 2000

# 5. Read DOM / CSS / probes
python3 tools/scripts/iwdp-sim.py dom "<data-name>" "<selector>" --rect --text
python3 tools/scripts/iwdp-sim.py css "<data-name>" "<selector>"
python3 tools/scripts/iwdp-sim.py probe "<data-name>" webspatialOverlayPush

# 6. Visual check
python3 tools/scripts/iwdp-sim.py screenshot /tmp/avp.png

Multi-step shells: export IWDP_KEEP_ALIVE=1

Other WebSpatial apps

export WEBSPATIAL_BUNDLE_ID=com.your.app
export WEBSPATIAL_DEV_ORIGIN=http://localhost:3000
python3 tools/scripts/iwdp-sim.py launch --route your-hash-route --wait-title "Your Panel"

App code: add data-name on every SpatialDiv you need to automate.

Assertions — prefer these over console

Need	Command
Element exists	dom … "[selector]"
Layout	dom … --rect
Styles	css …
Dev probe	probe … <datasetKey>
Visual	screenshot + image review
Arbitrary	eval …

Do not expect Console.messageAdded over iwdp on WebKit.

When stuck

1. Run list — titles wrong → fix data-name or wait.
2. iwdp won't start → boot simulator; set IWDP_SIM_SOCKET (see IWDP-SIM.md).
3. Click ineffective → --wait-ms 2000; use Pointer-friendly click subcommand.
4. Wrong webview → match title from list, not guessed WebSpatial.

Manual Safari path (human): skill webspatial-visionos-debugging.