Add Electrobun hybrid WGPU showcase

.github/release/RELEASE-GATE-CHECKLIST.md

@@ -34,7 +34,7 @@ Use this as the canonical gate artifact for `0.3.0+` releases. It complements
 
 - [ ] Candidate was promoted from `development` after successful staging deploy (`gametau-dev`) and smoke checks.
 - [ ] Scope issues are closed (or explicitly deferred with notes).
-- [ ] `CI` run on `master` is green for all required jobs (`MSRV`, `Rust`, `TypeScript`, `Lint`, `API Docs`, `Scaffold & Build Smoke`, `Electrobun Browser + GPU Smoke`, `Publish Preflight`, `Release Gate Contract`).
+- [ ] `CI` run on `master` is green for all required jobs (`MSRV`, `Rust`, `TypeScript`, `Lint`, `API Docs`, `Scaffold & Build Smoke`, `Electrobun Hybrid + GPU Smoke`, `Publish Preflight`, `Release Gate Contract`).
 - [ ] `create-gametau` template architecture checks pass (service seams + scaffold tests).
 - [ ] `CHANGELOG.md`, `README.md`, and docs reflect the release narrative and compatibility notes.
 - [ ] Version manifests are aligned across workspace crates, npm packages, and templates.

.github/workflows/ci.yml

@@ -231,7 +231,7 @@ jobs:
           test -f dist/index.html
 
   electrobun-smoke:
-    name: Electrobun Browser + GPU Smoke
+    name: Electrobun Hybrid + GPU Smoke
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -253,13 +253,14 @@ jobs:
       - name: Build Electrobun counter (web target)
         run: |
           cd examples/electrobun-counter
+          bun run test
           bun run build:web
           test -d dist
           test -f dist/index.html
-      - name: Build Electrobun counter (BrowserWindow package target)
+      - name: Build Electrobun counter (hybrid BrowserWindow package target)
         run: |
           cd examples/electrobun-counter
-          bun run build:electrobun:browser
+          bun run build:electrobun:hybrid
           test -d build
       - name: Build Electrobun counter (GpuWindow package target)
         run: |

.github/workflows/electrobun-dogfood.yml

@@ -66,7 +66,7 @@ jobs:
             cd examples/electrobun-counter
             bun install
             bun run build:web 2>&1 | tee ../../electrobun-smoke-results.log
-            bun run build:electrobun:browser 2>&1 | tee -a ../../electrobun-smoke-results.log
+            bun run build:electrobun:hybrid 2>&1 | tee -a ../../electrobun-smoke-results.log
             bun run build:electrobun:gpu 2>&1 | tee -a ../../electrobun-smoke-results.log
           else
             echo "Electrobun counter example not found, skipping." | tee electrobun-smoke-results.log

ELECTROBUN-SHOWCASE.md

@@ -6,7 +6,7 @@ This is the quickest way to try gametau running in Electrobun after the upstream
 
 gametau now supports two Electrobun shell shapes:
 
-- `BrowserWindow` for the current web-first app path
+- `BrowserWindow` + embedded `<electrobun-wgpu>` for the hybrid path
 - `GpuWindow` for a native WGPU shell that still reuses the shared Rust/WASM backend loop
 
 The fastest reference example is [`examples/electrobun-counter`](./examples/electrobun-counter).
@@ -21,10 +21,10 @@ bun run --cwd packages/webtau build
 bun run --cwd packages/webtau-vite build
 ```
 
-Launch the BrowserWindow path:
+Launch the hybrid BrowserWindow path:
 
 ```bash
-bun run --cwd examples/electrobun-counter dev:electrobun:browser
+bun run --cwd examples/electrobun-counter dev:electrobun:hybrid
 ```
 
 Launch the GPUWindow path:
@@ -35,9 +35,17 @@ bun run --cwd examples/electrobun-counter dev:electrobun:gpu
 
 What you should see:
 
-- Browser mode: a native Electrobun window loads the Vite app and the counter UI works normally.
+- Hybrid mode: a native Electrobun window loads the Vite app, the counter UI works normally, and an embedded native WGPU surface runs inside the same BrowserWindow.
 - GPU mode: a native `GpuWindow` opens and the shared counter state advances through the WASM-backed game loop.
 
+## Why hybrid first
+
+This path is sequenced before pure `GpuWindow` because it proves the render/UI split with lower risk:
+
+- existing DOM HUD and controls stay intact
+- native WGPU rendering is exercised in the same app shell
+- resize, masking, passthrough, and overlay behavior can be validated before broader renderer refactors
+
 ## Scaffold a project
 
 ```bash
@@ -55,7 +63,7 @@ The generated scaffold keeps the web/Tauri path intact and adds:
 ## Build desktop packages
 
 ```bash
-bun run --cwd examples/electrobun-counter build:electrobun:browser
+bun run --cwd examples/electrobun-counter build:electrobun:hybrid
 bun run --cwd examples/electrobun-counter build:electrobun:gpu
 ```
 

RUNTIME-PORTABILITY-READINESS.md

@@ -32,13 +32,13 @@ bunx create-gametau my-game --desktop-shell electrobun --electrobun-mode dual
 
 Current supported shapes:
 
-- `BrowserWindow` shell for the existing web-first app structure
+- `BrowserWindow` shell with embedded `<electrobun-wgpu>` for hybrid UI/native-render composition
 - `GpuWindow` shell for native WGPU windows that still reuse the shared WASM backend loop
 
 Reference example:
 
 ```bash
-bun run --cwd examples/electrobun-counter dev:electrobun:browser
+bun run --cwd examples/electrobun-counter dev:electrobun:hybrid
 bun run --cwd examples/electrobun-counter dev:electrobun:gpu
 ```
 
@@ -59,7 +59,6 @@ bun run --cwd examples/electrobun-counter dev:electrobun:gpu
 ## Known gaps
 
 - `resolveResource()` in `webtau/path` is not yet implemented for web mode.
-- BrowserWindow + embedded `<electrobun-wgpu>` is not yet covered by a gametau showcase.
 - The current GPUWindow proof path validates shared backend reuse, not a full renderer abstraction.
 
 ## Validating integration readiness

examples/electrobun-counter/README.md

@@ -4,7 +4,7 @@ This example is the reference Electrobun showcase for gametau.
 
 It covers two shell shapes:
 
-- `BrowserWindow` for the web-first counter UI
+- `BrowserWindow` + embedded `<electrobun-wgpu>` for the hybrid UI/render split
 - `GpuWindow` for a native WGPU shell that still reuses the shared counter WASM backend
 
 ## Run
@@ -15,10 +15,10 @@ Install dependencies:
 bun install
 ```
 
-Start the BrowserWindow path:
+Start the hybrid BrowserWindow path:
 
 ```bash
-bun run dev:electrobun:browser
+bun run dev:electrobun:hybrid
 ```
 
 Start the GPUWindow path:
@@ -29,14 +29,23 @@ bun run dev:electrobun:gpu
 
 ## Runtime behavior
 
-- Browser mode loads the normal Vite app and auto-checks for `window.__ELECTROBUN__`.
+- Hybrid mode loads the normal Vite app, auto-checks for `window.__ELECTROBUN__`, and embeds a native WGPU surface via `<electrobun-wgpu>`.
+- The example keeps HTML HUD/buttons in the webview while the native surface is resized and masked underneath it.
 - If no Electrobun bridge is exposed, the browser shell still falls back cleanly to the normal WASM path.
 - GPU mode configures `webtau` directly in the Bun runtime, loads the same counter WASM module, and advances the shared counter state inside a native `GpuWindow`.
 
+## Why this exists
+
+This hybrid path is the lowest-risk step before deeper GPU-only renderer work:
+
+- it proves DOM UI and native rendering can coexist in one BrowserWindow
+- it exercises resize, masking, and click-routing without abandoning current web-first app structure
+- it gives a migration step for richer apps before pure `GpuWindow` renderer abstractions
+
 ## Build
 
 ```bash
 bun run build:web
-bun run build:electrobun:browser
+bun run build:electrobun:hybrid
 bun run build:electrobun:gpu
 ```