mirror of
https://github.com/wailsapp/wails.git
synced 2026-03-17 16:10:09 +01:00
53c2275fea* 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.
144 lines
4.4 KiB
Markdown
144 lines
4.4 KiB
Markdown
# AI Agent Instructions for Wails v3
|
|
|
|
## Issue Tracking with bd (beads)
|
|
|
|
**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
|
|
|
|
### Why bd?
|
|
|
|
- Dependency-aware: Track blockers and relationships between issues
|
|
- Git-friendly: Auto-syncs to JSONL for version control
|
|
- Agent-optimized: JSON output, ready work detection, discovered-from links
|
|
- Prevents duplicate tracking systems and confusion
|
|
|
|
### Quick Start
|
|
|
|
**Check for ready work:**
|
|
```bash
|
|
bd ready --json
|
|
```
|
|
|
|
**Create new issues:**
|
|
```bash
|
|
bd create "Issue title" -t bug|feature|task -p 0-4 --json
|
|
bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
|
|
bd create "Subtask" --parent <epic-id> --json # Hierarchical subtask (gets ID like epic-id.1)
|
|
```
|
|
|
|
**Claim and update:**
|
|
```bash
|
|
bd update bd-42 --status in_progress --json
|
|
bd update bd-42 --priority 1 --json
|
|
```
|
|
|
|
**Complete work:**
|
|
```bash
|
|
bd close bd-42 --reason "Completed" --json
|
|
```
|
|
|
|
### Issue Types
|
|
|
|
- `bug` - Something broken
|
|
- `feature` - New functionality
|
|
- `task` - Work item (tests, docs, refactoring)
|
|
- `epic` - Large feature with subtasks
|
|
- `chore` - Maintenance (dependencies, tooling)
|
|
|
|
### Priorities
|
|
|
|
- `0` - Critical (security, data loss, broken builds)
|
|
- `1` - High (major features, important bugs)
|
|
- `2` - Medium (default, nice-to-have)
|
|
- `3` - Low (polish, optimization)
|
|
- `4` - Backlog (future ideas)
|
|
|
|
### Workflow for AI Agents
|
|
|
|
1. **Check ready work**: `bd ready` shows unblocked issues
|
|
2. **Claim your task**: `bd update <id> --status in_progress`
|
|
3. **Work on it**: Implement, test, document
|
|
4. **Discover new work?** Create linked issue:
|
|
- `bd create "Found bug" -p 1 --deps discovered-from:<parent-id>`
|
|
5. **Complete**: `bd close <id> --reason "Done"`
|
|
6. **Commit together**: Always commit the `.beads/issues.jsonl` file together with the code changes so issue state stays in sync with code state
|
|
|
|
### Auto-Sync
|
|
|
|
bd automatically syncs with git:
|
|
- Exports to `.beads/issues.jsonl` after changes (5s debounce)
|
|
- Imports from JSONL when newer (e.g., after `git pull`)
|
|
- No manual export/import needed!
|
|
|
|
### GitHub Copilot Integration
|
|
|
|
If using GitHub Copilot, also create `.github/copilot-instructions.md` for automatic instruction loading.
|
|
Run `bd onboard` to get the content, or see step 2 of the onboard instructions.
|
|
|
|
### MCP Server (Recommended)
|
|
|
|
If using Claude or MCP-compatible clients, install the beads MCP server:
|
|
|
|
```bash
|
|
pip install beads-mcp
|
|
```
|
|
|
|
Add to MCP config (e.g., `~/.config/claude/config.json`):
|
|
```json
|
|
{
|
|
"beads": {
|
|
"command": "beads-mcp",
|
|
"args": []
|
|
}
|
|
}
|
|
```
|
|
|
|
Then use `mcp__beads__*` functions instead of CLI commands.
|
|
|
|
### Managing AI-Generated Planning Documents
|
|
|
|
AI assistants often create planning and design documents during development:
|
|
- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
|
|
- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
|
|
- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
|
|
|
|
**Best Practice: Use a dedicated directory for these ephemeral files**
|
|
|
|
**Recommended approach:**
|
|
- Create a `history/` directory in the project root
|
|
- Store ALL AI-generated planning/design docs in `history/`
|
|
- Keep the repository root clean and focused on permanent project files
|
|
- Only access `history/` when explicitly asked to review past planning
|
|
|
|
**Example .gitignore entry (optional):**
|
|
```
|
|
# AI planning documents (ephemeral)
|
|
history/
|
|
```
|
|
|
|
**Benefits:**
|
|
- Clean repository root
|
|
- Clear separation between ephemeral and permanent documentation
|
|
- Easy to exclude from version control if desired
|
|
- Preserves planning history for archeological research
|
|
- Reduces noise when browsing the project
|
|
|
|
### CLI Help
|
|
|
|
Run `bd <command> --help` to see all available flags for any command.
|
|
For example: `bd create --help` shows `--parent`, `--deps`, `--assignee`, etc.
|
|
|
|
### Important Rules
|
|
|
|
- Use bd for ALL task tracking
|
|
- Always use `--json` flag for programmatic use
|
|
- Link discovered work with `discovered-from` dependencies
|
|
- Check `bd ready` before asking "what should I work on?"
|
|
- Store AI planning docs in `history/` directory
|
|
- Run `bd <cmd> --help` to discover available flags
|
|
- **ALWAYS run `coderabbit --plain` before committing** to get code analysis and catch issues early
|
|
- Do NOT create markdown TODO lists
|
|
- Do NOT use external issue trackers
|
|
- Do NOT duplicate tracking systems
|
|
- Do NOT clutter repo root with planning documents
|
|
|
|
For more details, see README.md and QUICKSTART.md.
|