vercel-labs / vercel-labs/native
feat: draggable HTML title bar in web-shell apps (-webkit-app-region)
Nobody has claimed this yet.
- Dominant language
- Zig
- Stars
- 7.7k
- Forks
- 314
- Avg merge
- 5h
- Merged PRs (30d)
- 13
Description
What
In a web-shell app (web_engine = "system") with titlebar = "hidden_inset" or "hidden_inset_tall", there is no way to make the window draggable from the app's own HTML title bar. The strip renders and the traffic lights work, but you cannot move the window by dragging the header.
This is the companion to #18: once the native decorations are hidden and the app draws its own titlebar in the web view, it needs a way to drag the window from that HTML, otherwise the window is stuck in place.
Tested on 0.5.1, macOS.
Why it does not work today
From reading the macOS host, none of the existing paths reach HTML content:
- The WKWebView consumes the mouse-down, and nothing forwards it to the window as a drag gesture.
startWindowDragWithId:needsNSApp.currentEventto be the liveLeftMouseDownthat arrived synchronously from a native view'smouseDown:. A JS-to-bridge call is async, so by the time it runs there is no current mouse event left to pass toperformWindowDragWithEvent:.- No builtin bridge command exposes window drag to JS, and
-webkit-app-regionis not honored inside the WKWebView. - The existing drag-region mirror (
window-drag="true"andset_window_drag_regions_fn) is wired for the native canvas/markup path, so it never sees the web view DOM.
A working proof of concept (macOS)
I have this working locally with a small patch to the macOS host:
- Inject a user script that collects the
-webkit-app-region: dragrectangles (minus the interactive child rectangles that should stay clickable) and posts them to aWKScriptMessageHandler. - Add a transparent overlay
NSViewabove the web view. ItshitTest:returns self only when the point is inside a drag rectangle and outside the interactive holes, so every other click falls through to the web content. ItsmouseDown:callsperformWindowDragWithEvent:, with the standard double-click zoom/minimize behavior.
It works, but a separate overlay feels like a workaround rather than the intended design.
Questions before I open a PR
- Is this something you would want in the SDK?
- Would you prefer feeding the web view's app-region rectangles into the existing
set_window_drag_regions_fnmirror instead of a separate overlay, so the WebView path reuses the same machinery the canvas path already uses? - Should a contribution also cover WebView2 and WebKitGTK, or is a macOS-first PR acceptable with the other platforms tracked separately?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the macOS host's WKWebView integration and the existing window-drag="true" and set_window_drag_regions_fn path. Compare the described user-script and overlay proof of concept, then clarify whether the SDK should support draggable HTML regions on macOS only or across WebView2 and WebKitGTK, with interactive child areas remaining clickable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- html, macos, zig
- Domain
- desktop, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100