* fix(v3): overhaul drag-and-drop for Linux reliability and simplify Windows
This commit fixes drag-and-drop reliability on Linux and simplifies the
Windows implementation.
## Linux
- Rewrite GTK drag handlers to properly intercept external file drops
- Fix HTML5 internal drag-and-drop being broken when file drop enabled
- Add hover effects during file drag operations
- Fix multiple app instances interfering with each other
## Windows
- Remove native IDropTarget in favor of JavaScript approach (matches v2)
- File drops now handled via chrome.webview.postMessageWithAdditionalObjects
## All Platforms
- Rename EnableDragAndDrop to EnableFileDrop
- Rename data-wails-drop-target to data-file-drop-target
- Rename wails-drop-target-active to file-drop-target-active
- Add comprehensive drag-and-drop documentation
## Breaking Changes
- EnableDragAndDrop -> EnableFileDrop
- data-wails-dropzone -> data-file-drop-target
- wails-dropzone-hover -> file-drop-target-active
- DropZoneDetails -> DropTargetDetails
- Remove WindowDropZoneFilesDropped event (use WindowFilesDropped)
* feat(macos): optimize drag event performance with debouncing and caching
- Add 50ms debouncing to limit drag events to 20/sec (was 120/sec)
- Implement window implementation caching to avoid repeated lookups
- Maintain existing 5-pixel threshold for immediate response
- Keep zero-allocation path with pre-allocated buffers
- Rename linuxDragActive to nativeDragActive for clarity
- Update IMPLEMENTATION.md with optimization details and Windows guidance
Performance improvements:
- 83% reduction in event frequency
- ~6x reduction in CPU/memory usage during drag operations
- Maintains smooth visual feedback with InvokeSync for timer callbacks
* fix(windows): implement proper file drop support for Windows
- Remove incorrect AllowExternalDrag(false) call that was blocking file drops
- Fix message prefix from 'FilesDropped' to 'file:drop:' to match JS runtime
- Fix coordinate parsing for 'file:drop:x:y' format (indices 2,3 not 1,2)
- Add enableFileDrop flag injection to JS runtime during navigation
- Update JS runtime to check enableFileDrop flag before processing drops
- Always call preventDefault() to stop browser navigation on file drags
- Show 'no drop' cursor when file drops are disabled
- Update example to filter file drags from HTML drop zone handlers
- Add documentation for combining file drop with HTML drag-and-drop
* fix(v3): block file drops on Linux when EnableFileDrop is false
- Add disableDND() to intercept and reject external file drags at GTK level
- Show 'no drop' cursor when files are dragged over window
- Allow internal HTML5 drag-and-drop to work normally
- Initialize _wails.flags object in runtime core to prevent undefined errors
- Inject enableFileDrop flag on Linux and macOS (matching Windows)
- Fix bare _wails reference to use window._wails
- Update docs with info about blocked drops and combining with HTML DnD
* fix(darwin): add missing fmt import in webview_window_darwin.go
* fix(macOS): implement hover effects for file drag-and-drop with optimizations
- Added draggingUpdated: handler to track mouse movement during drag operations
- Implemented macosOnDragEnter/Exit/Over export functions for real-time hover state
- Fixed JS function call from '_wails.handlePlatformFileDrop' to correct 'wails.Window.HandlePlatformFileDrop'
- Added EnableFileDrop flag checks to prevent hover effects when file drops are disabled
- Renamed linuxDragActive to nativeDragActive for cross-platform consistency
Performance optimizations:
- Added 50ms debounce to reduce event frequency from ~120/sec to ~20/sec
- Implemented 5-pixel movement threshold for immediate response
- Added window caching with sync.Map to avoid repeated lookups
- Zero-allocation JavaScript calls with pre-allocated 128-byte buffer
- Reduced memory usage to ~18 bytes per event (6x reduction)
Build improvements:
- Updated runtime Taskfile to include documentation generation
- Added docs:build task to runtime build process
- Fixed build order: events → docs → runtime
Documentation:
- Added IMPLEMENTATION.md with optimization details
- Included guidance for Windows implementation
* chore(v3/examples): remove html-dnd-api example
The drag-n-drop example now demonstrates both external file drops
and internal HTML5 drag-and-drop, making this separate example redundant.
* docs(v3): move drag-and-drop implementation details to runtime-internals
- Add drag-and-drop section to contributing/runtime-internals.mdx
- Remove IMPLEMENTATION.md from example (content now in proper docs)
- Covers platform differences, debugging tips, and key files
* fix(v3): remove html-dnd-api from example build list
* fix(v3): remove duplicate json import in application_darwin.go
* fix(v3): address CodeRabbit review feedback
- Fix docs to use app.Window.NewWithOptions() instead of deprecated API
- Add mutex protection to dragOverJSBuffer to prevent race conditions
- Add mutex protection to dragThrottleState fields for thread safety
* docs: add coderabbit pre-push requirement to AGENTS.md
* fix(v3/test): use correct CSS class name file-drop-target-active
* chore(v3/test): remove dnd-test directory
This was a development test file that shouldn't be in the PR.
The drag-n-drop example serves as the proper test case.
* docs(v3): update Windows file drop comment to reflect implemented fix
Remove stale TODO - enableFileDrop flag is now injected in navigationCompleted
* refactor(v3): make handleDragAndDropMessage unexported
Internal method only called by application event loop, not part of public API.
* All changes are complete. Here's a summary of what was implemented for issue #3896:
## Summary
Added four new WebKit2 load-change events for Linux to match WebKitGTK's documented load-change signals:
### New Events
| Event | ID | WebKit Signal | Description |
|-------|-----|---------------|-------------|
| `WindowLoadStarted` | 1059 | `WEBKIT_LOAD_STARTED` | Fired when page load begins |
| `WindowLoadRedirected` | 1060 | `WEBKIT_LOAD_REDIRECTED` | Fired when a redirect occurs |
| `WindowLoadCommitted` | 1061 | `WEBKIT_LOAD_COMMITTED` | Fired when load is committed |
| `WindowLoadFinished` | 1062 | `WEBKIT_LOAD_FINISHED` | Fired when load completes |
### Files Modified
1. **`v3/pkg/events/events.go`** - Added new event types to `linuxEvents` struct and updated all platform event IDs (Mac, Windows, iOS shifted by +4 to accommodate new Linux events)
2. **`v3/pkg/events/events_linux.h`** - Added C defines for new events
3. **`v3/pkg/application/linux_cgo.go`** - Updated `handleLoadChanged()` to dispatch all four load events
4. **`v3/UNRELEASED_CHANGELOG.md`** - Documented the new feature
### Backward Compatibility
- The existing `WindowLoadChanged` event (1058) continues to fire on `WEBKIT_LOAD_FINISHED` for backward compatibility
- `WindowLoadFinished` also fires on `WEBKIT_LOAD_FINISHED` for consistent naming with the new events
Would you like me to commit these changes?
* These are the remaining changes that need to be committed - the generator properly updated:
1. `events.txt` - source of truth for events
2. `event_types.ts` - TypeScript runtime types for JS/TS clients
3. `events_darwin.h` - Mac C header with updated event IDs
4. `events_ios.h` - iOS C header with updated event IDs
These are the final changes needed on top of the previous commit. Would you like me to commit these changes?
* chore: add new Linux WebKit2 load events to known_events.go
Add WindowLoadStarted, WindowLoadRedirected, WindowLoadCommitted,
and WindowLoadFinished to the known events registry.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: add Linux WebKit2 load events to events-reference guide
Document the new WindowLoadStarted, WindowLoadRedirected,
WindowLoadCommitted, and WindowLoadFinished events in the
Linux Events section of the events reference guide.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Update UNRELEASED_CHANGELOG
* refactor(linux): remove deprecated WindowLoadChanged event
Remove the legacy WindowLoadChanged event and replace all internal
references with WindowLoadFinished. This simplifies the event system
by having granular events (LoadStarted, LoadRedirected, LoadCommitted,
LoadFinished) rather than a generic LoadChanged that fired on any state.
- Remove WindowLoadChanged from events.go and event_types.ts
- Update linux_cgo.go to only fire WindowLoadFinished
- Update webview_window_linux.go hooks to use WindowLoadFinished
- Regenerate runtime bundles and known_events
- Update events documentation
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: add breaking change note for WindowLoadChanged removal
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
* new events
* macOS dnd improvements
* wailsio adds for dropzone
* update example
* sorta working
the top 300px of the window are not dropabble for some reason i suspect it has to do with the drag enter/drag leave xy as the performOperation needed to use the ContentView for appropriate X/Y
* implement attribute detection for data-wails-dropzone
* docs
* pass x/y dnd linux
* cleanup exmample
* changelog
* pass all attributes to golang on dragdrop
* filetree example
* fix dnd build windows
* Fix windows dnd
* update docs
* remove debug log
* appease the security bot
* Fix changelog
* Fix changelog
* Revert "Fix event generation issues."
This reverts commit ae4ed4fe
* Fix events
* Fix merge conflicts. Fix events generation formatting
* Update docs
* Fix duplicate bundledassets import causing build failures
Remove duplicate import of bundledassets package that was causing
compilation errors in PR #4318. The import was declared twice in
the same import block, causing "bundledassets redeclared" errors.
Fixes build issues in GitHub Actions for drag-and-drop zones feature.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Replace fmt.Printf debug statements with globalApplication.debug
Replace all fmt.Printf debug logging statements in drag-and-drop
functionality with proper globalApplication.debug calls. This provides:
- Consistent logging with the rest of the application
- Proper key-value structured logging
- Better integration with the application's logging system
- Cleaner debug output format
Changes:
- application_darwin.go: Replace 2 fmt.Printf calls
- webview_window.go: Replace 6 fmt.Printf calls
- webview_window_windows.go: Replace 13 fmt.Printf calls
- Remove unused fmt import from application_darwin.go
All debug messages maintain the same information but now use
structured logging with key-value pairs instead of printf formatting.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Add nil checks to WindowEventContext methods
Ensure all WindowEventContext methods properly handle nil c.data
by initializing the map when it's nil. This prevents panics when
methods are called on contexts that haven't been properly initialized.
Changes:
- DroppedFiles(): Add nil check and map initialization
- setCoordinates(): Add nil check and map initialization
- setDropZoneDetails(): Add nil check and map initialization
- DropZoneDetails(): Add nil check and map initialization
All methods now follow the same pattern as setDroppedFiles()
where a nil data map is automatically initialized to prevent
runtime panics during drag-and-drop operations.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Update v3/pkg/application/webview_window_darwin.m
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* reinstate events docs.
---------
Co-authored-by: Lea Anthony <lea.anthony@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* [linux] emit system specific event for theme change
Code was incorrectly emitting the `events.Common.ThemeChanged` event
instead of the OS Specific `events.Linux.SystemThemeChanged` event.
It is the reponsibility of the code in events_common_linux.go to map
it to the common variety.
* [linux] implement WindowDidMove
* [linux] implement debounce for WindowDidMove
* [example] listen for events.Common.WindowDidMove
* [windows] move WindowDidMove mapper outside of DnD guard
* WindowDidResize implementation
* windows: WindowDidResize
* chore: changelog update
* events.Common.WindowDidMove and events.Common.WindowDidResize
