Merge remote-tracking branch 'origin/v3-alpha' into refactor/runtime-init-scripts

# Conflicts:
#	v3/UNRELEASED_CHANGELOG.md
#	v3/internal/assetserver/bundledassets/runtime.debug.js
#	v3/internal/assetserver/bundledassets/runtime.js
#	v3/internal/runtime/desktop/@wailsio/runtime/docs/assets/hierarchy.js
#	v3/internal/runtime/desktop/@wailsio/runtime/docs/assets/navigation.js
#	v3/internal/runtime/desktop/@wailsio/runtime/docs/classes/CancelError.html
#	v3/internal/runtime/desktop/@wailsio/runtime/docs/classes/CancellablePromise.html
#	v3/internal/runtime/desktop/@wailsio/runtime/docs/classes/CancelledRejectionError.html
#	v3/internal/runtime/desktop/@wailsio/runtime/docs/hierarchy.html

Author: leaanthony

.beads/issues.jsonl

@@ -0,0 +1,3 @@
+
+# Use bd merge for beads JSONL files
+.beads/issues.jsonl merge=beads

.gitattributes

@@ -111,13 +111,19 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Install linux dependencies
+      - name: Install linux dependencies (GTK3)
         uses: awalsh128/cache-apt-pkgs-action@latest
         if: matrix.os == 'ubuntu-latest'
         with:
-          packages: libgtk-3-dev libwebkit2gtk-4.1-dev build-essential pkg-config xvfb x11-xserver-utils at-spi2-core xdg-desktop-portal-gtk
+          packages: libgtk-3-dev libwebkit2gtk-4.1-dev libwayland-dev build-essential pkg-config xvfb x11-xserver-utils at-spi2-core xdg-desktop-portal-gtk
           version: 1.0
 
+      - name: Install linux dependencies (GTK4)
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libgtk-4-dev libwebkitgtk-6.0-dev
+
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
@@ -137,12 +143,20 @@ jobs:
           name: runtime-build-artifacts
           path: v3/internal/runtime/desktop/@wailsio/runtime/
 
-      - name: Build Examples
+      - name: Build Examples (GTK3 default)
         working-directory: v3
         run: |
-          echo "Starting example compilation tests..."
+          echo "Starting example compilation tests (GTK3)..."
           task test:examples
-          echo "Example compilation tests completed successfully"
+          echo "Example compilation tests (GTK3) completed successfully"
+
+      - name: Build Examples (GTK4)
+        if: matrix.os == 'ubuntu-latest'
+        working-directory: v3
+        run: |
+          echo "Starting example compilation tests (GTK4)..."
+          BUILD_TAGS=gtk4 task test:examples
+          echo "Example compilation tests (GTK4) completed successfully"
 
       - name: Run tests (mac)
         if: matrix.os == 'macos-latest'
@@ -156,7 +170,7 @@ jobs:
         working-directory: v3
         run: go test -v ./...
 
-      - name: Run tests (ubuntu)
+      - name: Run tests (ubuntu) - GTK3 default
         if: matrix.os == 'ubuntu-latest'
         working-directory: v3
         run: >
@@ -166,6 +180,17 @@ jobs:
           go test -v ./...
           '
 
+      - name: Run tests (ubuntu) - GTK4
+        if: matrix.os == 'ubuntu-latest'
+        working-directory: v3
+        # Skip service tests that hang in CI due to GTK4 display requirements
+        run: >
+          xvfb-run --auto-servernum
+          sh -c '
+          dbus-update-activation-environment --systemd --all &&
+          go test -tags gtk4 -v -skip "TestService" ./...
+          '
+
       - name: Typecheck binding generator output
         working-directory: v3
         run: task generator:test:check
@@ -210,13 +235,19 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Install linux dependencies
+      - name: Install linux dependencies (GTK3)
         uses: awalsh128/cache-apt-pkgs-action@latest
         if: matrix.os == 'ubuntu-latest'
         with:
-          packages: libgtk-3-dev libwebkit2gtk-4.1-dev build-essential pkg-config
+          packages: libgtk-3-dev libwebkit2gtk-4.1-dev libwayland-dev build-essential pkg-config
           version: 1.0
 
+      - name: Install linux dependencies (GTK4)
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libgtk-4-dev libwebkitgtk-6.0-dev
+
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
@@ -242,7 +273,7 @@ jobs:
           name: runtime-package
           path: wails-runtime-temp
 
-      - name: Generate template '${{ matrix.template }}'
+      - name: Generate template '${{ matrix.template }}' (GTK3 default)
         shell: bash
         run: |
           # Get absolute path - use pwd -W on Windows for native paths, pwd elsewhere
@@ -260,6 +291,8 @@ jobs:
           cd ..
           wails3 build
 
+      # GTK4 template builds are covered by the Go example compilation tests above.
+
   build_results:
     if: ${{ always() }}
     runs-on: ubuntu-latest

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

@@ -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
+          packages: libgtk-3-dev libwebkit2gtk-4.1-dev libwayland-dev build-essential pkg-config
           version: 1.0
 
       - name: Setup Go
@@ -126,7 +126,7 @@ jobs:
 
       - 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 libwayland-dev build-essential pkg-config
 
       - name: Generate & Build template '${{ matrix.template }}'
         if: matrix.os != 'ubuntu-24.04'

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

@@ -153,7 +153,7 @@ jobs:
       - name: Install Linux dev dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev
+          sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev libwayland-dev
 
       - name: Install wails3 CLI
         run: |

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

@@ -0,0 +1,44 @@
+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-code-review.yml

@@ -0,0 +1,50 @@
+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/claude.yml

@@ -83,7 +83,7 @@ jobs:
       - name: Install Linux dependencies
         uses: awalsh128/cache-apt-pkgs-action@latest
         with:
-          packages: libgtk-3-dev libwebkit2gtk-4.1-dev build-essential pkg-config
+          packages: libgtk-3-dev libwebkit2gtk-4.1-dev libwayland-dev build-essential pkg-config
           version: 1.0
 
       - name: Install Wails3 CLI
@@ -126,8 +126,8 @@ jobs:
       - run: |
           result="${{ needs.cross_compile.result }}"
           echo "Cross-compile result: $result"
-          if [[ $result == "success" ]]; then
-            echo "All cross-compile tests passed!"
+          if [[ $result == "success" || $result == "skipped" ]]; then
+            echo "Cross-compile tests passed (or were skipped)!"
             exit 0
           else
             echo "One or more cross-compile tests failed"

.github/workflows/cross-compile-test-v3.yml

@@ -52,7 +52,7 @@ jobs:
 
       - 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 libwayland-dev build-essential pkg-config
 
       - name: Setup Go
         uses: actions/setup-go@v3

.github/workflows/pr-master.yml

@@ -142,3 +142,56 @@ For example: `bd create --help` shows `--parent`, `--deps`, `--assignee`, etc.
 - Do NOT clutter repo root with planning documents
 
 For more details, see README.md and QUICKSTART.md.
+
+## Implementation Tracking (IMPLEMENTATION.md)
+
+**IMPORTANT**: The `IMPLEMENTATION.md` file at the repository root is a **persistent tracking document** for the WebKitGTK 6.0 / GTK4 implementation work. It is NOT an ephemeral planning document.
+
+### Requirements
+
+1. **Update with EVERY commit** that touches GTK4/WebKitGTK 6.0 related code
+2. **Track all architectural decisions** with context, decision, and rationale
+3. **Maintain progress status** for each implementation phase
+4. **Document API differences** between GTK3 and GTK4
+5. **Keep file references** accurate and up-to-date
+
+### What to Update
+
+- Phase completion status (✅ COMPLETE, 🔄 IN PROGRESS, 📋 PENDING)
+- New decisions made during implementation
+- Files created or modified
+- Changelog entries with dates
+- TODO items discovered during work
+
+### Commit Message Pattern
+
+When updating IMPLEMENTATION.md:
+```
+docs: update implementation tracker for [phase/feature]
+```
+
+## Landing the Plane (Session Completion)
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd sync
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds