Reviewing files that changed from the base of the PR and between 53cd30a and a0d56d8.

• v3/internal/runtime/desktop/@wailsio/runtime/package-lock.json is excluded by !**/package-lock.json

• docs/astro.config.mjs
• docs/src/content/docs/contributing/runtime-internals.mdx
• docs/src/content/docs/features/drag-and-drop/files.mdx
• docs/src/content/docs/features/drag-and-drop/html.mdx
• docs/src/content/docs/features/windows/options.mdx
• docs/src/content/docs/quick-start/next-steps.mdx
• v3/UNRELEASED_CHANGELOG.md
• v3/examples/drag-n-drop/README.md
• v3/examples/drag-n-drop/assets/index.html
• v3/examples/drag-n-drop/main.go
• v3/examples/html-dnd-api/README.md
• v3/examples/html-dnd-api/assets/index.html
• v3/examples/html-dnd-api/main.go
• v3/examples/liquid-glass/main.go
• v3/internal/assetserver/bundledassets/runtime.debug.js
• v3/internal/assetserver/bundledassets/runtime.js
• v3/internal/generator/collect/known_events.go
• v3/internal/runtime/Taskfile.yaml
• v3/internal/runtime/desktop/@wailsio/runtime/src/event_types.ts
• v3/internal/runtime/desktop/@wailsio/runtime/src/index.ts
• v3/internal/runtime/desktop/@wailsio/runtime/src/system.ts
• v3/internal/runtime/desktop/@wailsio/runtime/src/window.ts
• v3/internal/runtime/runtime.go
• v3/pkg/application/application.go
• v3/pkg/application/application_darwin.go
• v3/pkg/application/context_window_event.go
• v3/pkg/application/linux_cgo.go
• v3/pkg/application/linux_purego.go
• v3/pkg/application/messageprocessor_window.go
• v3/pkg/application/webview_window.go
• v3/pkg/application/webview_window_darwin.go
• v3/pkg/application/webview_window_darwin.m
• v3/pkg/application/webview_window_darwin_drag.m
• v3/pkg/application/webview_window_linux.go
• v3/pkg/application/webview_window_options.go
• v3/pkg/application/webview_window_options_test.go
• v3/pkg/application/webview_window_windows.go
• v3/pkg/application/window.go
• v3/pkg/events/events.go
• v3/pkg/events/events.txt
• v3/pkg/events/events_darwin.h
• v3/pkg/events/events_ios.h
• v3/pkg/events/events_linux.h
• v3/pkg/events/known_events.go
• v3/test/dnd-test/assets/index.html
• v3/test/dnd-test/dnd-test
• v3/test/dnd-test/main.go

• v3/examples/html-dnd-api/main.go
• v3/internal/runtime/desktop/@wailsio/runtime/src/event_types.ts
• v3/pkg/events/events.txt
• v3/pkg/application/webview_window_options_test.go
• v3/internal/runtime/desktop/@wailsio/runtime/src/system.ts
• v3/examples/html-dnd-api/README.md
• v3/pkg/application/webview_window_darwin.m
• v3/examples/html-dnd-api/assets/index.html

• GitHub Check: Run Go Tests v3 (windows-latest, 1.24)
• GitHub Check: Cloudflare Pages

v3/examples/drag-n-drop/README.md (3)

67-73: Clarify platform testing status in the Status table.

The PR objectives indicate that "Linux verified (Arch, WebKit2GTK); Windows and macOS still need testing," but the Status table marks all platforms as "Working." This creates a discrepancy between the PR summary and the documentation. Either the table should reflect the testing status (e.g., "In Progress" for Windows/macOS), or the PR objectives need updating if these platforms have been tested since.

---

1-73: Documentation quality and structure is solid.

The README effectively communicates the file drop feature across all platforms, clearly distinguishes it from HTML5 internal drag-and-drop (via the "See also" section), and provides practical code examples that reflect the renamed APIs (EnableFileDrop, data-file-drop-target, WindowFilesDropped, DropTargetDetails). The four-step "How it works" process and styling documentation are well-organized and easy to follow.

---

21-23: No issues found - example code API method names are correct.

The method names DroppedFiles() and DropTargetDetails() in the example code match the actual implementation in v3/pkg/application/context_window_event.go, and both return the expected types ([]string and *DropTargetDetails respectively).

Likely an incorrect or invalid review comment.

v3/examples/drag-n-drop/main.go (3)

1-12: LGTM! Clean setup.

The imports and embedded assets follow standard Wails v3 patterns.

---

14-36: LGTM! Correct usage of the new API.

The window configuration correctly uses EnableFileDrop: true, which aligns with the API rename from EnableDragAndDrop in this PR.

---

56-59: LGTM! Appropriate error handling.

Using log.Fatal for the app run error is suitable for this example application.

v3/pkg/application/linux_purego.go (1)

396-404: Implementation is correct and consistent with the CGO version.

Both the CGO implementation (linux_cgo.go) and purego implementation (linux_purego.go) use G_APPLICATION_NON_UNIQUE (value 32). This change aligns both backends and intentionally matches the v2 behavior with gtk_init/gtk_main.

The application-level single-instance feature (via SingleInstanceOptions) is independent of this GTK flag and uses DBus on Linux, so it continues to work unchanged. No breaking changes or user communication needed.

v3/internal/runtime/runtime.go (1)

9-9: LGTM!

The initialization of window._wails.flags as an empty object ensures the flags namespace exists before any subsequent code attempts to access it, preventing potential undefined access errors in JavaScript.

v3/test/dnd-test/assets/index.html (1)

132-222: LGTM!

The test page correctly demonstrates both internal HTML5 drag-and-drop and external file drop scenarios. The event handlers properly distinguish between the two use cases, and the logging provides useful debugging output.

v3/UNRELEASED_CHANGELOG.md (1)

23-45: LGTM!

The changelog thoroughly documents all breaking changes, bug fixes, and removed features. The entries are clear and actionable for users migrating to the new API.

v3/internal/generator/collect/known_events.go (1)

8-222: LGTM!

The known events map is properly updated to reflect the new event naming convention (common:WindowFilesDropped) and includes the new platform-specific drag lifecycle events for macOS (WindowFileDraggingEntered, WindowFileDraggingExited, WindowFileDraggingPerformed).

v3/examples/drag-n-drop/assets/index.html (3)

63-71: LGTM!

The CSS correctly uses the new file-drop-target-active class name that aligns with the PR's documented breaking changes.

---

387-432: LGTM!

The internal drop zone handlers correctly filter out external file drags by checking e.dataTransfer?.types.includes('Files'). This ensures clean separation between OS file drops (handled by Wails) and in-page HTML5 drag-and-drop.

---

341-365: No action required. Event name is correct.

The JavaScript code correctly listens for 'files-dropped', which matches the custom event emitted by the Go backend in v3/examples/drag-n-drop/main.go: application.Get().Event.Emit("files-dropped", ...). While WindowFilesDropped is the system event type, this example implements custom drag-and-drop handling via explicit event emission, not the system event.

v3/internal/runtime/Taskfile.yaml (1)

38-112: LGTM!

The new tasks are well-organized with proper dependencies and clear summaries. The build:all task correctly sequences the generation and build steps, and the clean task provides useful artifact cleanup.

v3/pkg/application/linux_cgo.go (4)

1802-1862: LGTM!

The Go exports for drag callbacks correctly retrieve the window by ID and use type assertions with proper nil/ok checks. The onUriList function appropriately calls InitiateFrontendDropProcessing which aligns with the new drop-target architecture.

---

1021-1031: LGTM!

The enableDND and disableDND methods correctly pass the window ID using the established pattern (casting to uintptr as a pointer value). The comments clearly explain this approach matches other signal handlers in the file.

---

398-426: LGTM!

The blocked handlers correctly distinguish between external file drags (which are consumed to prevent navigation) and internal HTML5 drags (which pass through to WebKit). The gdk_drag_status(context, 0, time) call appropriately shows a "no drop" cursor for disabled file drop zones.

---

26-28: LGTM!

The change to G_APPLICATION_NON_UNIQUE aligns with v2 behavior as noted in the comment, allowing multiple instances of the application to run simultaneously.

docs/src/content/docs/quick-start/next-steps.mdx (1)

27-27: LGTM!

The updated link correctly points to the new drag-and-drop documentation structure introduced in this PR.

v3/internal/runtime/desktop/@wailsio/runtime/src/index.ts (2)

29-29: LGTM!

The import correctly brings in the drag event handlers needed for Linux/GTK drag event interception.

---

73-76: LGTM!

The drag handlers are correctly exposed through window._wails to enable GTK's native drag event interception on Linux. This pattern is consistent with other platform handlers like handlePlatformFileDrop.

v3/pkg/events/events_ios.h (1)

9-32: LGTM!

The event ID renumbering is consistent with the PR-wide realignment following the removal of WindowDropZoneFilesDropped. All IDs are systematically decremented by one while preserving the macro names.

v3/pkg/application/webview_window_linux.go (1)

285-289: LGTM!

The rename from EnableDragAndDrop to EnableFileDrop is correct, and the explicit handling of both enabled and disabled cases with disableDND() is good defensive programming.

docs/src/content/docs/features/windows/options.mdx (1)

549-602: No duplication issue exists.

The file contains only one ## Input Options section (line 549) with a single ### EnableFileDrop entry (line 551). The documentation is correctly structured without duplicates.

Likely an incorrect or invalid review comment.

docs/src/content/docs/contributing/runtime-internals.mdx (1)

173-245: Solid documentation for the new drag-and-drop architecture.

This section provides a clear explanation of the JavaScript-first approach and platform-specific implementations. The flow diagram, platform comparison table, and debugging tips are particularly helpful for contributors.

A few minor observations:

• Line 232: The TypeScript file path references src/window.ts, but verify this matches the actual location in the runtime after the PR changes.
• The C code snippet for Linux drag detection is a helpful reference for understanding the GTK signal handling.

v3/test/dnd-test/main.go (2)

35-44: Good defensive null check on DropTargetDetails.

The nil check before accessing details.ElementID is appropriate since drops outside defined drop targets may not have element details.

---

26-44: Add Show() call to display the window.

The window is created with NewWithOptions() but never shown. All examples in the codebase follow the pattern of calling Show() after window creation. Add win.Show() after line 44.

Diff

	// Listen for file drop events
	win.OnWindowEvent(events.Common.WindowFilesDropped, func(event *application.WindowEvent) {
		files := event.Context().DroppedFiles()
		details := event.Context().DropTargetDetails()

		log.Printf("[Go] Files dropped: %v", files)
		if details != nil {
			log.Printf("[Go] Drop target: id=%s, classes=%v, x=%d, y=%d",
				details.ElementID, details.ClassList, details.X, details.Y)
		}
	})
+	win.Show()

	err := app.Run()

⛔ Skipped due to learnings

Learnt from: popaprozac
Repo: wailsapp/wails PR: 4839
File: docs/src/content/docs/reference/window.mdx:616-620
Timestamp: 2025-12-29T08:02:06.122Z
Learning: In Wails v3, the correct API for creating windows is `app.Window.New()` and `app.Window.NewWithOptions(...)`, not `app.NewWebviewWindow()` or `app.NewWebviewWindowWithOptions(...)`. The Application struct exposes a Window field of type *WindowManager that provides these methods.

Learnt from: leaanthony
Repo: wailsapp/wails PR: 3763
File: v3/examples/window/main.go:472-475
Timestamp: 2024-09-30T06:13:46.595Z
Learning: In `v3/examples/window/main.go`, `time.Sleep` is used within a goroutine and does not block the UI thread.

Learnt from: leaanthony
Repo: wailsapp/wails PR: 3763
File: v3/examples/window/main.go:472-475
Timestamp: 2024-10-08T22:11:37.054Z
Learning: In `v3/examples/window/main.go`, `time.Sleep` is used within a goroutine and does not block the UI thread.

Learnt from: nixpare
Repo: wailsapp/wails PR: 3763
File: v3/examples/keybindings/main.go:16-17
Timestamp: 2024-09-20T23:34:29.841Z
Learning: In the codebase, `application.Options.KeyBindings` uses the `application.Window` type, whereas `application.WebviewWindowOptions.KeyBindings` uses `*application.WebviewWindow`. This is intentional and acceptable.

v3/pkg/events/known_events.go (2)

9-34: Common events updated with new WindowFilesDropped event.

The common events section correctly includes common:WindowFilesDropped (line 17), replacing the previous WindowDropZoneFilesDropped. The event set aligns with the PR's naming conventions.

---

138-140: New macOS drag lifecycle events added.

These three events (WindowFileDraggingEntered, WindowFileDraggingExited, WindowFileDraggingPerformed) enable the hover effects and drag handling documented in the PR for macOS.

docs/src/content/docs/features/drag-and-drop/html.mdx (3)

1-79: Well-structured HTML5 drag-and-drop documentation.

The documentation covers the fundamentals clearly: making elements draggable, defining drop zones with preventDefault(), and styling drag hover states. The explanation of why preventDefault() on dragover is required is helpful for developers unfamiliar with the HTML5 DnD API.

---

127-133: Correct solution for the dragleave flickering issue.

Using zone.contains(e.relatedTarget) to check if the pointer is actually leaving the zone (rather than entering a child element) is the correct approach. This is a common gotcha with HTML5 drag-and-drop.

---

177-207: Clear guidance on distinguishing file drags from internal drags.

The pattern of checking e.dataTransfer?.types.includes('Files') is correct and well-documented. This is essential for apps using both OS file drops and internal drag-and-drop.

docs/astro.config.mjs (1)

174-178: Sidebar now auto-generates from the drag-and-drop directory.

This change aligns with the pattern used for other feature sections (Clipboard, Browser, Keyboard, etc.) and will automatically include new documentation pages added to features/drag-and-drop/.

docs/src/content/docs/features/drag-and-drop/files.mdx (2)

59-101: Clear documentation for the WindowFilesDropped event and drop target routing.

The examples for detecting dropped files and routing based on ElementID are well-structured and demonstrate the new API effectively. The switch-case pattern for routing drops to different handlers is practical.

---

180-208: Good guidance on combining file drops with HTML5 drag-and-drop.

The documentation correctly explains how to distinguish external file drags from internal HTML5 drags using dataTransfer.types.includes('Files'), enabling both features to coexist in the same application.

v3/pkg/application/window.go (1)

24-24: HandleDragAndDropMessage signature change is complete and consistent.

The parameter rename from dropZone *DropZoneDetails to dropTarget *DropTargetDetails has been properly applied across the codebase. The interface definition, the WebviewWindow implementation, and all usage sites correctly reference the new parameter name and type.

v3/pkg/application/application_darwin.go (4)

420-440: LGTM!

The macosOnDragEnter and macosOnDragExit handlers correctly look up the window and dispatch JavaScript calls for UI updates. The early returns on missing windows prevent crashes gracefully.

---

475-511: LGTM!

The writeInt helper correctly converts integers to byte representation with proper bounds checking and edge case handling for zero and negative numbers.

---

577-644: LGTM!

The sendDragUpdate function correctly implements window caching with proper invalidation and zero-allocation JS string construction. The bounds checks prevent buffer overflows.

---

462-473: LGTM!

The clearWindowDragCache function properly cleans up cached window references and stops pending timers when a window is destroyed.

v3/pkg/application/webview_window_options.go (1)

107-110: LGTM!

The EnableFileDrop field is well-documented, clearly describing its purpose and referencing the data-file-drop-target attribute. This rename aligns with the PR's API consolidation goals.

v3/pkg/application/webview_window_darwin.go (4)

355-359: LGTM!

The windowExecJSNoAlloc C function provides a zero-allocation path for high-frequency drag-over JS execution. The comment clearly documents that the buffer is NOT freed, placing responsibility on the caller.

---

1104-1113: LGTM!

The execJSDragOver method correctly passes the pre-allocated buffer to C without additional allocations. The nil check prevents crashes on destroyed windows.

---

1265-1266: LGTM!

The window creation correctly uses the renamed EnableFileDrop option.

---

1499-1503: LGTM!

Calling clearWindowDragCache during window destruction ensures proper cleanup of cached window references and pending timers.

v3/pkg/application/webview_window_darwin_drag.m (5)

10-12: LGTM!

The extern declarations correctly expose the Go drag lifecycle callbacks for use in Objective-C.

---

37-58: LGTM!

The draggingUpdated: method correctly implements continuous drag position tracking with proper coordinate conversion from macOS's bottom-left origin to the web's top-left origin.

---

26-35: LGTM!

The draggingEntered: method correctly notifies both the window event system and JavaScript when a file drag enters the window.

---

60-65: LGTM!

The draggingExited: method correctly cleans up hover effects by notifying JavaScript when the drag leaves the window.

---

72-105: LGTM!

The performDragOperation: correctly extracts file paths, computes drop coordinates with proper Y-axis conversion, and passes them to the Go handler. Memory management is correct with malloc/free for the C array.

v3/examples/liquid-glass/main.go (2)

63-83: LGTM!

The example correctly uses the renamed EnableFileDrop field. Explicitly setting it to false documents intent clearly.

---

86-221: LGTM!

All seven window configurations consistently use the renamed EnableFileDrop field with proper formatting.

v3/pkg/application/context_window_event.go (2)

5-8: LGTM!

The constant rename from dropZoneDetailsKey to dropTargetDetailsKey aligns with the broader API rename.

---

45-73: LGTM!

The setDropTargetDetails and DropTargetDetails methods correctly handle the renamed type with proper nil checks and type assertions.

v3/pkg/application/application.go (3)

242-250: LGTM!

The DropTargetDetails struct is well-documented, clearly explaining its purpose and the data-file-drop-target attribute relationship.

---

252-268: LGTM!

The dragAndDropMessage struct and addDragAndDropMessage function correctly use the renamed DropTarget field.

---

712-722: LGTM!

The handleDragAndDropMessage correctly passes event.DropTarget to the window handler, completing the rename propagation.

v3/internal/runtime/desktop/@wailsio/runtime/src/window.ts (1)

72-104: Cross‑platform drag hover and Windows file‑drop pipeline look consistent

The new helpers (getDropTargetElement, canResolveFilePaths, resolveFilePaths) and native drag handlers (handleDragEnter/Leave/Over) line up with the Windows/WebView2 and Linux/macOS flows and respect window._wails.flags.enableFileDrop. The file:drop:x:y message shape also matches the Go side parsing, and HandlePlatformFileDrop correctly builds the elementDetails payload against the nearest [data-file-drop-target] element.

No functional issues stand out here.

Also applies to: 120-165

v3/pkg/events/events.go (1)

37-66: Event ID renumbering and WindowFilesDropped mapping are internally consistent

The per‑platform enums (Linux/Mac/Windows/iOS) and the eventToJS map all use the same shifted IDs, and WindowFilesDropped is wired as 1032 → "common:WindowFilesDropped". Linux IDs also match the updated C header values.

This keeps the public event surface coherent after removing the old drop‑zone event.

Also applies to: 84-98, 237-371, 423-470, 499-524, 526-766

v3/pkg/application/webview_window_windows.go (1)

2116-2119: EnableFileDrop flag injection timing looks correct

Injecting window._wails.flags.enableFileDrop immediately after runtime.Core(...) ensures the front‑end drop logic (canResolveFilePaths, drag listeners) sees the right flag state for each window.

Given _wails.flags is already used by other code paths, this order is appropriate; no changes needed here.

v3/pkg/application/webview_window.go (2)

1182-1194: DispatchWailsEvent now matches runtime’s _wails.dispatchWailsEvent hook

Switching to window._wails.dispatchWailsEvent(...) aligns this helper with the runtime.js assignment (window._wails.dispatchWailsEvent = ...) and avoids relying on a global symbol.

This fixes the mismatch cleanly.

---

1435-1462: InitiateFrontendDropProcessing wiring to Window.HandlePlatformFileDrop is correct

Marshalling filenames to JSON and invoking:

window.wails.Window.HandlePlatformFileDrop([...], x, y)

matches the runtime surface (Window.HandlePlatformFileDrop on window.wails.Window) and cleanly funnels both Windows and native (Linux/macOS) drops through the same JS entry point.

The pending‑JS handling when runtimeLoaded is false also mirrors other ExecJS flows.

v3/pkg/events/events_linux.h (1)

9-21: Linux event IDs and MAX_EVENTS match Go definitions

The Linux header’s event IDs (1050–1060) and MAX_EVENTS 1061 line up with newLinuxEvents() in events.go, so C↔Go event routing remains consistent after the renumbering.

No changes needed here.

v3/internal/assetserver/bundledassets/runtime.js (1)

1-9999: Bundled runtime.js mirrors the TS sources; prefer fixing issues in the TypeScript, not this file

This file is a minified, generated bundle. The drag‑and‑drop logic (oi/h constants, Y/io/oo, HandlePlatformFileDrop, global ro() listeners) matches the TypeScript we’ve already reviewed, and the event names (including WindowFilesDropped) line up with events.go.

The static‑analysis warnings here (sparse arrays, variable reuse, use‑before‑declaration) are typical artifacts of minification and should be addressed, if at all, by adjusting the TS/rollup build rather than hand‑editing this bundle.

v3/pkg/events/events_darwin.h (1)

9-142: Event ID sequence and new drag events verified correctly.

Event IDs are contiguous from 1061 to 1192 with no gaps or duplicates. MAX_EVENTS (1193) correctly reflects the highest event ID plus one. The three new drag events (EventWindowFileDraggingEntered, EventWindowFileDraggingExited, EventWindowFileDraggingPerformed) are properly implemented at IDs 1153–1155 and consistently mapped in events.go. The removal of WindowDropZoneFilesDropped has been confirmed. Cross-platform event spacing is maintained across Darwin, iOS, and Linux headers.

Reviewing files that changed from the base of the PR and between a0d56d8 and e74ab6b.

• AGENTS.md
• docs/src/content/docs/features/drag-and-drop/files.mdx
• v3/Taskfile.yaml
• v3/pkg/application/application_darwin.go
• v3/pkg/application/webview_window_windows.go

• v3/Taskfile.yaml

• AGENTS.md

• GitHub Check: Run Go Tests v3 (ubuntu-latest, 1.24)
• GitHub Check: Run Go Tests v3 (windows-latest, 1.24)
• GitHub Check: semgrep/ci
• GitHub Check: Analyze (go)
• GitHub Check: semgrep-cloud-platform/scan
• GitHub Check: Cloudflare Pages

v3/pkg/application/webview_window_windows.go (2)

1975-1988: LGTM! Clear documentation of the Windows drag-and-drop implementation.

The documentation block clearly explains the WebView2 constraints and how the two-path approach (EnableFileDrop true/false) works around the AllowExternalDrop limitations while preserving HTML5 drag-and-drop functionality.

---

2115-2117: LGTM! Proper injection of EnableFileDrop flag.

The flag is correctly injected into the JavaScript runtime after the core runtime is installed, allowing the frontend to check the file drop status before processing drops.

v3/pkg/application/application_darwin.go (6)

199-200: LGTM!

The new imports (sync and time) are necessary for the mutex protection and throttling logic in the drag-and-drop implementation.

---

441-461: LGTM! Race conditions properly addressed.

The mutex protection for dragOverJSBuffer (line 444) and the per-field mutex in dragThrottleState (line 455) correctly address the race conditions flagged in previous reviews. The synchronization strategy is sound: the global buffer mutex prevents concurrent buffer corruption, while per-window throttle state mutexes ensure thread-safe access to position tracking and timer management.

---

518-591: LGTM! Throttling and synchronization correctly implemented.

The function implements a sophisticated throttling strategy (5-pixel immediate threshold + 50ms debounce) with proper mutex protection. The locking pattern is correct: locks are released before calling sendDragUpdate (line 564) to avoid holding locks during potentially slow JS execution, and the timer callback uses InvokeSync (line 572) to ensure main-thread execution. This correctly addresses the race conditions flagged in previous reviews.

---

463-478: Confirm that clearWindowDragCache is called during window cleanup.

The function correctly clears per-window caches and stops pending timers with proper mutex synchronization. However, ensure this function is invoked when a window is destroyed to prevent memory leaks from accumulated windowImplCache and dragThrottle entries.

---

419-428: The code is correct. The ExecJS() method already handles runtime loading checks internally: if the runtime is not loaded, the JavaScript call is queued in pendingJS and executed automatically once the runtime becomes ready (rather than failing silently). No changes are needed.

---

593-665: LGTM! Zero-allocation optimization well-implemented.

The function uses effective caching and a protected pre-allocated buffer to achieve zero allocations in the hot path. The 128-byte buffer is appropriately sized (max usage ~54 bytes for int32 coordinates with the window._wails.handleDragOver() prefix), and buffer overflow is safely handled with an early return. The window lookup with fallback is robust. The execJSDragOver method is properly implemented to pass the buffer directly to C without additional allocations.