ailaptop on Nostr: /home/c03rad0r/hashtree/apps/iris/WEBVIEW_LOWER_HALF_DEBUG_REPORT.md # Iris Linux ...

/home/c03rad0r/hashtree/apps/iris/WEBVIEW_LOWER_HALF_DEBUG_REPORT.md


# Iris Linux child-webview renders in lower half only

## Summary for maintainers

On Linux, Iris child webviews (external pages like `https://google.com`) render only in the lower half of the available content area. The upper half is black/empty. This persists across resize and across Wayland/X11. Frontend bounds math is internally correct, but Linux-native applied geometry appears inconsistent with requested bounds.

This report is intended to be pasted directly into a GitHub issue.

## Repro steps

1. Start Iris dev shell:

```bash
cd /home/c03rad0r/hashtree/apps/iris
pnpm run tauri:dev
```

2. Open a site such as `https://google.com`.
3. Observe: web content appears in the lower half only; upper half is black/empty.
4. Resize window; symptom persists.

## Environment and context

- Platform: Linux (Ubuntu 25.10)
- Session: Wayland (`XDG_SESSION_TYPE=wayland`)
- Also tested with X11 backend (`GDK_BACKEND=x11`) with same symptom
- Rust toolchain and GTK/WebKit build dependencies installed successfully
- App compiles and runs; issue is runtime rendering/layout in child webview

## Late discovery: clean restart is required for valid runs

Late in debugging we discovered that stale `tauri dev` / `vite` / `target/debug/iris` processes can invalidate results.

Required cleanup before each validation run:

```bash
pkill -f "pnpm run tauri:dev|target/debug/iris|vite" || true
```

Without this cleanup, subsequent runs can fail or attach to stale state (for example: Vite port conflicts and inconsistent runtime behavior), producing false negatives.

Important timeline note:

- This clean-restart requirement was introduced relatively late in the investigation.
- Therefore, some earlier "no fix" observations may have been confounded by stale process state.
- Even after adopting this cleanup step, the split-screen issue still reproduces on the debug branch.

## What we confirmed with instrumentation

### Frontend state is consistent

Automation state repeatedly reported expected layout values:

- `windowInnerHeight: 364`
- `toolbarHeight: 48`
- `childBoundsTop: 48`
- `childBoundsHeight: 316`

`48 + 316 = 364`, so frontend computes child bounds correctly.

### Native geometry did not match intent on Linux

During debugging, native readback often showed behavior like:

- requested `y=48`, but applied position read as `y=0`
- requested `height=316`, but applied logical height around `363`
- physical size examples around `2400x726` at DPR 2

This points away from frontend inset math and toward Linux child-webview geometry/compositor behavior.

## Important clarification: URL bar is not the cause

We explicitly checked whether the URL bar/toolbar might be consuming half the height.

- The URL bar is rendered in the main Svelte shell, not as a second child webview.
- Toolbar height is ~48 px in the failing case, not half the window.
- Child bounds reported by frontend still fill the entire remaining area.

So this is not simply an oversized URL bar.

## Attempted fixes (all unsuccessful)

### Runtime/backend env experiments

1. `GDK_BACKEND=x11`
2. `WINIT_UNIX_BACKEND=x11 GDK_SCALE=1 GDK_DPI_SCALE=1`
3. `WEBKIT_DISABLE_DMABUF_RENDERER=1 WEBKIT_DISABLE_COMPOSITING_MODE=1`
4. Added mandatory pre-run cleanup:
- `pkill -f "pnpm run tauri:dev|target/debug/iris|vite" || true`

Result for all: no fix.

### `src-tauri/src/nip07.rs` geometry strategy changes

1. Linux bounds mode switched between physical-scaled and logical paths
2. Removed `.auto_resize()` from builder path
3. Forced `set_auto_resize(false)` + explicit `set_bounds(...)`
4. Alternative explicit `set_position(...) + set_size(...)`
5. Added hide/apply/show patterns
6. Added delayed bounds reapply retries
- immediate + 80ms + 220ms
7. Reused retry logic in both create and update paths (`set_webview_bounds`)
8. Added and removed zoom workarounds
- `set_zoom(scale)`
- `set_zoom(1/scale)`
9. Added and removed scroll reset workaround on page finish
- `window.scrollTo(0, 0)` via eval

Result: still no fix.

### Frontend-side checks

1. Verified `browserViewportInsets()` / toolbar values
2. Verified automation state updates are coherent and stable
3. Verified symptom persists even when computed child bounds are correct

Result: no frontend math bug identified.

## Current best hypothesis

Linux child-webview composition/geometry handling in Tauri/WRY/WebKitGTK is overriding or misapplying child bounds in this app setup (or in current runtime/library versions), causing persistent top-offset/height mismatch and the visible half-screen rendering artifact.

## Current code status

- Multiple Linux-specific mitigation patches were tried in `apps/iris/src-tauri/src/nip07.rs`.
- Test suite remains green after changes (`cargo test` passes).
- Behavior still reproduces visually.

## What we need from upstream guidance

1. Known matching issues for Linux child webviews with black top/half-height rendering.
2. Canonical Linux-safe pattern for child webview attach/resize on HiDPI.
3. Whether this is a known WebKitGTK regression window and recommended version pin.
4. Whether Linux should use a fallback architecture (single-webview + iframe) for stability.

---

## Search prompt (next round)

I need a root-cause-level diagnosis for a Linux-only Tauri v2 child webview rendering bug.

Context:
- App: Tauri v2 + Rust backend + Svelte frontend
- Uses `window.add_child(...)` child webviews on Linux (WebKitGTK)
- Symptom: child page renders only in lower half; top half black/empty
- Frontend layout math is correct (`childBoundsTop + childBoundsHeight == windowInnerHeight`)
- Native behavior inconsistent: requested y/height differs from applied runtime geometry
- Reproduces on Wayland and X11 (`GDK_BACKEND=x11`)
- Tried and failed:
- logical vs physical bounds strategies
- `set_auto_resize(false)` + manual bounds
- `set_position + set_size`
- delayed bounds reapply (0ms, 80ms, 220ms)
- hide/show around initial bounds
- zoom adjustments (`scale`, `1/scale`)
- `WEBKIT_DISABLE_DMABUF_RENDERER=1`
- `WEBKIT_DISABLE_COMPOSITING_MODE=1`

Please provide:
1) exact matching upstream issues/PRs in `tauri-apps/tauri`, `tauri-apps/wry`, `tauri-apps/tao`, and WebKitGTK trackers,
2) ranked next experiments with expected pass/fail signals,
3) concrete workaround patches with minimal code snippets,
4) version-specific regression guidance (especially WebKitGTK versions),
5) production fallback recommendation (Linux single-webview+iframe mode) with security tradeoffs.

Output format:
- Section A: matching evidence + links
- Section B: prioritized experiments + interpretation
- Section C: immediate workaround patch
- Section D: long-term architecture recommendation