automify 0.1.8 → 0.1.10

package/README.md

@@ -14,14 +14,14 @@ Computer use surfaces:
 | -------------- | --------------------------- | ----------------------------------------------------------- |
 | Browser        | `automify.browser()`        | Playwright browser with screenshots and actions             |
 | Desktop        | `automify.localComputer()`  | Native desktop on the current macOS, Windows, or Linux host |
-| Docker desktop | `automify.dockerComputer()` | Linux desktop inside a Docker container                     |
+| Docker desktop | `automify.dockerComputer()` | Linux desktop inside a running Docker container             |
 
 Command use surfaces:
 
-| Surface    | Factory                | What it does                                         |
-| ---------- | ---------------------- | ---------------------------------------------------- |
-| CLI        | `automify.cli()`       | Terminal automation through model-requested commands |
-| Docker CLI | `automify.dockerCli()` | Containerized terminal automation with shared files  |
+| Surface    | Factory                | What it does                                          |
+| ---------- | ---------------------- | ----------------------------------------------------- |
+| CLI        | `automify.cli()`       | Terminal automation through model-requested commands  |
+| Docker CLI | `automify.dockerCli()` | Containerized terminal automation with running Docker |
 
 OpenAI and Anthropic models are supported, and any other model can be plugged in with a custom provider adapter.
 
@@ -120,12 +120,12 @@ const browser = await automify.browser({
 });
 
 try {
-  const run = await browser.do("Extract the support email.", {
+  const run = await browser.do("Summarize what you see on the page.", {
     // Optional: structured result shape.
-    output: jsonOutput("support_contact", { email: "string" })
+    output: jsonOutput("page_summary", { title: "string", summary: "string" })
   });
 
-  console.log(run.parsed.email);
+  console.log(run.parsed.title, run.parsed.summary);
 } finally {
   await browser.close();
 }
@@ -147,7 +147,7 @@ const cli = automify.cli({
 await cli.do("Run the tests and summarize failures");
 ```
 
-Use Docker CLI when command execution should happen inside an isolated container:
+Use Docker CLI when command execution should happen inside an isolated container. Docker must be installed and running before you create the adapter:
 
 ```js
 import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
@@ -208,11 +208,14 @@ winget install --id Microsoft.VisualStudio.2022.BuildTools --exact --override "-
 winget install --id Kitware.CMake --exact --source winget
 
 # macOS: Xcode Command Line Tools plus CMake on PATH.
+# If Homebrew is not installed, install it first:
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
 xcode-select --install
 brew install cmake
 
 # Debian/Ubuntu Linux.
-sudo apt-get install -y build-essential cmake libxtst-dev libpng++-dev
+sudo apt-get install -y git build-essential cmake pkg-config libx11-dev libxtst-dev libpng++-dev
 
 # Fedora Linux.
 sudo dnf install -y gcc-c++ make cmake libXtst-devel libpng-devel
@@ -221,7 +224,9 @@ sudo dnf install -y gcc-c++ make cmake libXtst-devel libpng-devel
 sudo pacman -S --needed base-devel cmake libxtst libpng
 ```
 
-On headless Linux hosts, also install `xvfb` unless you manage `DISPLAY` yourself. On macOS and Windows, `cmake --version` must work in the terminal where you run `npx automify-install-desktop`. On Windows, the VS Code CMake Tools extension is not enough by itself, and Visual Studio 2026 is not currently recognized by the native build chain used by nut.js.
+On Linux, install the full package list before running `npx automify-install-desktop`; the installer checks for command-line build tools but does not verify every native library package. On headless Linux hosts, also install `xvfb` unless you manage `DISPLAY` yourself. On macOS, install Homebrew first if `brew` is not available, then install CMake with `brew install cmake`. On macOS and Windows, `cmake --version` must work in the terminal where you run `npx automify-install-desktop`. On Windows, the VS Code CMake Tools extension is not enough by itself, and Visual Studio 2026 is not currently recognized by the native build chain used by nut.js.
+
+`npx automify-install-desktop` stores the compiled desktop runtime outside `node_modules` in a long-term cache, so normal `npm update` runs do not remove it. If a later `npm install` or `npm update` detects that a previously installed desktop runtime no longer matches the current platform, CPU architecture, Node ABI, or pinned nut.js/libnut revisions, Automify rebuilds it automatically during `postinstall`. Default cache roots are `%LOCALAPPDATA%\automify\desktop-runtime` on Windows, `~/Library/Caches/automify/desktop-runtime` on macOS, and `${XDG_CACHE_HOME:-~/.cache}/automify/desktop-runtime` on Linux. Override with `AUTOMIFY_DESKTOP_RUNTIME_DIR`; disable auto-rebuild with `AUTOMIFY_SKIP_DESKTOP_AUTO_REBUILD=1`.
 
 ```js
 import { initAutomify } from "automify";
@@ -246,7 +251,7 @@ try {
 }
 ```
 
-For isolated Linux desktop computer use, use Docker. `dockerComputer()` can run from a macOS, Windows, or Linux host with Docker, but the desktop it controls inside the container is Linux. Docker desktop does not use `automify-install-desktop`; it needs Docker and an initial app command:
+For isolated Linux desktop computer use, use Docker. `dockerComputer()` can run from a macOS, Windows, or Linux host with Docker installed and running, but the desktop it controls inside the container is Linux. Docker desktop does not use `automify-install-desktop`; it needs a running Docker daemon and an initial app command:
 
 ```js
 import { initAutomify } from "automify";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "automify",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "AI computer use for browser, CLI, and desktop in Node.js.",
   "homepage": "https://aldovincenti.github.io/automify",
   "bugs": {
@@ -36,7 +36,7 @@
     "SECURITY.md"
   ],
   "scripts": {
-    "postinstall": "node scripts/install-browser.js",
+    "postinstall": "node scripts/install-browser.js && node scripts/install-desktop-if-needed.js",
     "install:desktop": "node scripts/install-desktop.js",
     "docs:arguments": "node scripts/generate-argument-reference.js",
     "test": "node --test test/*.test.js",

package/scripts/install-browser.js

@@ -9,6 +9,7 @@ if (process.env.AUTOMIFY_SKIP_BROWSER_INSTALL === "1" || process.env.PLAYWRIGHT_
 }
 
 const playwrightCli = join(dirname(require.resolve("playwright")), "cli.js");
+console.log("Automify: installing Playwright browser...");
 const result = spawnSync(process.execPath, [playwrightCli, "install", "chromium"], {
   cwd: process.cwd(),
   stdio: "inherit"

package/scripts/install-desktop-if-needed.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  desktopRuntimeDir,
+  desktopRuntimeIsInstalled,
+  desktopRuntimeKey,
+  findDesktopRuntimeManifests
+} from "../src/lib/desktop-runtime.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+
+if (process.env.AUTOMIFY_SKIP_DESKTOP_INSTALL === "1" || process.env.AUTOMIFY_SKIP_DESKTOP_AUTO_REBUILD === "1") {
+  process.exit(0);
+}
+
+if (desktopRuntimeIsInstalled()) {
+  process.exit(0);
+}
+
+const existingManifests = findDesktopRuntimeManifests();
+const legacyNodeModulesRuntime = existsSync(join(root, "node_modules", "@nut-tree", "nut-js", "package.json"));
+
+if (existingManifests.length === 0 && !legacyNodeModulesRuntime) {
+  process.exit(0);
+}
+
+console.log("Automify desktop runtime was previously installed but is not compatible with this environment.");
+console.log(`Rebuilding desktop runtime cache: ${desktopRuntimeKey()}`);
+console.log(`Runtime directory: ${desktopRuntimeDir()}`);
+
+const result = spawnSync(process.execPath, [join(__dirname, "install-desktop.js")], {
+  cwd: root,
+  env: process.env,
+  stdio: "inherit"
+});
+
+process.exit(result.status ?? 1);

package/scripts/install-desktop.js

@@ -4,6 +4,15 @@ import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } fr
 import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import {
+  DESKTOP_RUNTIME_MANIFEST,
+  desktopRuntimeDir,
+  desktopRuntimeKey,
+  desktopRuntimeManifest,
+  desktopRuntimeNodeModules,
+  desktopRuntimeRefs
+} from "../src/lib/desktop-runtime.js";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const root = resolve(__dirname, "..");
 const buildRoot = process.env.AUTOMIFY_DESKTOP_BUILD_DIR
@@ -12,12 +21,10 @@ const buildRoot = process.env.AUTOMIFY_DESKTOP_BUILD_DIR
 const nutSource = join(buildRoot, "nut.js");
 const libnutSource = join(buildRoot, "libnut-core");
 const macPermissionsSource = join(buildRoot, "node-mac-permissions");
-const refs = {
-  nut: process.env.AUTOMIFY_DESKTOP_NUT_REF ?? "e413fa1f19a19c4631812e4e1eaf47aa732b5cbe",
-  libnutCore: process.env.AUTOMIFY_DESKTOP_LIBNUT_CORE_REF ?? "6bbe5825f1123bcd740117ca932c8b1c6cffb48c",
-  macPermissions: process.env.AUTOMIFY_DESKTOP_MAC_PERMISSIONS_REF ?? "6b6ddee993ddce5071b637e42f6ee1434150d0bb"
-};
-const nodeModules = join(root, "node_modules");
+const refs = desktopRuntimeRefs();
+const runtimeDir = desktopRuntimeDir();
+const runtimeNodeModules = desktopRuntimeNodeModules();
+const nodeModules = runtimeNodeModules;
 const nutScope = join(nodeModules, "@nut-tree");
 const platformPackageName = `@nut-tree/libnut-${process.platform}`;
 const platformPackageDir = join(nutScope, `libnut-${process.platform}`);
@@ -27,6 +34,8 @@ const runtimeDependencies = ["jimp@1.6.1", "node-abort-controller@3.1.1", "clipb
 
 console.log("Building official nut.js from source.");
 console.log(`Build directory: ${buildRoot}`);
+console.log(`Runtime directory: ${runtimeDir}`);
+console.log(`Runtime key: ${desktopRuntimeKey()}`);
 console.log(`nut.js ref: ${refs.nut}`);
 console.log(`libnut-core ref: ${refs.libnutCore}`);
 if (process.platform === "darwin") {
@@ -36,6 +45,8 @@ if (process.platform === "darwin") {
 checkBuildPrerequisites();
 
 mkdirSync(buildRoot, { recursive: true });
+mkdirSync(runtimeDir, { recursive: true });
+writeRuntimePackageJson();
 cloneOrPull("https://github.com/nut-tree/libnut-core.git", libnutSource, refs.libnutCore);
 cloneOrPull("https://github.com/nut-tree/nut.js.git", nutSource, refs.nut);
 if (process.platform === "darwin") {
@@ -69,7 +80,7 @@ writeLibnutImportBridge();
 runPnpm(["--filter", "@nut-tree/nut-js", "run", "compile"], { cwd: nutSource });
 patchNutJimpCompatibility();
 
-run("npm", ["install", "--no-save", ...runtimeDependencies], { cwd: root });
+run("npm", ["install", "--no-save", ...runtimeDependencies], { cwd: runtimeDir });
 
 installWorkspacePackage(join(nutSource, "core", "shared"), join(nutScope, "shared"));
 installWorkspacePackage(join(nutSource, "core", "provider-interfaces"), join(nutScope, "provider-interfaces"));
@@ -81,9 +92,20 @@ if (process.platform === "darwin") {
   installWorkspacePackage(macPermissionsSource, macPermissionsPackageDir);
 }
 
-run("node", ["-e", "import('@nut-tree/nut-js').then(() => console.log('nut.js source build import ok'))"], {
-  cwd: root
-});
+writeRuntimeManifest();
+run(
+  "node",
+  [
+    "-e",
+    `const { createRequire } = require("node:module");
+const { join } = require("node:path");
+const runtimeDir = process.argv[1];
+createRequire(join(runtimeDir, "automify-desktop-runtime.cjs"))("@nut-tree/nut-js");
+console.log("nut.js source build import ok");`,
+    runtimeDir
+  ],
+  { cwd: root }
+);
 
 function cloneOrPull(repo, target, ref) {
   if (existsSync(join(target, ".git"))) {
@@ -132,7 +154,8 @@ function checkBuildPrerequisites() {
   if (process.platform === "darwin") {
     console.error("macOS: install Xcode Command Line Tools with `xcode-select --install` and install CMake.");
   } else if (process.platform === "linux") {
-    console.error("Linux: install CMake, a C/C++ compiler, libxtst-dev, and libpng++-dev.");
+    console.error("Linux: install git, build-essential, cmake, pkg-config, libx11-dev, libxtst-dev, and libpng++-dev.");
+    console.error("The Linux installer does not verify every native library package before building.");
   } else if (process.platform === "win32") {
     console.error("Windows: install CMake and Visual Studio 2022 C++ Build Tools.");
     console.error("Make sure the `Desktop development with C++` workload is installed.");
@@ -159,22 +182,26 @@ function resolveCommand(command) {
 function commandCandidates(command) {
   const candidates = [];
 
+  const npmCli = npmCliCandidate(command);
+  if (npmCli) candidates.push(npmCli);
+
   if (process.platform === "win32" && ["npm", "npx"].includes(command)) {
     candidates.push({ command: `${command}.cmd`, args: [] });
   }
 
-  const npmCli = npmCliCandidate(command);
-  if (npmCli) candidates.push(npmCli);
-
   candidates.push({ command, args: [] });
   return candidates;
 }
 
 function npmCliCandidate(command) {
-  if (!["npm", "npx"].includes(command) || !process.env.npm_execpath) return null;
-  if (command === "npm") return { command: process.execPath, args: [process.env.npm_execpath] };
+  if (!["npm", "npx"].includes(command)) return null;
+
+  const npmExecPath =
+    process.env.npm_execpath ?? join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js");
+  if (!existsSync(npmExecPath)) return null;
+  if (command === "npm") return { command: process.execPath, args: [npmExecPath] };
 
-  const npxExecPath = join(dirname(process.env.npm_execpath), "npx-cli.js");
+  const npxExecPath = join(dirname(npmExecPath), "npx-cli.js");
   if (!existsSync(npxExecPath)) return null;
   return { command: process.execPath, args: [npxExecPath] };
 }
@@ -403,6 +430,35 @@ function installWorkspacePackage(source, target) {
   });
 }
 
+function writeRuntimePackageJson() {
+  writeText(
+    join(runtimeDir, "package.json"),
+    `${JSON.stringify(
+      {
+        private: true,
+        name: "automify-desktop-runtime",
+        description: "Persistent native runtime cache for Automify local desktop support."
+      },
+      null,
+      2
+    )}\n`
+  );
+}
+
+function writeRuntimeManifest() {
+  writeText(
+    join(runtimeDir, DESKTOP_RUNTIME_MANIFEST),
+    `${JSON.stringify(
+      {
+        ...desktopRuntimeManifest(),
+        createdAt: new Date().toISOString()
+      },
+      null,
+      2
+    )}\n`
+  );
+}
+
 function run(command, args, options = {}) {
   const result = runResolvedCommand(command, args, {
     cwd: options.cwd ?? root,

package/src/lib/argument-reference.js

@@ -51,7 +51,7 @@ export const argumentReference = [
       "logFile"
     ],
     notes:
-      'Use additionalAptPackages to apt-install Debian packages before commands run. Use preset: "repo" to mount the current workspace at /workspace and allow common repo commands. Use logFile to capture CLI and Docker container events.'
+      'Requires Docker to be installed and running. Use additionalAptPackages to apt-install Debian packages before commands run. Use preset: "repo" to mount the current workspace at /workspace and allow common repo commands. Use logFile to capture CLI and Docker container events.'
   },
   {
     surface: "automify.dockerComputer()",
@@ -66,7 +66,7 @@ export const argumentReference = [
       "logFile"
     ],
     notes:
-      "Creates a Docker-backed Linux desktop runner. Pass startupCommand or desktop.startupCommand to launch the initial app. Use additionalAptPackages to apt-install extra Debian packages. Use logFile to capture automation and Docker desktop events. Explicit container names are locked per name until close()."
+      "Creates a Docker-backed Linux desktop runner and requires Docker to be installed and running. Pass startupCommand or desktop.startupCommand to launch the initial app. Use additionalAptPackages to apt-install extra Debian packages. Use logFile to capture automation and Docker desktop events. Explicit container names are locked per name until close()."
   },
   {
     surface: "automify.localComputer()",
@@ -93,6 +93,6 @@ export const argumentReference = [
       "logFile"
     ],
     notes:
-      "container controls Docker and resource limits; startupCommand or desktop.startupCommand is required; shared/sharedFiles control host file access. Use additionalAptPackages to apt-install extra Debian packages and logFile to capture Docker desktop events."
+      "Requires Docker to be installed and running. container controls Docker and resource limits; startupCommand or desktop.startupCommand is required; shared/sharedFiles control host file access. Use additionalAptPackages to apt-install extra Debian packages and logFile to capture Docker desktop events."
   }
 ];

package/src/lib/desktop-runtime.js

@@ -0,0 +1,135 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export const DESKTOP_RUNTIME_PACKAGE = "@nut-tree/nut-js";
+export const DESKTOP_RUNTIME_MANIFEST = "automify-desktop-runtime.json";
+
+export function desktopRuntimeRefs(env = process.env) {
+  return {
+    nut: env.AUTOMIFY_DESKTOP_NUT_REF ?? "e413fa1f19a19c4631812e4e1eaf47aa732b5cbe",
+    libnutCore: env.AUTOMIFY_DESKTOP_LIBNUT_CORE_REF ?? "6bbe5825f1123bcd740117ca932c8b1c6cffb48c",
+    macPermissions: env.AUTOMIFY_DESKTOP_MAC_PERMISSIONS_REF ?? "6b6ddee993ddce5071b637e42f6ee1434150d0bb"
+  };
+}
+
+export function desktopRuntimeCompatibility(env = process.env) {
+  const refs = desktopRuntimeRefs(env);
+  return {
+    platform: process.platform,
+    arch: process.arch,
+    nodeAbi: process.versions.modules,
+    nutRef: refs.nut,
+    libnutCoreRef: refs.libnutCore,
+    macPermissionsRef: process.platform === "darwin" ? refs.macPermissions : undefined
+  };
+}
+
+export function desktopRuntimeKey(compatibility = desktopRuntimeCompatibility()) {
+  return [
+    compatibility.platform,
+    compatibility.arch,
+    `node-${compatibility.nodeAbi}`,
+    `nut-${shortRef(compatibility.nutRef)}`,
+    `libnut-${shortRef(compatibility.libnutCoreRef)}`,
+    compatibility.macPermissionsRef ? `macperms-${shortRef(compatibility.macPermissionsRef)}` : null
+  ]
+    .filter(Boolean)
+    .join("-");
+}
+
+export function defaultDesktopRuntimeRoot(env = process.env) {
+  if (env.AUTOMIFY_DESKTOP_RUNTIME_DIR) {
+    return resolve(env.AUTOMIFY_DESKTOP_RUNTIME_DIR);
+  }
+
+  if (process.platform === "win32") {
+    return join(env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "automify", "desktop-runtime");
+  }
+
+  if (process.platform === "darwin") {
+    return join(homedir(), "Library", "Caches", "automify", "desktop-runtime");
+  }
+
+  return join(env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "automify", "desktop-runtime");
+}
+
+export function desktopRuntimeDir(env = process.env) {
+  return join(defaultDesktopRuntimeRoot(env), desktopRuntimeKey(desktopRuntimeCompatibility(env)));
+}
+
+export function desktopRuntimeNodeModules(env = process.env) {
+  return join(desktopRuntimeDir(env), "node_modules");
+}
+
+export function desktopRuntimePackageJsonPath(env = process.env) {
+  return join(desktopRuntimeNodeModules(env), "@nut-tree", "nut-js", "package.json");
+}
+
+export function desktopRuntimeManifestPath(env = process.env) {
+  return join(desktopRuntimeDir(env), DESKTOP_RUNTIME_MANIFEST);
+}
+
+export function desktopRuntimeManifest(env = process.env) {
+  return {
+    version: 1,
+    package: DESKTOP_RUNTIME_PACKAGE,
+    runtimeDir: desktopRuntimeDir(env),
+    compatibility: desktopRuntimeCompatibility(env)
+  };
+}
+
+export function readDesktopRuntimeManifest(env = process.env) {
+  const path = desktopRuntimeManifestPath(env);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+export function findDesktopRuntimeManifests(env = process.env) {
+  const root = defaultDesktopRuntimeRoot(env);
+  if (!existsSync(root)) return [];
+
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const runtimeDir = join(root, entry.name);
+      const manifestPath = join(runtimeDir, DESKTOP_RUNTIME_MANIFEST);
+      if (!existsSync(manifestPath)) return null;
+      try {
+        return {
+          runtimeDir,
+          manifestPath,
+          manifest: JSON.parse(readFileSync(manifestPath, "utf8"))
+        };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+export function desktopRuntimeIsInstalled(env = process.env) {
+  const manifest = readDesktopRuntimeManifest(env);
+  return desktopRuntimeManifestMatches(manifest, env) && existsSync(desktopRuntimePackageJsonPath(env));
+}
+
+export function desktopRuntimeManifestMatches(manifest, env = process.env) {
+  if (!manifest || manifest.version !== 1 || manifest.package !== DESKTOP_RUNTIME_PACKAGE) return false;
+
+  const expected = desktopRuntimeCompatibility(env);
+  const actual = manifest.compatibility ?? {};
+  return (
+    actual.platform === expected.platform &&
+    actual.arch === expected.arch &&
+    actual.nodeAbi === expected.nodeAbi &&
+    actual.nutRef === expected.nutRef &&
+    actual.libnutCoreRef === expected.libnutCoreRef &&
+    actual.macPermissionsRef === expected.macPermissionsRef
+  );
+}
+
+function shortRef(ref) {
+  return String(ref ?? "unknown")
+    .replace(/[^a-zA-Z0-9._-]/g, "_")
+    .slice(0, 12);
+}

package/src/lib/local-desktop-computer.js

@@ -1,3 +1,5 @@
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
 import { readFile, unlink } from "node:fs/promises";
 import { execFile, spawn } from "node:child_process";
 import { tmpdir } from "node:os";
@@ -8,6 +10,12 @@ import { promisify } from "node:util";
 import { AutomifyError } from "./errors.js";
 import { acquireAdapterLock } from "./adapter-locks.js";
 import { assertKnownOptions, normalizeLogFile, writeDebugLogFile } from "./runtime.js";
+import {
+  DESKTOP_RUNTIME_PACKAGE,
+  desktopRuntimeDir,
+  desktopRuntimeManifestMatches,
+  desktopRuntimeManifestPath
+} from "./desktop-runtime.js";
 
 const execFileAsync = promisify(execFile);
 const LOCAL_DESKTOP_OPTION_KEYS = new Set([
@@ -448,16 +456,39 @@ async function saveNutImageObject(nut, image, options = {}) {
 }
 
 async function importNut() {
+  let runtimeError;
   try {
-    return await import("@nut-tree/nut-js");
+    const runtimeNut = importNutFromDesktopRuntime();
+    if (runtimeNut) return runtimeNut;
   } catch (error) {
+    runtimeError = error;
+  }
+
+  try {
+    return await import(DESKTOP_RUNTIME_PACKAGE);
+  } catch (error) {
+    const runtimeSuffix = runtimeError ? ` Cached desktop runtime import failed: ${runtimeError.message}` : "";
     throw new AutomifyError(
-      `createLocalDesktopComputer requires the local desktop adapter dependency built from source. ${localDesktopInstallHelp()} After the OS prerequisites are available, run: npx automify-install-desktop`,
+      `createLocalDesktopComputer requires the local desktop adapter dependency built from source. ${localDesktopInstallHelp()} After the OS prerequisites are available, run: npx automify-install-desktop.${runtimeSuffix}`,
       { cause: error }
     );
   }
 }
 
+function importNutFromDesktopRuntime() {
+  const manifestPath = desktopRuntimeManifestPath();
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!desktopRuntimeManifestMatches(manifest)) return null;
+
+  const runtimeRequire = createRequire(join(desktopRuntimeDir(), "automify-desktop-runtime.cjs"));
+  return runtimeRequire(DESKTOP_RUNTIME_PACKAGE);
+}
+
 function normalizeLocalDesktopEnvironment(environment) {
   if (environment == null) return undefined;
   if (typeof environment !== "string" || environment.trim() === "") {
@@ -483,7 +514,7 @@ function localDesktopInstallHelp(platform = process.platform) {
     return "On Windows, install Visual Studio C++ Build Tools and make sure `cmake --version` works, for example after `winget install Kitware.CMake`.";
   }
   if (platform === "linux") {
-    return "On Linux, install the native build tools for your distro: Debian/Ubuntu need `build-essential cmake libxtst-dev libpng++-dev`; Fedora needs `gcc-c++ make cmake libXtst-devel libpng-devel`; Arch needs `base-devel cmake libxtst libpng`. Headless hosts also need `xvfb` unless DISPLAY is managed externally.";
+    return "On Linux, install the native build tools for your distro before running the desktop installer; it does not verify every native library package. Debian/Ubuntu need `git build-essential cmake pkg-config libx11-dev libxtst-dev libpng++-dev`; Fedora needs `gcc-c++ make cmake libXtst-devel libpng-devel`; Arch needs `base-devel cmake libxtst libpng`. Headless hosts also need `xvfb` unless DISPLAY is managed externally.";
   }
   return "Install the native build tools and CMake for this OS.";
 }
@@ -833,15 +864,20 @@ function describePointTransform(x, y, coordinateSpace) {
 
 function buildCoordinateSpace(options, screen) {
   const macOSDisplay = screen.macOSDisplay;
+  const environment = screen.environment ?? options.environment ?? defaultDesktopEnvironment();
   const pixelScale =
     positiveNumber(options.pixelScale) ??
     positiveNumber(macOSDisplay?.backingScaleFactor) ??
-    inferPixelScale(screen, options);
+    inferPixelScale({ ...screen, environment }, options);
   const defaultScale = 1 / pixelScale;
-  const mouseScaleX = scaleRatio(macOSDisplay?.width, screen.displayWidth) ?? defaultScale;
-  const mouseScaleY = scaleRatio(macOSDisplay?.height, screen.displayHeight) ?? defaultScale;
-  const mouseWidth = positiveNumber(macOSDisplay?.width) ?? positiveNumber(screen.displayWidth) * mouseScaleX;
-  const mouseHeight = positiveNumber(macOSDisplay?.height) ?? positiveNumber(screen.displayHeight) * mouseScaleY;
+  const mouseWidth =
+    measuredMouseSize("width", { ...screen, environment, macOSDisplay }) ??
+    scaledDisplaySize(screen.displayWidth, defaultScale);
+  const mouseHeight =
+    measuredMouseSize("height", { ...screen, environment, macOSDisplay }) ??
+    scaledDisplaySize(screen.displayHeight, defaultScale);
+  const mouseScaleX = scaleRatio(mouseWidth, screen.displayWidth) ?? defaultScale;
+  const mouseScaleY = scaleRatio(mouseHeight, screen.displayHeight) ?? defaultScale;
 
   return {
     ...screen,
@@ -856,6 +892,20 @@ function buildCoordinateSpace(options, screen) {
   };
 }
 
+function measuredMouseSize(axis, { environment, macOSDisplay, screenWidth, screenHeight }) {
+  const macOSValue = positiveNumber(macOSDisplay?.[axis]);
+  if (macOSValue) return macOSValue;
+  if (environment === "mac") return null;
+  return positiveNumber(axis === "width" ? screenWidth : screenHeight);
+}
+
+function scaledDisplaySize(size, scale) {
+  const numericSize = positiveNumber(size);
+  const numericScale = positiveNumber(scale);
+  if (!numericSize || !numericScale) return undefined;
+  return numericSize * numericScale;
+}
+
 function scaleRatio(target, source) {
   const numericTarget = positiveNumber(target);
   const numericSource = positiveNumber(source);
@@ -865,18 +915,29 @@ function scaleRatio(target, source) {
 
 function inferPixelScale({ displayWidth, displayHeight, screenWidth, screenHeight }, options = {}) {
   const environment = options.environment ?? defaultDesktopEnvironment();
-  if (environment !== "mac") return 1;
-
   const width = positiveNumber(displayWidth) ?? positiveNumber(screenWidth);
   const height = positiveNumber(displayHeight) ?? positiveNumber(screenHeight);
   if (!width || !height) return 1;
 
+  if (environment !== "mac") {
+    const widthScale = scaleRatio(width, screenWidth);
+    const heightScale = scaleRatio(height, screenHeight);
+    if (widthScale && heightScale && nearlyEqual(widthScale, heightScale)) {
+      return widthScale;
+    }
+    return 1;
+  }
+
   // libnut reports macOS screen size in backing pixels, while CGEvent mouse
   // coordinates use logical points. Built-in Retina displays are 2x here.
   if (width >= 2000 || height >= 1400) return 2;
   return 1;
 }
 
+function nearlyEqual(left, right, epsilon = 0.01) {
+  return Math.abs(left - right) <= epsilon;
+}
+
 function positiveNumber(value) {
   const number = Number(value);
   return Number.isFinite(number) && number > 0 ? number : null;