ReviewOS

craft-native/craft

macOS: the web view denies requestPointerLock, even from a user gesture

#333
Closed chris opened this 10 days ago ·
10 days ago

Measured with Craft v0.0.107 (published darwin-arm64) on macOS 27.0, M3 Pro, using the Stacks probe harness (`buddy desktop:probe`, stacksjs/stacks#877). The input was genuine OS-level mouse and keyboard events posted to the window, so the page saw `isTrusted` gestures.

  • `Element.requestPointerLock()` from a real click fires `pointerlockerror`.
  • Clicked after leaving element fullscreen, it fails with "requires the window to have focus", although the click itself landed in the window.
  • Element fullscreen from the same kind of click works (enabled in #332).

Pointer lock is what first-person and drag-heavy canvases use (three.js PointerLockControls, any FPS-style camera), so a game or 3D viewer hosted in a Craft window cannot capture the mouse today.

WKWebView has no public preference for this. WebKit routes the request through the UI delegate, and without a handler it refuses. Worth checking which delegate entry point the macOS SDK on the CI runners exposes, and whether it can be adopted without private API (a Store build must not use SPI). If it can't, documenting "pointer lock is unavailable in Craft windows" is the honest outcome, and the Stacks capability matrix already records it that way.

The focus message after leaving fullscreen may be a separate, smaller bug: the window should regain key status for its web view when element fullscreen ends.

10 days ago

Verified against Apple's current public WKUIDelegate surface: there is no pointer-lock permission callback for macOS WebKit, so Craft cannot enable it without private API. Documented the limitation and the required fallback in main at 565abc39: packages/macos/README.md and docs/guides/troubleshooting.md, with a contract test preventing the guidance from drifting. Element fullscreen remains supported; apps should handle pointerlockerror and offer drag/fullscreen input.

10 days ago

Closing as documented/unsupported by the public WebKit API. Craft cannot grant macOS pointer lock without a private API; the supported fallback is element fullscreen plus handling pointerlockerror and offering drag/fullscreen input. The limitation and fallback are documented in packages/macos/README.md and docs/guides/troubleshooting.md, with a contract test preventing drift.

Sign in to comment on this issue.