fix: restore events.go from v3-alpha to fix compilation errors

The iOS branch modified events.go with debug println statements and
changed the EventProcessor.Emit signature from returning error to void.
This broke compatibility with event_manager.go and messageprocessor_events.go.

Restored the v3-alpha version which:
- Uses atomic.Bool for cancelled flags (thread-safe)
- Has EventProcessor.Emit return error for validation
- Includes decodeEventData and validateCustomEvent functions
- Removes debug println statements

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.all-contributorsrc

@@ -1,6 +1,7 @@
 {
   "files": [
-    "website/src/pages/credits.mdx"
+    "website/src/pages/credits.mdx",
+    "docs/src/assets/contributors.html"
   ],
   "imageSize": 75,
   "commit": false,

.coderabbit.yaml

@@ -0,0 +1,71 @@
+language: en-US
+tone_instructions: ''
+early_access: false
+enable_free_tier: true
+reviews:
+  profile: chill
+  request_changes_workflow: false
+  high_level_summary: true
+  high_level_summary_placeholder: '@coderabbitai summary'
+  auto_title_placeholder: '@coderabbitai'
+  review_status: true
+  poem: true
+  collapse_walkthrough: false
+  sequence_diagrams: true
+  path_filters: []
+  path_instructions: []
+  abort_on_close: true
+  auto_review:
+    enabled: true
+    auto_incremental_review: true
+    ignore_title_keywords: []
+    labels: []
+    drafts: false
+    base_branches: ['v3-alpha', 'master']
+  tools:
+    shellcheck:
+      enabled: true
+    ruff:
+      enabled: true
+    markdownlint:
+      enabled: true
+    github-checks:
+      enabled: true
+      timeout_ms: 90000
+    languagetool:
+      enabled: true
+      enabled_only: false
+      level: default
+    biome:
+      enabled: true
+    hadolint:
+      enabled: true
+    swiftlint:
+      enabled: true
+    phpstan:
+      enabled: true
+      level: default
+    golangci-lint:
+      enabled: true
+    yamllint:
+      enabled: true
+    gitleaks:
+      enabled: true
+    checkov:
+      enabled: true
+    detekt:
+      enabled: true
+    eslint:
+      enabled: true
+chat:
+  auto_reply: true
+knowledge_base:
+  opt_out: false
+  learnings:
+    scope: auto
+  issues:
+    scope: auto
+  jira:
+    project_keys: []
+  linear:
+    team_keys: []

.crush/logs/crush.log

@@ -0,0 +1,63 @@
+{"time":"2025-08-27T20:12:32.005147+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.loadProviders","file":"/home/runner/work/crush/crush/internal/config/provider.go","line":113},"msg":"Getting live provider data"}
+{"time":"2025-08-27T20:12:32.261507+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.saveProvidersInCache","file":"/home/runner/work/crush/crush/internal/config/provider.go","line":48},"msg":"Saving cached provider data","path":"/Users/leaanthony/.local/share/crush/providers.json"}
+{"time":"2025-08-27T20:12:32.809036+10:00","level":"INFO","msg":"OK   20250424200609_initial.sql (926.42µs)"}
+{"time":"2025-08-27T20:12:32.809376+10:00","level":"INFO","msg":"OK   20250515105448_add_summary_message_id.sql (267.96µs)"}
+{"time":"2025-08-27T20:12:32.809554+10:00","level":"INFO","msg":"OK   20250624000000_add_created_at_indexes.sql (166.92µs)"}
+{"time":"2025-08-27T20:12:32.80977+10:00","level":"INFO","msg":"OK   20250627000000_add_provider_to_messages.sql (206.75µs)"}
+{"time":"2025-08-27T20:12:32.809775+10:00","level":"INFO","msg":"goose: successfully migrated database to version: 20250627000000"}
+{"time":"2025-08-27T20:12:32.811691+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.(*App).initLSPClients","file":"/home/runner/work/crush/crush/internal/app/lsp.go","line":18},"msg":"LSP clients initialization started in background"}
+{"time":"2025-08-27T20:12:32.834348+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.NewAgent.func1","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":172},"msg":"Initializing agent tools","agent":"task"}
+{"time":"2025-08-27T20:12:32.834614+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.NewAgent.func1.1","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":174},"msg":"Initialized agent tools","agent":"task"}
+{"time":"2025-08-27T20:12:32.854168+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.NewAgent.func1","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":172},"msg":"Initializing agent tools","agent":"coder"}
+{"time":"2025-08-27T20:12:32.854196+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.NewAgent.func1.1","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":174},"msg":"Initialized agent tools","agent":"coder"}
+{"time":"2025-08-27T20:12:38.134601+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.NewAgent.func1","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":172},"msg":"Initializing agent tools","agent":"task"}
+{"time":"2025-08-27T20:12:38.134666+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.NewAgent.func1.1","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":174},"msg":"Initialized agent tools","agent":"task"}
+{"time":"2025-08-27T20:12:38.152548+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.NewAgent.func1","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":172},"msg":"Initializing agent tools","agent":"coder"}
+{"time":"2025-08-27T20:12:38.152586+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.NewAgent.func1.1","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":174},"msg":"Initialized agent tools","agent":"coder"}
+{"time":"2025-08-27T20:12:41.898847+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"tool_0_ls","name":"ls","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:12:44.654937+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_47d3af89db484e90aecb719f","name":"glob","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:12:44.74985+10:00","level":"WARN","source":{"function":"github.com/charmbracelet/crush/internal/llm/tools.init.func1","file":"/home/runner/work/crush/crush/internal/llm/tools/rg.go","line":18},"msg":"Ripgrep (rg) not found in $PATH. Some grep features might be limited or slower."}
+{"time":"2025-08-27T20:12:49.683952+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_fe83dadd3dfd45e29a728688","name":"glob","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:12:53.584685+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_6eefca8b220343ac94df8971","name":"glob","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:12:57.730662+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_ecc886d655e445739185acc6","name":"glob","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:13:01.348247+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_998a53a38d16406fba49df1c","name":"bash","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:13:05.122118+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/shell.(*loggingAdapter).InfoPersist","file":"/home/runner/work/crush/crush/internal/shell/persistent.go","line":36},"msg":"POSIX command finished","command":"cat /Users/leaanthony/test/wails/.gitignore","err":null}
+{"time":"2025-08-27T20:13:07.978018+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"tool_0_bash","name":"bash","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:13:08.019929+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/shell.(*loggingAdapter).InfoPersist","file":"/home/runner/work/crush/crush/internal/shell/persistent.go","line":36},"msg":"POSIX command finished","command":"ls -la /Users/leaanthony/test/wails/v2/tools/","err":null}
+{"time":"2025-08-27T20:13:13.397674+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).Cancel","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":240},"msg":"Request cancellation initiated","session_id":"35c12659-36c0-4ef8-a15d-6d4adc6106ba"}
+{"time":"2025-08-27T20:14:53.933154+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.loadProviders","file":"/home/runner/work/crush/crush/internal/config/provider.go","line":99},"msg":"Using cached provider data","path":"/Users/leaanthony/.local/share/crush/providers.json"}
+{"time":"2025-08-27T20:14:53.934325+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.loadProviders.func1","file":"/home/runner/work/crush/crush/internal/config/provider.go","line":103},"msg":"Updating provider cache in background"}
+{"time":"2025-08-27T20:14:54.166264+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/config.saveProvidersInCache","file":"/home/runner/work/crush/crush/internal/config/provider.go","line":48},"msg":"Saving cached provider data","path":"/Users/leaanthony/.local/share/crush/providers.json"}
+{"time":"2025-08-27T20:14:54.434655+10:00","level":"INFO","msg":"goose: no migrations to run. current version: 20250627000000"}
+{"time":"2025-08-27T20:14:54.434719+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/app.(*App).initLSPClients","file":"/home/runner/work/crush/crush/internal/app/lsp.go","line":18},"msg":"LSP clients initialization started in background"}
+{"time":"2025-08-27T20:14:54.471191+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.NewAgent.func1","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":172},"msg":"Initializing agent tools","agent":"task"}
+{"time":"2025-08-27T20:14:54.471265+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.NewAgent.func1.1","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":174},"msg":"Initialized agent tools","agent":"task"}
+{"time":"2025-08-27T20:14:54.496888+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.NewAgent.func1","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":172},"msg":"Initializing agent tools","agent":"coder"}
+{"time":"2025-08-27T20:14:54.496948+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.NewAgent.func1.1","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":174},"msg":"Initialized agent tools","agent":"coder"}
+{"time":"2025-08-27T20:17:33.637828+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_93527162","name":"glob","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:17:34.037441+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_80010595","name":"glob","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:17:34.307688+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_91182610","name":"glob","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:17:34.580179+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_43322072","name":"glob","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:17:34.718351+10:00","level":"WARN","source":{"function":"github.com/charmbracelet/crush/internal/llm/tools.init.func1","file":"/home/runner/work/crush/crush/internal/llm/tools/rg.go","line":18},"msg":"Ripgrep (rg) not found in $PATH. Some grep features might be limited or slower."}
+{"time":"2025-08-27T20:17:48.635961+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_30955631","name":"ls","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:17:49.123428+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_45485050","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:17:49.551259+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_92078869","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:17:49.976417+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_00860205","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:17:50.401387+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_23176724","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:18:09.645526+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_35458981","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:18:14.824475+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_01662049","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:18:15.373523+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_48160986","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:18:39.008152+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_33565280","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:18:39.481014+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_69027448","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:18:39.944129+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_22908844","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:18:50.429194+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_08809019","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:19:09.697659+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_00750734","name":"fetch","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:21:45.597003+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_40867543","name":"sourcegraph","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:21:59.687591+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_64387684","name":"grep","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:22:25.526368+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_33416132","name":"sourcegraph","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:22:38.279089+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_90308626","name":"grep","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:22:42.511602+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_01511275","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:22:59.563995+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_22812461","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:23:34.07552+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_21416158","name":"edit","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:23:40.337975+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_48357770","name":"view","input":"","type":"","finished":false}}
+{"time":"2025-08-27T20:23:55.480593+10:00","level":"INFO","source":{"function":"github.com/charmbracelet/crush/internal/llm/agent.(*agent).processEvent","file":"/home/runner/work/crush/crush/internal/llm/agent/agent.go","line":626},"msg":"Tool call started","toolCall":{"id":"call_45728932","name":"edit","input":"","type":"","finished":false}}

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -7,6 +7,8 @@ body:
   - type: markdown
     attributes:
       value: |
+        ***Please note: No bug reports are currently being accepted for Wails v3***
+        ***Please note: No bug reports are currently being accepted for Wails v3***
         ***Please note: No bug reports are currently being accepted for Wails v3***
         Before submitting this issue, please do the following:
         - Do a web search for your error. This usually leads to a much better understanding of the issue.
@@ -70,7 +72,7 @@ body:
     validations:
       required: false
   - type: textarea
-    id: systemdetails
+    id: systemetails
     attributes:
       label: System Details
       description: Please add the output of `wails doctor`.

.github/pull_request_template.md

@@ -6,6 +6,7 @@
 *     YOUR PR MAY BE REJECTED IF IT DOES NOT FOLLOW THESE STEPS     *
 *********************************************************************
 
+- *DO NOT* submit bugs for a source install of v3, ONLY tagged versions, e.g. v3.0.0-alpha.11
 - *DO NOT* submit PRs for v3 alpha enhancements, unless you have opened a post on the discord channel.
   All enhancements must be discussed first.
   The feedback guide for v3 is here: https://v3alpha.wails.io/getting-started/feedback/
@@ -47,7 +48,7 @@ Please paste the output of `wails doctor`. If you are unable to run this command
 
 # Checklist:
 
-- [ ] I have updated `website/src/pages/changelog.mdx` with details of this PR
+- [ ] I have updated `v3/UNRELEASED_CHANGELOG.md` with details of this PR
 - [ ] My code follows the general coding style of this project
 - [ ] I have performed a self-review of my own code
 - [ ] I have commented my code, particularly in hard-to-understand areas

.github/workflows/auto-label-issues.yml

@@ -3,7 +3,7 @@ name: Auto Label Issues
 on:
   issues:
     types: [opened, edited, reopened]
-  pull_request:
+  pull_request_target:
     types: [opened, edited, reopened, synchronize]
 
 jobs:

.github/workflows/automated-releases.yml

@@ -0,0 +1,372 @@
+name: Automated Nightly Releases
+
+on:
+  workflow_dispatch:
+    inputs:
+      force_release:
+        description: 'Force release even if no changes detected'
+        required: false
+        default: false
+        type: boolean
+      dry_run:
+        description: 'Run in dry-run mode (no actual releases)'
+        required: false
+        default: false
+        type: boolean
+  # schedule:
+    # Run at 2 AM UTC every day - DISABLED for safety until ready
+    # - cron: '0 2 * * *'
+
+env:
+  GO_VERSION: '1.24'
+
+jobs:
+  check-permissions:
+    name: Check Release Permissions
+    runs-on: ubuntu-latest
+    outputs:
+      authorized: ${{ steps.check.outputs.authorized }}
+    steps:
+      - name: Check if user is authorized for releases
+        id: check
+        run: |
+          # Only allow specific users to trigger releases
+          AUTHORIZED_USERS="leaanthony"
+          
+          if [[ "$AUTHORIZED_USERS" == *"${{ github.actor }}"* ]]; then
+            echo "✅ User ${{ github.actor }} is authorized for releases"
+            echo "authorized=true" >> $GITHUB_OUTPUT
+          else
+            echo "❌ User ${{ github.actor }} is not authorized for releases"
+            echo "authorized=false" >> $GITHUB_OUTPUT
+          fi
+
+  detect-v2-changes:
+    name: Detect v2 Changes
+    runs-on: ubuntu-latest
+    needs: check-permissions
+    if: needs.check-permissions.outputs.authorized == 'true'
+    outputs:
+      has_changes: ${{ steps.changes.outputs.has_changes }}
+      commits_since_last: ${{ steps.changes.outputs.commits_since_last }}
+      last_release_tag: ${{ steps.changes.outputs.last_release_tag }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check for v2 changes since last release
+        id: changes
+        run: |
+          echo "🔍 Checking for v2 changes since last release..."
+          
+          # Find the last v2 release tag
+          LAST_TAG=$(git tag -l "v2.*" --sort=-version:refname | head -n 1)
+          if [ -z "$LAST_TAG" ]; then
+            echo "No previous v2 tags found, assuming first release"
+            LAST_TAG=$(git rev-list --max-parents=0 HEAD)
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+            echo "commits_since_last=999" >> $GITHUB_OUTPUT
+            echo "last_release_tag=none" >> $GITHUB_OUTPUT
+          else
+            echo "Last v2 release tag: $LAST_TAG"
+            echo "last_release_tag=$LAST_TAG" >> $GITHUB_OUTPUT
+            
+            # Count commits since last release affecting v2 or root files
+            COMMITS_COUNT=$(git rev-list --count ${LAST_TAG}..HEAD -- v2/ website/ README.md CHANGELOG.md || echo "0")
+            echo "Commits since last v2 release: $COMMITS_COUNT"
+            echo "commits_since_last=$COMMITS_COUNT" >> $GITHUB_OUTPUT
+            
+            if [ "$COMMITS_COUNT" -gt 0 ] || [ "${{ github.event.inputs.force_release }}" == "true" ]; then
+              echo "✅ Changes detected or forced release"
+              echo "has_changes=true" >> $GITHUB_OUTPUT
+            else
+              echo "ℹ️ No changes detected since last release"
+              echo "has_changes=false" >> $GITHUB_OUTPUT
+            fi
+          fi
+
+  detect-v3-changes:
+    name: Detect v3-alpha Changes  
+    runs-on: ubuntu-latest
+    needs: check-permissions
+    if: needs.check-permissions.outputs.authorized == 'true'
+    outputs:
+      has_changes: ${{ steps.changes.outputs.has_changes }}
+      commits_since_last: ${{ steps.changes.outputs.commits_since_last }}
+      last_release_tag: ${{ steps.changes.outputs.last_release_tag }}
+    steps:
+      - name: Checkout v3-alpha branch
+        uses: actions/checkout@v4
+        with:
+          ref: v3-alpha
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check for v3-alpha changes since last release
+        id: changes
+        run: |
+          echo "🔍 Checking for v3-alpha changes since last release..."
+          
+          # Find the last v3 alpha release tag
+          LAST_TAG=$(git tag -l "v3.*-alpha.*" --sort=-version:refname | head -n 1)
+          if [ -z "$LAST_TAG" ]; then
+            echo "No previous v3-alpha tags found, assuming first release"
+            LAST_TAG=$(git rev-list --max-parents=0 HEAD)
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+            echo "commits_since_last=999" >> $GITHUB_OUTPUT
+            echo "last_release_tag=none" >> $GITHUB_OUTPUT
+          else
+            echo "Last v3-alpha release tag: $LAST_TAG"
+            echo "last_release_tag=$LAST_TAG" >> $GITHUB_OUTPUT
+            
+            # Count commits since last release affecting v3 or docs
+            COMMITS_COUNT=$(git rev-list --count ${LAST_TAG}..HEAD -- v3/ docs/ || echo "0")
+            echo "Commits since last v3-alpha release: $COMMITS_COUNT"
+            echo "commits_since_last=$COMMITS_COUNT" >> $GITHUB_OUTPUT
+            
+            if [ "$COMMITS_COUNT" -gt 0 ] || [ "${{ github.event.inputs.force_release }}" == "true" ]; then
+              echo "✅ Changes detected or forced release"
+              echo "has_changes=true" >> $GITHUB_OUTPUT
+            else
+              echo "ℹ️ No changes detected since last release"
+              echo "has_changes=false" >> $GITHUB_OUTPUT
+            fi
+          fi
+
+  release-v2:
+    name: Create v2 Release
+    runs-on: ubuntu-latest
+    needs: [check-permissions, detect-v2-changes]
+    if: |
+      needs.check-permissions.outputs.authorized == 'true' &&
+      needs.detect-v2-changes.outputs.has_changes == 'true'
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      release_notes: ${{ steps.release.outputs.release_notes }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - name: Run v2 release script and extract notes
+        id: release
+        run: |
+          echo "🚀 Running v2 release script..."
+          cd v2/tools/release
+          
+          # Run release script and capture output
+          RELEASE_OUTPUT=$(go run release.go 2>&1)
+          echo "$RELEASE_OUTPUT"
+          
+          # Extract version from output or version file
+          NEW_VERSION=$(cat ../../cmd/wails/internal/version.txt)
+          echo "version=$NEW_VERSION" >> $GITHUB_OUTPUT
+          
+          # Extract release notes from delimited output
+          RELEASE_NOTES=$(echo "$RELEASE_OUTPUT" | sed -n '/=== RELEASE NOTES FOR/,/=== END RELEASE NOTES ===/p' | sed '1d;$d')
+          
+          # Save release notes to file for multiline output
+          echo "$RELEASE_NOTES" > ../../../release_notes_v2.md
+          
+          # Set output (escape for GitHub Actions)
+          {
+            echo "release_notes<<EOF"
+            echo "$RELEASE_NOTES"
+            echo "EOF"
+          } >> $GITHUB_OUTPUT
+          
+          echo "✅ v2 release script completed - version: $NEW_VERSION"
+
+      - name: Create v2 git tag and release
+        if: github.event.inputs.dry_run != 'true'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ steps.release.outputs.version }}"
+          echo "📝 Creating v2 release: $VERSION"
+          
+          # Configure git
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          
+          # Commit the changelog changes
+          git add website/src/pages/changelog.mdx v2/cmd/wails/internal/version.txt
+          git commit -m "chore: release $VERSION
+
+          Automated release created by GitHub Actions
+
+          🤖 Generated with [Claude Code](https://claude.ai/code)
+
+          Co-Authored-By: Claude <noreply@anthropic.com>"
+          
+          # Create and push tag
+          git tag -a "$VERSION" -m "Release $VERSION"
+          git push origin master
+          git push origin "$VERSION"
+          
+          # Create GitHub release with notes
+          gh release create "$VERSION" \
+            --title "Release $VERSION" \
+            --notes-file release_notes_v2.md \
+            --target master
+
+      - name: Log dry-run results for v2
+        if: github.event.inputs.dry_run == 'true'
+        run: |
+          echo "🧪 DRY RUN - Would have created v2 release:"
+          echo "Version: ${{ steps.release.outputs.version }}"
+          echo "Release Notes:"
+          cat release_notes_v2.md
+
+  release-v3:
+    name: Create v3-alpha Release
+    runs-on: ubuntu-latest
+    needs: [check-permissions, detect-v3-changes]
+    if: |
+      needs.check-permissions.outputs.authorized == 'true' &&
+      needs.detect-v3-changes.outputs.has_changes == 'true'
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      release_notes: ${{ steps.release.outputs.release_notes }}
+    steps:
+      - name: Checkout v3-alpha branch
+        uses: actions/checkout@v4
+        with:
+          ref: v3-alpha
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - name: Run v3 release script and extract notes
+        id: release
+        run: |
+          echo "🚀 Running v3-alpha release script..."
+          cd v3/tasks/release
+          
+          # Run release script and capture output
+          RELEASE_OUTPUT=$(go run release.go 2>&1)
+          echo "$RELEASE_OUTPUT"
+          
+          # Extract version from output or version file
+          NEW_VERSION=$(cat ../../internal/version/version.txt)
+          echo "version=$NEW_VERSION" >> $GITHUB_OUTPUT
+          
+          # Extract release notes from delimited output
+          RELEASE_NOTES=$(echo "$RELEASE_OUTPUT" | sed -n '/=== RELEASE NOTES FOR/,/=== END RELEASE NOTES ===/p' | sed '1d;$d')
+          
+          # Save release notes to file for multiline output
+          echo "$RELEASE_NOTES" > ../../../release_notes_v3.md
+          
+          # Set output (escape for GitHub Actions)
+          {
+            echo "release_notes<<EOF"
+            echo "$RELEASE_NOTES"
+            echo "EOF"
+          } >> $GITHUB_OUTPUT
+          
+          echo "✅ v3-alpha release script completed - version: $NEW_VERSION"
+
+      - name: Create v3-alpha git tag and release
+        if: github.event.inputs.dry_run != 'true'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ steps.release.outputs.version }}"
+          echo "📝 Creating v3-alpha release: $VERSION"
+          
+          # Configure git
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          
+          # Commit the changelog changes
+          git add docs/src/content/docs/changelog.mdx v3/internal/version/version.txt
+          git commit -m "chore: release $VERSION
+
+          Automated v3-alpha release created by GitHub Actions
+
+          🤖 Generated with [Claude Code](https://claude.ai/code)
+
+          Co-Authored-By: Claude <noreply@anthropic.com>"
+          
+          # Create and push tag
+          git tag -a "$VERSION" -m "Release $VERSION"
+          git push origin v3-alpha
+          git push origin "$VERSION"
+          
+          # Create GitHub release with notes
+          gh release create "$VERSION" \
+            --title "Release $VERSION" \
+            --notes-file release_notes_v3.md \
+            --target v3-alpha \
+            --prerelease
+
+      - name: Log dry-run results for v3-alpha
+        if: github.event.inputs.dry_run == 'true'
+        run: |
+          echo "🧪 DRY RUN - Would have created v3-alpha release:"
+          echo "Version: ${{ steps.release.outputs.version }}"
+          echo "Release Notes:"
+          cat release_notes_v3.md
+
+  summary:
+    name: Release Summary
+    runs-on: ubuntu-latest
+    needs: [check-permissions, detect-v2-changes, detect-v3-changes, release-v2, release-v3]
+    if: always() && needs.check-permissions.outputs.authorized == 'true'
+    steps:
+      - name: Create release summary
+        run: |
+          echo "# 🚀 Automated Release Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Repository**: ${{ github.repository }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Triggered by**: ${{ github.actor }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Dry Run Mode**: ${{ github.event.inputs.dry_run || 'false' }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          # v2 Summary
+          echo "## v2 Release" >> $GITHUB_STEP_SUMMARY
+          if [ "${{ needs.detect-v2-changes.outputs.has_changes }}" == "true" ]; then
+            if [ "${{ needs.release-v2.result }}" == "success" ]; then
+              echo "✅ **v2 Release**: Created successfully" >> $GITHUB_STEP_SUMMARY
+              echo "  - Version: ${{ needs.release-v2.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+              echo "  - Commits since last: ${{ needs.detect-v2-changes.outputs.commits_since_last }}" >> $GITHUB_STEP_SUMMARY
+            else
+              echo "❌ **v2 Release**: Failed" >> $GITHUB_STEP_SUMMARY
+            fi
+          else
+            echo "⏭️ **v2 Release**: Skipped (no changes)" >> $GITHUB_STEP_SUMMARY
+            echo "  - Commits since last: ${{ needs.detect-v2-changes.outputs.commits_since_last }}" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          # v3 Summary
+          echo "## v3-alpha Release" >> $GITHUB_STEP_SUMMARY
+          if [ "${{ needs.detect-v3-changes.outputs.has_changes }}" == "true" ]; then
+            if [ "${{ needs.release-v3.result }}" == "success" ]; then
+              echo "✅ **v3-alpha Release**: Created successfully" >> $GITHUB_STEP_SUMMARY
+              echo "  - Version: ${{ needs.release-v3.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+              echo "  - Commits since last: ${{ needs.detect-v3-changes.outputs.commits_since_last }}" >> $GITHUB_STEP_SUMMARY
+            else
+              echo "❌ **v3-alpha Release**: Failed" >> $GITHUB_STEP_SUMMARY
+            fi
+          else
+            echo "⏭️ **v3-alpha Release**: Skipped (no changes)" >> $GITHUB_STEP_SUMMARY
+            echo "  - Commits since last: ${{ needs.detect-v3-changes.outputs.commits_since_last }}" >> $GITHUB_STEP_SUMMARY
+          fi
+          
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "---" >> $GITHUB_STEP_SUMMARY
+          echo "🤖 **Automated Release System** | Generated with [Claude Code](https://claude.ai/code)" >> $GITHUB_STEP_SUMMARY

.github/workflows/build-and-test-v3.yml

@@ -5,8 +5,6 @@ on:
     types: [opened, synchronize, reopened, ready_for_review]
     branches:
       - v3-alpha
-    paths:
-      - 'v3/**'
   pull_request_review:
     types: [submitted]
     branches:
@@ -29,9 +27,78 @@ jobs:
             echo "approved=false" >> $GITHUB_OUTPUT
           fi
 
+  test_js:
+    name: Run JS Tests
+    needs: check_approval
+    runs-on: ubuntu-latest
+    if: github.base_ref == 'v3-alpha'
+    strategy:
+      matrix:
+        node-version: [20.x]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install Task
+        uses: arduino/setup-task@v2
+        with:
+          version: 3.x
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        working-directory: v3/internal/runtime/desktop/@wailsio/runtime
+        run: |
+          npm ci
+          npx --yes esbuild@latest --version
+
+      - name: Clean build artifacts
+        working-directory: v3/internal/runtime/desktop/@wailsio/runtime
+        run: npm run clean
+
+      - name: Type-check runtime
+        working-directory: v3
+        run: task runtime:check
+
+      - name: Test runtime
+        working-directory: v3
+        run: task runtime:test
+
+      - name: Check that the bundled runtime builds
+        working-directory: v3
+        run: task runtime:build
+
+      - name: Check that the npm package builds
+        working-directory: v3/internal/runtime/desktop/@wailsio/runtime
+        run: npm run build
+
+      - name: Pack runtime for template tests
+        working-directory: v3/internal/runtime/desktop/@wailsio/runtime
+        run: npm pack
+
+      - name: Store runtime build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: runtime-build-artifacts
+          path: |
+            v3/internal/runtime/desktop/@wailsio/runtime/dist/
+            v3/internal/runtime/desktop/@wailsio/runtime/types/
+            v3/internal/runtime/desktop/@wailsio/runtime/tsconfig.tsbuildinfo
+
+      - name: Store runtime package
+        uses: actions/upload-artifact@v4
+        with:
+          name: runtime-package
+          path: v3/internal/runtime/desktop/@wailsio/runtime/*.tgz
+
   test_go:
     name: Run Go Tests v3
-    needs: check_approval
+    needs: [check_approval, test_js]
     runs-on: ${{ matrix.os }}
     if: github.base_ref == 'v3-alpha'
     strategy:
@@ -55,6 +122,7 @@ jobs:
         uses: actions/setup-go@v5
         with:
           go-version: ${{ matrix.go-version }}
+          cache: true
           cache-dependency-path: "v3/go.sum"
 
       - name: Install Task
@@ -63,9 +131,18 @@ jobs:
           version: 3.x
           repo-token: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Retrieve runtime build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: runtime-build-artifacts
+          path: v3/internal/runtime/desktop/@wailsio/runtime/
+
       - name: Build Examples
         working-directory: v3
-        run: task test:examples
+        run: |
+          echo "Starting example compilation tests..."
+          task test:examples
+          echo "Example compilation tests completed successfully"
 
       - name: Run tests (mac)
         if: matrix.os == 'macos-latest'
@@ -93,35 +170,22 @@ jobs:
         working-directory: v3
         run: task generator:test:check
 
-  test_js:
-    name: Run JS Tests
-    needs: check_approval
+  cleanup:
+    name: Cleanup build artifacts
+    if: always()
+    needs: [test_js, test_go, test_templates]
     runs-on: ubuntu-latest
-    if: github.base_ref == 'v3-alpha'
-    strategy:
-      matrix:
-        node-version: [20.x]
-
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+      - uses: geekyeggo/delete-artifact@v5
         with:
-          node-version: ${{ matrix.node-version }}
-
-      - name: Install dependencies
-        run: npm install
-        working-directory: v2/internal/frontend/runtime
-
-      - name: Run tests
-        run: npm test
-        working-directory: v2/internal/frontend/runtime
+          name: |
+            runtime-build-artifacts
+            runtime-package
+          failOnError: false
 
   test_templates:
     name: Test Templates
-    needs: test_go
+    needs: [test_js, test_go]
     runs-on: ${{ matrix.os }}
     if: github.base_ref == 'v3-alpha'
     strategy:
@@ -157,6 +221,7 @@ jobs:
         uses: actions/setup-go@v5
         with:
           go-version: ${{ matrix.go-version }}
+          cache: true
           cache-dependency-path: "v3/go.sum"
 
       - name: Install Task
@@ -171,12 +236,28 @@ jobs:
           task install
           wails3 doctor
 
+      - name: Download runtime package
+        uses: actions/download-artifact@v4
+        with:
+          name: runtime-package
+          path: wails-runtime-temp
+
       - name: Generate template '${{ matrix.template }}'
+        shell: bash
         run: |
+          # Get absolute path - use pwd -W on Windows for native paths, pwd elsewhere
+          if [[ "$RUNNER_OS" == "Windows" ]]; then
+            RUNTIME_TGZ="$(cd wails-runtime-temp && pwd -W)/$(ls wails-runtime-temp/*.tgz | xargs basename)"
+          else
+            RUNTIME_TGZ="$(cd wails-runtime-temp && pwd)/$(ls wails-runtime-temp/*.tgz | xargs basename)"
+          fi
           mkdir -p ./test-${{ matrix.template }}
           cd ./test-${{ matrix.template }}
           wails3 init -n ${{ matrix.template }} -t ${{ matrix.template }}
-          cd ${{ matrix.template }}
+          cd ${{ matrix.template }}/frontend
+          # Replace @wailsio/runtime version with local tarball
+          npm pkg set dependencies.@wailsio/runtime="file://$RUNTIME_TGZ"
+          cd ..
           wails3 build
 
   build_results:

.github/workflows/build-and-test.yml

@@ -12,8 +12,8 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-22.04, ubuntu-24.04, windows-latest, macos-latest]
-        go-version: ['1.22']
+        os: [ubuntu-22.04, ubuntu-24.04, windows-latest, macos-latest, macos-11]
+        go-version: ['1.21']
 
     steps:
       - name: Checkout code
@@ -28,7 +28,7 @@ jobs:
       - uses: awalsh128/cache-apt-pkgs-action@latest
         if: matrix.os == 'ubuntu-24.04'
         with:
-          packages: libgtk-3-dev libwebkit2gtk-4.1-dev build-essential pkg-config libegl1
+          packages: libgtk-3-dev libwebkit2gtk-4.1-dev build-essential pkg-config
           version: 1.0
 
       - name: Setup Go
@@ -38,14 +38,14 @@ jobs:
           cache-dependency-path: ./v2/go.sum
 
       - name: Run tests (mac)
-        if: matrix.os == 'macos-latest'
+        if: matrix.os == 'macos-latest' || matrix.os == 'macos-11'
         env:
           CGO_LDFLAGS: -framework UniformTypeIdentifiers -mmacosx-version-min=10.13
         working-directory: ./v2
         run: go test -v ./...
 
       - name: Run tests (!mac)
-        if: matrix.os != 'macos-latest' && matrix.os != 'ubuntu-24.04'
+        if: matrix.os != 'macos-latest' && matrix.os != 'macos-11' && matrix.os != 'ubuntu-24.04'
         working-directory: ./v2
         run: go test -v ./...
 
@@ -86,7 +86,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        os: [ubuntu-22.04, windows-latest, macos-latest, ubuntu-24.04]
+        os: [ubuntu-22.04, windows-latest, macos-latest, ubuntu-24.04, macos-11]
         template:
           [
             svelte,
@@ -103,13 +103,13 @@ jobs:
             vanilla-ts,
             plain,
           ]
-        go-version: ['1.22']
+        go-version: ['1.21']
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
       - name: Setup Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v4
         with:
           go-version: ${{ matrix.go-version }}
           cache-dependency-path: ./v2/go.sum
@@ -120,25 +120,13 @@ jobs:
           go install
           wails -help
 
-      - uses: awalsh128/cache-apt-pkgs-action@latest
+      - name: Install linux dependencies ( 22.04 )
         if: matrix.os == 'ubuntu-22.04'
-        with:
-          packages: libgtk-3-dev libwebkit2gtk-4.0-dev build-essential pkg-config
-          version: 1.0
+        run: sudo apt-get update -y && sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev build-essential pkg-config
 
-#      - name: Install linux dependencies ( 22.04 )
-#        if: matrix.os == 'ubuntu-22.04'
-#        run: sudo apt-get update -y && sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev build-essential pkg-config
-
-      - uses: awalsh128/cache-apt-pkgs-action@latest
+      - name: Install linux dependencies ( 24.04 )
         if: matrix.os == 'ubuntu-24.04'
-        with:
-          packages: libgtk-3-dev libwebkit2gtk-4.1-dev build-essential pkg-config libegl1
-          version: 1.0
-
-#      - name: Install linux dependencies ( 24.04 )
-#        if: matrix.os == 'ubuntu-24.04'
-#        run: sudo apt-get update -y && sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev build-essential pkg-config
+        run: sudo apt-get update -y && sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev build-essential pkg-config
 
       - name: Generate & Build template '${{ matrix.template }}'
         if: matrix.os != 'ubuntu-24.04'

.github/workflows/build-cross-image.yml

@@ -1,423 +0,0 @@
-name: Build Cross-Compiler Image
-
-on:
-  workflow_dispatch:
-    inputs:
-      branch:
-        description: 'Branch containing Dockerfile'
-        required: true
-        default: 'v3-alpha'
-      sdk_version:
-        description: 'macOS SDK version'
-        required: true
-        default: '14.5'
-      zig_version:
-        description: 'Zig version'
-        required: true
-        default: '0.14.0'
-      image_version:
-        description: 'Image version tag'
-        required: true
-        default: 'latest'
-      skip_tests:
-        description: 'Skip cross-compilation tests'
-        required: false
-        default: 'false'
-        type: boolean
-  push:
-    branches:
-      - v3-alpha
-    paths:
-      - 'v3/internal/commands/build_assets/docker/Dockerfile.cross'
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: wailsapp/wails-cross
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-    outputs:
-      image_tag: ${{ steps.vars.outputs.image_version }}
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ inputs.branch || github.ref }}
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Log in to Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Set build variables
-        id: vars
-        run: |
-          echo "sdk_version=${{ inputs.sdk_version || '14.5' }}" >> $GITHUB_OUTPUT
-          echo "zig_version=${{ inputs.zig_version || '0.14.0' }}" >> $GITHUB_OUTPUT
-          echo "image_version=${{ inputs.image_version || 'latest' }}" >> $GITHUB_OUTPUT
-
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=raw,value=latest
-            type=raw,value=${{ steps.vars.outputs.image_version }}
-            type=raw,value=sdk-${{ steps.vars.outputs.sdk_version }}
-
-      - name: Build and push
-        uses: docker/build-push-action@v5
-        with:
-          context: v3/internal/commands/build_assets/docker
-          file: v3/internal/commands/build_assets/docker/Dockerfile.cross
-          platforms: linux/amd64,linux/arm64
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: |
-            ${{ steps.meta.outputs.labels }}
-            io.wails.zig.version=${{ steps.vars.outputs.zig_version }}
-            io.wails.sdk.version=${{ steps.vars.outputs.sdk_version }}
-          build-args: |
-            ZIG_VERSION=${{ steps.vars.outputs.zig_version }}
-            MACOS_SDK_VERSION=${{ steps.vars.outputs.sdk_version }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-
-  # Test cross-compilation for all platforms
-  test-cross-compile:
-    needs: build
-    if: ${{ inputs.skip_tests != 'true' }}
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          # Darwin targets (Zig + macOS SDK) - no platform emulation needed
-          - os: darwin
-            arch: arm64
-            platform: ""
-            expected_file: "Mach-O 64-bit.*arm64"
-          - os: darwin
-            arch: amd64
-            platform: ""
-            expected_file: "Mach-O 64-bit.*x86_64"
-          # Linux targets (GCC) - need platform to match architecture
-          - os: linux
-            arch: amd64
-            platform: "linux/amd64"
-            expected_file: "ELF 64-bit LSB.*x86-64"
-          - os: linux
-            arch: arm64
-            platform: "linux/arm64"
-            expected_file: "ELF 64-bit LSB.*ARM aarch64"
-          # Windows targets (Zig + mingw) - no platform emulation needed
-          - os: windows
-            arch: amd64
-            platform: ""
-            expected_file: "PE32\\+ executable.*x86-64"
-          - os: windows
-            arch: arm64
-            platform: ""
-            expected_file: "PE32\\+ executable.*Aarch64"
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ inputs.branch || github.ref }}
-
-      - name: Set up QEMU
-        if: matrix.platform != ''
-        uses: docker/setup-qemu-action@v3
-
-      - name: Log in to Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Create test CGO project
-        run: |
-          mkdir -p test-project
-          cd test-project
-
-          # Create a minimal CGO test program
-          cat > main.go << 'EOF'
-          package main
-
-          /*
-          #include <stdlib.h>
-
-          int add(int a, int b) {
-              return a + b;
-          }
-          */
-          import "C"
-          import "fmt"
-
-          func main() {
-              result := C.add(1, 2)
-              fmt.Printf("CGO test: 1 + 2 = %d\n", result)
-          }
-          EOF
-
-          cat > go.mod << 'EOF'
-          module test-cgo
-
-          go 1.21
-          EOF
-
-      - name: Build ${{ matrix.os }}/${{ matrix.arch }} (CGO)
-        run: |
-          cd test-project
-          PLATFORM_FLAG=""
-          if [ -n "${{ matrix.platform }}" ]; then
-            PLATFORM_FLAG="--platform ${{ matrix.platform }}"
-          fi
-
-          docker run --rm $PLATFORM_FLAG \
-            -v "$(pwd):/app" \
-            -e APP_NAME="test-cgo" \
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.build.outputs.image_tag || 'latest' }} \
-            ${{ matrix.os }} ${{ matrix.arch }}
-
-      - name: Verify binary format
-        run: |
-          cd test-project/bin
-          ls -la
-
-          # Find the built binary
-          if [ "${{ matrix.os }}" = "windows" ]; then
-            BINARY=$(ls test-cgo-${{ matrix.os }}-${{ matrix.arch }}.exe 2>/dev/null || ls *.exe | head -1)
-          else
-            BINARY=$(ls test-cgo-${{ matrix.os }}-${{ matrix.arch }} 2>/dev/null || ls test-cgo* | grep -v '.exe' | head -1)
-          fi
-
-          echo "Binary: $BINARY"
-          FILE_OUTPUT=$(file "$BINARY")
-          echo "File output: $FILE_OUTPUT"
-
-          # Verify the binary format matches expected
-          if echo "$FILE_OUTPUT" | grep -qE "${{ matrix.expected_file }}"; then
-            echo "✅ Binary format verified: ${{ matrix.os }}/${{ matrix.arch }}"
-          else
-            echo "❌ Binary format mismatch!"
-            echo "Expected pattern: ${{ matrix.expected_file }}"
-            echo "Got: $FILE_OUTPUT"
-            exit 1
-          fi
-
-      - name: Check library dependencies (Linux only)
-        if: matrix.os == 'linux'
-        run: |
-          cd test-project/bin
-          BINARY=$(ls test-cgo-${{ matrix.os }}-${{ matrix.arch }} 2>/dev/null || ls test-cgo* | grep -v '.exe' | head -1)
-
-          echo "## Library Dependencies for $BINARY"
-          echo ""
-
-          # Use readelf to show dynamic dependencies
-          echo "### NEEDED libraries:"
-          readelf -d "$BINARY" | grep NEEDED || echo "No dynamic dependencies (statically linked)"
-
-          # Verify expected libraries are linked
-          echo ""
-          echo "### Verifying required libraries..."
-          NEEDED=$(readelf -d "$BINARY" | grep NEEDED)
-
-          MISSING=""
-          for lib in libwebkit2gtk-4.1.so libgtk-3.so libglib-2.0.so libc.so; do
-            if echo "$NEEDED" | grep -q "$lib"; then
-              echo "✅ $lib"
-            else
-              echo "❌ $lib MISSING"
-              MISSING="$MISSING $lib"
-            fi
-          done
-
-          if [ -n "$MISSING" ]; then
-            echo ""
-            echo "ERROR: Missing required libraries:$MISSING"
-            exit 1
-          fi
-
-  # Test non-CGO builds (pure Go cross-compilation)
-  test-non-cgo:
-    needs: build
-    if: ${{ inputs.skip_tests != 'true' }}
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: darwin
-            arch: arm64
-            expected_file: "Mach-O 64-bit.*arm64"
-          - os: darwin
-            arch: amd64
-            expected_file: "Mach-O 64-bit.*x86_64"
-          - os: linux
-            arch: amd64
-            expected_file: "ELF 64-bit LSB"
-          - os: linux
-            arch: arm64
-            expected_file: "ELF 64-bit LSB.*ARM aarch64"
-          - os: windows
-            arch: amd64
-            expected_file: "PE32\\+ executable.*x86-64"
-          - os: windows
-            arch: arm64
-            expected_file: "PE32\\+ executable.*Aarch64"
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ inputs.branch || github.ref }}
-
-      - name: Log in to Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Create test non-CGO project
-        run: |
-          mkdir -p test-project
-          cd test-project
-
-          # Create a pure Go test program (no CGO)
-          cat > main.go << 'EOF'
-          package main
-
-          import "fmt"
-
-          func main() {
-              fmt.Println("Pure Go cross-compilation test")
-          }
-          EOF
-
-          cat > go.mod << 'EOF'
-          module test-pure-go
-
-          go 1.21
-          EOF
-
-      - name: Build ${{ matrix.os }}/${{ matrix.arch }} (non-CGO)
-        run: |
-          cd test-project
-
-          # For non-CGO, we can use any platform since Go handles cross-compilation
-          # We set CGO_ENABLED=0 to ensure pure Go build
-          docker run --rm \
-            -v "$(pwd):/app" \
-            -e APP_NAME="test-pure-go" \
-            -e CGO_ENABLED=0 \
-            --entrypoint /bin/sh \
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.build.outputs.image_tag || 'latest' }} \
-            -c "GOOS=${{ matrix.os }} GOARCH=${{ matrix.arch }} go build -o bin/test-pure-go-${{ matrix.os }}-${{ matrix.arch }}${{ matrix.os == 'windows' && '.exe' || '' }} ."
-
-      - name: Verify binary format
-        run: |
-          cd test-project/bin
-          ls -la
-
-          # Find the built binary
-          if [ "${{ matrix.os }}" = "windows" ]; then
-            BINARY="test-pure-go-${{ matrix.os }}-${{ matrix.arch }}.exe"
-          else
-            BINARY="test-pure-go-${{ matrix.os }}-${{ matrix.arch }}"
-          fi
-
-          echo "Binary: $BINARY"
-          FILE_OUTPUT=$(file "$BINARY")
-          echo "File output: $FILE_OUTPUT"
-
-          # Verify the binary format matches expected
-          if echo "$FILE_OUTPUT" | grep -qE "${{ matrix.expected_file }}"; then
-            echo "✅ Binary format verified: ${{ matrix.os }}/${{ matrix.arch }} (non-CGO)"
-          else
-            echo "❌ Binary format mismatch!"
-            echo "Expected pattern: ${{ matrix.expected_file }}"
-            echo "Got: $FILE_OUTPUT"
-            exit 1
-          fi
-
-      - name: Check library dependencies (Linux only)
-        if: matrix.os == 'linux'
-        run: |
-          cd test-project/bin
-          BINARY="test-pure-go-${{ matrix.os }}-${{ matrix.arch }}"
-
-          echo "## Library Dependencies for $BINARY (non-CGO)"
-          echo ""
-
-          # Non-CGO builds should have minimal dependencies (just libc or statically linked)
-          echo "### NEEDED libraries:"
-          readelf -d "$BINARY" | grep NEEDED || echo "No dynamic dependencies (statically linked)"
-
-          # Verify NO GTK/WebKit libraries (since CGO is disabled)
-          NEEDED=$(readelf -d "$BINARY" | grep NEEDED || true)
-          if echo "$NEEDED" | grep -q "libwebkit\|libgtk"; then
-            echo "❌ ERROR: Non-CGO binary should not link to GTK/WebKit!"
-            exit 1
-          else
-            echo "✅ Confirmed: No GTK/WebKit dependencies (expected for non-CGO)"
-          fi
-
-  # Summary job
-  test-summary:
-    needs: [build, test-cross-compile, test-non-cgo]
-    if: always() && inputs.skip_tests != 'true'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check test results
-        run: |
-          echo "## Cross-Compilation Test Results" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-
-          if [ "${{ needs.test-cross-compile.result }}" = "success" ]; then
-            echo "✅ **CGO Tests**: All passed" >> $GITHUB_STEP_SUMMARY
-          else
-            echo "❌ **CGO Tests**: Failed" >> $GITHUB_STEP_SUMMARY
-          fi
-
-          if [ "${{ needs.test-non-cgo.result }}" = "success" ]; then
-            echo "✅ **Non-CGO Tests**: All passed" >> $GITHUB_STEP_SUMMARY
-          else
-            echo "❌ **Non-CGO Tests**: Failed" >> $GITHUB_STEP_SUMMARY
-          fi
-
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "### Tested Platforms" >> $GITHUB_STEP_SUMMARY
-          echo "| Platform | Architecture | CGO | Non-CGO |" >> $GITHUB_STEP_SUMMARY
-          echo "|----------|-------------|-----|---------|" >> $GITHUB_STEP_SUMMARY
-          echo "| Darwin | arm64 | ✅ | ✅ |" >> $GITHUB_STEP_SUMMARY
-          echo "| Darwin | amd64 | ✅ | ✅ |" >> $GITHUB_STEP_SUMMARY
-          echo "| Linux | arm64 | ✅ | ✅ |" >> $GITHUB_STEP_SUMMARY
-          echo "| Linux | amd64 | ✅ | ✅ |" >> $GITHUB_STEP_SUMMARY
-          echo "| Windows | arm64 | ✅ | ✅ |" >> $GITHUB_STEP_SUMMARY
-          echo "| Windows | amd64 | ✅ | ✅ |" >> $GITHUB_STEP_SUMMARY
-
-          # Fail if any test failed
-          if [ "${{ needs.test-cross-compile.result }}" != "success" ] || [ "${{ needs.test-non-cgo.result }}" != "success" ]; then
-            echo ""
-            echo "❌ Some tests failed. Check the individual job logs for details."
-            exit 1
-          fi

.github/workflows/changelog-v3.yml

@@ -1,216 +0,0 @@
-name: Changelog Validation (v3)
-
-on:
-  pull_request:
-    branches: [ v3-alpha ]
-    paths:
-      - 'docs/src/content/docs/changelog.mdx'
-  workflow_dispatch:
-    inputs:
-      pr_number:
-        description: 'PR number to validate'
-        required: true
-        type: string
-
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-      actions: write
-    
-    steps:
-    - name: Checkout PR code
-      uses: actions/checkout@v4
-      with:
-        ref: ${{ github.event.pull_request.head.sha || format('refs/pull/{0}/head', github.event.inputs.pr_number) }}
-        fetch-depth: 0
-        token: ${{ secrets.GITHUB_TOKEN || github.token }}
-        
-    - name: Get REAL validation script from v3-alpha
-      run: |
-        echo "Fetching the REAL validation script from v3-alpha branch..."
-        git fetch origin v3-alpha
-        git checkout origin/v3-alpha -- v3/scripts/validate-changelog.go
-        
-        echo "Validation script fetched successfully:"
-        ls -la v3/scripts/
-        
-    - name: Setup Go
-      uses: actions/setup-go@v4
-      with:
-        go-version: '1.23'
-        
-    - name: Get PR information
-      id: pr_info
-      run: |
-        if [ "${{ github.event_name }}" = "pull_request" ]; then
-          echo "pr_number=${{ github.event.pull_request.number }}" >> $GITHUB_OUTPUT
-          echo "base_ref=${{ github.event.pull_request.base.ref }}" >> $GITHUB_OUTPUT
-        else
-          echo "pr_number=${{ github.event.inputs.pr_number }}" >> $GITHUB_OUTPUT
-          echo "base_ref=v3-alpha" >> $GITHUB_OUTPUT
-        fi
-        
-    - name: Check changelog modifications
-      id: changelog_check
-      run: |
-        echo "Checking PR #${{ steps.pr_info.outputs.pr_number }} for changelog changes"
-        git fetch origin ${{ steps.pr_info.outputs.base_ref }}
-        
-        if git diff --name-only origin/${{ steps.pr_info.outputs.base_ref }}..HEAD | grep -q "docs/src/content/docs/changelog.mdx"; then
-          echo "changelog_modified=true" >> $GITHUB_OUTPUT
-          echo "✅ Changelog was modified in this PR"
-        else
-          echo "changelog_modified=false" >> $GITHUB_OUTPUT
-          echo "ℹ️ Changelog was not modified - skipping validation"
-        fi
-        
-    - name: Get changelog diff
-      id: get_diff
-      if: steps.changelog_check.outputs.changelog_modified == 'true'
-      run: |
-        echo "Getting diff for changelog changes..."
-        git diff origin/${{ steps.pr_info.outputs.base_ref }}..HEAD docs/src/content/docs/changelog.mdx | grep "^+" | grep -v "^+++" | sed 's/^+//' > /tmp/pr_added_lines.txt
-        
-        echo "Lines added in this PR:"
-        cat /tmp/pr_added_lines.txt
-        echo "Total lines added: $(wc -l < /tmp/pr_added_lines.txt)"
-        
-    - name: Validate changelog
-      id: validate
-      if: steps.changelog_check.outputs.changelog_modified == 'true'
-      run: |
-        echo "Running changelog validation..."
-        cd v3/scripts
-        OUTPUT=$(go run validate-changelog.go ../../docs/src/content/docs/changelog.mdx /tmp/pr_added_lines.txt 2>&1)
-        echo "$OUTPUT"
-        
-        RESULT=$(echo "$OUTPUT" | grep "VALIDATION_RESULT=" | cut -d'=' -f2)
-        echo "result=$RESULT" >> $GITHUB_OUTPUT
-        
-    - name: Commit fixes
-      id: commit_fixes
-      if: steps.validate.outputs.result == 'fixed'
-      run: |
-        echo "Committing automatic fixes..."
-        git config --local user.email "action@github.com"
-        git config --local user.name "GitHub Action"
-        
-        # Check only the changelog file for changes
-        if git diff --quiet docs/src/content/docs/changelog.mdx; then
-          echo "No changes to commit"
-          echo "committed=false" >> $GITHUB_OUTPUT
-        else
-          # Ensure validation script doesn't get committed
-          echo "v3/scripts/validate-changelog.go" >> .git/info/exclude
-          # Get the correct branch name to push to
-          REPO_OWNER="wailsapp"  # Always wailsapp for this repo
-          
-          if [ "${{ github.event_name }}" = "pull_request" ]; then
-            BRANCH_NAME="${{ github.event.pull_request.head.ref }}"
-          else
-            # For manual workflow dispatch, get PR info
-            PR_INFO=$(gh pr view ${{ steps.pr_info.outputs.pr_number }} --json headRefName,headRepository)
-            BRANCH_NAME=$(echo "$PR_INFO" | jq -r '.headRefName')
-            HEAD_REPO=$(echo "$PR_INFO" | jq -r '.headRepository.name')
-            
-            echo "🔍 PR source branch: $BRANCH_NAME"
-            echo "🔍 Head repository: $HEAD_REPO"
-            
-            # Don't push if this is from a fork or if branch is v3-alpha (main branch)
-            if [ "$HEAD_REPO" != "wails" ] || [ "$BRANCH_NAME" = "v3-alpha" ]; then
-              echo "⚠️ Cannot push - either fork or direct v3-alpha branch. Manual fix required."
-              echo "committed=false" >> $GITHUB_OUTPUT
-              exit 0
-            fi
-          fi
-          
-          echo "Pushing to branch: $BRANCH_NAME in repo: $REPO_OWNER"
-          
-          # Only commit the changelog changes, not the validation script
-          git add docs/src/content/docs/changelog.mdx
-          git commit -m "🤖 Fix changelog: move entries to Unreleased section"
-          
-          # Only push if running on the main wailsapp repository
-          if [ "${{ github.repository }}" = "wailsapp/wails" ]; then
-            # Pull latest changes and rebase our commit
-            git fetch origin $BRANCH_NAME
-            git rebase origin/$BRANCH_NAME
-            git push origin HEAD:$BRANCH_NAME
-          else
-            echo "⚠️ Running on fork (${{ github.repository }}). Skipping push - manual fix required."
-            echo "committed=false" >> $GITHUB_OUTPUT
-            exit 0
-          fi
-          
-          echo "committed=true" >> $GITHUB_OUTPUT
-          echo "✅ Changes committed and pushed"
-        fi
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        
-    - name: Get PR author for tagging
-      id: pr_author
-      if: steps.validate.outputs.result && github.event.inputs.pr_number
-      run: |
-        PR_AUTHOR=$(gh pr view ${{ steps.pr_info.outputs.pr_number }} --json author --jq '.author.login')
-        echo "author=$PR_AUTHOR" >> $GITHUB_OUTPUT
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-    - name: Comment on PR
-      if: steps.validate.outputs.result && github.event.inputs.pr_number
-      uses: actions/github-script@v7
-      with:
-        script: |
-          const result = '${{ steps.validate.outputs.result }}';
-          const committed = '${{ steps.commit_fixes.outputs.committed }}';
-          const author = '${{ steps.pr_author.outputs.author }}';
-          
-          let message;
-          if (result === 'success') {
-            message = '## ✅ Changelog Validation Passed\n\nNo misplaced changelog entries detected.';
-          } else if (result === 'fixed' && committed === 'true') {
-            message = '## 🔧 Changelog Updated\n\nMisplaced entries were automatically moved to the `[Unreleased]` section. The changes have been committed to this PR.';
-          } else if (result === 'fixed' || result === 'cannot_fix' || result === 'error') {
-            // Read the fixed changelog content
-            const fs = require('fs');
-            let fixedContent = '';
-            try {
-              fixedContent = fs.readFileSync('docs/src/content/docs/changelog.mdx', 'utf8');
-            } catch (error) {
-              fixedContent = 'Error reading fixed changelog content';
-            }
-            
-            message = '## ⚠️ Changelog Validation Issue\\n\\n' +
-              '@' + author + ' Your PR contains changelog entries that were added to already-released versions. These need to be moved to the `[Unreleased]` section.\\n\\n' +
-              (committed === 'true' ? 
-                '✅ **Auto-fix applied**: The changes have been automatically committed to this PR.' :
-                '❌ **Manual fix required**: Please apply the changes shown below manually.') + '\\n\\n' +
-              '<details>\\n' +
-              '<summary>📝 Click to see the corrected changelog content</summary>\\n\\n' +
-              '```mdx\\n' +
-              fixedContent +
-              '\\n```\\n\\n' +
-              '</details>\\n\\n' +
-              '**What happened?** \\n' +
-              'The validation script detected that you added changelog entries to a version section that has already been released (like `v3.0.0-alpha.10`). All new entries should go in the `[Unreleased]` section under the appropriate category (`### Added`, `### Fixed`, etc.).\\n\\n' +
-              (committed !== 'true' ? '**Action needed:** Please copy the corrected content from above and replace your changelog file.' : '');
-          }
-          
-          if (message) {
-            await github.rest.issues.createComment({
-              issue_number: ${{ steps.pr_info.outputs.pr_number }},
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: message
-            });
-          }
-          
-    - name: Fail if validation failed
-      if: steps.validate.outputs.result == 'cannot_fix' || steps.validate.outputs.result == 'error'
-      run: |
-        echo "❌ Changelog validation failed"
-        exit 1

.github/workflows/changelog-validation-v3.yml

@@ -0,0 +1,74 @@
+name: Changelog Validation (v3)
+
+on:
+  pull_request:
+    branches: [ v3-alpha ]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'PR number to validate (for manual testing)'
+        required: true
+        type: string
+
+jobs:
+  validate-changelog:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' || github.event.inputs.pr_number
+    
+    permissions:
+      contents: write
+      pull-requests: write
+      
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ github.event.pull_request.head.sha || format('refs/pull/{0}/head', github.event.inputs.pr_number) }}
+        fetch-depth: 0
+        token: ${{ secrets.GITHUB_TOKEN }}
+        
+    - name: Setup Go
+      uses: actions/setup-go@v4
+      with:
+        go-version: '1.23'
+        
+    - name: Get PR information
+      id: pr_info
+      run: |
+        if [ "${{ github.event_name }}" = "pull_request" ]; then
+          echo "pr_number=${{ github.event.pull_request.number }}" >> $GITHUB_OUTPUT
+          echo "base_ref=${{ github.event.pull_request.base.ref }}" >> $GITHUB_OUTPUT
+        else
+          echo "pr_number=${{ github.event.inputs.pr_number }}" >> $GITHUB_OUTPUT
+          echo "base_ref=v3-alpha" >> $GITHUB_OUTPUT
+        fi
+        
+    - name: Check if changelog was modified
+      id: changelog_check
+      run: |
+        git fetch origin ${{ steps.pr_info.outputs.base_ref }}
+        if git diff --name-only origin/${{ steps.pr_info.outputs.base_ref }}..HEAD | grep -q "v3/UNRELEASED_CHANGELOG.md"; then
+          echo "changelog_modified=true" >> $GITHUB_OUTPUT
+          echo "✅ UNRELEASED_CHANGELOG.md was modified in this PR"
+        else
+          echo "changelog_modified=false" >> $GITHUB_OUTPUT
+          echo "⚠️ UNRELEASED_CHANGELOG.md was not modified"
+        fi
+        
+    - name: Comment on PR about missing changelog
+      if: steps.changelog_check.outputs.changelog_modified == 'false' && github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const author = context.payload.pull_request.user.login;
+          const message = '## ⚠️ Missing Changelog Update\n\n' +
+            `Hi @${author}, please update \`v3/UNRELEASED_CHANGELOG.md\` with a description of your changes.\n\n` +
+            'This helps us keep track of changes for the next release.';
+          
+          await github.rest.issues.createComment({
+            issue_number: ${{ steps.pr_info.outputs.pr_number }},
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            body: message
+          });
+        

.github/workflows/claude-code-review.yml

@@ -1,44 +0,0 @@
-name: Claude Code Review
-
-on:
-  pull_request:
-    types: [opened, synchronize, ready_for_review, reopened]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
-
-jobs:
-  claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
-
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
-      issues: read
-      id-token: write
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-
-      - name: Run Claude Code Review
-        id: claude-review
-        uses: anthropics/claude-code-action@v1
-        with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
-          plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://code.claude.com/docs/en/cli-reference for available options
-

.github/workflows/claude.yml

@@ -1,50 +0,0 @@
-name: Claude Code
-
-on:
-  issue_comment:
-    types: [created]
-  pull_request_review_comment:
-    types: [created]
-  issues:
-    types: [opened, assigned]
-  pull_request_review:
-    types: [submitted]
-
-jobs:
-  claude:
-    if: |
-      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
-      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
-      issues: read
-      id-token: write
-      actions: read # Required for Claude to read CI results on PRs
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-
-      - name: Run Claude Code
-        id: claude
-        uses: anthropics/claude-code-action@v1
-        with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-
-          # This is an optional setting that allows Claude to read CI results on PRs
-          additional_permissions: |
-            actions: read
-
-          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
-          # prompt: 'Update the pull request description to include a summary of changes.'
-
-          # Optional: Add claude_args to customize behavior and configuration
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://code.claude.com/docs/en/cli-reference for available options
-          # claude_args: '--allowed-tools Bash(gh pr:*)'
-

.github/workflows/generate-sponsor-image.yml

@@ -25,7 +25,7 @@ jobs:
           SPONSORKIT_GITHUB_LOGIN: wailsapp
 
       - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v6
+        uses: peter-evans/create-pull-request@v4
         with:
           commit-message: "chore: update sponsors.svg"
           add-paths: "website/static/img/sponsors.svg"

.github/workflows/issue-triage-automation.yml

@@ -2,7 +2,7 @@ name: Issue Triage Automation
 
 on:
   issues:
-    types: [opened]
+    types: [opened, reopened, labeled, unlabeled]
 
 jobs:
   triage:

.github/workflows/pr-master.yml

@@ -1,26 +1,17 @@
-# Updated to ensure "Run Go Tests" runs for pull requests as expected.
-# Key fix: the test_go job previously required github.event.review.state == 'approved'
-# which only exists on pull_request_review events. That prevented the job from
-# running for regular pull_request events (opened / synchronize / reopened).
-# New logic: run tests for pull_request events, and also allow running when a
-# pull_request_review is submitted with state == 'approved'.
+name: PR Checks (master)
+
 on:
   pull_request:
-    types: [opened, synchronize, reopened]
     branches:
       - master
   pull_request_review:
     types: [submitted]
     branches:
       - master
-  workflow_dispatch: {}
-
-name: PR Checks (master)
-
 jobs:
   check_docs:
     name: Check Docs
-    if: ${{ github.repository == 'wailsapp/wails' && github.base_ref == 'master' }}
+    if: ${{github.repository == 'wailsapp/wails' && github.base_ref == 'master'}}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -32,6 +23,7 @@ jobs:
           files: |
             website/**/*.mdx
             website/**/*.md
+
       - name: Run step only when files change.
         if: steps.verify-changed-files.outputs.files_changed != 'true'
         run: |
@@ -40,18 +32,11 @@ jobs:
   test_go:
     name: Run Go Tests
     runs-on: ${{ matrix.os }}
-    # Run when:
-    #  - the event is a pull_request (opened/synchronize/reopened) OR
-    #  - the event is a pull_request_review AND the review state is 'approved'
-    # plus other existing filters (not the update-sponsors branch, repo and base_ref)
     if: >
-      github.repository == 'wailsapp/wails' &&
+      github.event.review.state == 'approved' && 
+      github.repository == 'wailsapp/wails' && 
       github.base_ref == 'master' &&
-      github.event.pull_request.head.ref != 'update-sponsors' &&
-      (
-        github.event_name == 'pull_request' ||
-        (github.event_name == 'pull_request_review' && github.event.review.state == 'approved')
-      )
+      github.event.pull_request.head.ref != 'update-sponsors'
     strategy:
       matrix:
         os: [ubuntu-22.04, windows-latest, macos-latest, ubuntu-24.04]
@@ -90,15 +75,3 @@ jobs:
         if: matrix.os == 'ubuntu-24.04'
         working-directory: ./v2
         run: go test -v -tags webkit2_41 ./...
-
-  # This job will run instead of test_go for the update-sponsors branch
-  skip_tests:
-    name: Skip Tests (Sponsor Update)
-    if: github.event.pull_request.head.ref == 'update-sponsors'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Skip tests for sponsor updates
-        run: |
-          echo "Skipping tests for sponsor update branch"
-          echo "This is an automated update of the sponsors image."
-        continue-on-error: true

.github/workflows/publish-npm.yml

@@ -0,0 +1,119 @@
+on:
+  push:
+    branches: ['v3-alpha']
+  workflow_dispatch:
+
+concurrency:
+  group: publish-npm-v3
+  cancel-in-progress: true
+
+jobs:
+  detect:
+    name: Detect committed changes
+    if: github.event_name != 'workflow_dispatch'
+    outputs:
+      changed: ${{ steps.package-json-changes.outputs.any_modified == 'true' || steps.source-changes.outputs.any_modified == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: 'true'
+
+      - name: Detect committed package.json changes
+        id: package-json-changes
+        uses: step-security/changed-files@3dbe17c78367e7d60f00d78ae6781a35be47b4a1 # v45.0.1
+        with:
+          files: |
+            v3/internal/runtime/desktop/@wailsio/runtime/package.json
+            v3/internal/runtime/desktop/@wailsio/runtime/package-lock.json
+
+      - name: Detect committed source changes
+        if: >-
+          steps.package-json-changes.outputs.any_modified != 'true'
+        id: source-changes
+        uses: step-security/changed-files@3dbe17c78367e7d60f00d78ae6781a35be47b4a1 # v45.0.1
+        with:
+          files: |
+            v3/internal/runtime/Taskfile.yaml
+            v3/internal/runtime/desktop/@wailsio/compiled/main.js
+            v3/internal/runtime/desktop/@wailsio/runtime/tsconfig.json
+            v3/internal/runtime/desktop/@wailsio/runtime/src/**
+            v3/pkg/events/events.txt
+            v3/tasks/events/**
+
+  rebuild_and_publish:
+    name: Rebuild and publish
+    needs: [detect]
+    if: >-
+      !failure() && !cancelled()
+      && (github.event_name == 'workflow_dispatch' || needs.detect.outputs.changed == 'true')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      actions: read
+      pull-requests: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: 'v3-alpha'
+          token: ${{ secrets.WAILS_REPO_TOKEN || github.token }}
+
+      - name: Configure git
+        run: |
+          git config --global user.email "github-actions@github.com"
+          git config --global user.name "GitHub Actions"
+          git config --global url."https://x-access-token:${{ secrets.WAILS_REPO_TOKEN || github.token }}@github.com/".insteadOf "https://github.com/"
+
+      - name: Install Task
+        uses: arduino/setup-task@v2
+        with:
+          version: 3.x
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install dependencies
+        working-directory: v3/internal/runtime/desktop/@wailsio/runtime
+        run: |
+          npm ci
+          npx --yes esbuild@latest --version
+
+      - name: Clean build artifacts
+        working-directory: v3/internal/runtime/desktop/@wailsio/runtime
+        run: npm run clean
+
+      - name: Build bundled runtime
+        working-directory: v3
+        run: task runtime:build
+
+      - name: Test+Build npm package
+        working-directory: v3/internal/runtime/desktop/@wailsio/runtime
+        run: |
+          npm test
+          npm run build
+
+      - name: Bump version
+        id: bump-version
+        working-directory: v3/internal/runtime/desktop/@wailsio/runtime
+        run: |
+          echo "version=$(npm --no-git-tag-version --force version prerelease)" >> "$GITHUB_OUTPUT"
+
+      - name: Commit changes
+        run: |
+          git add .
+          git commit -m "[skip ci] Publish @wailsio/runtime ${{ steps.bump-version.outputs.version }}"
+          git push
+
+      - name: Publish npm package
+        uses: JS-DevTools/npm-publish@v3
+        with:
+          package: v3/internal/runtime/desktop/@wailsio/runtime
+          access: public
+          token: ${{ secrets.NPM_TOKEN }}

.github/workflows/test-simple.yml

@@ -0,0 +1,11 @@
+name: Test Simple
+
+on:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Test
+      run: echo "Hello World"

.github/workflows/unreleased-changelog-trigger.yml

@@ -39,7 +39,6 @@ jobs:
     name: Trigger v3-alpha Release
     permissions:
       contents: read
-      actions: write
     runs-on: ubuntu-latest
     needs: check-permissions
     if: needs.check-permissions.outputs.authorized == 'true'

.github/workflows/v3-docs.yml

@@ -0,0 +1,51 @@
+name: Deploy to GitHub Pages
+
+on:
+  # Trigger the workflow every time you push to the `main` branch
+  # Using a different branch name? Replace `main` with your branch's name
+  push:
+    branches: [v3-alpha]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/v3-docs.yml'
+  # Allows you to run this workflow manually from the Actions tab on GitHub.
+  workflow_dispatch:
+
+# Allow this job to clone the repo and create a page deployment
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: github.event.repository.fork == false
+    steps:
+      - name: Checkout your repository using git
+        uses: actions/checkout@v4
+      - name: Install D2
+        run: |
+          curl -fsSL https://d2lang.com/install.sh > install.sh
+          chmod +x install.sh
+          ./install.sh
+          sudo cp ~/.local/bin/d2 /usr/local/bin/d2
+          d2 --version
+          rm install.sh
+      - name: Install, build, and upload your site output
+        uses: withastro/action@v2
+        with:
+           path: docs
+           node-version: 20 # The specific version of Node that should be used to build your site. Defaults to 18. (optional)
+        # package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -37,5 +37,61 @@ v2/cmd/wails/internal/commands/initialise/templates/testtemplates/
 /websitev3/site/
 /v3/examples/plugins/bin/testapp
 
+# V3 Example binaries - ignore executables that match directory names
+/v3/examples/badge-custom/badge-custom
+/v3/examples/badge/badge
+/v3/examples/binding/binding
+/v3/examples/cancel-async/cancel-async
+/v3/examples/cancel-chaining/cancel-chaining
+/v3/examples/clipboard/clipboard
+/v3/examples/contextmenus/contextmenus
+/v3/examples/dev/dev
+/v3/examples/dialogs-basic/dialogs-basic
+/v3/examples/dialogs/dialogs
+/v3/examples/drag-n-drop/drag-n-drop
+/v3/examples/environment/environment
+/v3/examples/events-bug/events-bug
+/v3/examples/events/events
+/v3/examples/file-association/file-association
+/v3/examples/frameless/frameless
+/v3/examples/gin-example/gin-example
+/v3/examples/gin-routing/gin-routing
+/v3/examples/gin-service/gin-service
+/v3/examples/hide-window/hide-window
+/v3/examples/html-dnd-api/html-dnd-api
+/v3/examples/ignore-mouse/ignore-mouse
+/v3/examples/keybindings/keybindings
+/v3/examples/menu/menu
+/v3/examples/notifications/notifications
+/v3/examples/panic-handling/panic-handling
+/v3/examples/plain/plain
+/v3/examples/raw-message/raw-message
+/v3/examples/screen/screen
+/v3/examples/services/services
+/v3/examples/show-macos-toolbar/show-macos-toolbar
+/v3/examples/single-instance/single-instance
+/v3/examples/systray-basic/systray-basic
+/v3/examples/systray-custom/systray-custom
+/v3/examples/systray-menu/systray-menu
+/v3/examples/video/video
+/v3/examples/window-api/window-api
+/v3/examples/window-call/window-call
+/v3/examples/window-menu/window-menu
+/v3/examples/window/window
+/v3/examples/wml/wml
+
+# Common binary names in examples
+/v3/examples/*/main
+/v3/examples/*/app
+/v3/examples/*/changeme
+/v3/examples/*/testbuild-*
+
 # Temporary called mkdocs, should be renamed to more standard -website or similar
-/mkdocs-website/site
+/docs/site
+.aider*
+.aider*
+.cache
+.local
+
+# Ignore local iOS test app
+/v3/testiosapp/

.prettierrc.yml

@@ -1,6 +1,7 @@
 overrides:
   - files:
       - "**/*.md"
+      - "**/*.mdx"
     options:
       printWidth: 80
       proseWrap: always

.replit

@@ -1,8 +0,0 @@
-modules = ["go-1.21", "web", "nodejs-20"]
-run = "go run v2/cmd/wails/main.go"
-
-[nix]
-channel = "stable-24_05"
-
-[deployment]
-run = ["sh", "-c", "go run v2/cmd/wails/main.go"]

AGENTS.md

@@ -0,0 +1,143 @@
+# 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
+- 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.

CNAME

@@ -0,0 +1 @@
+v3alpha.wails.io

IOS_ARCHITECTURE.md

@@ -0,0 +1,419 @@
+# Wails v3 iOS Architecture
+
+## Executive Summary
+
+This document provides a comprehensive technical architecture for iOS support in Wails v3. The implementation enables Go applications to run natively on iOS with a WKWebView frontend, maintaining the Wails philosophy of using web technologies for UI while leveraging Go for business logic.
+
+## Table of Contents
+
+1. [Architecture Overview](#architecture-overview)
+2. [Core Components](#core-components)
+3. [Layer Architecture](#layer-architecture)
+4. [Implementation Details](#implementation-details)
+5. [Battery Optimization](#battery-optimization)
+6. [Build System](#build-system)
+7. [Security Considerations](#security-considerations)
+8. [API Reference](#api-reference)
+
+## Architecture Overview
+
+### Design Principles
+
+1. **Battery Efficiency First**: All architectural decisions prioritize battery life
+2. **No Network Ports**: Asset serving happens in-process via native APIs
+3. **Minimal WebView Instances**: Maximum 2 concurrent WebViews (1 primary, 1 for transitions)
+4. **Native Integration**: Deep iOS integration using Objective-C runtime
+5. **Wails v3 Compatibility**: Maintain API compatibility with existing Wails v3 applications
+
+### High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     iOS Application                          │
+├─────────────────────────────────────────────────────────────┤
+│                    UIKit Framework                           │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │              WailsViewController                     │   │
+│  │  ┌───────────────────────────────────────────────┐  │   │
+│  │  │            WKWebView Instance                  │  │   │
+│  │  │  ┌─────────────────────────────────────────┐  │  │   │
+│  │  │  │         Web Application (HTML/JS)        │  │  │   │
+│  │  │  └─────────────────────────────────────────┘  │  │   │
+│  │  └───────────────────────────────────────────────┘  │   │
+│  └─────────────────────────────────────────────────────┘   │
+├─────────────────────────────────────────────────────────────┤
+│                  Bridge Layer (CGO)                          │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │URL Handler   │  │JS Bridge     │  │Message Handler│     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+├─────────────────────────────────────────────────────────────┤
+│                    Go Runtime                                │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │                 Wails Application                     │  │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │  │
+│  │  │App Logic │  │Services  │  │Asset Server      │  │  │
+│  │  └──────────┘  └──────────┘  └──────────────────┘  │  │
+│  └──────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Core Components
+
+### 1. Platform Layer (`application_ios.go`)
+
+**Purpose**: Go interface for iOS platform operations
+
+**Key Functions**:
+- `platformRun()`: Initialize and run the iOS application
+- `platformQuit()`: Gracefully shutdown the application
+- `isDarkMode()`: Detect iOS dark mode state
+- `ExecuteJavaScript(windowID uint, js string)`: Execute JS in WebView
+
+**Exported Go Functions (Called from Objective-C)**:
+- `ServeAssetRequest(windowID C.uint, urlStr *C.char, callbackID C.uint)`
+- `HandleJSMessage(windowID C.uint, message *C.char)`
+
+### 2. Native iOS Layer (`application_ios.m`)
+
+**Components**:
+
+#### WailsSchemeHandler
+```objc
+@interface WailsSchemeHandler : NSObject <WKURLSchemeHandler>
+```
+- Implements `WKURLSchemeHandler` protocol
+- Intercepts `wails://` URL requests
+- Bridges to Go for asset serving
+- Manages pending requests with callback IDs
+
+**Methods**:
+- `startURLSchemeTask:`: Intercept request, call Go handler
+- `stopURLSchemeTask:`: Cancel pending request
+- `completeRequest:withData:mimeType:`: Complete request with data from Go
+
+#### WailsMessageHandler
+```objc
+@interface WailsMessageHandler : NSObject <WKScriptMessageHandler>
+```
+- Implements JavaScript to Go communication
+- Handles `window.webkit.messageHandlers.external.postMessage()`
+- Serializes messages to JSON for Go processing
+
+**Methods**:
+- `userContentController:didReceiveScriptMessage:`: Process JS messages
+
+#### WailsViewController
+```objc
+@interface WailsViewController : UIViewController
+```
+- Main view controller containing WKWebView
+- Manages WebView lifecycle
+- Handles JavaScript execution requests
+
+**Properties**:
+- `webView`: WKWebView instance
+- `schemeHandler`: Custom URL scheme handler
+- `messageHandler`: JS message handler
+- `windowID`: Unique window identifier
+
+**Methods**:
+- `viewDidLoad`: Initialize WebView with configuration
+- `executeJavaScript:`: Run JS code in WebView
+
+### 3. Bridge Layer (CGO)
+
+**C Interface Functions**:
+```c
+void ios_app_init(void);                    // Initialize iOS app
+void ios_app_run(void);                     // Run main loop
+void ios_app_quit(void);                    // Quit application
+bool ios_is_dark_mode(void);                // Check dark mode
+unsigned int ios_create_webview(void);      // Create WebView
+void ios_execute_javascript(unsigned int windowID, const char* js);
+void ios_complete_request(unsigned int callbackID, const char* data, const char* mimeType);
+```
+
+## Layer Architecture
+
+### Layer 1: Presentation Layer (WebView)
+
+**Responsibilities**:
+- Render HTML/CSS/JavaScript UI
+- Handle user interactions
+- Communicate with native layer
+
+**Key Features**:
+- WKWebView for modern web standards
+- Hardware-accelerated rendering
+- Efficient memory management
+
+### Layer 2: Communication Layer
+
+**Request Interception**:
+```
+WebView Request → WKURLSchemeHandler → Go ServeAssetRequest → AssetServer → Response
+```
+
+**JavaScript Bridge**:
+```
+JS postMessage → WKScriptMessageHandler → Go HandleJSMessage → Process → ExecuteJavaScript
+```
+
+### Layer 3: Application Layer (Go)
+
+**Components**:
+- Application lifecycle management
+- Service binding and method calls
+- Asset serving from embedded fs.FS
+- Business logic execution
+
+### Layer 4: Platform Integration Layer
+
+**iOS-Specific Features**:
+- Dark mode detection
+- System appearance integration
+- iOS-specific optimizations
+
+## Implementation Details
+
+### Request Handling Flow
+
+1. **WebView makes request** to `wails://localhost/path`
+2. **WKURLSchemeHandler intercepts** request
+3. **Creates callback ID** and stores `WKURLSchemeTask`
+4. **Calls Go function** `ServeAssetRequest` with URL and callback ID
+5. **Go processes request** through AssetServer
+6. **Go calls** `ios_complete_request` with response data
+7. **Objective-C completes** the `WKURLSchemeTask` with response
+
+### JavaScript Execution Flow
+
+1. **Go calls** `ios_execute_javascript` with JS code
+2. **Bridge dispatches** to main thread
+3. **WKWebView evaluates** JavaScript
+4. **Completion handler** logs any errors
+
+### Message Passing Flow
+
+1. **JavaScript calls** `window.webkit.messageHandlers.wails.postMessage(data)`
+2. **WKScriptMessageHandler receives** message
+3. **Serializes to JSON** and passes to Go
+4. **Go processes** message in `HandleJSMessage`
+5. **Go can respond** via `ExecuteJavaScript`
+
+## Battery Optimization
+
+### WebView Configuration
+
+```objc
+// Disable unnecessary features
+config.suppressesIncrementalRendering = NO;
+config.allowsInlineMediaPlayback = YES;
+config.mediaTypesRequiringUserActionForPlayback = WKAudiovisualMediaTypeNone;
+```
+
+### Memory Management
+
+1. **Single WebView Instance**: Reuse instead of creating new instances
+2. **Automatic Reference Counting**: Use ARC for Objective-C objects
+3. **Lazy Loading**: Initialize components only when needed
+4. **Resource Cleanup**: Properly release resources when done
+
+### Request Optimization
+
+1. **In-Process Serving**: No network overhead
+2. **Direct Memory Transfer**: Pass data directly without serialization
+3. **Efficient Caching**: Leverage WKWebView's built-in cache
+4. **Minimal Wake Locks**: No background network activity
+
+## Build System
+
+### Build Tags
+
+```go
+//go:build ios
+```
+
+### CGO Configuration
+
+```go
+#cgo CFLAGS: -x objective-c -fobjc-arc
+#cgo LDFLAGS: -framework Foundation -framework UIKit -framework WebKit
+```
+
+### Build Script (`build_ios.sh`)
+
+**Steps**:
+1. Check dependencies (go, xcodebuild, xcrun)
+2. Set up iOS cross-compilation environment
+3. Build Go binary with iOS tags
+4. Create app bundle structure
+5. Generate Info.plist
+6. Sign for simulator
+7. Create launch script
+
+**Environment Variables**:
+```bash
+export CGO_ENABLED=1
+export GOOS=ios
+export GOARCH=arm64
+export SDK_PATH=$(xcrun --sdk iphonesimulator --show-sdk-path)
+```
+
+### Simulator Deployment
+
+```bash
+xcrun simctl install "$DEVICE_ID" "WailsIOSDemo.app"
+xcrun simctl launch "$DEVICE_ID" "com.wails.iosdemo"
+```
+
+## Security Considerations
+
+### URL Scheme Security
+
+1. **Custom Scheme**: Use `wails://` to avoid conflicts
+2. **Origin Validation**: Only serve to authorized WebViews
+3. **No External Access**: Scheme handler only responds to app's WebView
+
+### JavaScript Execution
+
+1. **Input Validation**: Sanitize JS code before execution
+2. **Sandboxed Execution**: WKWebView provides isolation
+3. **No eval()**: Avoid dynamic code evaluation
+
+### Data Protection
+
+1. **In-Memory Only**: No temporary files on disk
+2. **ATS Compliance**: App Transport Security enabled
+3. **Secure Communication**: All data stays within app process
+
+## API Reference
+
+### Go API
+
+#### Application Functions
+
+```go
+// Create new iOS application
+app := application.New(application.Options{
+    Name: "App Name",
+    Description: "App Description",
+})
+
+// Run the application
+app.Run()
+
+// Execute JavaScript
+app.ExecuteJavaScript(windowID, "console.log('Hello')")
+```
+
+#### Service Binding
+
+```go
+type MyService struct{}
+
+func (s *MyService) Greet(name string) string {
+    return fmt.Sprintf("Hello, %s!", name)
+}
+
+app := application.New(application.Options{
+    Services: []application.Service{
+        application.NewService(&MyService{}),
+    },
+})
+```
+
+### JavaScript API
+
+#### Send Message to Go
+
+```javascript
+window.webkit.messageHandlers.wails.postMessage({
+    type: 'methodCall',
+    service: 'MyService',
+    method: 'Greet',
+    args: ['World']
+});
+```
+
+#### Receive from Go
+
+```javascript
+window.wailsCallback = function(data) {
+    console.log('Received:', data);
+};
+```
+
+### Objective-C Bridge API
+
+#### From Go to Objective-C
+
+```c
+// Execute JavaScript
+ios_execute_javascript(windowID, "alert('Hello')");
+
+// Complete asset request
+ios_complete_request(callbackID, htmlData, "text/html");
+```
+
+#### From Objective-C to Go
+
+```c
+// Serve asset request
+ServeAssetRequest(windowID, urlString, callbackID);
+
+// Handle JavaScript message
+HandleJSMessage(windowID, jsonMessage);
+```
+
+## Performance Metrics
+
+### Target Metrics
+
+- **WebView Creation**: < 100ms
+- **Asset Request**: < 10ms for cached, < 50ms for first load
+- **JS Execution**: < 5ms for simple scripts
+- **Message Passing**: < 2ms round trip
+- **Memory Usage**: < 50MB baseline
+- **Battery Impact**: < 2% per hour active use
+
+### Monitoring
+
+1. **Xcode Instruments**: CPU, Memory, Energy profiling
+2. **WebView Inspector**: JavaScript performance
+3. **Go Profiling**: pprof for Go code analysis
+
+## Future Enhancements
+
+### Phase 1: Core Stability
+- [ ] Production-ready error handling
+- [ ] Comprehensive test suite
+- [ ] Performance optimization
+
+### Phase 2: Feature Parity
+- [ ] Multiple window support
+- [ ] System tray integration
+- [ ] Native menu implementation
+
+### Phase 3: iOS-Specific Features
+- [ ] Widget extension support
+- [ ] App Clip support
+- [ ] ShareSheet integration
+- [ ] Siri Shortcuts
+
+### Phase 4: Advanced Features
+- [ ] Background task support
+- [ ] Push notifications
+- [ ] CloudKit integration
+- [ ] Apple Watch companion app
+
+## Conclusion
+
+This architecture provides a solid foundation for iOS support in Wails v3. The design prioritizes battery efficiency, native performance, and seamless integration with the existing Wails ecosystem. The proof of concept demonstrates all four required capabilities:
+
+1. ✅ **WebView Creation**: Native WKWebView with optimized configuration
+2. ✅ **Request Interception**: Custom scheme handler without network ports
+3. ✅ **JavaScript Execution**: Bidirectional communication bridge
+4. ✅ **iOS Simulator Support**: Complete build and deployment pipeline
+
+The architecture is designed to scale from this proof of concept to a full production implementation while maintaining the simplicity and elegance that Wails developers expect.

README.de.md

@@ -25,7 +25,7 @@ Erschaffe Desktop Anwendungen mit Go & Web Technologien.
     <img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome" />
   </a>
   <a href="https://discord.gg/BrRSWTaxVK">
-    <img alt="Discord" src="https://img.shields.io/discord/1042734330029547630?logo=discord"/>
+    <img alt="Discord" src="https://dcbadge.vercel.app/api/server/BrRSWTaxVK?style=flat"/>
   </a>
   <br/>
   <a href="https://github.com/wailsapp/wails/actions/workflows/build-and-test.yml" rel="nofollow">

README.es.md

@@ -25,7 +25,7 @@
     <img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome" />
   </a>
   <a href="https://discord.gg/BrRSWTaxVK">
-    <img alt="Discord" src="https://img.shields.io/discord/1042734330029547630?logo=discord"/>
+    <img alt="Discord" src="https://dcbadge.vercel.app/api/server/BrRSWTaxVK?style=flat"/>
   </a>
   <br/>
   <a href="https://github.com/wailsapp/wails/actions/workflows/build-and-test.yml" rel="nofollow">

README.fr.md

@@ -25,7 +25,7 @@
     <img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome" />
   </a>
   <a href="https://discord.gg/BrRSWTaxVK">
-    <img alt="Discord" src="https://img.shields.io/discord/1042734330029547630?logo=discord"/>
+    <img alt="Discord" src="https://dcbadge.vercel.app/api/server/BrRSWTaxVK?style=flat"/>
   </a>
   <br/>
   <a href="https://github.com/wailsapp/wails/actions/workflows/build-and-test.yml" rel="nofollow">

README.ja.md

@@ -27,7 +27,7 @@
     <img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome" />
   </a>
   <a href="https://discord.gg/BrRSWTaxVK">
-    <img alt="Discord" src="https://img.shields.io/discord/1042734330029547630?logo=discord"/>
+    <img alt="Discord" src="https://dcbadge.vercel.app/api/server/BrRSWTaxVK?style=flat"/>
   </a>
   <br/>
   <a href="https://github.com/wailsapp/wails/actions/workflows/build-and-test.yml" rel="nofollow">

README.ko.md

@@ -27,7 +27,7 @@
     <img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome" />
   </a>
   <a href="https://discord.gg/BrRSWTaxVK">
-    <img alt="Discord" src="https://img.shields.io/discord/1042734330029547630?logo=discord"/>
+    <img alt="Discord" src="https://dcbadge.vercel.app/api/server/BrRSWTaxVK?style=flat"/>
   </a>
   <br/>
   <a href="https://github.com/wailsapp/wails/actions/workflows/build-and-test.yml" rel="nofollow">

README.md

@@ -25,7 +25,7 @@
     <img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome" />
   </a>
   <a href="https://discord.gg/BrRSWTaxVK">
-    <img alt="Discord" src="https://img.shields.io/discord/1042734330029547630?logo=discord"/>
+    <img alt="Discord" src="https://dcbadge.vercel.app/api/server/BrRSWTaxVK?style=flat"/>
   </a>
   <br/>
   <a href="https://github.com/wailsapp/wails/actions/workflows/build-and-test.yml" rel="nofollow">
@@ -98,9 +98,9 @@ The installation instructions are on the [official website](https://wails.io/doc
 This project is supported by these kind people / companies:
 <img src="website/static/img/sponsors.svg" style="width:100%;max-width:800px;"/>
 
-## Powered By
-
-[![JetBrains logo.](https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg)](https://jb.gg/OpenSource)
+<p align="center">
+<img src="https://wails.io/img/sponsor/jetbrains-grayscale.webp" style="width: 100px"/>
+</p>
 
 ## FAQ
 

README.pt-br.md

@@ -25,7 +25,7 @@
     <img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome" />
   </a>
   <a href="https://discord.gg/BrRSWTaxVK">
-    <img alt="Discord" src="https://img.shields.io/discord/1042734330029547630?logo=discord"/>
+    <img alt="Discord" src="https://dcbadge.vercel.app/api/server/BrRSWTaxVK?style=flat"/>
   </a>
   <br/>
   <a href="https://github.com/wailsapp/wails/actions/workflows/build-and-test.yml" rel="nofollow">

README.ru.md

@@ -25,7 +25,7 @@
     <img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome" />
   </a>
   <a href="https://discord.gg/BrRSWTaxVK">
-    <img alt="Discord" src="https://img.shields.io/discord/1042734330029547630?logo=discord"/>
+    <img alt="Discord" src="https://dcbadge.vercel.app/api/server/BrRSWTaxVK?style=flat"/>
   </a>
   <br/>
   <a href="https://github.com/wailsapp/wails/actions/workflows/build-and-test.yml" rel="nofollow">

README.tr.md

@@ -25,7 +25,7 @@
     <img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome" />
   </a>
   <a href="https://discord.gg/BrRSWTaxVK">
-    <img alt="Discord" src="https://img.shields.io/discord/1042734330029547630?logo=discord"/>
+    <img alt="Discord" src="https://dcbadge.vercel.app/api/server/BrRSWTaxVK?style=flat"/>
   </a>
   <br/>
   <a href="https://github.com/wailsapp/wails/actions/workflows/build-and-test.yml" rel="nofollow">

README.uz.md

@@ -25,7 +25,7 @@
     <img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome" />
   </a>
   <a href="https://discord.gg/BrRSWTaxVK">
-    <img alt="Discord" src="https://img.shields.io/discord/1042734330029547630?logo=discord"/>
+    <img alt="Discord" src="https://dcbadge.vercel.app/api/server/BrRSWTaxVK?style=flat"/>
   </a>
   <br/>
   <a href="https://github.com/wailsapp/wails/actions/workflows/build-and-test.yml" rel="nofollow">

README.zh-Hans.md

@@ -27,7 +27,7 @@
     <img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome" />
   </a>
   <a href="https://discord.gg/BrRSWTaxVK">
-    <img alt="Discord" src="https://img.shields.io/discord/1042734330029547630?logo=discord"/>
+    <img alt="Discord" src="https://dcbadge.vercel.app/api/server/BrRSWTaxVK?style=flat"/>
   </a>
   <br/>
   <a href="https://github.com/wailsapp/wails/actions/workflows/build-and-test.yml" rel="nofollow">

Taskfile.yaml

@@ -16,6 +16,11 @@ includes:
     dir: v3
     optional: true
 
+  docs:
+    taskfile: docs
+    dir: docs
+    optional: true
+
 tasks:
   contributors:check:
     cmds:

docs/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

docs/.npmrc

@@ -0,0 +1 @@
+save-exact=true

docs/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

docs/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

docs/CNAME

@@ -0,0 +1 @@
+v3alpha.wails.io

docs/README.md

@@ -0,0 +1,65 @@
+# Wails v3 Documentation
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+World-class documentation for Wails v3, redesigned following Netflix documentation principles.
+
+## 📚 Documentation Redesign (2025-10-01)
+
+This documentation has been completely redesigned to follow the **Netflix approach** to developer documentation:
+
+- **Problem-first framing** - Start with why, not what
+- **Progressive disclosure** - Multiple entry points for different skill levels
+- **Real production examples** - No toy code
+- **Story-Code-Context pattern** - Why → How → When
+- **Scannable content** - Clear structure, visual aids
+
+**Status:** Foundation complete (~20%), ready for content migration
+
+See [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) for full details.
+
+## 🚀 Project Structure
+
+Inside of your Astro + Starlight project, you'll see the following folders and
+files:
+
+```sh
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── content/
+│   │   ├── docs/
+│   │   └── config.ts
+│   └── env.d.ts
+├── astro.config.mjs
+├── package.json
+└── tsconfig.json
+```
+
+Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory.
+Each file is exposed as a route based on its file name.
+
+Images can be added to `src/assets/` and embedded in Markdown with a relative
+link.
+
+Static assets, like favicons, can be placed in the `public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `npm install`             | Installs dependencies                            |
+| `npm run dev`             | Starts local dev server at `localhost:4321`      |
+| `npm run build`           | Build your production site to `./dist/`          |
+| `npm run preview`         | Preview your build locally, before deploying     |
+| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `npm run astro -- --help` | Get help using the Astro CLI                     |
+
+## 👀 Want to learn more?
+
+Check out [Starlight’s docs](https://starlight.astro.build/), read
+[the Astro documentation](https://docs.astro.build), or jump into the
+[Astro Discord server](https://astro.build/chat).

docs/Taskfile.yml

@@ -0,0 +1,36 @@
+# https://taskfile.dev
+
+version: '3'
+
+vars:
+  # Change this to switch package managers: bun, npm, pnpm, yarn
+  PKG_MANAGER: npm
+
+tasks:
+
+  setup:
+    summary: Setup the project (including D2 diagram tool)
+    preconditions:
+      - sh: '{{.PKG_MANAGER}} --version'
+        msg: "Looks like {{.PKG_MANAGER}} isn't installed."
+      - sh: 'go version'
+        msg: "Go is not installed. Install from https://go.dev/dl/"
+    cmds:
+      - '{{.PKG_MANAGER}} install'
+      - go install oss.terrastruct.com/d2@latest
+      - echo "✓ Setup complete. D2 installed to $(go env GOPATH)/bin/d2"
+
+  dev:
+    summary: Run the dev server
+    deps: [setup]
+    cmds:
+      - '{{.PKG_MANAGER}} run dev'
+
+  build:
+    summary: Build the docs
+    preconditions:
+      - sh: '{{.PKG_MANAGER}} --version'
+        msg: "Looks like {{.PKG_MANAGER}} isn't installed."
+    cmds:
+      - '{{.PKG_MANAGER}} run build'
+

docs/astro.config.mjs

@@ -0,0 +1,344 @@
+// @ts-check
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+import sitemap from "@astrojs/sitemap";
+import starlightLinksValidator from "starlight-links-validator";
+import starlightImageZoom from "starlight-image-zoom";
+import starlightBlog from "starlight-blog";
+import { authors } from "./src/content/authors";
+import d2 from 'astro-d2';
+import react from '@astrojs/react';
+
+// https://astro.build/config
+export default defineConfig({
+  site: "https://wails.io",
+  trailingSlash: "ignore",
+  compressHTML: true,
+  output: "static",
+  build: { format: "directory" },
+  devToolbar: { enabled: true },
+  integrations: [
+    react(),
+    d2(),
+    sitemap(),
+    starlight({
+      title: "",
+      titleDelimiter: "",
+      logo: {
+        dark: "./src/assets/wails-logo-horizontal-dark.svg",
+        light: "./src/assets/wails-logo-horizontal-light.svg",
+      },
+      favicon: "./public/favicon.svg",
+      description: "Build beautiful desktop applications using Go and modern web technologies.",
+      pagefind: true,
+      customCss: ["./src/stylesheets/extra.css"],
+      lastUpdated: true,
+      pagination: true,
+      editLink: {
+        baseUrl: "https://github.com/wailsapp/wails/edit/v3-alpha/docs",
+      },
+      social: [
+        { icon: 'github', label: 'GitHub', href: 'https://github.com/wailsapp/wails' },
+        { icon: 'discord', label: 'Discord', href: 'https://discord.gg/JDdSxwjhGf' },
+        { icon: 'x.com', label: 'X', href: 'https://x.com/wailsapp' },
+      ],
+      head: [
+        {
+          tag: 'script',
+          content: `
+            document.addEventListener('DOMContentLoaded', () => {
+              const socialLinks = document.querySelector('.social-icons');
+              if (socialLinks) {
+                const sponsorLink = document.createElement('a');
+                sponsorLink.href = 'https://github.com/sponsors/leaanthony';
+                sponsorLink.className = 'sl-flex';
+                sponsorLink.title = 'Sponsor';
+                sponsorLink.innerHTML = '<span class="sr-only">Sponsor</span><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="#ef4444" stroke="none"><path d="M19 14c1.49-1.46 3-3.21 3-5.5A5.5 5.5 0 0 0 16.5 3c-1.76 0-3 .5-4.5 2-1.5-1.5-2.74-2-4.5-2A5.5 5.5 0 0 0 2 8.5c0 2.3 1.5 4.05 3 5.5l7 7Z"/></svg>';
+                socialLinks.appendChild(sponsorLink);
+              }
+            });
+          `,
+        },
+      ],
+      defaultLocale: "root",
+      locales: {
+        root: { label: "English", lang: "en", dir: "ltr" },
+      },
+      plugins: [
+        starlightImageZoom(),
+        starlightBlog({
+          title: "Wails Blog",
+          authors: authors,
+        }),
+      ],
+      sidebar: [
+        { label: "Home", link: "/" },
+
+        // Progressive Onboarding - Netflix Principle: Start with the problem
+        { label: "Why Wails?", link: "/quick-start/why-wails" },
+
+        {
+          label: "Quick Start",
+          collapsed: false,
+          items: [
+            { label: "Installation", link: "/quick-start/installation" },
+            { label: "Your First App", link: "/quick-start/first-app" },
+            { label: "Next Steps", link: "/quick-start/next-steps" },
+          ],
+        },
+
+        // Tutorials
+        {
+          label: "Tutorials",
+          collapsed: true,
+          autogenerate: { directory: "tutorials" },
+        },
+
+        // Core Concepts
+        {
+          label: "Core Concepts",
+          collapsed: true,
+          items: [
+            { label: "How Wails Works", link: "/concepts/architecture" },
+            { label: "Manager API", link: "/concepts/manager-api" },
+            { label: "Application Lifecycle", link: "/concepts/lifecycle" },
+            { label: "Go-Frontend Bridge", link: "/concepts/bridge" },
+            { label: "Build System", link: "/concepts/build-system" },
+          ],
+        },
+
+        {
+          label: "Features",
+          collapsed: true,
+          items: [
+            {
+              label: "Windows",
+              collapsed: true,
+              items: [
+                { label: "Window Basics", link: "/features/windows/basics" },
+                { label: "Window Options", link: "/features/windows/options" },
+                { label: "Multiple Windows", link: "/features/windows/multiple" },
+                { label: "Frameless Windows", link: "/features/windows/frameless" },
+                { label: "Window Events", link: "/features/windows/events" },
+              ],
+            },
+            {
+              label: "Menus",
+              collapsed: true,
+              items: [
+                { label: "Application Menus", link: "/features/menus/application" },
+                { label: "Context Menus", link: "/features/menus/context" },
+                { label: "System Tray Menus", link: "/features/menus/systray" },
+                { label: "Menu Reference", link: "/features/menus/reference" },
+              ],
+            },
+            {
+              label: "Bindings & Services",
+              collapsed: true,
+              items: [
+                { label: "Method Binding", link: "/features/bindings/methods" },
+                { label: "Services", link: "/features/bindings/services" },
+                { label: "Advanced Binding", link: "/features/bindings/advanced" },
+                { label: "Best Practices", link: "/features/bindings/best-practices" },
+              ],
+            },
+            {
+              label: "Events",
+              collapsed: true,
+              items: [
+                { label: "Event System", link: "/features/events/system" },
+                { label: "Application Events", link: "/features/events/application" },
+                { label: "Window Events", link: "/features/events/window" },
+                { label: "Custom Events", link: "/features/events/custom" },
+              ],
+            },
+            {
+              label: "Dialogs",
+              collapsed: true,
+              items: [
+                { label: "File Dialogs", link: "/features/dialogs/file" },
+                { label: "Message Dialogs", link: "/features/dialogs/message" },
+                { label: "Custom Dialogs", link: "/features/dialogs/custom" },
+              ],
+            },
+            {
+              label: "Clipboard",
+              collapsed: true,
+              autogenerate: { directory: "features/clipboard" },
+            },
+            {
+              label: "Browser",
+              collapsed: true,
+              autogenerate: { directory: "features/browser" },
+            },
+            { label: "Drag & Drop", link: "/features/drag-drop" },
+            {
+              label: "Keyboard",
+              collapsed: true,
+              autogenerate: { directory: "features/keyboard" },
+            },
+            {
+              label: "Notifications",
+              collapsed: true,
+              autogenerate: { directory: "features/notifications" },
+            },
+            {
+              label: "Screens",
+              collapsed: true,
+              autogenerate: { directory: "features/screens" },
+            },
+            {
+              label: "Environment",
+              collapsed: true,
+              autogenerate: { directory: "features/environment" },
+            },
+            {
+              label: "Platform-Specific",
+              collapsed: true,
+              autogenerate: { directory: "features/platform" },
+            },
+          ],
+        },
+
+        // Guides - Task-oriented patterns (Netflix: When to use it, when not to use it)
+        {
+          label: "Guides",
+          collapsed: true,
+          items: [
+            {
+              label: "Development",
+              collapsed: true,
+              items: [
+                { label: "Project Structure", link: "/guides/dev/project-structure" },
+                { label: "Development Workflow", link: "/guides/dev/workflow" },
+                { label: "Debugging", link: "/guides/dev/debugging" },
+                { label: "Testing", link: "/guides/dev/testing" },
+              ],
+            },
+            {
+              label: "Building & Packaging",
+              collapsed: true,
+              items: [
+                { label: "Building Applications", link: "/guides/build/building" },
+                { label: "Build Customization", link: "/guides/build/customization" },
+                { label: "Cross-Platform Builds", link: "/guides/build/cross-platform" },
+                { label: "Code Signing", link: "/guides/build/signing" },
+                { label: "Windows Packaging", link: "/guides/build/windows" },
+                { label: "macOS Packaging", link: "/guides/build/macos" },
+                { label: "Linux Packaging", link: "/guides/build/linux" },
+                { label: "MSIX Packaging", link: "/guides/build/msix" },
+              ],
+            },
+            {
+              label: "Distribution",
+              collapsed: true,
+              items: [
+                { label: "Auto-Updates", link: "/guides/distribution/auto-updates" },
+                { label: "File Associations", link: "/guides/distribution/file-associations" },
+                { label: "Custom Protocols", link: "/guides/distribution/custom-protocols" },
+                { label: "Single Instance", link: "/guides/distribution/single-instance" },
+              ],
+            },
+            {
+              label: "Integration Patterns",
+              collapsed: true,
+              items: [
+                { label: "Using Gin Router", link: "/guides/patterns/gin-routing" },
+                { label: "Gin Services", link: "/guides/patterns/gin-services" },
+                { label: "Database Integration", link: "/guides/patterns/database" },
+                { label: "REST APIs", link: "/guides/patterns/rest-api" },
+              ],
+            },
+            {
+              label: "Advanced Topics",
+              collapsed: true,
+              items: [
+                { label: "Custom Templates", link: "/guides/advanced/custom-templates" },
+                { label: "WML (Wails Markup)", link: "/guides/advanced/wml" },
+                { label: "Panic Handling", link: "/guides/advanced/panic-handling" },
+                { label: "Security Best Practices", link: "/guides/advanced/security" },
+              ],
+            },
+          ],
+        },
+
+        // Reference - Comprehensive API docs (Netflix: Complete technical reference)
+        {
+          label: "API Reference",
+          collapsed: true,
+          items: [
+            { label: "Overview", link: "/reference/overview" },
+            { label: "Application", link: "/reference/application" },
+            { label: "Window", link: "/reference/window" },
+            { label: "Menu", link: "/reference/menu" },
+            { label: "Events", link: "/reference/events" },
+            { label: "Dialogs", link: "/reference/dialogs" },
+            { label: "Frontend Runtime", link: "/reference/frontend-runtime" },
+            { label: "CLI", link: "/reference/cli" },
+          ],
+        },
+
+        // Contributing
+        {
+          label: "Contributing",
+          collapsed: true,
+          items: [
+            { label: "Getting Started", link: "/contributing/getting-started" },
+            { label: "Development Setup", link: "/contributing/setup" },
+            { label: "Coding Standards", link: "/contributing/standards" },
+          ],
+        },
+
+        // Migration & Troubleshooting
+        {
+          label: "Migration",
+          collapsed: true,
+          items: [
+            { label: "From v2 to v3", link: "/migration/v2-to-v3" },
+            { label: "From Electron", link: "/migration/from-electron" },
+          ],
+        },
+
+        {
+          label: "Troubleshooting",
+          collapsed: true,
+          autogenerate: { directory: "troubleshooting" },
+        },
+
+        // Community & Resources
+        {
+          label: "Community",
+          collapsed: true,
+          items: [
+            { label: "Links", link: "/community/links" },
+            { label: "Templates", link: "/community/templates" },
+            {
+              label: "Showcase",
+              collapsed: true,
+              items: [
+                { label: "Overview", link: "/community/showcase" },
+                {
+                  label: "Applications",
+                  autogenerate: {
+                    directory: "community/showcase",
+                    collapsed: true,
+                  },
+                },
+              ],
+            },
+          ],
+        },
+
+        { label: "What's New", link: "/whats-new" },
+        { label: "Status", link: "/status" },
+        { label: "Changelog", link: "/changelog" },
+        {
+          label: "Sponsor",
+          link: "https://github.com/sponsors/leaanthony",
+          badge: { text: "❤️" },
+        },
+        { label: "Credits", link: "/credits" },
+      ],
+    }),
+  ],
+});

docs/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "wails-docs",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro check && astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/check": "^0.9.4",
+    "@astrojs/react": "^4.1.0",
+    "@astrojs/starlight": "0.36.2",
+    "@types/react": "^19.0.1",
+    "@types/react-dom": "^19.0.2",
+    "astro": "^5.0.0",
+    "astro-d2": "^0.5.0",
+    "framer-motion": "^11.14.4",
+    "motion": "^11.14.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "sharp": "^0.33.5",
+    "starlight-blog": "0.25.1",
+    "starlight-image-zoom": "^0.9.0",
+    "starlight-links-validator": "^0.13.4",
+    "starlight-showcases": "^0.2.0",
+    "typescript": "^5.7.2"
+  }
+}

docs/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" version="1.1" viewBox="0 0 550 310" xml:space="preserve" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2"><g><path d="M0.883,-0.081L0.121,0.081L0.256,-0.063L0.883,-0.081Z" transform="matrix(-166.599,4.57132,4.57132,166.599,147.403,167.648)" style="fill:url(#_Linear1);fill-rule:nonzero"/></g><g><path d="M0.878,-0.285L-0.073,0.71L-1.186,0.542L0.015,0.207L-0.846,0.077L0.355,-0.258L-0.505,-0.388L0.649,-0.71L0.878,-0.285Z" transform="matrix(-106.443,-16.0669,-16.0669,106.443,428.19,188.033)" style="fill:url(#_Linear2);fill-rule:nonzero"/></g><g><path d="M0.44,-0.04L0.265,-0.056L0.177,0.437L-0.311,-0.255L0.262,-0.437L0.568,-0.437L0.44,-0.04Z" transform="matrix(-114.484,-162.408,-162.408,114.484,333.291,285.804)" style="fill:url(#_Linear3);fill-rule:nonzero"/></g><g><path d="M0.622,-0.115L0.761,-0.115L0.806,-0.013L0.826,0.182L0.622,-0.115Z" transform="matrix(238.126,298.893,298.893,-238.126,113.516,-150.536)" style="fill:url(#_Linear4);fill-rule:nonzero"/></g><g><path d="M0.467,0.005L0.49,0.062L0.271,-0.062L0.467,0.005Z" transform="matrix(-369.529,-97.4118,-97.4118,369.529,582.38,94.027)" style="fill:url(#_Linear5);fill-rule:nonzero"/></g><g><path d="M0.2,0.001L0.219,-0.018L0.614,0.012L0.519,0.089L0.282,0.068L0.2,0.135L0.463,0.194L0.374,0.266L0.138,0.186L0.047,0.033L-0.131,-0.266L0.2,0.001Z" transform="matrix(-496.156,-53.9751,-53.9751,496.156,367.888,125.085)" style="fill:url(#_Linear6);fill-rule:nonzero"/></g><g><path d="M269.095,104.527L287.764,111.419L263.632,106.75L269.095,104.527Z" transform="matrix(0.436503,-1.22916,4.88651,1.73532,-368.043,253.619)" style="fill:#fff"/></g><defs><linearGradient id="_Linear1" x1="0" x2="1" y1="0" y2="0" gradientTransform="matrix(1,-3.46945e-18,3.46945e-18,1,0,-3.05761e-06)" gradientUnits="userSpaceOnUse"><stop offset="0" style="stop-color:#e33232;stop-opacity:1"/><stop offset="1" style="stop-color:#6b000d;stop-opacity:1"/></linearGradient><linearGradient id="_Linear2" x1="0" x2="1" y1="0" y2="0" gradientTransform="matrix(1,0,0,1,0,-2.75467e-06)" gradientUnits="userSpaceOnUse"><stop offset="0" style="stop-color:#e33232;stop-opacity:1"/><stop offset="1" style="stop-color:#6b000d;stop-opacity:1"/></linearGradient><linearGradient id="_Linear3" x1="0" x2="1" y1="0" y2="0" gradientTransform="matrix(1,-1.11022e-16,1.11022e-16,1,0,-2.61861e-06)" gradientUnits="userSpaceOnUse"><stop offset="0" style="stop-color:#e33232;stop-opacity:1"/><stop offset="1" style="stop-color:#6b000d;stop-opacity:1"/></linearGradient><linearGradient id="_Linear4" x1="0" x2="1" y1="0" y2="0" gradientTransform="matrix(-0.801899,-0.59746,0.59746,-0.801899,1.3495,0.447457)" gradientUnits="userSpaceOnUse"><stop offset="0" style="stop-color:#e33232;stop-opacity:1"/><stop offset="1" style="stop-color:#6b000d;stop-opacity:1"/></linearGradient><linearGradient id="_Linear5" x1="0" x2="1" y1="0" y2="0" gradientTransform="matrix(1,-2.77556e-17,2.77556e-17,1,0,-1.92826e-06)" gradientUnits="userSpaceOnUse"><stop offset="0" style="stop-color:#e33232;stop-opacity:1"/><stop offset="1" style="stop-color:#6b000d;stop-opacity:1"/></linearGradient><linearGradient id="_Linear6" x1="0" x2="1" y1="0" y2="0" gradientTransform="matrix(1,0,0,1,0,9.68429e-07)" gradientUnits="userSpaceOnUse"><stop offset="0" style="stop-color:#e33232;stop-opacity:1"/><stop offset="1" style="stop-color:#6b000d;stop-opacity:1"/></linearGradient></defs></svg>