Clypra Cross-Platform Tauri Native Thread Safety Engineering

1. Mission & Architectural Invariant (Invariant 16)

Clypra is a high-performance native desktop NLE targeting macOS, Windows, and Linux. The native preview pipeline involves custom window creation, layering above/below WebViews, transparent child surfaces, and direct GPU presentation (wgpu).

Architecture Invariant 16:

All native window, view, and OS-level UI hierarchy operations across macOS (AppKit/NSWindow), Windows (Win32/HWND), and Linux (GTK/GtkWidget) must execute exclusively on the thread owning the native window/event loop via window.run_on_main_thread() or app.run_on_main_thread().

Background tasks — Tokio async workers, render loops, audio threads, background Tauri command threads, and worker pools — must never invoke restricted platform UI APIs directly. Background tasks must request operations via approved main-thread dispatch boundaries.

2. Platform-Specific Threading Contracts

Native operating-system windowing models do not share a single generic threading implementation. Engineers must understand the distinct OS-level constraints for every platform Clypra supports:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                 Background Execution                                   │
│                  (Tokio Workers, Render Loops, Audio WSOLA, File I/O)                  │
└───────────────────────────────────────────┬────────────────────────────────────────────┘
                                            │
                                            ▼  window.run_on_main_thread()
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                 Main UI Thread Boundary                                │
├──────────────────────────┬─────────────────────────────┬───────────────────────────────┤
│          macOS           │           Windows           │             Linux             │
│   (AppKit / Cocoa)       │       (Win32 / Tao)         │      (GTK / WebKitGTK)        │
├──────────────────────────┼─────────────────────────────┼───────────────────────────────┤
│ • NSWindow is main-actor │ • HWND owned by creator     │ • GTK objects not thread-safe │
│   isolated.              │   thread message loop.      │ • Must run on default         │
│ • addChildWindow, show,  │ • SetWindowPos, ShowWindow, │   GMainContext event loop.    │
│   hide, close, orderFront│   SetWindowLongPtrW must run│ • Direct calls trigger GLib   │
│   assert main thread.    │   on message loop thread.   │   assertion warnings or aborts│
│ • SIGTRAP on violation.  │ • Stalls/races if cross-thd.│ • Wayland/X11 race crashes.   │
└──────────────────────────┴─────────────────────────────┴───────────────────────────────┘

2.1 macOS (AppKit / Cocoa)

• Constraint: NSWindow and its associated views are main-actor-isolated in AppKit. Operations mutating window hierarchy, visibility, ordering, or style must execute on the macOS main Cocoa run loop.
• Enforcement in OS: macOS 26+ and modern Cocoa frameworks (WindowManagement.framework) enforce this with active assertions. Calling APIs such as -[NSWindow addChildWindow:ordered:], -[NSWindow orderOut:], -[NSWindow makeKeyAndOrderFront:], or modifying collection behaviors from a Tokio background thread triggers an immediate EXC_BREAKPOINT (SIGTRAP) with:

  Application Specific Information:
  Must only be used from the main thread
  

• Historical Case Study (Clypra Bug 13): During cold playback startup, a Tokio worker thread called surface.show_surface(), which invoked objc2::msg_send![parent, addChildWindow: child, ordered: 1isize]. This crashed the process with SIGTRAP on Thread 12 (tokio-rt-worker). The fix requires scheduling the call via surface_window.run_on_main_thread().

2.2 Windows (Win32 / Tao)

• Constraint: A Win32 window (HWND) has thread affinity with the thread that called CreateWindowExW and runs its GetMessage/DispatchMessage loop. In Tauri v2, this is the main thread managed by Tao.
• Enforcement in OS: Win32 window APIs such as SetWindowPos, ShowWindow, SetWindowLongPtrW, and DestroyWindow must execute on the thread owning the HWND. Cross-thread window operations can result in synchronous message deadlocks, dropped messages, failure of DWM composition synchronization (e.g. WS_EX_LAYERED child window layering behind WebView2), or ERROR_ACCESS_DENIED.
• Requirements in Clypra:
  • SetWindowPos(HWND_TOP, ...) used to keep the transparent child surface above WebView2 must run on the main UI thread.
  • Window style updates (GWL_EXSTYLE with WS_EX_LAYERED | WS_EX_TRANSPARENT | WS_EX_NOACTIVATE) must be dispatched to the main UI thread during configuration.

2.3 Linux (GTK 3/4 / WebKitGTK)

• Constraint: GTK is not thread-safe. The GTK toolkit documentation explicitly states that all GTK objects must only be accessed and manipulated from the thread running the default GMainContext (the thread calling gtk_main or running Tauri's main loop).
• Enforcement in OS: Accessing GtkWindow or GtkWidget from Tokio worker threads leads to memory corruption, GLib assertion failures (G_IS_WIDGET(widget) failing), or X11/Wayland event loop race crashes.
• Requirements in Clypra:
  • Any child window positioning, window reparenting, showing/hiding, or WebKitGTK inspector hooks must be routed via window.run_on_main_thread().

3. Five Core Disciplines of Native Thread Safety

Every change touching native windowing or platform integration must strictly adhere to these 5 disciplines:

Discipline 1: Thread-Affinity Inventory

Before modifying or introducing native platform code, audit the threading requirements of every affected API:

Discipline 2: Safe Dispatch Boundaries

All background operations requesting native UI modifications must use the approved Tauri dispatch abstractions:

Pattern A: Fire-and-Forget (No result needed by caller)

Used for presentation show/hide transitions where the background worker does not block:

// Clone the window handle before moving into the closure
let sw = surface_window.clone();
#[cfg(target_os = "macos")]
let parent_clone = self.parent_window.clone();

surface_window
    .run_on_main_thread(move || {
        if let Err(e) = sw.show() {
            log::warn!("[NativeSurface] show failed: {e}");
            return;
        }

        #[cfg(target_os = "macos")]
        unsafe {
            if let Some(parent) = &parent_clone {
                if let (Ok(ns_win), Ok(parent_ns_win)) = (sw.ns_window(), parent.ns_window()) {
                    let _: () = objc2::msg_send![
                        parent_ns_win as *mut objc2::runtime::AnyObject,
                        addChildWindow: ns_win as *mut objc2::runtime::AnyObject,
                        ordered: 1isize // NSWindowAbove = 1
                    ];
                }
            }
        }
    })
    .map_err(|e| format!("Unable to dispatch show to main thread: {e}"))?;

Pattern B: Asynchronous Completion (Caller needs operation result)

Used for setup, configuration, and resizing where the caller must await the outcome:

let (sender, receiver) = tokio::sync::oneshot::channel();
let surface_window = window.clone();
let surface_app = app.clone();

window
    .run_on_main_thread(move || {
        let result = configure_surface(surface_app, surface_window, gpu, geometry, runtime);
        let _ = sender.send(result);
    })
    .map_err(|error| format!("Unable to schedule configuration: {error}"))?;

receiver
    .await
    .map_err(|_| "Configuration was cancelled".to_string())?

Discipline 3: Lifecycle Correctness & State Transitions

Because run_on_main_thread enqueues work onto the main loop asynchronously, state flags must account for the queueing delay:

• Optimistic Show Guarding: When requesting a show, check is_shown first (atomic acquire). If false, enqueue the main-thread task and set is_shown = true (atomic release). This prevents every subsequent 60fps render frame from queueing redundant main-thread closures.
• Pessimistic Hide Guarding: When requesting a hide, set is_shown = false (atomic release) immediately before enqueueing window.hide(). Concurrent render workers immediately see the surface as hidden and cease trying to acquire or present swapchain textures.
• Session Reset Invariant: On project close or reset, advance runtime_epoch, drop GPU surfaces, take the window handle, and enqueue window.close() on the main thread. In-flight presentations from stale sessions discard their work when observing an epoch mismatch.

Discipline 4: Static Architecture Enforcement

The repository harness automatically inspects native code to ensure direct window mutations do not bypass run_on_main_thread:

• Enforcement Script: scripts/harness/check-architecture.mjs (Check 7: Native UI Thread Safety).
• Verified Files: src-tauri/src/commands/native_surface.rs and related native modules.
• Verification Command: npm run verify:architecture (part of npm run verify:fast and CI).

Discipline 5: Platform-Specific Runtime Verification

Mocked unit tests and compilation passes are not sufficient proof that native thread safety is maintained on real operating systems.

• macOS:
  • Run under Apple's Main Thread Checker:

    DYLD_INSERT_LIBRARIES=/Applications/Xcode.app/Contents/Developer/usr/lib/libMainThreadChecker.dylib \
      MTC_RESET_INSERT_LIBRARIES=0 \
      ./src-tauri/target/debug/clypra
    

• Windows:
  • Verify with Application Verifier / WinDbg: Inspect that thread creating HWND handles matches thread executing SetWindowPos.
• Linux:
  • Run with G_DEBUG=fatal-warnings or G_ENABLE_DIAGNOSTIC=1 to ensure no GLib or GTK threading warnings are emitted during window operations.

4. Mandatory Completion Checklist

Before declaring any native UI or windowing task complete:

1. Thread-Affinity Audit: Listed all native APIs touched and verified their OS thread requirements.
2. Dispatch Boundary Verified: Confirmed no bare show(), hide(), close(), addChildWindow, or SetWindowPos calls exist in Tokio async contexts or render workers.
3. State Machine Checked: Atomic visibility flags (is_shown) prevent redundant queueing and race conditions.
4. Rust Compilation Passed: cargo check --manifest-path src-tauri/Cargo.toml passed with 0 errors.
5. Lifecycle Unit Tests Passed: cargo test --manifest-path src-tauri/Cargo.toml --lib commands::native_surface::tests passed.
6. Architecture Invariant Check Passed: npm run verify:architecture passed with 100% check parity.
7. Documentation Parity: Links in docs/engineering/ and AGENTS.md updated and validated via npm run docs:check.