Windows capsule needs a stable native container/input contract

[Cooper-X-Oak]

This was generated by AI during triage.

Summary

Windows capsule currently lacks a stable native container/input contract. The visible DOM pill can look correct while the transparent WebView/Tauri host still blocks desktop clicks, and native Windows materials can paint the transparent carrier as a gray rectangle. Recent PR exploration around #497 showed that local pixel patches are not enough: the platform contract itself needs to be explicit and tested.

This issue should supersede treating the symptom as only a capsule gray-edge bug. The goal is to make future Windows capsule calls reliable across DPI, WebView2 child HWND hit-testing, no-activate show, state transitions, and translation badge rendering.

Evidence from exploration

• Applying Acrylic/Mica/DWM material to the capsule HWND can paint transparent carrier margins as a visible gray box.
• Dynamic WS_EX_TRANSPARENT / SetWindowLongPtrW / WebView child-HWND approaches are not a stable fix; real WindowFromPoint can still hit Chrome_RenderWidgetHostHWND in transparent host margins.
• SetWindowRgn can bound the native input surface, but it must not be tied to the strict CSS pill border box. A too-tight 180x44 CSS pill region clipped the rendered capsule. The native Windows input envelope needs to cover the full visible rendered capsule, including buttons, antialiasing, shadow edge, and DPI-scaled bounds.
• HITL evidence must be DPI-aware. On a 125% DPI display, a logical 220x84 capsule is observed as 275x105 physical pixels. A DPI-unaware screenshot pipeline can falsely crop a healthy capsule and create misleading evidence.

Proposed Windows capsule contract

• DOM owns the visible capsule surface.
• Windows native host is only a carrier/input envelope.
• Windows capsule host must not use Acrylic/Mica/DWM material.
• Transparent host margins must not block clicks.
• Visible pill/buttons remain interactive.
• Capsule remains no-activate and must not steal focus.
• Native input envelope must represent the complete rendered capsule surface, not the strict CSS pill box.
• DPI conversion must be explicit in tests and evidence.
• macOS vibrancy/backdrop behavior must remain untouched.

Acceptance gates

• Static contract gate rejects Windows capsule Acrylic/Mica/DWM material.
• Static contract gate rejects dynamic WebView child-HWND click-through hacks as the primary solution.
• Layout contract distinguishes host metrics, CSS pill metrics, and Windows native input envelope metrics.
• Rust build passes for the Windows app binary.
• Windows HITL recording gate proves:
  • transparent top-left, left-middle, and bottom-right host points pass through to the green backdrop;
  • pill center hits OpenLess Capsule;
  • screen crop captures a full, non-clipped capsule;
  • logical dimensions are converted to physical pixels using window DPI.
• Windows HITL translation badge gate proves badge and pill regions update together without gray host paint or stale hitboxes.
• State transition gate covers recording -> transcribing/polishing -> done/error -> idle without clipped exit animation or stale region.

References

• PR exploration: fix(windows): clip capsule Acrylic to visible regions #497
• Suggested implementation state: ready for agent once a fresh beta-based branch is opened.
• Latest local evidence during triage used a DPI-aware green-screen HITL pipeline and showed why both input gates and visual gates are required.

[Cooper-X-Oak]

Opened PR #499 for this issue: #499

Scope: stable Windows capsule native container/input contract, not a cosmetic gray-edge rollback.

Highlights:

• Capsule HWND is now a transparent carrier/input envelope on Windows.
• DOM pill owns the visible surface; no capsule Acrylic/Mica/DWM material.
• Rounded native region covers the rendered pill and translation badge.
• HITL evidence for recording and translation modes is embedded in the PR body.