Add viewport safe-area API for play overlays

[querielo]

Adds a runtime viewport safe-area API so play-mode overlays can avoid Stem Studio chrome instead of relying on raw window bounds.

This change:

• adds a measured safe-area helper based on the active runtime viewport
• exposes the API through the runtime and behavior-facing surfaces
• registers the player watermark as a host overlay occluder
• updates behavior editor typings and runtime docs
• adds focused unit coverage for safe-area measurement

Why

Play-mode UI already has host chrome layered around the viewport, but custom DOM overlays and behavior-driven screen-space UI did not have a stable way to know which part of the screen was actually safe to use.

That led to UI being positioned under Stem Studio elements like the top nav or watermark.

What changed

• Added viewport safe-area measurement utility and tests
• Added runtime accessors for the measured safe area
• Exposed safe area to behaviors via this.erth.viewport.getSafeArea()
• Added a game.getViewportSafeArea() path for compatibility with existing behavior code
• Registered the player watermark as an occluding host overlay
• Documented the new runtime API
• Added a short implementation plan doc

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a viewport “safe area” API to the runtime/behavior interfaces so screen-space UI and DOM overlays can avoid host chrome (e.g., player watermark), and documents how behaviors should consume it.

Changes:

• Introduces viewport safe-area measurement utilities (+ tests) and exposes them via EngineRuntime, GameManager, and this.erth.viewport.getSafeArea().
• Registers the player watermark as a safe-area occluder so the measured safe area excludes it.
• Updates developer docs (runtime API + planning note) to describe the new API and intended usage.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/runtime-api.md	Documents this.erth.viewport and provides a usage example.
docs/planning/2026-06-03-viewport-safe-area.md	Planning/implementation checklist for the safe-area feature.
client/packages/shared/src/player/component/PlayerWatermark.tsx	Registers watermark DOM as an occluder for safe-area measurement.
client/packages/editor-oss/src/utils/viewportSafeArea.ts	Implements safe-area measurement from viewport + occluder rects.
client/packages/editor-oss/src/utils/viewportSafeArea.test.ts	Adds unit tests for safe-area measurement behavior.
client/packages/editor-oss/src/editor/assets/v2/BehaviorEditor/types/behavior.d.ts	Adds typing for viewport.getSafeArea() and getViewportSafeArea().
client/packages/editor-oss/src/behaviors/stem/createStemEngineInterface.ts	Exposes viewport.getSafeArea() on the behavior erth interface.
client/packages/editor-oss/src/behaviors/stem/StemEngineInterface.ts	Adds StemViewport interface/type imports for safe area.
client/packages/editor-oss/src/behaviors/game/GameManager.ts	Adds getViewportSafeArea() passthrough for behaviors/game API.
client/packages/editor-oss/src/EngineRuntime.ts	Stores occluder elements and computes viewport safe area on demand.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.