Skip to content

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

Description

@raymond-UI

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?

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions