Keep the WebView stub compile silent and support GLib 2.72 (#152)

* Remove the informational pragma from both WebView stub paths

- zig renders every clang diagnostic of a failing C compile as error:, so the note masqueraded as the build-killer whenever a real error joined it
- the stub branches keep their explanatory comments; the misconfigured web-build #error stays
- build graphs (build/app.zig and the ejected template) document why the expected state is silent: runtime WebViewNotFound is the teaching channel

Co-authored-by: nextpointer <110530249+nextpointer@users.noreply.github.com>

* Compile the GTK host against GLib 2.72

- G_APPLICATION_DEFAULT_FLAGS is GLib 2.74+; the host's GTK floor is 4.10, whose own GLib floor is 2.72
- distros backporting GTK 4.10 onto a 2.72 base (Ubuntu 22.04 derivatives) now compile canvas apps out of the box

Co-authored-by: nextpointer <110530249+nextpointer@users.noreply.github.com>

* Pin diagnostic-free stub compiles in both canvas-smoke CI lanes

- zig cc passthrough is the one channel where C warnings reach stderr, so each lane compiles its stub host and asserts zero diagnostics
- fails on the old pragma, passes after its removal; the webkit-less build + ELF audit receipts already live in these lanes
- changelog fragment for the user-visible fix

Co-authored-by: nextpointer <110530249+nextpointer@users.noreply.github.com>

* Run the stub diagnostic receipts against a cold zig cache

- on a cache hit zig cc replays nothing, stderr included, so a restored cache would hide the exact diagnostics the steps pin against
- throwaway ZIG_GLOBAL/LOCAL_CACHE_DIR per step keeps every run cold

Co-authored-by: nextpointer <110530249+nextpointer@users.noreply.github.com>

* Print the captured compiler output when a stub receipt compile fails

- Actions runs steps under bash -e, so a nonzero command substitution killed the step at the assignment and swallowed the forensics the step captured; the || arm keeps errexit out of the capture.

Co-authored-by: nextpointer <110530249+nextpointer@users.noreply.github.com>

* Pin the GLib 2.72 fallback with an error-set receipt on stock 22.04

- No stock image pairs old glib with GTK 4.10, so the receipt asserts the error set: GTK-age failures only, never a glib symbol - a future 2.74+ symbol without a fallback trips it.

Co-authored-by: nextpointer <110530249+nextpointer@users.noreply.github.com>

* Whitelist GTK-age diagnostic shapes in the GLib 2.72 receipt

- The prefix blacklist missed non-undeclared shapes (unknown glib type names); the whitelist rejects everything that is not a GTK-age root or its cascades, with the cascade rationale in the script.

Co-authored-by: nextpointer <110530249+nextpointer@users.noreply.github.com>

* Demand positive evidence from the GLib 2.72 receipt

- Unlocated error shapes (driver/invocation failures) reject instead of sailing past the located-diagnostic parser, and fewer than five GTK-age roots means the compile proved nothing.
- Renamed to the allowlist vocabulary.

Co-authored-by: nextpointer <110530249+nextpointer@users.noreply.github.com>

* Narrow the conversion cascade to its signature and document the lattice

- Int-to-pointer lines only pass when converting from 'int' (the undeclared-function-returns-int shape); the docstring now records why cascade allowances are sound: full-GTK lanes compile the same file, so only the old-glib delta reaches this filter, and glib regressions always reject at their root.

Co-authored-by: nextpointer <110530249+nextpointer@users.noreply.github.com>

---------

Co-authored-by: nextpointer <110530249+nextpointer@users.noreply.github.com>

Author: ctate

.github/scripts/glib272_error_allowlist.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""The GLib 2.72 receipt's error-set allowlist.
+
+Compiling gtk_host.c on stock ubuntu 22.04 (GLib 2.72, GTK 4.6) cannot
+succeed: the toolkit's GTK floor is 4.10, so GTK-age failures are the
+expected steady state. What this receipt pins is that NOTHING ELSE
+fails - a glib/gio symbol needing 2.74+ without a version-checked
+fallback shows up here as a diagnostic outside the allowlist below.
+
+The allowlist is by diagnostic SHAPE, not symbol prefix:
+- undeclared gtk_/GTK_ functions are the GTK-age roots;
+- undeclared plain (non-glib-namespaced) identifiers are their
+  cascades (locals whose declaring line failed);
+- int-conversion lines are cascades of undeclared functions returning
+  int, and incidentally name glib types (GListModel), so a prefix
+  denylist would false-positive on them.
+Everything else fails the step: unknown type name 'G...', undeclared
+g_/G_ symbols, missing members, any located shape not seen before,
+and any error line WITHOUT a file:line:col location (driver failures
+like "error: Unknown Clang option" never classify as diagnostics, so
+they must reject rather than sail through an empty error set).
+
+The receipt also demands positive evidence it ran: at least
+MIN_GTK_ROOTS allowlisted GTK-age root diagnostics. A compile that
+produced no classifiable error set (wrong file, broken include path,
+invocation failure) proves nothing and must fail loudly - the clean
+run produces ~21 roots, so the floor sits far below real variance
+while catching "nothing actually compiled".
+
+Why the cascade allowances are sound despite looking broad: this
+receipt is one lane in a lattice, not the sole guard on gtk_host.c.
+Every full-GTK lane (linux-webkitgtk, the canvas smokes, macOS)
+compiles the same file cleanly, so a typo'd local or an independent
+conversion bug is a red build elsewhere before it ever reaches this
+filter - the only errors unique to this lane are the old-glib delta.
+And within that delta, regressions always announce themselves through
+a REJECTED root before their cascades matter: a missing glib function
+is "call to undeclared function 'g_...'" (only gtk_/GTK_ roots are
+allowed), a missing glib type/macro is an unknown-type-name or
+undeclared-G_-identifier line - all rejected. The cascades allowed
+below can only follow roots this filter already failed the step for,
+or GTK-age roots it exists to permit.
+"""
+import re
+import sys
+
+MIN_GTK_ROOTS = 5
+
+located = re.compile(r"^[^:\n]+:\d+:\d+: error: (.*)")
+rejected = []
+gtk_roots = 0
+for line in sys.stdin:
+    if "error:" not in line:
+        continue
+    m = located.match(line)
+    if not m:
+        rejected.append(line.rstrip() + "  [unlocated error shape - driver or invocation failure]")
+        continue
+    msg = m.group(1)
+    if re.match(r"call to undeclared function '(gtk_|GTK_)", msg):
+        gtk_roots += 1
+        continue
+    if re.match(r"use of undeclared identifier '(?!g_|G_|G[A-Z])", msg):
+        continue
+    if "incompatible integer to pointer conversion" in msg and "from 'int'" in msg:
+        # Only the cascade signature: an undeclared function defaults to
+        # returning int, so its assignment lines convert FROM 'int'.
+        # Conversions from any other type are not that cascade - reject.
+        continue
+    rejected.append(line.rstrip())
+
+if rejected:
+    print("non-GTK-age diagnostics against GLib 2.72 - the pre-2.74 fallback story regressed:")
+    print("\n".join(rejected))
+    sys.exit(1)
+if gtk_roots < MIN_GTK_ROOTS:
+    print(
+        f"only {gtk_roots} GTK-age root diagnostics (need >= {MIN_GTK_ROOTS}) - "
+        "the compile did not exercise the old-GTK error set, so this receipt proved nothing"
+    )
+    sys.exit(1)
+print(f"fallback receipt ok: every error is GTK-age by shape ({gtk_roots} roots)")

.github/workflows/ci.yml

@@ -179,6 +179,30 @@ jobs:
       # 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 xvfb
+      # The stub is the expected, configured state of every native-only
+      # Linux app, so compiling the GTK host with the stub define must be
+      # diagnostic-FREE, not merely successful: zig renders every clang
+      # diagnostic of a failing translation unit as `error:` (serialized
+      # clang diagnostics carry no severity into its error bundle), so
+      # even an informational #pragma message in this path masquerades as
+      # the build-killing error the moment any unrelated real error
+      # appears in the file. `zig cc` runs clang in passthrough mode,
+      # where warnings actually reach stderr — `zig build` only surfaces
+      # C diagnostics on failure, which is exactly the escalation this
+      # step pins against. The throwaway cache dir keeps the compile
+      # cold: on a cache hit zig replays nothing, stderr included, so a
+      # warm cache (setup-zig restores one) would hide the diagnostics
+      # this step exists to catch.
+      - name: WebKitGTK stub compile is diagnostic-free
+        run: |
+          export ZIG_GLOBAL_CACHE_DIR=$(mktemp -d) ZIG_LOCAL_CACHE_DIR=$(mktemp -d)
+          status=0
+          out=$(zig cc -c src/platform/linux/gtk_host.c -DNATIVE_SDK_ALLOW_WEBKITGTK_STUB $(pkg-config --cflags gtk4) -o /tmp/gtk_host_stub.o 2>&1) || status=$?
+          if [ "$status" -ne 0 ] || [ -n "$out" ]; then
+            echo "the WebKitGTK stub compile must succeed with zero diagnostics (exit $status):"
+            echo "$out"
+            exit 1
+          fi
       # Drives the gpu_surface software path under Xvfb: snapshot ready,
       # gpu_backend=software, gpu_nonblank=true, automation widget-click,
       # a rendered screenshot, an ELF audit that the built binary carries
@@ -189,6 +213,33 @@ jobs:
       # all live in the script.
       - name: Build and drive ui-inbox headless
         run: .github/scripts/linux-canvas-smoke.sh
+      # Durable receipt for the GLib 2.72 fallback (the pre-2.74
+      # G_APPLICATION_DEFAULT_FLAGS shim in gtk_host.c): no stock image
+      # pairs an old glib with GTK >= 4.10 (only backport distros do),
+      # and ubuntu 22.04 ships GTK 4.6 — so a clean compile is
+      # impossible here by design. This pins the error SET instead:
+      # every diagnostic must match a GTK-age shape (the allowlist
+      # script holds the shapes, why cascades are allowed, and the
+      # positive-evidence floor) — a 2.74+ glib symbol, type, or
+      # member used without a version-checked fallback surfaces as a
+      # rejected diagnostic and fails this step, and so does a compile
+      # that produced no classifiable error set at all. If this compile ever succeeds outright, the premise
+      # changed (newer GTK in the image) and the receipt must be
+      # re-verified rather than trusted.
+      - name: GTK host GLib 2.72 fallback holds (error-set receipt)
+        run: |
+          docker run --rm -v "$PWD:/src" -v "$(dirname "$(which zig)"):/zig" ubuntu:22.04 bash -ec '
+            export DEBIAN_FRONTEND=noninteractive
+            apt-get update -q >/dev/null && apt-get install -y -q libgtk-4-dev pkg-config >/dev/null
+            export ZIG_GLOBAL_CACHE_DIR=$(mktemp -d) ZIG_LOCAL_CACHE_DIR=$(mktemp -d)
+            status=0
+            out=$(/zig/zig cc -c /src/src/platform/linux/gtk_host.c -DNATIVE_SDK_ALLOW_WEBKITGTK_STUB $(pkg-config --cflags gtk4) -ferror-limit=0 -o /tmp/gtk_host_2272.o 2>&1) || status=$?
+            if [ "$status" -eq 0 ]; then
+              echo "unexpected clean compile on ubuntu 22.04 - this receipt assumes GTK-age errors; re-verify what it proves now"
+              exit 1
+            fi
+            echo "$out" | python3 /src/.github/scripts/glib272_error_allowlist.py
+          '
 
   linux-dev-smoke:
     name: Linux Dev Smoke (Debug scaffold)
@@ -230,6 +281,22 @@ jobs:
           version: 0.16.0
       - name: Install Wine, Xvfb, and xdotool
         run: sudo apt-get update && sudo apt-get install -y wine xvfb xdotool
+      # The Windows twin of the linux-canvas-smoke stub receipt: the
+      # WebView2 stub is the expected, configured state of every
+      # native-only Windows app, so cross-compiling the host with the
+      # stub define must be diagnostic-free (see that job's step comment
+      # for why even an informational #pragma message is dangerous, and
+      # why the compile must run against a cold cache).
+      - name: WebView2 stub cross-compile is diagnostic-free
+        run: |
+          export ZIG_GLOBAL_CACHE_DIR=$(mktemp -d) ZIG_LOCAL_CACHE_DIR=$(mktemp -d)
+          status=0
+          out=$(zig c++ -target x86_64-windows-gnu -std=c++17 -DNATIVE_SDK_ALLOW_WEBVIEW2_STUB -c src/platform/windows/webview2_host.cpp -o /tmp/webview2_host_stub.o 2>&1) || status=$?
+          if [ "$status" -ne 0 ] || [ -n "$out" ]; then
+            echo "the WebView2 stub cross-compile must succeed with zero diagnostics (exit $status):"
+            echo "$out"
+            exit 1
+          fi
       # Cross-compiles ui-inbox for x86_64-windows-gnu and drives the
       # gpu_surface software path (child HWND + WM_TIMER + SetDIBitsToDevice)
       # under Wine: snapshot ready, gpu_backend=software, gpu_nonblank=true,

build/app.zig

@@ -946,7 +946,14 @@ fn linkPlatform(b: *std.Build, dep: *std.Build.Dependency, target: std.Build.Res
                 // 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.
+                // executable carries no WebKit reference at all. This
+                // is the expected, configured state of every canvas
+                // app on Linux, so the stub compile is deliberately
+                // silent — no build note, no compiler diagnostic (the
+                // host's seam comment explains why even an
+                // informational pragma is dangerous); a stubbed host
+                // teaches at runtime by reporting WebViewNotFound the
+                // moment an app actually uses a WebView.
                 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", .{});
@@ -999,6 +1006,14 @@ fn linkPlatform(b: *std.Build, dep: *std.Build.Dependency, target: std.Build.Res
                 // headers are reachable through the system include paths
                 // — no WebView2Loader.dll is installed or path-wired,
                 // and the executable carries no reference to it at all.
+                // This is the expected, configured state of every
+                // canvas app on Windows, so the stub compile is
+                // deliberately silent — no build note, no compiler
+                // diagnostic (the host's seam comment explains why
+                // even an informational pragma is dangerous); a
+                // stubbed host teaches at runtime by reporting
+                // WebViewNotFound the moment an app actually uses a
+                // WebView.
                 app_mod.addCSourceFile(.{ .file = dep.path("src/platform/windows/webview2_host.cpp"), .flags = &.{ "-std=c++17", "-DNATIVE_SDK_ALLOW_WEBVIEW2_STUB" } });
             },
             .chromium => {

changelog.d/webview-stub-silent-compile.md

@@ -0,0 +1,2 @@
+fix: **Canvas-app hosts compile silently without a WebView SDK**: the informational `#pragma message` in the GTK host's WebKitGTK stub path (and its Windows WebView2 twin) is gone — zig renders every clang diagnostic of a failing C compile as `error:`, so on machines where a real, unrelated compile error occurred (for example a too-old GTK), the note itself surfaced as the first build-killing error and masked the actual cause; the stub is the expected state of every canvas app and now compiles with zero diagnostics, while a genuinely misconfigured web build still fails loudly via `#error`.
+- **GTK host compiles against GLib 2.72**: the host now spells "no application flags" in a way that compiles on GLib older than 2.74, so distros that backport GTK 4.10 onto a GLib 2.72 base (Ubuntu 22.04-derived) build canvas apps out of the box.

src/platform/linux/gtk_host.c

@@ -24,8 +24,17 @@
  * NATIVE_SDK_ALLOW_WEBVIEW2_STUB. */
 #if defined(NATIVE_SDK_ALLOW_WEBKITGTK_STUB)
 #define NATIVE_SDK_HAS_WEBKITGTK 0
-#pragma message("Embedded web layer excluded by the build configuration: building the GTK host without WebKitGTK (canvas apps unaffected; WebView loads will report WebViewNotFound)")
-/* The stubbed web layer keeps the window/webview bookkeeping SHAPE so
+/* Deliberately NO compiler diagnostic in this branch — not even an
+ * informational #pragma message. The stub is the expected, configured
+ * state of every native-only Linux build, and zig renders every clang
+ * diagnostic of a failing translation unit as `error:` (its serialized
+ * clang diagnostics carry no severity into the error bundle), so an
+ * informational note here masquerades as the build-killing error the
+ * moment any unrelated real error appears anywhere in this file. The
+ * teaching lives where it is actionable instead: a stubbed host
+ * reports WebViewNotFound the moment an app actually uses a WebView.
+ *
+ * The stubbed web layer keeps the window/webview bookkeeping SHAPE so
  * every GTK-only path (overlay reordering, focus lookups, window
  * teardown) compiles unchanged: the web-view pointers below are opaque
  * and permanently NULL — every path that could create one is compiled
@@ -43,6 +52,18 @@ typedef struct native_sdk_absent_content_manager WebKitUserContentManager;
 #error "webkit/webkit.h not found: install the WebKitGTK 6.0 development package (libwebkitgtk-6.0-dev on Debian/Ubuntu), or define NATIVE_SDK_ALLOW_WEBKITGTK_STUB to build without the embedded web layer"
 #endif
 
+/* G_APPLICATION_DEFAULT_FLAGS arrived in GLib 2.74 as the
+ * non-deprecated spelling of "no flags". This host's GTK floor is 4.10
+ * (the GtkFileDialog family below), and GTK 4.10's own GLib floor is
+ * 2.72 — distros that backport GTK 4.10 onto a GLib 2.72 base (Ubuntu
+ * 22.04 derivatives) must still compile this file. Same value, gated to
+ * older GLib only; the pre-2.74 name G_APPLICATION_FLAGS_NONE is not
+ * used because it is deprecated from 2.74 on and would emit a warning
+ * exactly where the newer name exists. */
+#if !GLIB_CHECK_VERSION(2, 74, 0)
+#define G_APPLICATION_DEFAULT_FLAGS ((GApplicationFlags) 0)
+#endif
+
 #define NATIVE_SDK_MAX_WINDOWS 16
 #define NATIVE_SDK_MAX_WEBVIEWS 16
 #define NATIVE_SDK_MAX_TIMERS 64

src/platform/windows/webview2_host.cpp

@@ -41,7 +41,16 @@
  * WebView loads report WebViewNotFound at runtime. */
 #if defined(NATIVE_SDK_ALLOW_WEBVIEW2_STUB)
 #define NATIVE_SDK_HAS_WEBVIEW2 0
-#pragma message("Embedded WebView layer excluded by the build configuration: building the Windows host without it (canvas apps unaffected; WebView loads will report WebViewNotFound)")
+/* Deliberately NO compiler diagnostic in this branch — not even an
+ * informational #pragma message. The stub is the expected, configured
+ * state of every native-only Windows build, and zig renders every
+ * clang diagnostic of a failing translation unit as `error:` (its
+ * serialized clang diagnostics carry no severity into the error
+ * bundle), so an informational note here masquerades as the
+ * build-killing error the moment any unrelated real error appears
+ * anywhere in this file. The teaching lives where it is actionable
+ * instead: a stubbed host reports WebViewNotFound the moment an app
+ * actually uses a WebView. */
 #elif __has_include(<WebView2.h>) && __has_include(<wrl.h>)
 #include <WebView2.h>
 #include <wrl.h>

src/tooling/templates.zig

@@ -1751,7 +1751,14 @@ fn buildZig(allocator: std.mem.Allocator, names: TemplateNames, framework_path:
         \\                // 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.
+        \\                // executable carries no WebKit reference at all. This
+        \\                // is the expected, configured state of every canvas
+        \\                // app on Linux, so the stub compile is deliberately
+        \\                // silent — no build note, no compiler diagnostic (the
+        \\                // host's seam comment explains why even an
+        \\                // informational pragma is dangerous); a stubbed host
+        \\                // teaches at runtime by reporting WebViewNotFound the
+        \\                // moment an app actually uses a WebView.
         \\                app_mod.addCSourceFile(.{ .file = nativeSdkPath(b, native_sdk_path, "src/platform/linux/gtk_host.c"), .flags = &.{"-DNATIVE_SDK_ALLOW_WEBKITGTK_STUB"} });
         \\                app_mod.linkSystemLibrary("gtk4", .{});
         \\                app_mod.linkSystemLibrary("dl", .{});
@@ -1797,6 +1804,14 @@ fn buildZig(allocator: std.mem.Allocator, names: TemplateNames, framework_path:
         \\                // headers are reachable through the system include paths
         \\                // — no WebView2Loader.dll is installed or path-wired,
         \\                // and the executable carries no reference to it at all.
+        \\                // This is the expected, configured state of every
+        \\                // canvas app on Windows, so the stub compile is
+        \\                // deliberately silent — no build note, no compiler
+        \\                // diagnostic (the host's seam comment explains why
+        \\                // even an informational pragma is dangerous); a
+        \\                // stubbed host teaches at runtime by reporting
+        \\                // WebViewNotFound the moment an app actually uses a
+        \\                // WebView.
         \\                app_mod.addCSourceFile(.{ .file = nativeSdkPath(b, native_sdk_path, "src/platform/windows/webview2_host.cpp"), .flags = &.{ "-std=c++17", "-DNATIVE_SDK_ALLOW_WEBVIEW2_STUB" } });
         \\            },
         \\            .chromium => {