@nativedesktop/host 0.1.2 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nativedesktop/host",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Resolves the prebuilt NativeDesktop host binary for the current platform",
   "type": "module",
   "license": "MIT",
@@ -20,10 +20,11 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./cef": "./src/cef.ts"
   },
   "optionalDependencies": {
-    "@nativedesktop/host-darwin-arm64": "0.1.2",
-    "@nativedesktop/host-linux-x64": "0.1.2"
+    "@nativedesktop/host-darwin-arm64": "0.3.0",
+    "@nativedesktop/host-linux-x64": "0.3.0"
   }
 }

package/src/cef.test.ts

@@ -0,0 +1,86 @@
+// CEF resolution order. The engine backends read the same three places in the
+// same sequence natively, so the order here is a contract, not a preference.
+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 {
+  bundleCefDir,
+  cefCacheRoot,
+  cefDistDir,
+  cefLoadableName,
+  cefPlatformKey,
+  cefRootCandidates,
+  isCefRoot,
+  resolveCefRoot,
+} from "./cef.ts";
+
+describe("cefPlatformKey", () => {
+  test("maps os/arch onto the names cef-builds.spotifycdn.com uses", () => {
+    expect(cefPlatformKey("darwin", "arm64")).toBe("macosarm64");
+    expect(cefPlatformKey("darwin", "x64")).toBe("macosx64");
+    expect(cefPlatformKey("linux", "x64")).toBe("linux64");
+    expect(cefPlatformKey("linux", "arm64")).toBe("linuxarm64");
+  });
+
+  test("rejects a platform CEF has no build for", () => {
+    expect(() => cefPlatformKey("win32", "arm64")).toThrow("no CEF build");
+  });
+});
+
+describe("cefCacheRoot", () => {
+  test("honors XDG_CACHE_HOME, else ~/.cache", () => {
+    expect(cefCacheRoot({ XDG_CACHE_HOME: "/x", HOME: "/home/k" })).toBe("/x/nativedesktop/cef");
+    expect(cefCacheRoot({ HOME: "/home/k" })).toBe("/home/k/.cache/nativedesktop/cef");
+  });
+
+  test("the dist dir is keyed version-platform", () => {
+    expect(cefDistDir("151.3.23", "macosarm64", { HOME: "/home/k" }))
+      .toBe("/home/k/.cache/nativedesktop/cef/151.3.23-macosarm64");
+  });
+});
+
+describe("cefRootCandidates", () => {
+  test("ND_CEF_ROOT, then the bundle, then the dev cache", () => {
+    const candidates = cefRootCandidates({
+      cefPlatform: "macosarm64",
+      version: "151.3.23",
+      bundleRoot: "/apps/Demo.app",
+      env: { ND_CEF_ROOT: "/opt/cef", HOME: "/home/k" },
+    });
+    expect(candidates).toEqual([
+      "/opt/cef",
+      "/apps/Demo.app/Contents/Frameworks",
+      "/home/k/.cache/nativedesktop/cef/151.3.23-macosarm64/Release",
+    ]);
+  });
+
+  test("without ND_CEF_ROOT or a bundle only the cache remains", () => {
+    expect(cefRootCandidates({ cefPlatform: "linux64", version: "151.3.23", env: { HOME: "/home/k" } }))
+      .toEqual(["/home/k/.cache/nativedesktop/cef/151.3.23-linux64/Release"]);
+  });
+
+  test("a linux bundle keeps CEF under lib/cef", () => {
+    expect(bundleCefDir("/build/AppDir", "linux64")).toBe("/build/AppDir/lib/cef");
+  });
+});
+
+describe("resolveCefRoot", () => {
+  test("skips candidates that hold no loadable and takes the first that does", () => {
+    const home = mkdtempSync(join(tmpdir(), "nd-cef-"));
+    const empty = join(home, "empty");
+    mkdirSync(empty, { recursive: true });
+    const cache = join(home, ".cache", "nativedesktop", "cef", "151.3.23-linux64", "Release");
+    mkdirSync(cache, { recursive: true });
+    writeFileSync(join(cache, cefLoadableName("linux64")), "");
+
+    const env = { HOME: home, ND_CEF_ROOT: empty };
+    expect(isCefRoot(empty, "linux64")).toBe(false);
+    expect(resolveCefRoot({ cefPlatform: "linux64", version: "151.3.23", env })).toBe(cache);
+  });
+
+  test("undefined when nothing on disk answers", () => {
+    const home = mkdtempSync(join(tmpdir(), "nd-cef-"));
+    expect(resolveCefRoot({ cefPlatform: "linux64", version: "151.3.23", env: { HOME: home } })).toBeUndefined();
+  });
+});

package/src/cef.ts

@@ -0,0 +1,123 @@
+// @nativedesktop/host/cef: where the Chromium Embedded Framework lives for a
+// given platform. CEF is never linked into a host binary (it is dlopened at
+// runtime), so `nd dev`, `nd package`, `nd doctor` and both engine backends all
+// have to agree on one search order. This module is that order for the
+// TypeScript side; the Zig and Swift loaders read the same three places in the
+// same sequence.
+//
+//   1. ND_CEF_ROOT       an explicit directory, ahead of everything else
+//   2. the app bundle    Contents/Frameworks (mac), lib/cef (linux)
+//   3. the dev cache     ~/.cache/nativedesktop/cef/<version>-<platform>/Release
+//
+// Nothing here downloads anything: resolution answers from what is already on
+// disk. Fetching and staging a dist is `nd package`'s job (packages/nd).
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/** CEF release the framework pins. `webview.cef.version` overrides it. */
+export const DEFAULT_CEF_VERSION = "151.3.23";
+
+/** The CEF subprocess executable, built beside the appkit host binary and
+ * copied into each of the five helper .apps a packaged macOS bundle carries. */
+export const CEF_HELPER_BINARY_NAME = "nd-cef-helper";
+
+/** Platform names as cef-builds.spotifycdn.com spells them. */
+export type CefPlatform = "macosarm64" | "macosx64" | "linux64" | "linuxarm64";
+
+const CEF_PLATFORMS: Record<string, CefPlatform> = {
+  "darwin-arm64": "macosarm64",
+  "darwin-x64": "macosx64",
+  "linux-x64": "linux64",
+  "linux-arm64": "linuxarm64",
+};
+
+/** The CEF platform key for an os/arch pair, e.g. "macosarm64". */
+export function cefPlatformKey(platform: string = process.platform, arch: string = process.arch): CefPlatform {
+  const key = CEF_PLATFORMS[`${platform}-${arch}`];
+  if (!key) throw new Error(`@nativedesktop/host: no CEF build for "${platform}-${arch}"`);
+  return key;
+}
+
+/** True for the two macOS keys, which carry a framework instead of a .so. */
+export function isMacCefPlatform(cefPlatform: CefPlatform): boolean {
+  return cefPlatform.startsWith("macos");
+}
+
+/** The loadable, relative to the directory that holds it. Its presence is what
+ * makes a candidate directory a CEF root. */
+export function cefLoadableName(cefPlatform: CefPlatform): string {
+  return isMacCefPlatform(cefPlatform)
+    ? "Chromium Embedded Framework.framework/Chromium Embedded Framework"
+    : "libcef.so";
+}
+
+/** ~/.cache/nativedesktop/cef, or $XDG_CACHE_HOME/nativedesktop/cef. */
+export function cefCacheRoot(env: Record<string, string | undefined> = process.env): string {
+  const base = env.XDG_CACHE_HOME || join(env.HOME || homedir(), ".cache");
+  return join(base, "nativedesktop", "cef");
+}
+
+/** Extracted dist for a version+platform: <cache>/<version>-<platform>, the
+ * tarball's contents with its top-level cef_binary_… directory stripped. */
+export function cefDistDir(
+  version: string,
+  cefPlatform: CefPlatform,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  return join(cefCacheRoot(env), `${version}-${cefPlatform}`);
+}
+
+export interface CefRootOptions {
+  cefPlatform: CefPlatform;
+  version?: string;
+  /** A packaged bundle to search: the .app on macOS, the AppDir on Linux. */
+  bundleRoot?: string;
+  env?: Record<string, string | undefined>;
+}
+
+/** The three candidate directories, in resolution order, whether or not they exist. */
+export function cefRootCandidates(opts: CefRootOptions): string[] {
+  const env = opts.env ?? process.env;
+  const version = opts.version ?? DEFAULT_CEF_VERSION;
+  const candidates: string[] = [];
+  if (env.ND_CEF_ROOT) candidates.push(resolve(env.ND_CEF_ROOT));
+  if (opts.bundleRoot) candidates.push(bundleCefDir(opts.bundleRoot, opts.cefPlatform));
+  candidates.push(join(cefDistDir(version, opts.cefPlatform, env), "Release"));
+  return candidates;
+}
+
+/** Where a packaged bundle keeps its CEF payload. */
+export function bundleCefDir(bundleRoot: string, cefPlatform: CefPlatform): string {
+  return isMacCefPlatform(cefPlatform)
+    ? join(bundleRoot, "Contents", "Frameworks")
+    : join(bundleRoot, "lib", "cef");
+}
+
+/** A directory counts as a CEF root once it holds the platform's loadable. */
+export function isCefRoot(dir: string, cefPlatform: CefPlatform): boolean {
+  return existsSync(join(dir, cefLoadableName(cefPlatform)));
+}
+
+/** First candidate that actually holds the loadable, or undefined. */
+export function resolveCefRoot(opts: CefRootOptions): string | undefined {
+  return cefRootCandidates(opts).find((dir) => isCefRoot(dir, opts.cefPlatform));
+}
+
+/**
+ * Basenames of the CEF artifacts a bundle would carry. The doctor check that
+ * proves an engine="system" bundle ships zero Chromium bytes matches on these,
+ * so one list covers both platforms' layouts.
+ */
+export const CEF_ARTIFACT_NAMES: readonly string[] = [
+  "Chromium Embedded Framework.framework",
+  "libcef.so",
+  "chrome-sandbox",
+  "icudtl.dat",
+  "resources.pak",
+  "chrome_100_percent.pak",
+  "chrome_200_percent.pak",
+  "v8_context_snapshot.bin",
+  "libvk_swiftshader.so",
+  "vk_swiftshader_icd.json",
+];

package/src/index.ts

@@ -20,7 +20,8 @@
 //     built on first run.
 import { existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
-import { resolve } from "node:path";
+import { basename, dirname, resolve } from "node:path";
+import { CEF_HELPER_BINARY_NAME } from "./cef.ts";
 
 const OS_NAMES: Record<string, string> = { darwin: "darwin", linux: "linux", win32: "windows" };
 const ARCH_NAMES: Record<string, string> = { arm64: "arm64", x64: "x64" };
@@ -199,6 +200,31 @@ export async function resolveHostBinary(
   throw new Error(`@nativedesktop/host: no ${backend} host binary for "${key}". ${hint}`);
 }
 
+/**
+ * The CEF subprocess executable for an appkit host binary, built from the same
+ * SwiftPM package the host came from. Packaging copies it into the five helper
+ * .apps, and it is a separate product, so a checkout that has only ever run
+ * `nd dev` has the host built and this one missing.
+ *
+ * Returns undefined when the host binary is not a source-checkout build: a
+ * prebuilt platform package ships the helper beside the host, and there is
+ * nothing to build from.
+ */
+export async function buildCefHelper(hostBinary: string): Promise<string | undefined> {
+  const buildDir = dirname(resolve(hostBinary));
+  const repoRoot = resolve(buildDir, "..", "..", "..");
+  if (!isSourceCheckout(repoRoot)) return undefined;
+  const configuration = basename(buildDir) === "debug" ? "debug" : "release";
+  process.stderr.write(`nd: building ${CEF_HELPER_BINARY_NAME} (first run)…\n`);
+  await run(
+    ["swift", "build", "-c", configuration, "--product", CEF_HELPER_BINARY_NAME],
+    resolve(repoRoot, "swift"),
+    appkitBuildEnv(),
+  );
+  const out = resolve(buildDir, CEF_HELPER_BINARY_NAME);
+  return existsSync(out) ? out : undefined;
+}
+
 function backendBuildHint(backend: Backend): string {
   return backend === "gtk"
     ? "`zig build`"