Native-only Linux host: compile out WebKitGTK when no web intent is declared (#110)

* Compile the GTK host without WebKitGTK for native-only apps

- NATIVE_SDK_ALLOW_WEBKITGTK_STUB mirrors the Windows WebView2 seam: the define wins over header visibility, compiles out every WebKit-touching path (opaque never-non-NULL web-view pointers keep the GTK-only bookkeeping shape), and stubs the exported webview entry points
- Both Linux build graphs (build/app.zig and the generated template) compile gtk_host.c with the stub and drop the webkitgtk-6.0 link when the web layer is excluded; the native scaffold's generated CI stops installing libwebkitgtk-6.0-dev

Co-authored-by: WhiteHades <44260523+WhiteHades@users.noreply.github.com>

* Audit the web layer in Linux ELF executables

- tools/audit_web_layer.zig auto-detects PE vs ELF and hand-rolls an ELF64 reader over the section headers: DT_NEEDED entries naming libwebkitgtk/libjavascriptcoregtk and webkit_/jsc_ dynamic symbols are the evidence, refusal (never a pass) for anything it cannot parse
- native package grows the ELF twin of the PE guard: a WebKitGTK-linking binary packaged under a native-only decision is refused with the same teaching message, pinned by synthetic-ELF tests covering both evidence channels

Co-authored-by: WhiteHades <44260523+WhiteHades@users.noreply.github.com>

* Prove the Linux seam in CI from both directions

- linux-webkitgtk gains test-linux-web-layer-audit (seam under webkit-PRESENT conditions: native-only ELF scans clean, web ELF keeps its references) and linux-canvas-smoke drops libwebkitgtk-6.0-dev so the build itself is the native-only link test, with the ELF audit run on the real binary
- vendor pins keep the stub define wired through gtk_host.c and both build graphs; the macOS gpu-dashboard smoke asserts a native-only session spawns zero new WebKit helper processes

Co-authored-by: WhiteHades <44260523+WhiteHades@users.noreply.github.com>

* Pin native-only behavior: automation sessions, record/replay, docs

- An automation-driven session on a native-only canvas app proves normal command dispatch plus the WebViewLayerNotBuilt teaching error on a webview attempt, with zero webviews reaching the platform host
- The session record/replay reference journal round-trips identically under web_layer=false; the capabilities and app.zon pages note the user-visible Linux consequence (no WebKitGTK to build or run)

Co-authored-by: WhiteHades <44260523+WhiteHades@users.noreply.github.com>

* Forward the web engine to native package from the SDK build graph

- A Chromium exe packaged through zig build package shipped no CEF runtime because the CLI defaults to the system engine; forward --web-engine, --cef-dir, and --cef-auto-install exactly as the generated build graph already does

---------

Co-authored-by: WhiteHades <44260523+WhiteHades@users.noreply.github.com>

Author: ctate

.github/scripts/linux-canvas-smoke.sh

@@ -1,18 +1,23 @@
 #!/usr/bin/env bash
-# Linux canvas smoke under Xvfb.
+# Linux canvas smoke under Xvfb — run on a machine with NO WebKitGTK dev
+# package, which makes the build itself the native-only link test.
 #
-# Exercises the Linux gpu_surface software path against system WebKitGTK
-# without a display server: builds examples/ui-inbox with -Dplatform=linux
-# -Dweb-engine=system -Dautomation=true, runs it under Xvfb, and asserts
-# against the automation snapshot:
+# Exercises the Linux gpu_surface software path without a display server:
+# builds examples/ui-inbox (a native-only app, so its GTK host compiles
+# with the WebKitGTK stub seam and never links webkitgtk-6.0) with
+# -Dplatform=linux -Dweb-engine=system -Dautomation=true, runs it under
+# Xvfb, and asserts against the automation snapshot:
 #
-#   1. snapshot ready=true            (app booted, automation server live)
-#   2. gpu_backend=software           (the software present path is active)
-#   3. gpu_nonblank=true              (real pixels were presented)
-#   4. widget-click "Add task" -> '4 open'   (automation input mutates state)
-#   5. automate screenshot renders a non-empty PNG
-#   6. ZERO WebKit helper processes for the whole run (the main WebView is
-#      lazy; a canvas app must never boot the WebKit stack)
+#   1. the built ELF carries no WebKitGTK reference (no libwebkitgtk
+#      DT_NEEDED entry, no webkit_/jsc_ dynamic symbol), audited on the
+#      real binary by tools/audit_web_layer.zig
+#   2. snapshot ready=true            (app booted, automation server live)
+#   3. gpu_backend=software           (the software present path is active)
+#   4. gpu_nonblank=true              (real pixels were presented)
+#   5. widget-click "Add task" -> '4 open'   (automation input mutates state)
+#   6. automate screenshot renders a non-empty PNG
+#   7. ZERO WebKit helper processes for the whole run (a native-only app
+#      has no web layer to boot WebKit with)
 #
 # Deliberately NOT `set -e` (same as windows-canvas-smoke.sh): grep exits 1
 # on zero matches, and under `set -e` an assignment like `x=$(grep ...)` or
@@ -21,10 +26,11 @@
 # goes through fail(), which dumps the snapshot and the app log.
 set -u
 
-# No WebKit sandbox workaround: a canvas app's main WebView is created
-# lazily and never materializes, so no WebKit helper processes start and
-# the runner's user-namespace restrictions never come into play. The
-# zero-WebKit assertion below keeps it that way.
+# No WebKit sandbox workaround: a native-only app's host is compiled
+# without the web layer entirely (and even in web builds the main
+# WebView is lazy), so no WebKit helper processes start and the runner's
+# user-namespace restrictions never come into play. The zero-WebKit
+# assertion below keeps it that way.
 
 # GTK_A11Y=none: under Xvfb there is no session bus providing org.a11y.Bus,
 # and GTK4's a11y init blocks ~25 s on the GDBus name lookup before warning
@@ -94,22 +100,27 @@ assert_no_webkit() {
 # ---- build ----------------------------------------------------------------
 (cd "$repo_root" && zig build) || fail "root zig build (CLI) failed"
 (cd "$app_dir" && zig build -Dplatform=linux -Dweb-engine=system -Dautomation=true) \
-  || fail "ui-inbox Linux build failed"
+  || fail "ui-inbox Linux build failed (a native-only app must build without the WebKitGTK dev package)"
+
+# ---- 1: the native-only ELF carries no WebKitGTK reference -----------------
+(cd "$repo_root" && zig run tools/audit_web_layer.zig -- "$app_dir/zig-out/bin/ui-inbox" absent) \
+  || fail "native-only ELF audit failed (the binary references WebKitGTK)"
+echo "== native-only ELF audit ok"
 
 # ---- launch ---------------------------------------------------------------
 cd "$app_dir" || fail "missing $app_dir"
 rm -rf .zig-cache/native-sdk-automation
 xvfb-run -a "$app_dir/zig-out/bin/ui-inbox" > "$app_log" 2>&1 &
 app_pid=$!
 
-# ---- 1: automation snapshot becomes ready ---------------------------------
+# ---- 2: automation snapshot becomes ready ---------------------------------
 # `automate assert` self-reports on timeout (missing patterns + snapshot
 # tail) and prints the measured latency on success, so green logs carry
 # the readiness margin.
 "$cli" automate assert --timeout-ms "$ready_timeout_ms" 'ready=true' \
   || fail "snapshot never became ready"
 
-# ---- 2 + 3: software backend presented non-blank pixels --------------------
+# ---- 3 + 4: software backend presented non-blank pixels --------------------
 "$cli" automate assert --timeout-ms 30000 'gpu_nonblank=true' \
   || fail "gpu_nonblank never became true"
 grep -q 'gpu_backend=software' "$snap" || fail "gpu_backend is not software"
@@ -118,7 +129,7 @@ echo "== canvas: $(grep -o 'gpu_backend=[a-z]*' "$snap" | head -1)" \
 assert_no_webkit "after first presented frame"
 echo "== zero WebKit processes after first presented frame"
 
-# ---- 4: automation widget-click mutates the model --------------------------
+# ---- 5: automation widget-click mutates the model --------------------------
 echo "== open before click: $(grep -oE '[0-9]+ open' "$snap" | head -1)"
 add_id=$(grep -o 'widget @w1/inbox-canvas#[0-9]* role=button name="Add task"' "$snap" \
   | grep -o '#[0-9]*' | tr -d '#')
@@ -128,12 +139,12 @@ add_id=$(grep -o 'widget @w1/inbox-canvas#[0-9]* role=button name="Add task"' "$
   || fail "widget-click did not reach '4 open'"
 echo "== open after click: $(grep -oE '[0-9]+ open' "$snap" | head -1)"
 
-# ---- 5: screenshot renders a non-empty PNG ---------------------------------
+# ---- 6: screenshot renders a non-empty PNG ---------------------------------
 "$cli" automate screenshot inbox-canvas || fail "CLI screenshot failed"
 test -s .zig-cache/native-sdk-automation/screenshot-inbox-canvas.png \
   || fail "screenshot PNG missing or empty"
 
-# ---- 6: still zero WebKit processes at the end of the run -------------------
+# ---- 7: still zero WebKit processes at the end of the run -------------------
 assert_no_webkit "at end of run"
 echo "== zero WebKit processes at end of run"
 

.github/workflows/ci.yml

@@ -81,6 +81,15 @@ jobs:
       - name: Install WebKitGTK dependencies
         run: sudo apt-get update && sudo apt-get install -y libgtk-4-dev libwebkitgtk-6.0-dev
       - run: zig build test-webview-system-link -Dplatform=linux
+      # Declare-to-use, proven on real Linux executables WITH the
+      # WebKitGTK dev package installed — the seam, not the environment:
+      # the native-only ui-inbox binary must carry no libwebkitgtk
+      # DT_NEEDED entry and no webkit_/jsc_ dynamic symbol even though
+      # the headers were right there, while the webview example must
+      # keep them. (The environment half — building native-only on a
+      # runner with no WebKitGTK dev package at all — is the
+      # linux-canvas-smoke job.)
+      - run: zig build test-linux-web-layer-audit
 
   windows-webview:
     name: Windows WebView
@@ -144,15 +153,22 @@ jobs:
       - uses: mlugg/setup-zig@v2
         with:
           version: 0.16.0
+      # Deliberately NO libwebkitgtk-6.0-dev: ui-inbox declares no web
+      # use, so its host compiles with the WebKitGTK stub seam and this
+      # job doubles as the native-only Linux LINK test — the build can
+      # only succeed if nothing in a native-only app needs the WebKitGTK
+      # headers or pkg-config entry. (The seam under webkit-PRESENT
+      # conditions is the linux-webkitgtk job's ELF cross-audit.)
       - name: Install GTK and Xvfb
-        run: sudo apt-get update && sudo apt-get install -y libgtk-4-dev libwebkitgtk-6.0-dev xvfb
+        run: sudo apt-get update && sudo apt-get install -y libgtk-4-dev xvfb
       # Drives the gpu_surface software path under Xvfb: snapshot ready,
       # gpu_backend=software, gpu_nonblank=true, automation widget-click,
-      # a rendered screenshot, and ZERO WebKit helper processes (the main
-      # WebView is lazy; canvas apps never boot WebKit). A11y env, the
-      # widened cold-start readiness budget (shared runners stall ~27 s
-      # before the first runtime event), and failure forensics (dump
-      # snapshot + app log) all live in the script.
+      # a rendered screenshot, an ELF audit that the built binary carries
+      # no WebKitGTK reference, and ZERO WebKit helper processes (canvas
+      # apps never boot WebKit). A11y env, the widened cold-start
+      # readiness budget (shared runners stall ~27 s before the first
+      # runtime event), and failure forensics (dump snapshot + app log)
+      # all live in the script.
       - name: Build and drive ui-inbox headless
         run: .github/scripts/linux-canvas-smoke.sh
 

build.zig

@@ -510,6 +510,19 @@ pub fn build(b: *std.Build) void {
         .{ .path = "src/tooling/templates.zig", .pattern = "third_party/webview2/include" },
         .{ .path = "src/tooling/templates.zig", .pattern = "third_party/webview2/x64/WebView2Loader.dll" },
     });
+    // The Linux mirror of the Windows seam: the stub define wins over
+    // header visibility (a native-only build never reintroduces the
+    // libwebkitgtk link even where the dev package is installed), the
+    // header is required for web builds, and both build graphs compile
+    // gtk_host.c with the stub and drop the webkitgtk-6.0 link when the
+    // web layer is excluded.
+    addFileContainsCheckStep(b, file_contains_checker, test_step, "test-linux-webkitgtk-seam", "Verify the WebKitGTK compile seam stays wired through the GTK host and both Linux build graphs", &.{
+        .{ .path = "src/platform/linux/gtk_host.c", .pattern = "#if defined(NATIVE_SDK_ALLOW_WEBKITGTK_STUB)" },
+        .{ .path = "src/platform/linux/gtk_host.c", .pattern = "#elif __has_include(<webkit/webkit.h>)" },
+        .{ .path = "src/platform/linux/gtk_host.c", .pattern = "#error \"webkit/webkit.h not found" },
+        .{ .path = "build/app.zig", .pattern = "\"-DNATIVE_SDK_ALLOW_WEBKITGTK_STUB\"" },
+        .{ .path = "src/tooling/templates.zig", .pattern = "\"-DNATIVE_SDK_ALLOW_WEBKITGTK_STUB\"" },
+    });
     addLayoutCheckStep(b, test_step, "test-windows-webview2-loader-layout", "Verify the vendored WebView2 loader binaries are present", &.{
         "third_party/webview2/x64/WebView2Loader.dll",
         "third_party/webview2/arm64/WebView2Loader.dll",
@@ -838,7 +851,8 @@ pub fn build(b: *std.Build) void {
     audit_webview_exe.addArgs(&.{ "examples/webview/zig-out/bin/webview.exe", "present" });
     audit_webview_exe.has_side_effects = true;
     audit_webview_exe.step.dependOn(&build_webview_windows.step);
-    const audit_native_only_loader = b.addSystemCommand(&.{ "sh", "-c",
+    const audit_native_only_loader = b.addSystemCommand(&.{
+        "sh", "-c",
         \\test ! -f examples/ui-inbox/zig-out/bin/WebView2Loader.dll || {
         \\  echo "web-layer audit FAILED: the native-only build installed WebView2Loader.dll" >&2
         \\  exit 1
@@ -850,6 +864,33 @@ pub fn build(b: *std.Build) void {
     web_layer_audit_step.dependOn(&audit_webview_exe.step);
     web_layer_audit_step.dependOn(&audit_native_only_loader.step);
 
+    // Linux web-layer ELF cross-audit: the same declare-to-use proof on
+    // real Linux executables. Unlike the Windows step this cannot
+    // cross-compile from any host — the GTK host needs the system GTK4
+    // (and, for the web example, WebKitGTK) development headers — so the
+    // step runs on Linux with both packages installed and proves the
+    // SEAM, not the environment: the native-only exe must carry no
+    // libwebkitgtk DT_NEEDED entry and no webkit_/jsc_ dynamic symbol
+    // even though the dev package was right there, while the web example
+    // must keep them. The environment half (a native-only app building
+    // on a runner with no WebKitGTK dev package at all) is proven by the
+    // linux-canvas-smoke CI job.
+    const build_native_only_linux = b.addSystemCommand(&.{ "zig", "build", "-Dplatform=linux" });
+    build_native_only_linux.setCwd(b.path("examples/ui-inbox"));
+    const build_webview_linux = b.addSystemCommand(&.{ "zig", "build", "-Dplatform=linux", "-Dweb-engine=system" });
+    build_webview_linux.setCwd(b.path("examples/webview"));
+    const audit_native_only_elf = b.addRunArtifact(web_layer_auditor);
+    audit_native_only_elf.addArgs(&.{ "examples/ui-inbox/zig-out/bin/ui-inbox", "absent" });
+    audit_native_only_elf.has_side_effects = true;
+    audit_native_only_elf.step.dependOn(&build_native_only_linux.step);
+    const audit_webview_elf = b.addRunArtifact(web_layer_auditor);
+    audit_webview_elf.addArgs(&.{ "examples/webview/zig-out/bin/webview", "present" });
+    audit_webview_elf.has_side_effects = true;
+    audit_webview_elf.step.dependOn(&build_webview_linux.step);
+    const linux_web_layer_audit_step = b.step("test-linux-web-layer-audit", "Build a native-only and a web example for Linux (Linux host with GTK4 + WebKitGTK dev packages) and audit the web layer in each ELF");
+    linux_web_layer_audit_step.dependOn(&audit_native_only_elf.step);
+    linux_web_layer_audit_step.dependOn(&audit_webview_elf.step);
+
     const frontend_examples_step = b.step("test-examples-frontends", "Run frontend example tests");
     addExampleTestStep(b, host_cli_exe, frontend_examples_step, "test-example-next", "Run Next example tests", "examples/next", .owned);
     addExampleTestStep(b, host_cli_exe, frontend_examples_step, "test-example-react", "Run React example tests", "examples/react", .owned);
@@ -1459,6 +1500,16 @@ pub fn build(b: *std.Build) void {
         \\ready_budget_ms="$smoke_budget_ms"
         \\if [ "$ready_budget_ms" -lt 500 ]; then ready_budget_ms=500; fi
         \\ready_budget_ns=$((ready_budget_ms * 1000000))
+        \\# gpu-dashboard is a native-only app (nothing in app.zon declares web
+        \\# use), so its macOS host must never boot the WebKit stack: WKWebView
+        \\# instantiation spawns com.apple.WebKit.* XPC helpers. They are
+        \\# launchd-parented (not app children), so the honest cheap probe is
+        \\# the machine-wide helper set before launch vs at the end of the
+        \\# session — a NEW helper during this headless smoke window means the
+        \\# lazy main-WebView path regressed (the failure lists the processes
+        \\# so a coincidental web app launched mid-smoke is tellable apart).
+        \\webkit_helpers() { pgrep -f 'com\.apple\.WebKit\.(WebContent|Networking|GPU)' 2>/dev/null | tr '\n' ' '; }
+        \\webkit_before="$(webkit_helpers)"
         \\pid=""
         \\trap 'status=$?; kill "$pid" >/dev/null 2>&1 || true; wait "$pid" >/dev/null 2>&1 || true; if [ "$status" -ne 0 ]; then echo "---- app log (.zig-cache/native-sdk-gpu-dashboard-smoke.log) ----" >&2; cat .zig-cache/native-sdk-gpu-dashboard-smoke.log >&2 2>/dev/null || true; fi' EXIT
         \\stop_app() {
@@ -1625,6 +1676,19 @@ pub fn build(b: *std.Build) void {
         \\if ! grep -q "gpu incremental verify view=dashboard-canvas checks=" "$verify_log" 2>/dev/null; then echo "dashboard verify mode recorded no incremental checks" >&2; exit 1; fi
         \\if grep -q "verify MISMATCH" "$verify_log" 2>/dev/null; then echo "dashboard incremental present diverged from a full redraw:" >&2; grep "verify MISMATCH" "$verify_log" >&2; exit 1; fi
         \\if grep "gpu incremental verify view=dashboard-canvas checks=" "$verify_log" | grep -qv "mismatches=0"; then echo "dashboard incremental verify reported mismatches" >&2; exit 1; fi
+        \\# The whole session ran (two launches, clicks, resizes): a native-only
+        \\# macOS app must have spawned ZERO new WebKit helper processes.
+        \\webkit_after="$(webkit_helpers)"
+        \\new_webkit=""
+        \\for helper_pid in $webkit_after; do
+        \\  case " $webkit_before " in *" $helper_pid "*) ;; *) new_webkit="$new_webkit $helper_pid" ;; esac
+        \\done
+        \\if [ -n "$new_webkit" ]; then
+        \\  echo "native-only gpu-dashboard session spawned WebKit helper processes:$new_webkit" >&2
+        \\  for helper_pid in $new_webkit; do ps -p "$helper_pid" -o pid,ppid,command >&2 || true; done
+        \\  exit 1
+        \\fi
+        \\echo "zero new WebKit helper processes during the native-only session"
         \\echo "gpu-dashboard smoke ok"
         ,
         "sh",

build/app.zig

@@ -347,6 +347,11 @@ pub fn addAppArtifacts(b: *std.Build, dep: *std.Build.Dependency, app_options: A
         // without its loader. Handing over the decision itself makes
         // exe/package agreement structural.
         package_run.addArgs(&.{ "--web-layer", if (web_layer) "include" else "exclude" });
+        // Same reasoning for the web engine: the CLI defaults to system, so
+        // a Chromium exe packaged without these flags would ship no CEF
+        // runtime (the generated build graph already forwards them).
+        package_run.addArgs(&.{ "--web-engine", @tagName(web_engine), "--cef-dir", cef_dir });
+        if (cef_auto_install) package_run.addArg("--cef-auto-install");
         package_run.has_side_effects = true;
         const package_step = b.step("package", "Create a distributable package via the native CLI");
         package_step.dependOn(&package_run.step);
@@ -537,11 +542,23 @@ fn linkPlatform(b: *std.Build, dep: *std.Build.Dependency, target: std.Build.Res
         if (web_engine == .chromium) app_mod.linkSystemLibrary("c++", .{});
     } else if (platform == .linux) {
         switch (web_engine) {
-            .system => {
+            .system => if (web_layer) {
                 app_mod.addCSourceFile(.{ .file = dep.path("src/platform/linux/gtk_host.c"), .flags = &.{} });
                 app_mod.linkSystemLibrary("gtk4", .{});
                 app_mod.linkSystemLibrary("webkitgtk-6.0", .{});
                 app_mod.linkSystemLibrary("dl", .{});
+            } else {
+                // Native-only app (nothing in app.zon declares web use):
+                // compile the GTK host without the embedded web layer.
+                // The stub define excludes the layer outright — the host
+                // honors it before probing for the WebKitGTK header, so
+                // the layer stays out even on machines where the
+                // development package is installed — libwebkitgtk is
+                // neither linked nor required at runtime, and the
+                // executable carries no WebKit reference at all.
+                app_mod.addCSourceFile(.{ .file = dep.path("src/platform/linux/gtk_host.c"), .flags = &.{"-DNATIVE_SDK_ALLOW_WEBKITGTK_STUB"} });
+                app_mod.linkSystemLibrary("gtk4", .{});
+                app_mod.linkSystemLibrary("dl", .{});
             },
             .chromium => {
                 const cef_check = addCefCheck(b, target, cef_dir);

changelog.d/native-only-host-linux.md

@@ -0,0 +1 @@
+feature: **Native-only host builds (Linux)**: the WebKitGTK compile seam mirrors the Windows one — an app whose app.zon declares no web use compiles its GTK host with `NATIVE_SDK_ALLOW_WEBKITGTK_STUB`, so the executable neither links `webkitgtk-6.0` nor references any `webkit_`/`jsc_` symbol, building needs no WebKitGTK development package, and users need no `libwebkitgtk` at runtime. The web-layer auditor (`tools/audit_web_layer.zig`) grew a hand-rolled ELF reader (DT_NEEDED entries + dynamic symbols) that CI runs both ways: the native-only fixture must scan clean even with the dev package installed, and the Linux canvas smoke now builds on a runner without WebKitGTK at all. `native package` refuses to package a WebKitGTK-linking binary under a native-only decision, record→replay and automation-driven sessions are pinned on native-only apps, and the macOS GPU dashboard smoke asserts a native-only app spawns zero WebKit helper processes.