[v3 Windows] Frameless window gotchas & workarounds (hit-test, HiddenOnTaskbar, event data)

[harry18456]

Background

I've been building GlanceHUD — a floating
system-monitor HUD using Wails v3 alpha.72 on Windows 11. I used AI-assisted
development (vibe coding with Claude) throughout the project.

During development, the AI helped me identify several Windows-specific gotchas
through code analysis and trial-and-error. I'm sharing these here as a consolidated
reference, along with the workarounds that worked for me. I'm not sure if all of
these are known — happy to open separate issues if any are worth tracking formally.

---

1. Frameless + transparent window: hit-test region frozen at creation size

Related: #4871 (same symptom and root cause)

Symptom: After creating a frameless+transparent window at e.g. 400×300 and later
resizing it via Window.SetSize, only the original 400×300 area responds to mouse
events. The expanded area is permanently click-through.

Root cause: In webview_window_windows.go (~L318-322), frameless+transparent
windows receive WS_EX_LAYERED | WS_EX_TRANSPARENT. On Windows, the hit-testable
region of a WS_EX_LAYERED window is fixed at CreateWindowEx time and is not
updated by subsequent SetWindowPos calls. setSize() (L686) only calls setBounds()
→ SetWindowPos, without refreshing the layered window state.

Workaround: Create the window at 3840×2160 with Hidden: true, so the
hit-test region covers any realistic content size. The frontend calls Window.Show()
after the first SetSize completes.

hudWindow := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Width:  3840, // must be >= max expected content size
    Height: 2160,
    Hidden: true, // shown by frontend after first resize
    Frameless:        true,
    BackgroundType:   application.BackgroundTypeTransparent,
    BackgroundColour: application.NewRGBA(0, 0, 0, 0),
    // ...
})

Possible upstream fix: Call SetLayeredWindowAttributes(hwnd, 0, 255, LWA_ALPHA)
after each SetWindowPos in setBounds() to refresh the layered region.

---

2. HiddenOnTaskbar: true likely prevents window from receiving keyboard focus

Note: We discovered this through source code inspection, not actual usage —
we chose to omit HiddenOnTaskbar entirely after seeing the implementation.
Flagging it here in case it affects others.

Root cause: In webview_window_windows.go L331-334:

// If we're frameless, we need to add the WS_EX_TOOLWINDOW style to hide the window from the taskbar
if options.Windows.HiddenOnTaskbar {
    //exStyle |= w32.WS_EX_TOOLWINDOW  // ← correct, but commented out
    exStyle |= w32.WS_EX_NOACTIVATE    // ← this blocks focus/input
}

The comment states WS_EX_TOOLWINDOW is the intended style for hiding from the
taskbar, but it's commented out in favour of WS_EX_NOACTIVATE. WS_EX_NOACTIVATE
prevents the window from being activated, which would block keyboard focus and input.

Workaround: Omit HiddenOnTaskbar entirely.

Possible upstream fix: Use WS_EX_TOOLWINDOW as originally intended.

---

3. Event.Emit with a single arg vs. multiple args changes event.data shape on the frontend

Symptom: event.data received in the frontend sometimes arrives as a direct
object, sometimes wrapped in an array [object], requiring defensive code.

Root cause: In event_manager.go L24-38:

// When there is exactly one data argument, it will be used as the custom event's data field.
// When more than one argument is provided, the event's data field will be set to the argument slice.
func (em *EventManager) Emit(name string, data ...any) bool {
    if len(data) == 1 {
        event.Data = data[0]   // direct object
    } else if len(data) > 1 {
        event.Data = data      // slice → JSON array
    }

So the shape of event.data on the frontend depends entirely on how the Go caller
invokes Emit. If any code path uses Emit("my-event", a, b) (two args), the
frontend receives an array; single-arg calls give a direct object.

The godoc documents this behaviour but does not explain the rationale. It's unclear
whether this asymmetry is intentional design or simply an artifact of the variadic
signature. If a caller accidentally passes two args, the frontend breaks silently.

Workaround:

const payload = Array.isArray(event.data) ? event.data[0] : event.data;

Suggestion: Consider documenting this behaviour on the JS side (Events.On docs),
or normalising event.data to always be a consistent shape regardless of how many
args were passed to Emit.

---

System info (wails3 doctor)

Wails CLI	v3.0.0-alpha.72
Go	go1.25.7
OS	Windows 11 家用版 (Build 26200, 25H2)
Architecture	amd64
WebView2	145.0.3800.65
CPU	Intel Core i9-14900HX

Happy to provide more details or test any patches. Thanks for the great framework!

[leaanthony]

Does this work better for you? #5010