@nativedesktop/cli 0.2.0 → 0.3.0

package/src/package/cef.ts

@@ -0,0 +1,454 @@
+// CEF acquisition and staging for `nd package`. Nothing here runs unless the
+// target's `webview.engine` is "chromium": with the default engine the app ships
+// zero Chromium bytes, which is a product claim the doctor's bundle audit
+// (cefBundleAudit, below) proves.
+//
+// Acquisition: the pinned version is resolved against the official build index,
+// the "minimal" dist is downloaded, its sha1 from the index is verified, and the
+// tarball plus its extraction are cached under ~/.cache/nativedesktop/cef/ so a
+// second package run and `nd dev` share one copy.
+//
+// Staging is split into a pure plan and an executor. The plan is what the tests
+// assert, so both platforms' layouts are covered from one cached dist without
+// writing a bundle.
+import { $ } from "bun";
+import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { buildCefHelper } from "@nativedesktop/host";
+import {
+  CEF_ARTIFACT_NAMES,
+  CEF_HELPER_BINARY_NAME,
+  type CefPlatform,
+  cefCacheRoot,
+  cefDistDir,
+  DEFAULT_CEF_VERSION,
+  isCefRoot,
+} from "@nativedesktop/host/cef";
+import type { CefConfig } from "../config.ts";
+import { cefHelperEntitlements, cefHelperPlist } from "./templates.ts";
+
+const CEF_INDEX_URL = "https://cef-builds.spotifycdn.com/index.json";
+const CEF_DOWNLOAD_BASE = "https://cef-builds.spotifycdn.com/";
+
+/** Locales staged when the config names none. */
+export const DEFAULT_CEF_LOCALES: readonly string[] = ["en-US"];
+
+export { CEF_HELPER_BINARY_NAME } from "@nativedesktop/host/cef";
+
+/** Helper bundle suffixes CEF requires on macOS, in the order they are signed.
+ * The names are fixed by CEF: it derives each helper path from the main bundle
+ * name plus exactly these suffixes. */
+export const CEF_HELPER_SUFFIXES: readonly string[] = ["", " (Alerts)", " (GPU)", " (Plugin)", " (Renderer)"];
+
+/** Suffix to bundle-id tail, e.g. " (Renderer)" to ".renderer". */
+function helperIdSuffix(suffix: string): string {
+  return suffix ? `.${suffix.trim().replace(/[()]/g, "").toLowerCase()}` : "";
+}
+
+// ---------------------------------------------------------------------------
+// Acquisition
+// ---------------------------------------------------------------------------
+
+interface CefIndexFile {
+  type: string;
+  name: string;
+  sha1: string;
+  size: number;
+}
+
+interface CefIndexVersion {
+  cef_version: string;
+  channel: string;
+  files: CefIndexFile[];
+}
+
+export interface CefIndex {
+  [platform: string]: { versions: CefIndexVersion[] };
+}
+
+export interface CefBuild {
+  /** Full version as the index spells it, e.g. "151.3.23+gd211df0+chromium-151.0.7922.170". */
+  cefVersion: string;
+  name: string;
+  sha1: string;
+  size: number;
+  url: string;
+}
+
+/**
+ * The minimal dist for a pinned version. The pin is the short release number
+ * ("151.3.23"); the index keys on the full build string, so it matches on the
+ * "+" boundary rather than a bare prefix (151.3.2 must not match 151.3.23).
+ */
+export function selectCefBuild(index: CefIndex, cefPlatform: CefPlatform, version: string): CefBuild {
+  const versions = index[cefPlatform]?.versions;
+  if (!versions?.length) throw new Error(`nd: the CEF build index lists no builds for "${cefPlatform}"`);
+  const entry = versions.find((v) => v.cef_version === version || v.cef_version.startsWith(`${version}+`));
+  if (!entry) {
+    throw new Error(`nd: CEF ${version} has no ${cefPlatform} build in the index (newest is ${versions[0]!.cef_version})`);
+  }
+  const file = entry.files.find((f) => f.type === "minimal");
+  if (!file) throw new Error(`nd: CEF ${entry.cef_version} ships no minimal ${cefPlatform} dist`);
+  return {
+    cefVersion: entry.cef_version,
+    name: file.name,
+    sha1: file.sha1,
+    size: file.size,
+    url: CEF_DOWNLOAD_BASE + encodeURIComponent(file.name),
+  };
+}
+
+/** The build index. ND_CEF_INDEX points at a local copy (offline builds, tests). */
+export async function fetchCefIndex(env: Record<string, string | undefined> = process.env): Promise<CefIndex> {
+  const local = env.ND_CEF_INDEX;
+  if (local) return (await Bun.file(local).json()) as CefIndex;
+  const response = await fetch(CEF_INDEX_URL);
+  if (!response.ok) throw new Error(`nd: CEF build index request failed (${response.status} ${response.statusText})`);
+  return (await response.json()) as CefIndex;
+}
+
+export async function sha1OfFile(path: string): Promise<string> {
+  const hasher = new Bun.CryptoHasher("sha1");
+  for await (const chunk of Bun.file(path).stream()) hasher.update(chunk);
+  return hasher.digest("hex");
+}
+
+export interface EnsureCefDistOptions {
+  cefPlatform: CefPlatform;
+  version?: string;
+  env?: Record<string, string | undefined>;
+  /** Refuse to touch the network: the dist must already be cached. */
+  offline?: boolean;
+}
+
+/**
+ * Absolute path to an extracted dist, downloading and verifying it first when
+ * the cache has none. An extraction counts as complete only once the platform's
+ * loadable is in place, so a killed run re-extracts instead of staging a
+ * half-written tree.
+ */
+export async function ensureCefDist(opts: EnsureCefDistOptions): Promise<string> {
+  const env = opts.env ?? process.env;
+  const version = opts.version ?? DEFAULT_CEF_VERSION;
+  const dist = cefDistDir(version, opts.cefPlatform, env);
+  if (isCefRoot(join(dist, "Release"), opts.cefPlatform)) return dist;
+  if (opts.offline) {
+    throw new Error(`nd: CEF ${version} for ${opts.cefPlatform} is not in the cache (${dist}) and downloads are disabled`);
+  }
+
+  const build = selectCefBuild(await fetchCefIndex(env), opts.cefPlatform, version);
+  const cache = cefCacheRoot(env);
+  mkdirSync(cache, { recursive: true });
+  const tarball = join(cache, `cef_${version}-${opts.cefPlatform}_minimal.tar.bz2`);
+  if (!existsSync(tarball) || (await sha1OfFile(tarball)) !== build.sha1) {
+    console.error(`nd: downloading CEF ${build.cefVersion} for ${opts.cefPlatform} (${(build.size / 1e6).toFixed(0)} MB)`);
+    const response = await fetch(build.url);
+    if (!response.ok) throw new Error(`nd: CEF download failed (${response.status} ${response.statusText}) for ${build.url}`);
+    await Bun.write(tarball, response);
+    const got = await sha1OfFile(tarball);
+    if (got !== build.sha1) {
+      rmSync(tarball, { force: true });
+      throw new Error(`nd: CEF download sha1 mismatch for ${build.name} (index ${build.sha1}, got ${got})`);
+    }
+  }
+
+  // Extract beside the target and rename, so an interrupted run cannot leave a
+  // partial tree that later passes the completeness check. --strip-components
+  // drops the tarball's cef_binary_<version>_<platform>_minimal/ wrapper, and
+  // tar keeps symlinks as symlinks, which the macOS framework layout needs for
+  // codesign to accept it.
+  const staging = `${dist}.partial`;
+  rmSync(staging, { recursive: true, force: true });
+  mkdirSync(staging, { recursive: true });
+  await $`tar -xjf ${tarball} -C ${staging} --strip-components=1`;
+  rmSync(dist, { recursive: true, force: true });
+  renameSync(staging, dist);
+  return dist;
+}
+
+// ---------------------------------------------------------------------------
+// macOS staging
+// ---------------------------------------------------------------------------
+
+export interface CefHelperPlan {
+  /** "" for the base helper, " (Renderer)" and friends for the rest. */
+  suffix: string;
+  appPath: string;
+  executablePath: string;
+  bundleId: string;
+  plist: string;
+  /** Renderer and GPU run JIT-compiled code and need the entitlements for it. */
+  jit: boolean;
+}
+
+export interface CefMacPlan {
+  framework: { from: string; to: string };
+  /** Mach-O inside the framework that codesign has to seal before the bundle. */
+  frameworkLibraries: string[];
+  helpers: CefHelperPlan[];
+  helperBinary: string;
+}
+
+export interface CefMacPlanInput {
+  distRoot: string;
+  /** The .app's Contents directory. */
+  contents: string;
+  appName: string;
+  appId: string;
+  version: string;
+  minimumSystemVersion: string;
+  helperBinary: string;
+}
+
+const FRAMEWORK_NAME = "Chromium Embedded Framework.framework";
+
+/** What `nd package mac` will put in Contents/Frameworks, without writing it. */
+export function planCefMac(input: CefMacPlanInput): CefMacPlan {
+  const from = join(input.distRoot, "Release", FRAMEWORK_NAME);
+  if (!existsSync(join(from, "Chromium Embedded Framework"))) {
+    throw new Error(`nd: the CEF dist at ${input.distRoot} has no ${FRAMEWORK_NAME}`);
+  }
+  const frameworks = join(input.contents, "Frameworks");
+  const to = join(frameworks, FRAMEWORK_NAME);
+  const librariesDir = join(from, "Libraries");
+  const frameworkLibraries = existsSync(librariesDir)
+    ? readdirSync(librariesDir).filter((f) => f.endsWith(".dylib")).sort().map((f) => join(to, "Libraries", f))
+    : [];
+
+  const helpers = CEF_HELPER_SUFFIXES.map((suffix) => {
+    const name = `${input.appName} Helper${suffix}`;
+    const appPath = join(frameworks, `${name}.app`);
+    const bundleId = `${input.appId}.helper${helperIdSuffix(suffix)}`;
+    return {
+      suffix,
+      appPath,
+      executablePath: join(appPath, "Contents", "MacOS", name),
+      bundleId,
+      plist: cefHelperPlist({
+        name,
+        id: bundleId,
+        version: input.version,
+        minimumSystemVersion: input.minimumSystemVersion,
+      }),
+      jit: suffix === " (Renderer)" || suffix === " (GPU)",
+    };
+  });
+
+  return { framework: { from, to }, frameworkLibraries, helpers, helperBinary: input.helperBinary };
+}
+
+/** Inside-out codesign order for the staged CEF payload: the framework's own
+ * Mach-O, the framework, then each helper executable and its bundle. Everything
+ * here is signed before the outer .app. */
+export function cefMacSignTargets(plan: CefMacPlan): { path: string; jit: boolean }[] {
+  const targets = plan.frameworkLibraries.map((path) => ({ path, jit: false }));
+  targets.push({ path: plan.framework.to, jit: false });
+  for (const helper of plan.helpers) {
+    targets.push({ path: helper.executablePath, jit: helper.jit });
+    targets.push({ path: helper.appPath, jit: helper.jit });
+  }
+  return targets;
+}
+
+/** Writes a mac plan: the framework tree and the five helper bundles. */
+export function applyCefMacPlan(plan: CefMacPlan): void {
+  if (!existsSync(plan.helperBinary)) {
+    throw new Error(
+      `nd: the CEF helper executable is missing (${plan.helperBinary}). ` +
+        `engine "chromium" needs ${CEF_HELPER_BINARY_NAME} from the AppKit host build; ` +
+        `point ND_CEF_HELPER at one, or package with engine "system".`,
+    );
+  }
+  mkdirSync(join(plan.framework.to, ".."), { recursive: true });
+  rmSync(plan.framework.to, { recursive: true, force: true });
+  // verbatimSymlinks keeps the framework's internal links as links. Resolving
+  // them duplicates the 224 MB binary and makes codesign reject the bundle.
+  cpSync(plan.framework.from, plan.framework.to, { recursive: true, verbatimSymlinks: true });
+  for (const helper of plan.helpers) {
+    mkdirSync(join(helper.appPath, "Contents", "MacOS"), { recursive: true });
+    cpSync(plan.helperBinary, helper.executablePath, { dereference: true });
+    chmodSync(helper.executablePath, 0o755);
+    writeFileSync(join(helper.appPath, "Contents", "Info.plist"), helper.plist);
+  }
+}
+
+/** Entitlements file for the JIT helpers, written next to the app's own. */
+export function writeCefHelperEntitlements(dir: string): string {
+  const path = join(dir, "cef-helper-entitlements.plist");
+  writeFileSync(path, cefHelperEntitlements());
+  return path;
+}
+
+// ---------------------------------------------------------------------------
+// Linux staging
+// ---------------------------------------------------------------------------
+
+/** Release/ payload, from the dist's own cmake/cef_variables.cmake list.
+ * libvulkan.so.1 belongs to the swiftshader set: dropping it leaves the
+ * software renderer unable to load. */
+const LINUX_BINARIES: readonly string[] = [
+  "libcef.so",
+  "libEGL.so",
+  "libGLESv2.so",
+  "libvk_swiftshader.so",
+  "libvulkan.so.1",
+  "vk_swiftshader_icd.json",
+  "v8_context_snapshot.bin",
+  "chrome-sandbox",
+];
+
+/** Resources/ payload, minus locales/, which is trimmed to the config list. */
+const LINUX_RESOURCES: readonly string[] = [
+  "icudtl.dat",
+  "resources.pak",
+  "chrome_100_percent.pak",
+  "chrome_200_percent.pak",
+];
+
+export interface CefLinuxFile {
+  from: string;
+  to: string;
+  /** libcef.so ships with full debug info: 1.43 GB unstripped, ~269 MB stripped. */
+  strip?: boolean;
+}
+
+export interface CefLinuxPlan {
+  root: string;
+  files: CefLinuxFile[];
+  locales: CefLinuxFile[];
+  /** Dist entries the plan wanted and could not find. A non-empty list is fatal. */
+  missing: string[];
+}
+
+export interface CefLinuxPlanInput {
+  distRoot: string;
+  /** The AppDir root. */
+  appDir: string;
+  locales?: string[];
+}
+
+/** What `nd package linux` will put in <AppDir>/lib/cef, without writing it. */
+export function planCefLinux(input: CefLinuxPlanInput): CefLinuxPlan {
+  const root = join(input.appDir, "lib", "cef");
+  const release = join(input.distRoot, "Release");
+  const resources = join(input.distRoot, "Resources");
+  const missing: string[] = [];
+  const files: CefLinuxFile[] = [];
+
+  for (const name of LINUX_BINARIES) {
+    const from = join(release, name);
+    if (!existsSync(from)) missing.push(`Release/${name}`);
+    files.push({ from, to: join(root, name), strip: name === "libcef.so" });
+  }
+  for (const name of LINUX_RESOURCES) {
+    const from = join(resources, name);
+    if (!existsSync(from)) missing.push(`Resources/${name}`);
+    files.push({ from, to: join(root, name) });
+  }
+
+  const wanted = input.locales?.length ? input.locales : DEFAULT_CEF_LOCALES;
+  const locales = wanted.map((locale) => {
+    const from = join(resources, "locales", `${locale}.pak`);
+    if (!existsSync(from)) missing.push(`Resources/locales/${locale}.pak`);
+    return { from, to: join(root, "locales", `${locale}.pak`) };
+  });
+
+  return { root, files, locales, missing };
+}
+
+/** Writes a linux plan, preserving each file's mode from the dist. chrome-sandbox
+ * ships mode 0755 and needs 4755 root-owned to use the setuid sandbox; that is a
+ * post-install step for whoever installs the AppImage, not something a packaging
+ * run can do for them (see the doctor's cef note). The userns sandbox is the
+ * automatic fallback, so `--no-sandbox` is never the answer. */
+export async function applyCefLinuxPlan(plan: CefLinuxPlan): Promise<void> {
+  if (plan.missing.length) {
+    throw new Error(`nd: the CEF dist is missing ${plan.missing.length} staged file(s): ${plan.missing.join(", ")}`);
+  }
+  mkdirSync(join(plan.root, "locales"), { recursive: true });
+  for (const file of [...plan.files, ...plan.locales]) {
+    cpSync(file.from, file.to, { dereference: true });
+    chmodSync(file.to, statSync(file.from).mode & 0o7777);
+  }
+  const strip = plan.files.find((f) => f.strip);
+  if (strip) await stripInPlace(strip.to);
+}
+
+/** `strip` on the staged libcef.so. Cross-packaging from macOS has no ELF strip,
+ * so a failure warns and ships the unstripped copy rather than failing the run. */
+async function stripInPlace(path: string): Promise<void> {
+  const before = statSync(path).size;
+  const result = await $`strip ${path}`.quiet().nothrow();
+  if (result.exitCode !== 0) {
+    console.error(`ND_WARN nd: strip failed on ${basename(path)}; shipping it unstripped (${(before / 1e9).toFixed(2)} GB)`);
+    return;
+  }
+  const after = statSync(path).size;
+  console.error(`ND_PACKAGE_CEF_STRIP ${basename(path)} ${(before / 1e6).toFixed(0)}MB -> ${(after / 1e6).toFixed(0)}MB`);
+}
+
+// ---------------------------------------------------------------------------
+// The zero-bytes claim
+// ---------------------------------------------------------------------------
+
+/**
+ * Every CEF artifact found in a bundle, bundle-relative. An engine="system"
+ * build must return an empty list: that is the "zero Chromium bytes unless the
+ * config asks for it" claim, checked rather than asserted.
+ */
+export function cefBundleAudit(bundleRoot: string): string[] {
+  const names = new Set(CEF_ARTIFACT_NAMES);
+  const found: string[] = [];
+  const walk = (dir: string, prefix: string): void => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (names.has(entry.name)) {
+        found.push(rel);
+        continue;
+      }
+      if (entry.isDirectory() && !entry.isSymbolicLink()) walk(join(dir, entry.name), rel);
+    }
+  };
+  walk(bundleRoot, "");
+  return found.sort();
+}
+
+/** The pinned CEF release for a config. */
+export function cefVersionFor(cef: CefConfig | undefined): string {
+  return cef?.version ?? DEFAULT_CEF_VERSION;
+}
+
+/** The helper executable: ND_CEF_HELPER, else beside the host binary. */
+export function resolveCefHelperBinary(
+  hostBinary: string,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  return env.ND_CEF_HELPER ?? join(hostBinary, "..", CEF_HELPER_BINARY_NAME);
+}
+
+/** The helper executable, built from the framework checkout when the host is a
+ * source build and the helper product has never been built. Same resolution the
+ * host binary itself gets: use what is there, otherwise build it, and only then
+ * give up. */
+export async function ensureCefHelperBinary(
+  hostBinary: string,
+  env: Record<string, string | undefined> = process.env,
+): Promise<string> {
+  const path = resolveCefHelperBinary(hostBinary, env);
+  if (existsSync(path)) return path;
+  if (!env.ND_CEF_HELPER) {
+    const built = await buildCefHelper(hostBinary);
+    if (built) return built;
+  }
+  throw new Error(
+    `nd: the CEF helper executable is missing (${path}). ` +
+      `engine "chromium" needs ${CEF_HELPER_BINARY_NAME} from the AppKit host build; ` +
+      "point ND_CEF_HELPER at one, or package with engine \"system\".",
+  );
+}

package/src/package/doctor.test.ts

@@ -0,0 +1,84 @@
+// The two CEF doctor checks: a config that asks for chromium with no dist
+// resolvable, and the zero-Chromium-bytes claim an engine="system" bundle makes.
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { NativeDesktopConfig } from "../config.ts";
+import { builtBundles, type Check, webviewChecks } from "./doctor.ts";
+
+const FRAMEWORK = "Chromium Embedded Framework.framework";
+const target = process.platform === "darwin" ? "mac" : "linux";
+
+function tempApp(): string {
+  return mkdtempSync(join(tmpdir(), "nd-doctor-"));
+}
+
+function find(checks: Check[], name: string): Check[] {
+  return checks.filter((c) => c.name === name);
+}
+
+/** Stage a packaged bundle of the host platform's shape under <app>/dist. */
+function stageBundle(app: string, withCef: boolean): string {
+  if (process.platform === "darwin") {
+    const bundle = join(app, "dist", "mac", "Demo.app");
+    mkdirSync(join(bundle, "Contents", "MacOS"), { recursive: true });
+    if (withCef) mkdirSync(join(bundle, "Contents", "Frameworks", FRAMEWORK), { recursive: true });
+    return bundle;
+  }
+  const bundle = join(app, "dist", "linux", "AppDir");
+  mkdirSync(join(bundle, "usr", "bin"), { recursive: true });
+  if (withCef) {
+    mkdirSync(join(bundle, "lib", "cef"), { recursive: true });
+    writeFileSync(join(bundle, "lib", "cef", "libcef.so"), "");
+  }
+  return bundle;
+}
+
+describe("builtBundles", () => {
+  test("finds what a previous package run left in the output dir", () => {
+    const app = tempApp();
+    const bundle = stageBundle(app, false);
+    expect(builtBundles({}, app)).toEqual([bundle]);
+    expect(builtBundles({}, tempApp())).toEqual([]);
+  });
+});
+
+describe("webviewChecks", () => {
+  test("reports the resolved engine for this platform", () => {
+    const checks = webviewChecks({}, tempApp());
+    expect(find(checks, "webview")[0]!.detail).toBe(`engine=system (${target})`);
+    expect(find(checks, "cef")).toEqual([]);
+  });
+
+  test("chromium with no resolvable dist is an error naming the cache path", () => {
+    const config: NativeDesktopConfig = {
+      webview: { engine: { [target]: "chromium" }, cef: { version: "0.0.0-absent" } },
+    };
+    const cef = find(webviewChecks(config, tempApp()), "cef");
+    const failure = cef.find((c) => c.status === "error");
+    expect(failure).toBeDefined();
+    expect(failure!.detail).toContain("0.0.0-absent");
+    expect(failure!.detail).toContain("ND_CEF_ROOT");
+  });
+
+  test("an engine=system bundle carrying CEF fails the zero-bytes claim", () => {
+    const clean = webviewChecks({}, (() => { const a = tempApp(); stageBundle(a, false); return a; })());
+    expect(find(clean, "cef-bytes")[0]!.status).toBe("ok");
+
+    const dirty = webviewChecks({}, (() => { const a = tempApp(); stageBundle(a, true); return a; })());
+    expect(find(dirty, "cef-bytes")[0]!.status).toBe("error");
+    expect(find(dirty, "cef-bytes")[0]!.detail).toContain('engine "system"');
+  });
+
+  test("with chromium configured the same bundle is what the check wants to see", () => {
+    const config: NativeDesktopConfig = { webview: { engine: { [target]: "chromium" } } };
+    const app = tempApp();
+    stageBundle(app, true);
+    expect(find(webviewChecks(config, app), "cef-bytes")[0]!.status).toBe("ok");
+
+    const empty = tempApp();
+    stageBundle(empty, false);
+    expect(find(webviewChecks(config, empty), "cef-bytes")[0]!.status).toBe("error");
+  });
+});

package/src/package/doctor.ts

@@ -1,10 +1,19 @@
 // `nd doctor`: checks the current directory's packaging readiness and the
 // host toolchain. Warnings are advisory; only real gaps (a config that names
 // missing files, an unresolvable host binary) exit non-zero.
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { hostBinaryCandidates, prebuiltHostBinary, resolveBackend } from "@nativedesktop/host";
-import { loadConfig, type NativeDesktopConfig } from "../config.ts";
+import { cefDistDir, cefPlatformKey, resolveCefRoot } from "@nativedesktop/host/cef";
+import {
+  engineTargetFor,
+  loadConfig,
+  type NativeDesktopConfig,
+  resolveCefSchemes,
+  resolveWebViewEngine,
+  type WebViewEngine,
+} from "../config.ts";
+import { cefBundleAudit, cefVersionFor } from "./cef.ts";
 import { DEFAULT_ENTRY } from "./payload.ts";
 
 export type CheckStatus = "ok" | "warn" | "error";
@@ -44,6 +53,83 @@ function macIconChecks(config: NativeDesktopConfig): Check[] {
   return [];
 }
 
+/** Bundles a previous `nd package` run left in the output dir, which is what the
+ * zero-CEF-bytes claim can be checked against. */
+export function builtBundles(config: NativeDesktopConfig, cwd: string): string[] {
+  const outDir = resolve(cwd, config.package?.workspaceRoot ?? ".", config.package?.outDir ?? "dist");
+  const bundles: string[] = [];
+  const macDir = join(outDir, "mac");
+  if (existsSync(macDir)) {
+    for (const entry of readdirSync(macDir)) if (entry.endsWith(".app")) bundles.push(join(macDir, entry));
+  }
+  const appDir = join(outDir, "linux", "AppDir");
+  if (existsSync(appDir)) bundles.push(appDir);
+  return bundles;
+}
+
+/**
+ * The engine the current platform resolves to, whether CEF can be found when it
+ * asks for one, and whether the last packaged bundle matches: an engine="system"
+ * bundle carrying Chromium bytes breaks the framework's central claim about the
+ * default path, so it fails rather than warns.
+ */
+export function webviewChecks(config: NativeDesktopConfig, cwd: string): Check[] {
+  const target = engineTargetFor();
+  if (!target) return [];
+  let engine: WebViewEngine;
+  let schemes: string[];
+  try {
+    engine = resolveWebViewEngine(config, target);
+    schemes = resolveCefSchemes(config);
+  } catch (err) {
+    return [{ name: "webview", status: "error", detail: String(err) }];
+  }
+  const checks: Check[] = [{
+    name: "webview",
+    status: "ok",
+    detail: `engine=${engine} (${target})${process.env.ND_WEBVIEW_ENGINE ? " from ND_WEBVIEW_ENGINE" : ""}` +
+      (schemes.length ? ` schemes=${schemes.join(",")}` : ""),
+  }];
+
+  const version = cefVersionFor(config.webview?.cef);
+  if (engine === "chromium") {
+    try {
+      const cefPlatform = cefPlatformKey();
+      const root = resolveCefRoot({ cefPlatform, version });
+      checks.push(root
+        ? { name: "cef", status: "ok", detail: `CEF ${version} at ${root}` }
+        : {
+          name: "cef",
+          status: "error",
+          detail: `engine "chromium" but no CEF ${version} dist found (ND_CEF_ROOT, the app bundle, or ${cefDistDir(version, cefPlatform)}); \`nd package\` downloads it`,
+        });
+    } catch (err) {
+      checks.push({ name: "cef", status: "error", detail: String(err) });
+    }
+    if (target === "linux") {
+      checks.push({
+        name: "cef",
+        status: "warn",
+        detail: "chrome-sandbox ships with the dist's own mode; the setuid sandbox wants root:root 4755 at install time (the userns sandbox is the automatic fallback, never --no-sandbox)",
+      });
+    }
+  }
+
+  for (const bundle of builtBundles(config, cwd)) {
+    const found = cefBundleAudit(bundle);
+    if (engine === "chromium") {
+      checks.push(found.length
+        ? { name: "cef-bytes", status: "ok", detail: `${bundle}: ${found.length} CEF artifact(s) staged` }
+        : { name: "cef-bytes", status: "error", detail: `${bundle} carries no CEF payload but engine is "chromium" (repackage)` });
+    } else {
+      checks.push(found.length
+        ? { name: "cef-bytes", status: "error", detail: `${bundle} ships CEF with engine "system": ${found.slice(0, 3).join(", ")}` }
+        : { name: "cef-bytes", status: "ok", detail: `${bundle}: no CEF bytes` });
+    }
+  }
+  return checks;
+}
+
 export async function collectChecks(cwd: string): Promise<Check[]> {
   const checks: Check[] = [];
   const configPath = resolve(cwd, "nativedesktop.config.ts");
@@ -114,6 +200,8 @@ export async function collectChecks(cwd: string): Promise<Check[]> {
       : { name: "appimage", status: "warn", detail: "neither appimagetool nor mksquashfs on PATH (only the raw AppDir can be produced)" });
   }
 
+  checks.push(...webviewChecks(config, cwd));
+
   if (config.package?.updates) {
     checks.push(which("minisign")
       ? { name: "updates", status: "ok", detail: "updates configured, minisign available" }

package/src/package/identity.test.ts

@@ -205,5 +205,19 @@ describe("buildDesktopEntry / appRunTemplate", () => {
     expect(script).toContain('export ND_APP_ID="com.nativedesktop.gallery"');
     expect(script).toContain('export ND_PLUGIN_PATHS="$HERE/app/native/libdemo.so"');
     expect(script).toContain('exec "$HERE/usr/bin/gallery" "$@"');
+    expect(script).not.toContain("ND_WEBVIEW_ENGINE");
+  });
+
+  test("AppRun exports the engine and its schemes, behind an override", () => {
+    const script = appRunTemplate({
+      entry: "src/main.tsx",
+      cwd: ".",
+      slug: "gallery",
+      pluginPaths: [],
+      engine: "chromium",
+      schemes: ["nbext", "nbint"],
+    });
+    expect(script).toContain('export ND_WEBVIEW_ENGINE="${ND_WEBVIEW_ENGINE:-chromium}"');
+    expect(script).toContain('export ND_CEF_SCHEMES="${ND_CEF_SCHEMES:-nbext,nbint}"');
   });
 });