HydraIssues

Background

Portrait-mode experiences (e.g. mercator-talks) require three layers to all agree on the same resolution simultaneously:

1. Stream encoding — the Moonlight client (or moonlight-web-stream) must request portrait resolution (1080x1920) from Sunshine
2. Display resolution — Sunshine's dd_manual_resolution must be set to portrait
3. App window — the UE experience must be launched with portrait-aware args (-ResX=1080 -ResY=1920 -windowed -ForceRes)

Plus the Virtual Display Driver (VDD) must have portrait resolutions in vdd_settings.xml (hydrabody provisions this at startup).

All three must match simultaneously or the stream renders incorrectly: app in wrong resolution, captured at wrong frame size, or stretched in the browser.

Two paths, same three layers

hydraheadflatscreen path

• Layer 1 (stream encoding): moonlight_*.go directly passes --resolution 1080x1920 to the Moonlight client CLI args
• Layers 2+3 (display + app): hydrabody owns both — reads orientation from its own experience cache (synced from hydraexperiencelibrary), sets dd_manual_resolution, and registers the Sunshine app with portrait launch args
• Result: robust and direct because the flatscreen IS the Moonlight client — layer 1 is always in sync with layers 2+3

hydraheadwebstream (browser) path

• Layer 1 (stream encoding): webstream passes orientation: portrait string to hydraneckwebrtc, which sets videoSizeCustom: {width: 1080, height: 1920} in moonlight-web-stream DefaultSettings
• Layers 2+3 (display + app): hydrabody — same as flatscreen path, independently
• Fragility: if hydraneckwebrtc is on an old version, layer 1 silently breaks while layers 2+3 still work. This happened in production: issue #81 showed the Brussels node on v1.10.81 silently stripped the orientation field, producing a portrait body streaming into a landscape WebRTC frame.

The problem

There is no cross-layer verification. Failures are silent:

• hydraneckwebrtc on old version: layer 1 wrong, layers 2+3 correct — portrait body but landscape WebRTC frame
• hydrabody with stale catalog: layers 2+3 wrong, layer 1 correct — correct stream resolution but app renders at wrong resolution
• Brussels controller not in hydracluster (issue #81): silently different behaviour per district as versions drift

Proposed implementation

1. hydrabody — expose resolved orientation in the register/launch response

When hydraneckwebrtc calls hydrabody to register or launch an experience, hydrabody should include the orientation it actually applied in the response body. This gives hydraneckwebrtc the ability to verify its own layer 1 matches what hydrabody applied to layers 2+3.

2. hydraneckwebrtc — cross-layer orientation verification

In worker.go handleCreateSession, after calling RegisterSunshineApp (or receiving the hydrabody response), compare req.Orientation with the orientation hydrabody reports it applied. Log the result clearly:

[session abc] orientation: requested=portrait body_applied=portrait OK
[session abc] orientation: requested=portrait body_applied=landscape MISMATCH — check hydrabody catalog sync

Non-fatal: stream proceeds regardless. The log line makes silent mismatches visible.

3. hydraneckwebrtc — include orientation in session status response

Surface the orientation that was applied in GET /session/{id}/status so upstream callers (hydraheadwebstream) can read it back and use it to inform the browser user.

4. hydraheadwebstream — portrait hint in experience selection UI

The /api/v1/experiences response already includes orientation on every experience object. The experience dropdown in internal/web/templates/stream.html ignores it today. Add:

• A portrait badge (e.g. a small vertical icon or label) next to portrait experiences in the dropdown
• After a portrait experience is selected, show a contextual note below the dropdown: "Portrait experience — for the best view, hold your phone or tablet vertically."

Frontend-only change, no server-side changes needed.

5. hydraheadflatscreen — CLAUDE.md note

No code changes needed. Document in CLAUDE.md that hydraheadflatscreen controls layer 1 directly, and that any future path through hydraneckwebrtc must explicitly pass the orientation string — the same way hydraheadwebstream does.

Acceptance criteria

• hydrabody register/launch API response includes orientation as actually applied
• hydraneckwebrtc logs orientation agreement/mismatch between layer 1 and hydrabody layers 2+3
• hydraneckwebrtc GET /session/{id}/status response includes orientation field
• hydraheadwebstream shows portrait badge in experience dropdown
• hydraheadwebstream shows rotate-device hint when portrait experience is selected
• Verified end-to-end: mercator-talks (portrait) and a landscape experience on the same body, both heads

Affected repos

• hydrabody — expose orientation in API response
• hydraneckwebrtc — cross-layer orientation log + session status field
• hydraheadwebstream — portrait hint in UI
• hydraheadflatscreen — CLAUDE.md note only

Related

• Issue #81 (Brussels node not in hydracluster) is a prerequisite for reliable orientation on the webstream Brussels path — version drift on that node is what triggered this investigation.