Infer the web layer and enforce native-only builds end to end (#107)

* Infer the web layer and enforce native-only builds end to end

- The build graph parses app.zon and strips the Windows webview layer, loader staging, and dev PATH wiring when nothing declares web use; a webview_layer manifest field and -Dweb-layer flag override inference in both directions
- Conflicting declarations are rejected with one teaching message at validate, configure, runner compile, and package time, and a native-only build that reaches webview creation fails fast with WebViewLayerNotBuilt instead of a blank window
- A PE cross-audit build step pins that native-only Windows exes never reference the loader while webview apps must, and native check prints the web-layer verdict

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

* Unify web-layer inference behind one shared contract

- app_manifest.web_layer owns the declaration scan, engine folding, and include/exclude decision, usable at comptime by the runner and at runtime by the build graph, validator, CLI, and generated scaffolds, with boundary ownership documented where each adapter lives
- Packaging decides from the resolved engine so --web-engine overrides cannot skew the layer, the runner guard covers shell views and manifest chromium, and the full scaffold emits the same inference, conflict panic, and conditional Windows wiring as the SDK graph
- A contract matrix test runs every manifest shape through every boundary form so the definitions can never diverge again

* Document the webview_layer override and Chromium web intent

- The capabilities page counts a Chromium-resolved engine as web intent and points at the override; the app.zon reference gains the webview_layer field, its inference and include/exclude semantics, and the exclude-conflict rule with the shipped error's remedy

* Carry the web-layer resolution into packaging

- Both build graphs forward their computed web-layer decision to native package via a new --web-layer flag, so the exe and the package can never disagree; a confirming flag keeps the manifest's reason while an overriding one names itself
- Packaging PE-scans Windows binaries and refuses to package a loader-referencing exe under a loaderless decision, closing the mismatch for hand-built binaries too
- Fixes an adjacent buildgraph bug where a sentinel-terminated path allocation was returned as a plain slice

* Honor the webview stub define before header visibility

- NATIVE_SDK_ALLOW_WEBVIEW2_STUB now excludes the embedded layer even when WebView2 headers are globally visible, so a native-only build can never reintroduce the loader reference; the vendor pins lock the guard order
- The stub message says the layer is excluded by configuration instead of claiming the header is missing

---------

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

Author: ctate

.github/workflows/ci.yml

@@ -130,6 +130,11 @@ jobs:
       - name: Install GTK dependencies
         run: sudo apt-get update && sudo apt-get install -y libgtk-4-dev libwebkitgtk-6.0-dev
       - run: zig build test-examples-native
+      # Declare-to-use, proven on real Windows executables: the
+      # canvas-only ui-inbox cross-compiles without the embedded WebView
+      # layer (no WebView2Loader.dll reference, no loader installed) and
+      # the webview example keeps it.
+      - run: zig build test-windows-web-layer-audit
 
   linux-canvas-smoke:
     name: Linux Canvas Smoke

build.zig

@@ -482,19 +482,31 @@ pub fn build(b: *std.Build) void {
         .{ .path = "src/platform/linux/gtk_host.c", .pattern = "change != NATIVE_SDK_GST_STATE_CHANGE_ASYNC" },
         .{ .path = "src/platform/linux/gtk_host.c", .pattern = "#define NATIVE_SDK_GST_STATE_CHANGE_ASYNC 2" },
     });
-    // The embedded-WebView layer must stay real: the vendored WebView2
-    // SDK header turns the guard on, every first-party build graph puts
-    // it on the include path, and a build that cannot see it fails at
-    // compile time instead of quietly shipping the stubbed host (whose
-    // WebView loads report WebViewNotFound at runtime).
-    addFileContainsCheckStep(b, file_contains_checker, test_step, "test-windows-webview2-vendor", "Verify the vendored WebView2 SDK stays wired into every Windows build graph", &.{
+    // The embedded-WebView layer must stay real AND declare-to-use: the
+    // standard build graph puts the vendored WebView2 SDK header on the
+    // include path exactly when app.zon declares web use (`if
+    // (web_layer)`), and only the native-only branch passes the stub
+    // define. In the guard the stub define is tested FIRST, before
+    // header visibility: on a machine where the WebView2 SDK headers are
+    // reachable through the system include paths, an
+    // include-path-decides guard would compile the full layer into a
+    // native-only build and reintroduce the WebView2Loader.dll reference
+    // its executable must not carry. Without the define the header is
+    // required — a web build that cannot see it fails at compile time
+    // instead of quietly shipping the stubbed host (whose WebView loads
+    // report WebViewNotFound at runtime).
+    addFileContainsCheckStep(b, file_contains_checker, test_step, "test-windows-webview2-vendor", "Verify the vendored WebView2 SDK stays wired into every web-declaring Windows build graph", &.{
         .{ .path = "third_party/webview2/include/WebView2.h", .pattern = "CreateCoreWebView2EnvironmentWithOptions" },
         .{ .path = "third_party/webview2/include/EventToken.h", .pattern = "EventRegistrationToken" },
         .{ .path = "third_party/webview2/LICENSE.txt", .pattern = "Redistribution and use in source and binary forms" },
+        .{ .path = "src/platform/windows/webview2_host.cpp", .pattern = "#if defined(NATIVE_SDK_ALLOW_WEBVIEW2_STUB)" },
+        .{ .path = "src/platform/windows/webview2_host.cpp", .pattern = "#elif __has_include(<WebView2.h>) && __has_include(<wrl.h>)" },
         .{ .path = "src/platform/windows/webview2_host.cpp", .pattern = "#error \"WebView2.h not found" },
         .{ .path = "src/platform/windows/webview2_host.cpp", .pattern = "LoadLibraryW(L\"WebView2Loader.dll\")" },
+        .{ .path = "build/app.zig", .pattern = ".system => if (web_layer) {" },
         .{ .path = "build/app.zig", .pattern = "app_mod.addIncludePath(dep.path(\"third_party/webview2/include\"));" },
         .{ .path = "build/app.zig", .pattern = "third_party/webview2/x64/WebView2Loader.dll" },
+        .{ .path = "build/app.zig", .pattern = "\"-DNATIVE_SDK_ALLOW_WEBVIEW2_STUB\"" },
         .{ .path = "src/tooling/templates.zig", .pattern = "third_party/webview2/include" },
         .{ .path = "src/tooling/templates.zig", .pattern = "third_party/webview2/x64/WebView2Loader.dll" },
     });
@@ -797,6 +809,47 @@ pub fn build(b: *std.Build) void {
     const browser_system_link_step = b.step("test-browser-system-link", "Build the browser example with the system engine");
     browser_system_link_step.dependOn(&build_browser_system.step);
 
+    // Windows web-layer PE cross-audit: the declare-to-use inference,
+    // proven on real executables from any host via cross-compile.
+    // ui-inbox's manifest declares no web use, so its exe must carry no
+    // WebView2Loader.dll reference (the whole embedded layer compiles
+    // out) and no loader may land beside it; the webview example declares
+    // the "webview" capability, so its exe must keep the reference. The
+    // loader string lives as UTF-16 in the host, so the audit is a
+    // dedicated scanner (tools/audit_web_layer.zig), not a text grep.
+    const web_layer_auditor = b.addExecutable(.{
+        .name = "audit-web-layer",
+        .root_module = module(b, host_target, optimize, "tools/audit_web_layer.zig"),
+    });
+    // A loader installed by a build predating the inference would fail
+    // the absence check below without being this build's fault; clear it
+    // so the assertion tests what THIS build installs.
+    const clean_native_only_loader = b.addSystemCommand(&.{ "sh", "-c", "rm -f examples/ui-inbox/zig-out/bin/WebView2Loader.dll" });
+    const build_native_only_windows = b.addSystemCommand(&.{ "zig", "build", "-Dtarget=x86_64-windows-gnu", "-Dplatform=windows" });
+    build_native_only_windows.setCwd(b.path("examples/ui-inbox"));
+    build_native_only_windows.step.dependOn(&clean_native_only_loader.step);
+    const build_webview_windows = b.addSystemCommand(&.{ "zig", "build", "-Dtarget=x86_64-windows-gnu", "-Dplatform=windows", "-Dweb-engine=system" });
+    build_webview_windows.setCwd(b.path("examples/webview"));
+    const audit_native_only_exe = b.addRunArtifact(web_layer_auditor);
+    audit_native_only_exe.addArgs(&.{ "examples/ui-inbox/zig-out/bin/ui-inbox.exe", "absent" });
+    audit_native_only_exe.has_side_effects = true;
+    audit_native_only_exe.step.dependOn(&build_native_only_windows.step);
+    const audit_webview_exe = b.addRunArtifact(web_layer_auditor);
+    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",
+        \\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
+        \\}
+    });
+    audit_native_only_loader.step.dependOn(&build_native_only_windows.step);
+    const web_layer_audit_step = b.step("test-windows-web-layer-audit", "Cross-compile a native-only and a web example for Windows and audit the web layer in each exe");
+    web_layer_audit_step.dependOn(&audit_native_only_exe.step);
+    web_layer_audit_step.dependOn(&audit_webview_exe.step);
+    web_layer_audit_step.dependOn(&audit_native_only_loader.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);