fix(desktop): Windows applied the first-launch deep link twice, and the first one was too early to work (GDK-293) (#34)

`desktop/main.go` applied argv whenever `runtime.GOOS != "darwin"`. The
comment right above it explained the hazard correctly — apply argv on a
platform that also emits the event and you navigate twice — and then put
Windows on the wrong side of it. The pinned wails
(v3.0.0-beta.6) emits ApplicationLaunchedWithUrl on Windows when
`len(os.Args) == 2` and the argument contains "://", which is exactly the
shape the CLI's own launcher produces.

Confirmed on real hardware before this change: Windows 11 Home, WebView2
151.0.4129.86, a probe build logging both paths.

    PROBE293 event-path applying deep link "gadak://view?issue=NMB-1"
    deep link →/#/?issue=NMB-1
    [WebView2] Environment created successfully
    wails runtime ready
    PROBE293 argv-path applying deep link "gadak://view?issue=NMB-1"
    deep link →/#/?issue=NMB-1

The ordering in that log is why "pick one of the two" would have been the
wrong fix: the event path runs *before* the webview environment exists, so
the first application was already a no-op and the one that reached the
screen was the second. Picking the event without an ordering contract would
have picked the dead one.

So there are two changes, not one. `coldStartDecisionFor(goos, args)` is
now the single owner of where a cold-start URL comes from, and exactly one
source is armed per platform and argv shape — darwin defers to the event,
Linux always reads argv because GTK4 never emits it, and Windows defers
only when wails will actually emit, falling back to argv for every other
argv shape. There is no `!= darwin` left; that negation was the bug,
because it lumped two platforms with opposite behaviour into one branch.
And `coldStartGate` holds anything offered before WindowRuntimeReady in a
one-slot queue and flushes it there, so nothing is handed to a webview that
does not exist yet.

Double application is now structurally impossible rather than avoided by
care: `ApplyArgv` and `DeferToEvent` are mutually exclusive, and the event
handler returns early unless it is the armed source.

`OnSecondInstanceLaunch` is untouched — that path was always correct — and
the macOS reopen case still works, because the event arrives after ready and
the gate applies it immediately.

Two comments corrected. The one on ApplicationShouldHandleReopen used to
analogise it to ApplicationLaunchedWithUrl ("never fires off darwin — same
as"), which is the same false premise; it now says the opposite explicitly.

FAIL-first, reproduced by the lead by restoring the `!= darwin` rule under
the new table: the Windows launcher row comes back as
`{ApplyArgv:true DeferToEvent:true}` — both sources armed — against a want
of `{ApplyArgv:false DeferToEvent:true}`, plus two more Windows rows. The
test pins the decision, not the rendering; no runtime event ordering is
asserted, because three rounds have just been spent on timing-sensitive
tests.

Debuggability: the probe build is no longer needed to answer "which source
supplied this URL" — `deep link source=argv|event` is logged beside the
existing `deep link →` line.

Gates, lead-run in desktop/: build, vet, `go test ./... -count=1` ok
(4.6s). Cross-compile windows/amd64 and darwin/arm64 both build.
linux/amd64 with CGO_ENABLED=0 fails on wails' own menu_linux.go, which is
the pre-existing reason ci.yml documents, not this change.

Co-authored-by: midagedev <midagedev@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: midagedev

desktop/coldstart_test.go

@@ -0,0 +1,121 @@
+package main
+
+import "testing"
+
+// The launcher that broke (cmd/gadak/views.go startWindowsDesktopImpl) starts
+// the exe with exactly one argument — the gadak:// URL. wails v3.0.0-beta.6
+// treats that shape as ApplicationLaunchedWithUrl on Windows.
+const launcherURL = "gadak://view?issue=NMB-1"
+
+func TestColdStartDecisionFor(t *testing.T) {
+	for _, tc := range []struct {
+		name             string
+		goos             string
+		args             []string
+		wantApplyArgv    bool
+		wantDeferToEvent bool
+	}{
+		{
+			name:             "windows launcher one-arg (GDK-293)",
+			goos:             "windows",
+			args:             []string{"gadak-desktop.exe", launcherURL},
+			wantApplyArgv:    false,
+			wantDeferToEvent: true,
+		},
+		{
+			name:             "windows no extra args — argv fallback is a no-op",
+			goos:             "windows",
+			args:             []string{"gadak-desktop.exe"},
+			wantApplyArgv:    true,
+			wantDeferToEvent: false,
+		},
+		{
+			name:             "windows extra args — wails ignores, argv owns the URL",
+			goos:             "windows",
+			args:             []string{"gadak-desktop.exe", "--flag", launcherURL},
+			wantApplyArgv:    true,
+			wantDeferToEvent: false,
+		},
+		{
+			name:             "windows two extra args including the URL",
+			goos:             "windows",
+			args:             []string{"gadak-desktop.exe", launcherURL, "other"},
+			wantApplyArgv:    true,
+			wantDeferToEvent: false,
+		},
+		{
+			name:             "windows one arg without :// — wails does not emit",
+			goos:             "windows",
+			args:             []string{"gadak-desktop.exe", "not-a-url"},
+			wantApplyArgv:    true,
+			wantDeferToEvent: false,
+		},
+		{
+			name:             "darwin one-arg is still event-only",
+			goos:             "darwin",
+			args:             []string{"gadak-desktop", launcherURL},
+			wantApplyArgv:    false,
+			wantDeferToEvent: true,
+		},
+		{
+			name:             "darwin no args is event-only",
+			goos:             "darwin",
+			args:             []string{"gadak-desktop"},
+			wantApplyArgv:    false,
+			wantDeferToEvent: true,
+		},
+		{
+			name:             "linux one-arg is argv (GTK4 does not emit the event)",
+			goos:             "linux",
+			args:             []string{"gadak-desktop", launcherURL},
+			wantApplyArgv:    true,
+			wantDeferToEvent: false,
+		},
+		{
+			name:             "linux no args is argv",
+			goos:             "linux",
+			args:             []string{"gadak-desktop"},
+			wantApplyArgv:    true,
+			wantDeferToEvent: false,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			got := coldStartDecisionFor(tc.goos, tc.args)
+			if got.ApplyArgv != tc.wantApplyArgv || got.DeferToEvent != tc.wantDeferToEvent {
+				t.Fatalf("coldStartDecisionFor(%q, %q) = {ApplyArgv:%v DeferToEvent:%v}, want {ApplyArgv:%v DeferToEvent:%v}",
+					tc.goos, tc.args, got.ApplyArgv, got.DeferToEvent, tc.wantApplyArgv, tc.wantDeferToEvent)
+			}
+		})
+	}
+}
+
+// TestColdStartGate is a state machine, not a runtime event-order test: it
+// pins "nothing is applied before markReady" without opening a window.
+func TestColdStartGate(t *testing.T) {
+	type applied struct{ raw, src string }
+	var got []applied
+	g := coldStartGate{apply: func(raw, source string) {
+		got = append(got, applied{raw, source})
+	}}
+
+	g.offer("gadak://view?issue=NMB-1", "event")
+	if len(got) != 0 {
+		t.Fatalf("offer before ready applied %v", got)
+	}
+
+	g.offer("gadak://view?issue=NMB-2", "event")
+	g.markReady()
+	if len(got) != 1 || got[0] != (applied{"gadak://view?issue=NMB-1", "event"}) {
+		t.Fatalf("markReady flush = %v, want first-offer only", got)
+	}
+
+	g.offer("gadak://view?issue=NMB-3", "argv")
+	if len(got) != 2 || got[1] != (applied{"gadak://view?issue=NMB-3", "argv"}) {
+		t.Fatalf("offer after ready = %v, want immediate apply", got)
+	}
+
+	g.offer("", "event")
+	if len(got) != 2 {
+		t.Fatalf("empty offer applied %v", got)
+	}
+}

desktop/main.go

@@ -21,6 +21,7 @@ import (
 	"path"
 	"runtime"
 	"strings"
+	"sync"
 	"unsafe"
 
 	"github.com/wailsapp/wails/v3/pkg/application"
@@ -61,6 +62,91 @@ func main() {
 	}
 }
 
+// coldStartDecision is the single owner of how a first-launch gadak://
+// reaches this process: from argv, or from ApplicationLaunchedWithUrl.
+type coldStartDecision struct {
+	ApplyArgv    bool
+	DeferToEvent bool
+}
+
+// coldStartDecisionFor reports the cold-start URL source for this GOOS and
+// the process argv (full os.Args, including argv[0]).
+//
+//   - darwin: event only. LaunchServices delivers the URL as an Apple Event;
+//     applying argv as well would navigate twice.
+//   - windows: event when wails will emit ApplicationLaunchedWithUrl — that
+//     is len(args)==2 and args[1] contains "://" (wails v3.0.0-beta.6
+//     pkg/application/application_windows.go:159-162). Every other argv
+//     shape is ignored by wails, so argv is the fallback.
+//   - linux (and anything else): argv. GTK4 run() in the same wails pin
+//     (application_linux.go:89-99) does not emit the event.
+func coldStartDecisionFor(goos string, args []string) coldStartDecision {
+	switch goos {
+	case "darwin":
+		return coldStartDecision{ApplyArgv: false, DeferToEvent: true}
+	case "windows":
+		if wailsEmitsLaunchURL(args) {
+			return coldStartDecision{ApplyArgv: false, DeferToEvent: true}
+		}
+		return coldStartDecision{ApplyArgv: true, DeferToEvent: false}
+	default:
+		return coldStartDecision{ApplyArgv: true, DeferToEvent: false}
+	}
+}
+
+// wailsEmitsLaunchURL is the argv shape wails v3.0.0-beta.6 special-cases
+// on Windows (application_windows.go:159-162). GTK3 has the same check;
+// GTK4, which this pin compiles, does not.
+func wailsEmitsLaunchURL(args []string) bool {
+	return len(args) == 2 && strings.Contains(args[1], "://")
+}
+
+// coldStartGate applies a cold-start URL only after WindowRuntimeReady.
+// Bound: one slot. An offer that arrives before ready is queued; a second
+// offer before ready is dropped (first wins). After ready, offer applies
+// immediately. A URL that is still queued when markReady runs is flushed
+// then. There is no drop-on-timeout — the window either becomes ready or
+// the process exits.
+type coldStartGate struct {
+	mu         sync.Mutex
+	ready      bool
+	pendingRaw string
+	pendingSrc string
+	apply      func(raw, source string)
+}
+
+func (g *coldStartGate) offer(raw, source string) {
+	if raw == "" {
+		return
+	}
+	g.mu.Lock()
+	if !g.ready {
+		if g.pendingRaw == "" {
+			g.pendingRaw = raw
+			g.pendingSrc = source
+		}
+		g.mu.Unlock()
+		return
+	}
+	apply := g.apply
+	g.mu.Unlock()
+	if apply != nil {
+		apply(raw, source)
+	}
+}
+
+func (g *coldStartGate) markReady() {
+	g.mu.Lock()
+	g.ready = true
+	raw, src := g.pendingRaw, g.pendingSrc
+	g.pendingRaw, g.pendingSrc = "", ""
+	apply := g.apply
+	g.mu.Unlock()
+	if raw != "" && apply != nil {
+		apply(raw, src)
+	}
+}
+
 func run() error {
 	cfg, err := config.Load()
 	if err != nil {
@@ -225,15 +311,32 @@ func run() error {
 	}
 	app.Menu.Set(appMenu)
 
+	decision := coldStartDecisionFor(runtime.GOOS, os.Args)
+	var gate coldStartGate
+	gate.apply = func(raw, source string) {
+		if applyDeepLink == nil {
+			return
+		}
+		log.Printf("deep link source=%s", source)
+		applyDeepLink(raw)
+	}
+
 	window = app.Window.NewWithOptions(mainWindowOptions())
 	window.OnWindowEvent(events.Common.WindowRuntimeReady, func(*application.WindowEvent) {
 		log.Print("wails runtime ready — --wails-draggable listeners are attached")
-		// Windows (and Linux) deliver a first-launch gadak:// as argv. macOS
-		// uses ApplicationLaunchedWithUrl for that; applying argv there too
-		// would navigate twice.
-		if runtime.GOOS != "darwin" && applyDeepLink != nil {
+		// Cold-start URL source is coldStartDecisionFor, not "!= darwin".
+		// Linux always reads argv (GTK4 does not emit ApplicationLaunchedWithUrl).
+		// Windows reads argv only when wails will not emit the event
+		// (len(os.Args) != 2 or the single arg has no "://"). macOS never
+		// reads argv. Nothing is handed to the webview until this event:
+		// an ApplicationLaunchedWithUrl that arrived earlier sits in gate
+		// (one slot, first offer wins) and is flushed here. Argv, when this
+		// process owns it, is offered after the flush so it cannot race a
+		// pending event.
+		gate.markReady()
+		if decision.ApplyArgv {
 			if raw := firstDeepLinkArg(os.Args[1:]); raw != "" {
-				applyDeepLink(raw)
+				gate.offer(raw, "argv")
 			}
 		}
 	})
@@ -242,17 +345,23 @@ func run() error {
 		window.SetURL(path)
 		raiseWindow(window)
 	})
-	// The other delivery route: the app was already running, so the Apple
-	// Event reaches this process and wails emits it as an application event.
+	// ApplicationLaunchedWithUrl: macOS Apple Event (first launch and
+	// same-process reopen) and Windows when wails sees a single argument
+	// containing "://". Linux GTK4 never emits it. Offers go through the
+	// ready gate so a URL that arrives before the webview exists is queued,
+	// not applied.
 	app.Event.OnApplicationEvent(events.Common.ApplicationLaunchedWithUrl,
 		func(e *application.ApplicationEvent) {
-			applyDeepLink(e.Context().URL())
+			if !decision.DeferToEvent {
+				return
+			}
+			gate.offer(e.Context().URL(), "event")
 		})
 	// Dock click (minimised or no visible window). wails' own handler only
 	// Show()s when HasVisibleWindows is false; a miniaturised window is still
 	// "visible", so Restore+Focus is the same raise the second-instance path
-	// already uses. The event is defined on every GOOS and never fires off
-	// darwin — same as ApplicationLaunchedWithUrl.
+	// already uses. ApplicationShouldHandleReopen is macOS-only; do not
+	// analogise it to ApplicationLaunchedWithUrl, which Windows does emit.
 	app.Event.OnApplicationEvent(events.Mac.ApplicationShouldHandleReopen,
 		func(*application.ApplicationEvent) {
 			raiseWindow(window)