vercel-labs / vercel-labs/native

feat: draggable HTML title bar in web-shell apps (-webkit-app-region)

Open
#136 0 comments 0 reactions 0 assignees View on GitHub

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: needs NSApp.currentEvent to be the live LeftMouseDown that arrived synchronously from a native view's mouseDown:. A JS-to-bridge call is async, so by the time it runs there is no current mouse event left to pass to performWindowDragWithEvent:.
  • No builtin bridge command exposes window drag to JS, and -webkit-app-region is not honored inside the WKWebView.
  • The existing drag-region mirror (window-drag="true" and set_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:

  1. Inject a user script that collects the -webkit-app-region: drag rectangles (minus the interactive child rectangles that should stay clickable) and posts them to a WKScriptMessageHandler.
  2. Add a transparent overlay NSView above the web view. Its hitTest: 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. Its mouseDown: calls performWindowDragWithEvent:, 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
  1. Is this something you would want in the SDK?
  2. Would you prefer feeding the web view's app-region rectangles into the existing set_window_drag_regions_fn mirror instead of a separate overlay, so the WebView path reuses the same machinery the canvas path already uses?
  3. Should a contribution also cover WebView2 and WebKitGTK, or is a macOS-first PR acceptable with the other platforms tracked separately?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.