- Wrap `<=8` in backticks in changelog.mdx to prevent MDX interpreting
`<` as JSX element start
- Remove unsupported {#custom-id} syntax from heading in linux.mdx as
Starlight/Astro auto-generates heading IDs
This fixes the docs build failure in the Deploy to GitHub Pages workflow.
* 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.
* feat(macos): add CollectionBehavior option to MacWindow (#4756)
Add configurable NSWindowCollectionBehavior support for macOS windows,
allowing control over window behavior across Spaces and fullscreen.
New options include:
- MacWindowCollectionBehaviorCanJoinAllSpaces
- MacWindowCollectionBehaviorFullScreenAuxiliary
- MacWindowCollectionBehaviorMoveToActiveSpace
- And more...
This enables building Spotlight-like apps that appear on all Spaces
or overlay fullscreen applications.
Closes#4756🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Potential fix for code scanning alert no. 140: Workflow does not contain permissions
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
* Potential fix for code scanning alert no. 139: Workflow does not contain permissions
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
* feat(examples): add spotlight example for CollectionBehavior
Demonstrates creating a Spotlight-like launcher window that:
- Appears on all macOS Spaces
- Floats above other windows
- Uses accessory activation policy (no Dock icon)
- Has frameless translucent design
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* feat(macos): support bitwise OR for CollectionBehavior options
Update CollectionBehavior to use actual NSWindowCollectionBehavior
bitmask values, allowing multiple behaviors to be combined:
```go
CollectionBehavior: application.MacWindowCollectionBehaviorCanJoinAllSpaces |
application.MacWindowCollectionBehaviorFullScreenAuxiliary,
```
Changes:
- Update Go constants to use actual bitmask values (1<<0, 1<<1, etc.)
- Simplify C function to pass through combined bitmask directly
- Add ParticipatesInCycle, IgnoresCycle, FullScreenDisallowsTiling options
- Update documentation with combined behavior examples
- Update spotlight example to demonstrate combining behaviors
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
* docs: fix custom protocol association documentation
The documentation was incorrectly referencing `wails.json` with JSON format
when the actual configuration file is `build/config.yml` using YAML format.
Changes:
- Update config file reference from `wails.json` to `build/config.yml`
- Change format from JSON to YAML in code examples
- Fix structure: `protocols` is at root level, not nested under `info`
- Correct template variable references from `{{.Info.Protocols}}` to `{{.Protocols}}`
- Update Info.plist example to show actual generated format (`wails.com.scheme`)
- Add note about running `wails3 task common:update:build-assets` after changes
- Clean up redundant file path references in platform-specific sections
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: consolidate custom protocol docs and add Universal Links
- Remove duplicate custom-protocol-association.mdx
- Add Universal Links section to macOS tab
- Add Web-to-App Linking section to Windows tab
- Keep the more comprehensive distribution/custom-protocols.mdx
Addresses review comment about duplicate documentation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat(windows): add custom protocol support to MSIX packaging
- Add uap3 namespace and protocol extension to MSIX template
- Protocols defined in build/config.yml are now automatically
registered when building MSIX packages
- Update docs with MSIX section and clarify Web-to-App linking
requires manual manifest configuration
🤖 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>
* Enhance bindings generation documentation
Added TypeScript option and help command for bindings generation.
* Update UNRELEASED_CHANGELOG with new events and docs
Updated the changelog to include new WebKit2 load-change events and additional documentation for frontend bindings.
---------
Co-authored-by: Lea Anthony <lea.anthony@gmail.com>
* Refactor asset-server documentation for clarity
Updated references from 'frontend/Taskfile.yml' to 'build/Taskfile.yml' and adjusted environment variable names for clarity. Enhanced the explanation of how the dev proxy works and clarified the roles of the tasks in the templates.
* Update changelog
* Apply suggestion from @coderabbitai[bot]
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
---------
Co-authored-by: Lea Anthony <lea.anthony@gmail.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* All the documentation files have been updated. Here's a summary of the changes I made:
## Summary of Documentation Updates
### Key API Corrections Made:
1. **Dialog Creation**:
- Changed `app.InfoDialog()` → `application.InfoDialog()` (package-level functions)
- Also documented `app.Dialog.Info()` via DialogManager
2. **Question Dialog Buttons**:
- Removed non-existent `SetButtons("Save", "Don't Save", "Cancel")` method
- Now uses `AddButton("label")` which returns a `*Button`
- Button callbacks via `button.OnClick(func() { ... })`
3. **Default/Cancel Buttons**:
- Changed `SetDefaultButton("Cancel")` (string) → `SetDefaultButton(cancelBtn)` (`*Button`)
- Changed `SetCancelButton("Cancel")` (string) → `SetCancelButton(cancelBtn)` (`*Button`)
- Also documented fluent `SetAsDefault()` and `SetAsCancel()` methods on Button
4. **File Dialog Filters**:
- Changed `SetFilters([]application.FileFilter{...})` → `AddFilter("Display Name", "*.ext;*.ext2")`
5. **Save Dialog Filename**:
- Changed `SetDefaultFilename()` → `SetFilename()`
6. **Folder Selection**:
- Removed non-existent `app.SelectFolderDialog()`
- Now uses `application.OpenFileDialog().CanChooseDirectories(true).CanChooseFiles(false)`
7. **Show() Return Value**:
- Removed incorrect `result, err := dialog.Show()` pattern
- `Show()` returns nothing - responses are handled via button callbacks
### Files Modified:
- `docs/src/content/docs/features/dialogs/message.mdx` - Complete rewrite of question dialog examples
- `docs/src/content/docs/features/dialogs/overview.mdx` - Updated all code examples
- `docs/src/content/docs/features/dialogs/file.mdx` - Updated file dialog examples
- `v3/UNRELEASED_CHANGELOG.md` - Added changelog entry
* All changes are complete. Here's a summary of what was updated:
## Summary
I've updated the Wails v3 dialogs documentation to match the actual API. The documentation now consistently uses:
### DialogManager Pattern (Recommended)
- `app.Dialog.Info()`, `app.Dialog.Question()`, `app.Dialog.Warning()`, `app.Dialog.Error()`
- `app.Dialog.OpenFile()`, `app.Dialog.SaveFile()`
This is consistent with other runtime features like `app.Window`, `app.Event`, etc.
### Key API Corrections
1. **Dialog Creation**: Both `app.Dialog.*()` (DialogManager) and `application.*Dialog()` (package-level) are documented
2. **Question Dialog Buttons**: Use `AddButton("label")` which returns `*Button`, then `button.OnClick(callback)`
3. **Default/Cancel Buttons**: `SetDefaultButton(button)` and `SetCancelButton(button)` take `*Button` pointers
4. **File Filters**: Use `AddFilter("Display Name", "*.ext")` instead of `SetFilters()`
5. **Save Dialog Filename**: Use `SetFilename()` instead of `SetDefaultFilename()`
6. **Folder Selection**: Use `app.Dialog.OpenFile().CanChooseDirectories(true).CanChooseFiles(false)`
### Files Modified
- `docs/src/content/docs/features/dialogs/overview.mdx`
- `docs/src/content/docs/features/dialogs/message.mdx`
- `docs/src/content/docs/features/dialogs/file.mdx`
- `v3/UNRELEASED_CHANGELOG.md`
* Audit complete! All documentation files now consistently use `app.Dialog.*` for all code examples. Here's the summary:
## Audit Complete
All dialog documentation has been updated to consistently use the `app.Dialog.*` pattern:
### Changes Made:
**message.mdx:**
- All examples now use `app.Dialog.Info()`, `app.Dialog.Question()`, `app.Dialog.Warning()`, `app.Dialog.Error()`
- Function signatures updated to accept `app *application.App` parameter
- Nested dialog calls within callbacks also updated
**file.mdx:**
- All examples now use `app.Dialog.OpenFile()`, `app.Dialog.SaveFile()`
- Function signatures updated to accept `app *application.App` parameter
- All error/info dialogs within file operations also updated
**overview.mdx:**
- Already consistent from earlier edits
### Documentation Structure:
Each file now properly documents both approaches in a dedicated section:
```go
// Via DialogManager (recommended when you have an app instance):
app.Dialog.Info()
app.Dialog.OpenFile()
// Package-level functions (useful in callbacks or when app isn't in scope):
application.InfoDialog()
application.OpenFileDialog()
```
But all code examples use the `app.Dialog.*` pattern for consistency with other runtime features like `app.Window`, `app.Event`, etc.
* docs: Fix reference/dialogs.mdx and reference/application.mdx API documentation
Updated docs to match actual Wails v3 Dialogs API:
- reference/dialogs.mdx: Complete rewrite with correct API
- Use `app.Dialog.OpenFile()` and `app.Dialog.SaveFile()` instead of `app.OpenFileDialog()`
- Use `AddFilter("name", "pattern")` instead of `SetFilters([]FileFilter{...})`
- Use `SetFilename()` instead of `SetDefaultFilename()`
- Use `SetDirectory()` instead of `SetDefaultDirectory()`
- Remove non-existent `SelectFolderDialog()` - use `OpenFile().CanChooseDirectories(true).CanChooseFiles(false)`
- Use `AddButton()` with callbacks instead of `SetButtons()`
- Use `SetDefaultButton(*Button)` instead of `SetDefaultButton(int)`
- Document that `Show()` returns nothing, use callbacks
- reference/application.mdx: Fix Dialog Methods section
- Use `app.Dialog.*` manager pattern
- Show correct Question dialog with button callbacks
- Fix file dialog examples with `AddFilter()`
- Remove `SelectFolderDialog()` reference
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: Remove package-level dialog function references
Remove all references to package-level dialog functions
(application.InfoDialog(), application.OpenFileDialog(), etc.)
from documentation. Only the app.Dialog manager pattern
should be used.
Updated files:
- reference/dialogs.mdx
- features/dialogs/overview.mdx
- features/dialogs/message.mdx
- features/dialogs/file.mdx
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: Remove package-level dialog functions in favor of app.Dialog manager
BREAKING CHANGE: Remove package-level dialog functions. Use app.Dialog manager instead.
Removed functions:
- application.InfoDialog()
- application.QuestionDialog()
- application.WarningDialog()
- application.ErrorDialog()
- application.OpenFileDialog()
- application.SaveFileDialog()
Use the Dialog manager pattern instead:
- app.Dialog.Info()
- app.Dialog.Question()
- app.Dialog.Warning()
- app.Dialog.Error()
- app.Dialog.OpenFile()
- app.Dialog.SaveFile()
This aligns dialogs with other runtime managers like app.Window and app.Event.
Updated files:
- v3/pkg/application/application.go - Remove exported dialog functions
- v3/pkg/application/dialog_manager.go - Use internal newMessageDialog/newOpenFileDialog
- v3/pkg/application/messageprocessor_dialog.go - Use internal dialog constructors
- v3/examples/* - Update all examples to use app.Dialog pattern
- v3/internal/commands/appimage_testfiles/main.go - Update test file
- v3/UNRELEASED_CHANGELOG.md - Document breaking change
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Use application.Get() in dialogs-basic example and correct filter docs
- Update dialogs-basic helper functions to use application.Get() instead
of passing app through function parameters
- Fix incorrect documentation claiming space/comma delimiters work for
filter patterns (only semicolons are supported)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
fix(macos): fix print dialog not opening and add Window.Print() to runtime (#4290)
The print dialog was not opening on macOS because the CGO windowPrint function was passing the wrong pointer type to NSPrintOperation's runOperationModalForWindow method. It was passing the raw void* window instead of the properly cast WebviewWindow* nsWindow.
This also adds a Window.Print() method to the JavaScript runtime, allowing frontend code to trigger the print dialog directly without needing a Go binding.
Changes:
- Fix webview_window_darwin.go to use nsWindow instead of window
- Add WindowPrint constant (51) and handler to messageprocessor_window.go
- Add Print() method to window.ts in the runtime
- Rebuild bundled runtime (runtime.js and runtime.debug.js)
- Add print example in v3/examples/print to demonstrate both Go API and JS runtime methods
- Update API documentation for Window.Print() in both Go and JavaScript references
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
* 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>
Modern Linux distributions (Arch, Fedora 39+, Ubuntu 24.04+) compile
libraries with .relr.dyn ELF sections. The bundled strip binary in
linuxdeploy cannot process these sections, causing AppImage builds to fail.
This commit:
- Adds hasRelrDynSections() to proactively detect modern toolchains
- Automatically disables stripping (NO_STRIP=1) when detected
- Fixes error output to properly display as string
- Adds documentation explaining the issue and workaround
Fixes#4642🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Modern Linux distributions (Arch, Fedora 39+, Ubuntu 24.04+) compile
libraries with .relr.dyn ELF sections. The bundled strip binary in
linuxdeploy cannot process these sections, causing AppImage builds to fail.
This commit:
- Adds hasRelrDynSections() to proactively detect modern toolchains
- Automatically disables stripping (NO_STRIP=1) when detected
- Fixes error output to properly display as string
- Adds documentation explaining the issue and workaround
Fixes#4642🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit integrates iOS platform support for Wails v3, adapting the
iOS-specific code to work with the new transport layer architecture.
Key changes:
- Add iOS-specific application, webview, and runtime files
- Add iOS event types and processing
- Add iOS examples and templates
- Update messageprocessor to handle iOS requests
- Move badge_ios.go to dock package
Note: The iOS branch was based on an older v3-alpha and required
significant conflict resolution due to the transport layer refactor
(PR #4702). Some iOS-specific code may need further adaptation:
- processIOSMethod needs to be implemented with new RuntimeRequest signature
- iOS event generation in tasks/events/generate.go needs updating
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace <Aside type="caution"> JSX with :::caution markdown syntax
to fix the docs build error.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Update `RawMessageHandler` to include `originInfo` parameter in documentation
- Expanded examples and handler signature to reflect the additional `originInfo` parameter.
- Detailed `OriginInfo` structure and its platform-specific behaviors added.
* Expand `raw-messages` documentation to include origin validation guidance
* Rename `HandleCustomProtocol` to `HandleOpenURL` and add universal link support on macOS.
* Update changelog.
* add docs
* add docs
---------
Co-authored-by: Lea Anthony <lea.anthony@gmail.com>
- Add RawMessageHandler section to Application API reference
- Add System.invoke() to Frontend Runtime reference
- Create comprehensive Raw Messages guide
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Replace incorrect OnStartup hook with actual v3 lifecycle mechanisms
- Document Services with ServiceStartup/ServiceShutdown interfaces
- Document application-level hooks: ShouldQuit, OnShutdown, PostShutdown
- Document event-based lifecycle with OnApplicationEvent and OnWindowEvent
- Document window hooks with RegisterHook for cancellable events
- Add correct platform-specific defaults for quit-on-last-window-close
- Add JavaScript example to services Quick Start
- Make Taskfile dev task depend on setup task
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Install D2 binary in GitHub Actions before building docs
- Remove DEVELOPER_GUIDE.md temporary file from docs content
- This fixes the docs build failure on GitHub Pages
This commit represents a complete redesign of the Wails v3 documentation structure
and includes all recent v3-alpha updates.
## Major Changes
### Documentation Restructure
- Migrated from /learn to organized /features, /guides, /reference structure
- Created new Quick Start section with installation and first app guides
- Added comprehensive Concepts section explaining architecture and lifecycle
- Reorganized Contributing section with detailed guides for different contribution types
- Added complete API Reference with separate pages for each major component
### New Documentation
- Custom URL Protocols guide with NSIS automatic registration
- Windows Packaging guide with NSIS, MSI, and MSIX options
- Typed Events system with TypeScript binding generation
- Complete menu documentation (Application, Context, System Tray)
- Comprehensive dialog documentation (File, Message, Custom)
- Window management guides (Basics, Events, Frameless, Multiple Windows)
- Bindings documentation (Services, Methods, Models, Best Practices)
- New tutorials: Todo app and Notes app (vanilla JS)
### v3-alpha API Updates
- Typed Events: RegisterEvent[T] with strict mode and binding generation
- Custom Protocols: NSIS macros for automatic Windows protocol registration
- System Tray: Windows Show/Hide now fully functional with tooltip limits
- Window Hidden: Fixed white flash on Windows when creating hidden windows
- Notifications: Corrected import path to pkg/services/notifications
- Frontend Runtime: Events.Emit now returns Promise<boolean> for cancellation
### Documentation Improvements
- Updated all code examples to use @wailsio/runtime imports
- Added platform-specific event tables and examples
- Created comprehensive event reference with use cases
- Added security best practices and validation patterns
- Improved code examples with real-world use cases
- Added troubleshooting sections and common patterns
### Files
- Created: 60+ new documentation pages
- Deleted: Old /learn structure (13 files)
- Modified: 15 existing files for v3-alpha compatibility
- Added: Tutorial assets and showcase images
* Add strong event typings
* Make `EmitEvent` take one data argument only
* Add event registration logic
* Report event cancellation to the emitter
* Prevent registration of system events
* Add support for typed event data initialisation
* Binding generation for events
* Tests for event bindings
* Add vite plugin for typed events
* Fix dev command execution order
Co-authored-by: Fabio Massaioli <fabio.massaioli@gmail.com>
* Propagate module path to templates
* Update templates
Co-authored-by: Ian VanSchooten <ian.vanschooten@gmail.com>
* Go mod tidy for examples
* Switch to tsconfig.json for jetbrains IDE support
* Replace jsconfig in example
* Convert vite plugin to typescript
* Downgrade vite for now
The templates all use 5.x
* Remove root plugins dir from npm files
It's now '/dist/plugins'
* Include types for Create
But keep out of the docs
* Assign a type for cancelAll results
* Restore variadic argument in EmitEvent methods
* Support registered events with void data
* Test cases for void alias support
* Support strict mode
* Support custom event hooks
* Update docs
* Update changelog
* Testdata for typed events
* Test data for void alias support
* fix webview_window emit event
* Update changelog.mdx
* Update events
* Fix generator test path normalization for cross-platform compatibility
The generator tests were failing on CI because they compared absolute file paths
in warning messages. These paths differ between development machines and CI environments.
Changes:
- Normalize file paths in warnings to be relative to testcases/ directory
- Handle both Unix and Windows path separators
- Use Unix line endings consistently in test output
- Update all test expectation files to use normalized paths
This ensures tests pass consistently across different environments including
Windows, macOS, Linux, and CI systems.
* Remove stale comment
* Handle errors returned from validation
* Restore variadic argument to Emit (fix bad rebase)
* Event emitters return a boolean
* Don't use `EmitEvent` in docs
Supposedly it's for internal use, according to comment
* Fix event docs (from rebase)
* Ensure all templates specify @wailsio/runtime: "latest"
* Fix Windows test failure due to CRLF line endings
The test was failing on Windows because:
1. Hardcoded "\n" was being used instead of render.Newline when writing
warning logs, causing CRLF vs LF mismatch
2. The render package import was missing
3. .got.log files weren't being skipped when building expected file list
Changes:
- Add render package import
- Use render.Newline instead of hardcoded "\n" for cross-platform compatibility
- Skip .got.log files in test file walker
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix template tests by using local runtime package
The template tests were failing because they were installing @wailsio/runtime@latest from npm, which doesn't have the new vite plugin yet. This change packs the local runtime and uses it in template tests instead.
Changes:
- Pack the runtime to a tarball in test_js job
- Upload the runtime package as an artifact
- Download and install the local runtime in template tests before building
- Update cleanup job to delete the runtime package artifact
* Apply suggestion from @leaanthony
* Fix: Install local runtime in frontend directory with correct path
The previous fix wasn't working because:
1. npm install was run in the project root, not in frontend/
2. wails3 build runs npm install again, which would reinstall from npm
Fixed by:
- Using npm pkg set to modify package.json to use file:// protocol
- This ensures subsequent npm install calls use the local tarball
* Fix Vue template syntax conflicts with Go template delimiters
The Vue templates were converted to .tmpl files to support dynamic module
paths, but Vue's template syntax {{ }} conflicts with Go's template syntax.
Fixed by escaping Vue template braces:
- {{ becomes {{"{{"}}
- }} becomes {{"}}"}}
This allows the Go template engine to output the literal {{ }} for Vue to process.
* Fix Vue template escaping and Windows shell compatibility
Two issues fixed:
1. Vue template escaping: Changed from {{"{{"}} to {{ "{{" }}
- The previous syntax caused "missing value for command" error
- Correct Go template syntax uses spaces between delimiters and strings
2. Windows PowerShell compatibility: Added 'shell: bash' to template generation step
- The bash syntax (ls, head, $()) doesn't work in PowerShell
- Git Bash is available on all GitHub runners including Windows
* Fix: test_templates depends on test_js for runtime package artifact
The runtime-package artifact is created in test_js job, not test_go.
Added test_js to the needs array so the artifact is available for download.
* Fix Windows path compatibility for runtime package artifact
Changed from absolute Unix path '/tmp/wails-runtime' to relative path
'wails-runtime-temp' which works cross-platform. Using realpath to
convert to absolute path for file:// URL in npm pkg set command.
* Fix realpath issue on Windows for runtime package
realpath on Windows Git Bash was producing malformed paths with duplicate
drive letters (D:\d\a\...). Replaced with portable solution using pwd
that works correctly across all platforms.
* Use pwd -W on Windows to get native Windows paths
Git Bash's pwd returns Unix-style paths (/d/a/wails/wails) which npm
then incorrectly resolves as D:/d/a/wails/wails. Using pwd -W returns
native Windows paths (D:\a\wails\wails) that npm can handle correctly.
This is the root cause of all the Windows path issues.
* Improve typechecking for Events.Emit()
* [docs] Clarify where `Events` is imported from in each example
* Add docs for runtime Events.Emit()
* Revert to v2-style Events.Emit (name, data)
* Update changelog
---------
Co-authored-by: Fabio Massaioli <fabio.massaioli@gmail.com>
Co-authored-by: Atterpac <Capretta.Michael@gmail.com>
Co-authored-by: Lea Anthony <lea.anthony@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
