@slowclap/rezi-native 0.1.0-fork.1

package/README.md

@@ -0,0 +1,38 @@
+# @rezi-ui/native
+
+Rust + `napi-rs` Node-API addon that hosts the Zireael C engine and exposes a minimal, safe JS API for the Node backend.
+
+This package is not used directly by most applications. Install and use `@rezi-ui/node`, which depends on this package.
+
+## Local development
+
+Build the native addon for your host platform:
+
+```bash
+npm -w @rezi-ui/native run build:native
+```
+
+Smoke test:
+
+```bash
+npm -w @rezi-ui/native run test:native:smoke
+```
+
+Vendoring integrity check:
+
+```bash
+npm run check:native-vendor
+```
+
+## Design and constraints
+
+- Engine placement is controlled by `@rezi-ui/node` `executionMode` (`auto` | `worker` | `inline`).
+- `executionMode: "auto"` selects inline when `fpsCap <= 30`, worker otherwise.
+- All buffers across the boundary are caller-owned; binary formats are validated strictly.
+- Native compilation reads `packages/native/vendor/zireael` (not `vendor/zireael`).
+- `packages/native/vendor/VENDOR_COMMIT.txt` must match the `vendor/zireael` gitlink commit.
+
+See:
+
+- [Native addon docs](../../docs/backend/native.md)
+- [Releasing](../../RELEASING.md)

package/index.d.ts

@@ -0,0 +1,97 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export interface DebugStats {
+  totalRecords: bigint;
+  totalDropped: bigint;
+  errorCount: number;
+  warnCount: number;
+  currentRingUsage: number;
+  ringCapacity: number;
+}
+export interface DebugQueryResult {
+  recordsReturned: number;
+  recordsAvailable: number;
+  oldestRecordId: bigint;
+  newestRecordId: bigint;
+  recordsDropped: number;
+}
+export declare function engineDebugEnable(
+  engineId: number,
+  config?: object | undefined | null,
+): number;
+export declare function engineDebugDisable(engineId: number): number;
+export declare function engineDebugQuery(
+  engineId: number,
+  query: object | undefined | null,
+  outHeaders: Uint8Array,
+): DebugQueryResult;
+export declare function engineDebugGetPayload(
+  engineId: number,
+  recordId: bigint,
+  outPayload: Uint8Array,
+): number;
+export declare function engineDebugGetStats(engineId: number): DebugStats;
+export declare function engineDebugExport(engineId: number, outBuf: Uint8Array): number;
+export declare function engineDebugReset(engineId: number): number;
+export interface EngineMetrics {
+  structSize: number;
+  negotiatedEngineAbiMajor: number;
+  negotiatedEngineAbiMinor: number;
+  negotiatedEngineAbiPatch: number;
+  negotiatedDrawlistVersion: number;
+  negotiatedEventBatchVersion: number;
+  frameIndex: bigint;
+  fps: number;
+  bytesEmittedTotal: bigint;
+  bytesEmittedLastFrame: number;
+  dirtyLinesLastFrame: number;
+  dirtyColsLastFrame: number;
+  usInputLastFrame: number;
+  usDrawlistLastFrame: number;
+  usDiffLastFrame: number;
+  usWriteLastFrame: number;
+  eventsOutLastPoll: number;
+  eventsDroppedTotal: number;
+  arenaFrameHighWaterBytes: bigint;
+  arenaPersistentHighWaterBytes: bigint;
+  damageRectsLastFrame: number;
+  damageCellsLastFrame: number;
+  damageFullFrame: boolean;
+}
+export interface TerminalCaps {
+  /** Color mode: 0=unknown, 1=16, 2=256, 3=rgb */
+  colorMode: number;
+  supportsMouse: boolean;
+  supportsBracketedPaste: boolean;
+  supportsFocusEvents: boolean;
+  supportsOsc52: boolean;
+  supportsSyncUpdate: boolean;
+  supportsScrollRegion: boolean;
+  supportsCursorShape: boolean;
+  supportsOutputWaitWritable: boolean;
+  supportsUnderlineStyles: boolean;
+  supportsColoredUnderlines: boolean;
+  supportsHyperlinks: boolean;
+  /** Bitmask of supported SGR attributes */
+  sgrAttrsSupported: number;
+}
+export declare function engineCreate(config?: object | undefined | null): number;
+export declare function engineDestroy(engineId: number): void;
+export declare function engineSubmitDrawlist(engineId: number, drawlist: Uint8Array): number;
+export declare function enginePresent(engineId: number): number;
+export declare function enginePollEvents(
+  engineId: number,
+  timeoutMs: number,
+  out: Uint8Array,
+): number;
+export declare function enginePostUserEvent(
+  engineId: number,
+  tag: number,
+  payload: Uint8Array,
+): number;
+export declare function engineSetConfig(engineId: number, cfg?: object | undefined | null): number;
+export declare function engineGetMetrics(engineId: number): EngineMetrics;
+export declare function engineGetCaps(engineId: number): TerminalCaps;

package/index.js

@@ -0,0 +1,21 @@
+import native from "./loader.cjs";
+
+export const {
+  engineCreate,
+  engineDestroy,
+  engineSubmitDrawlist,
+  enginePresent,
+  enginePollEvents,
+  enginePostUserEvent,
+  engineGetMetrics,
+  engineSetConfig,
+  engineGetCaps,
+  // Debug trace API
+  engineDebugEnable,
+  engineDebugDisable,
+  engineDebugQuery,
+  engineDebugGetPayload,
+  engineDebugGetStats,
+  engineDebugExport,
+  engineDebugReset,
+} = native;

package/loader.cjs

@@ -0,0 +1,134 @@
+const { readdirSync } = require("node:fs");
+
+let native = null;
+let lastErr = null;
+const tried = [];
+
+function tryDynamicRequire(file) {
+  tried.push(file);
+  try {
+    return require(`./${file}`);
+  } catch (err) {
+    lastErr = err;
+    return null;
+  }
+}
+
+if (process.platform === "linux" && process.arch === "x64") {
+  tried.push("rezi_ui_native.linux-x64-gnu.node");
+  try {
+    native = require("./rezi_ui_native.linux-x64-gnu.node");
+  } catch (err) {
+    lastErr = err;
+  }
+
+  if (!native) {
+    tried.push("rezi_ui_native.linux-x64-musl.node");
+    try {
+      native = require("./rezi_ui_native.linux-x64-musl.node");
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+
+  if (!native) {
+    tried.push("rezi_ui_native.linux-x64.node");
+    try {
+      native = require("./rezi_ui_native.linux-x64.node");
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+} else if (process.platform === "linux" && process.arch === "arm64") {
+  tried.push("rezi_ui_native.linux-arm64-gnu.node");
+  try {
+    native = require("./rezi_ui_native.linux-arm64-gnu.node");
+  } catch (err) {
+    lastErr = err;
+  }
+
+  if (!native) {
+    tried.push("rezi_ui_native.linux-arm64-musl.node");
+    try {
+      native = require("./rezi_ui_native.linux-arm64-musl.node");
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+
+  if (!native) {
+    tried.push("rezi_ui_native.linux-arm64.node");
+    try {
+      native = require("./rezi_ui_native.linux-arm64.node");
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+} else if (process.platform === "darwin" && process.arch === "x64") {
+  tried.push("rezi_ui_native.darwin-x64.node");
+  try {
+    native = require("./rezi_ui_native.darwin-x64.node");
+  } catch (err) {
+    lastErr = err;
+  }
+} else if (process.platform === "darwin" && process.arch === "arm64") {
+  tried.push("rezi_ui_native.darwin-arm64.node");
+  try {
+    native = require("./rezi_ui_native.darwin-arm64.node");
+  } catch (err) {
+    lastErr = err;
+  }
+} else if (process.platform === "win32" && process.arch === "x64") {
+  tried.push("rezi_ui_native.win32-x64-msvc.node");
+  try {
+    native = require("./rezi_ui_native.win32-x64-msvc.node");
+  } catch (err) {
+    lastErr = err;
+  }
+} else if (process.platform === "win32" && process.arch === "arm64") {
+  tried.push("rezi_ui_native.win32-arm64-msvc.node");
+  try {
+    native = require("./rezi_ui_native.win32-arm64-msvc.node");
+  } catch (err) {
+    lastErr = err;
+  }
+}
+
+if (!native) {
+  const platformCandidates = [
+    "rezi_ui_native.linux-x64-gnu.node",
+    "rezi_ui_native.linux-x64-musl.node",
+    "rezi_ui_native.linux-x64.node",
+    "rezi_ui_native.linux-arm64-gnu.node",
+    "rezi_ui_native.linux-arm64-musl.node",
+    "rezi_ui_native.linux-arm64.node",
+    "rezi_ui_native.darwin-x64.node",
+    "rezi_ui_native.darwin-arm64.node",
+    "rezi_ui_native.win32-x64-msvc.node",
+    "rezi_ui_native.win32-arm64-msvc.node",
+  ];
+
+  let discovered = [];
+  try {
+    discovered = readdirSync(__dirname).filter((file) => file.endsWith(".node"));
+  } catch {
+    discovered = [];
+  }
+
+  const candidates = ["index.node", "rezi_ui_native.node", ...platformCandidates, ...discovered];
+
+  for (const file of new Set(candidates)) {
+    native = tryDynamicRequire(file);
+    if (native) break;
+  }
+}
+
+if (!native) {
+  const extra =
+    lastErr instanceof Error ? `\n\nLast error:\n${lastErr.stack ?? lastErr.message}` : "";
+  throw new Error(
+    `Failed to load @rezi-ui/native binary. Tried: ${[...new Set(tried)].join(", ")}${extra}`,
+  );
+}
+
+module.exports = native;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@slowclap/rezi-native",
+  "version": "0.1.0-fork.1",
+  "description": "Native addon for Rezi (napi-rs + Zireael engine).",
+  "license": "Apache-2.0",
+  "homepage": "https://rezitui.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RtlZeroMemory/Rezi.git",
+    "directory": "packages/native"
+  },
+  "bugs": {
+    "url": "https://github.com/RtlZeroMemory/Rezi/issues"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "loader.cjs",
+    "index.d.ts",
+    "*.node",
+    "scripts/*.mjs",
+    "package.json"
+  ],
+  "scripts": {
+    "build:native": "node ./scripts/build-native.mjs",
+    "test:native:smoke": "node ./scripts/smoke.mjs"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4"
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.3.0"
+  },
+  "napi": {
+    "name": "rezi_ui_native"
+  }
+}

package/scripts/build-native.mjs

@@ -0,0 +1,487 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+
+function splitPathList(value, delim) {
+  return value
+    .split(delim)
+    .map((p) => p.trim().replace(/^"+|"+$/g, ""))
+    .filter(Boolean);
+}
+
+function envHasLib(env, libName) {
+  if (process.platform !== "win32") return true;
+  const libPath = env.LIB;
+  if (typeof libPath !== "string" || libPath.length === 0) return false;
+  for (const dir of splitPathList(libPath, ";")) {
+    if (existsSync(join(dir, libName))) return true;
+  }
+  return false;
+}
+
+function parseCmdSetOutput(output) {
+  const next = {};
+  for (const raw of output.split(/\r?\n/)) {
+    const line = raw.trimEnd();
+    if (line.length === 0) continue;
+    const idx = line.indexOf("=");
+    if (idx <= 0) continue;
+    const key = line.slice(0, idx);
+    // cmd.exe prints internal per-drive cwd entries like `=C:=C:\...`.
+    if (key.startsWith("=")) continue;
+    next[key] = line.slice(idx + 1);
+  }
+  return next;
+}
+
+function runBatchAndGetEnv(batchFile, batchArgs, env) {
+  const args = Array.isArray(batchArgs) ? batchArgs : [];
+
+  // Avoid nested quoting issues between Node/Windows argument escaping and cmd.exe parsing
+  // by writing a temporary .cmd file. This keeps the `call "C:\\path with spaces\\..."` intact.
+  const scriptPath = join(
+    tmpdir(),
+    `rezi-ui-native-msvc-env-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.cmd`,
+  );
+  const script = `@echo off\r\ncall "${batchFile}" ${args.join(" ")}\r\nset\r\n`;
+  writeFileSync(scriptPath, script, { encoding: "utf8" });
+
+  try {
+    const out = execFileSync("cmd.exe", ["/d", "/s", "/c", scriptPath], { encoding: "utf8", env });
+    return parseCmdSetOutput(out);
+  } finally {
+    rmSync(scriptPath, { force: true });
+  }
+}
+
+function findVswhere() {
+  const pf86 = process.env["ProgramFiles(x86)"];
+  const pf = process.env.ProgramFiles;
+  const candidates = [
+    pf86 ? join(pf86, "Microsoft Visual Studio", "Installer", "vswhere.exe") : null,
+    pf ? join(pf, "Microsoft Visual Studio", "Installer", "vswhere.exe") : null,
+  ].filter(Boolean);
+  for (const p of candidates) {
+    if (p && existsSync(p)) return p;
+  }
+  return null;
+}
+
+function tryGetVisualStudioInstallPath(env) {
+  const vswhere = findVswhere();
+  if (!vswhere) return null;
+  try {
+    const out = execFileSync(
+      vswhere,
+      [
+        "-latest",
+        "-products",
+        "*",
+        "-requires",
+        "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
+        "-property",
+        "installationPath",
+      ],
+      { encoding: "utf8", env },
+    );
+    const installPath = out.trim();
+    return installPath.length > 0 ? installPath : null;
+  } catch {
+    return null;
+  }
+}
+
+function getMsvcArchFromRustTarget(hostTargetTriple) {
+  if (typeof hostTargetTriple !== "string") return "x64";
+  if (hostTargetTriple.startsWith("x86_64-")) return "x64";
+  if (hostTargetTriple.startsWith("i686-")) return "x86";
+  if (hostTargetTriple.startsWith("aarch64-")) return "arm64";
+  return "x64";
+}
+
+function getMsvcHostArch() {
+  if (process.arch === "x64") return "x64";
+  if (process.arch === "arm64") return "arm64";
+  if (process.arch === "ia32") return "x86";
+  return "x64";
+}
+
+function compareSemverDirs(a, b) {
+  // Windows SDK folders look like `10.0.22621.0`. Compare numerically.
+  const pa = a.split(".").map((n) => Number(n));
+  const pb = b.split(".").map((n) => Number(n));
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const da = pa[i] ?? 0;
+    const db = pb[i] ?? 0;
+    if (da !== db) return da - db;
+  }
+  return 0;
+}
+
+function tryGetLatestWindowsSdkVersion(sdkRoot) {
+  const libRoot = join(sdkRoot, "Lib");
+  if (!existsSync(libRoot)) return null;
+
+  try {
+    const dirs = readdirSync(libRoot, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && /^\d+\.\d+\.\d+\.\d+$/.test(d.name))
+      .map((d) => d.name)
+      .sort(compareSemverDirs);
+    return dirs.length > 0 ? dirs[dirs.length - 1] : null;
+  } catch {
+    return null;
+  }
+}
+
+function withWindowsSdkEnv(env, hostTargetTriple) {
+  if (process.platform !== "win32") return env;
+
+  const arch = getMsvcArchFromRustTarget(hostTargetTriple);
+  const pf86 = env["ProgramFiles(x86)"] ?? process.env["ProgramFiles(x86)"];
+  const sdkRoot =
+    typeof pf86 === "string" && pf86.length > 0
+      ? join(pf86, "Windows Kits", "10")
+      : join("C:\\", "Program Files (x86)", "Windows Kits", "10");
+
+  const sdkVersion = tryGetLatestWindowsSdkVersion(sdkRoot);
+  if (!sdkVersion) return env;
+
+  const libUcrt = join(sdkRoot, "Lib", sdkVersion, "ucrt", arch);
+  const libUm = join(sdkRoot, "Lib", sdkVersion, "um", arch);
+  const incRoot = join(sdkRoot, "Include", sdkVersion);
+  const incUcrt = join(incRoot, "ucrt");
+  const incShared = join(incRoot, "shared");
+  const incUm = join(incRoot, "um");
+  const incWinrt = join(incRoot, "winrt");
+  const incCppWinrt = join(incRoot, "cppwinrt");
+  const binVersioned = join(sdkRoot, "Bin", sdkVersion, arch);
+  const binFallback = join(sdkRoot, "Bin", arch);
+
+  const next = { ...env };
+
+  // SDK variables are not strictly required for linking, but setting them helps
+  // downstream tools (rc.exe, mt.exe, and various build scripts) behave.
+  if (typeof next.WindowsSdkDir !== "string" || next.WindowsSdkDir.length === 0) {
+    next.WindowsSdkDir = `${sdkRoot}\\`;
+  }
+  if (typeof next.WindowsSDKVersion !== "string" || next.WindowsSDKVersion.length === 0) {
+    next.WindowsSDKVersion = `${sdkVersion}\\`;
+  }
+
+  const addTo = (key, paths) => {
+    const current = typeof next[key] === "string" ? next[key] : "";
+    const parts = current.length > 0 ? splitPathList(current, ";") : [];
+    const seen = new Set(parts.map((p) => p.toLowerCase()));
+    for (const p of paths) {
+      if (!p || !existsSync(p)) continue;
+      const lower = p.toLowerCase();
+      if (seen.has(lower)) continue;
+      parts.push(p);
+      seen.add(lower);
+    }
+    next[key] = parts.join(";");
+  };
+
+  addTo("LIB", [libUcrt, libUm]);
+  addTo("INCLUDE", [incUcrt, incShared, incUm, incWinrt, incCppWinrt]);
+  addTo("PATH", [binVersioned, binFallback]);
+
+  return next;
+}
+
+function withMsvcDevEnv(env, hostTargetTriple) {
+  if (process.platform !== "win32") return env;
+
+  // If the environment already has the MSVC/SDK lib paths, don't mutate it.
+  if (envHasLib(env, "msvcrt.lib") && envHasLib(env, "kernel32.lib")) return env;
+
+  const vsInstallPath = tryGetVisualStudioInstallPath(env);
+  if (!vsInstallPath) return env;
+
+  const vsDevCmd = join(vsInstallPath, "Common7", "Tools", "VsDevCmd.bat");
+  const vcvars64 = join(vsInstallPath, "VC", "Auxiliary", "Build", "vcvars64.bat");
+  const batchFile = existsSync(vsDevCmd) ? vsDevCmd : existsSync(vcvars64) ? vcvars64 : null;
+  if (!batchFile) return env;
+
+  const targetArch = getMsvcArchFromRustTarget(hostTargetTriple);
+  const hostArch = getMsvcHostArch();
+
+  try {
+    const batchArgs = batchFile.toLowerCase().endsWith("vsdevcmd.bat")
+      ? ["-no_logo", `-arch=${targetArch}`, `-host_arch=${hostArch}`]
+      : [];
+    const next = runBatchAndGetEnv(batchFile, batchArgs, env);
+    return envHasLib(next, "msvcrt.lib") ? next : env;
+  } catch {
+    return env;
+  }
+}
+
+function spawnNpm(args, options) {
+  // Prefer the npm CLI path provided by npm itself when running under `npm run`.
+  // This avoids shell differences on Windows (cmd.exe vs bash) and PATH issues.
+  const npmExecPath = process.env.npm_execpath;
+  if (npmExecPath && existsSync(npmExecPath)) {
+    return spawnSync(process.execPath, [npmExecPath, ...args], options);
+  }
+
+  const candidates = process.platform === "win32" ? ["npm", "npm.cmd"] : ["npm"];
+  let last = null;
+  for (const cmd of candidates) {
+    const res = spawnSync(cmd, args, options);
+    last = res;
+    if (!res.error) return res;
+  }
+  return last;
+}
+
+function canRunCargo(env) {
+  try {
+    execFileSync("cargo", ["--version"], { stdio: "ignore", env });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getCargoExePath(env) {
+  const cargoHome =
+    typeof env.CARGO_HOME === "string" && env.CARGO_HOME.length > 0
+      ? env.CARGO_HOME
+      : typeof env.USERPROFILE === "string" && env.USERPROFILE.length > 0
+        ? join(env.USERPROFILE, ".cargo")
+        : null;
+  if (!cargoHome) return null;
+  const cargoBin = join(cargoHome, "bin");
+  const cargoExe =
+    process.platform === "win32" ? join(cargoBin, "cargo.exe") : join(cargoBin, "cargo");
+  return existsSync(cargoExe) ? cargoExe : null;
+}
+
+function ensureCargoOnPath(env) {
+  if (canRunCargo(env)) return env;
+
+  const cargoExe = getCargoExePath(env);
+  if (!cargoExe) {
+    const hint =
+      process.platform === "win32"
+        ? [
+            "@rezi-ui/native: cargo not found (Rust toolchain missing).",
+            "",
+            "Install Rust (includes cargo) via rustup: https://rustup.rs/",
+            "Then reopen your terminal and verify:",
+            "  cargo --version",
+            "  rustc --version",
+          ].join("\n")
+        : [
+            "@rezi-ui/native: cargo not found (Rust toolchain missing).",
+            "",
+            "Install Rust via rustup: https://rustup.rs/",
+            "Then verify: cargo --version",
+          ].join("\n");
+    process.stderr.write(`${hint}\n`);
+    process.exit(1);
+  }
+
+  const next = { ...env };
+  const cargoBin = join(cargoExe, "..");
+  const currentPath = typeof next.PATH === "string" ? next.PATH : "";
+  next.PATH = `${cargoBin}${delimiter}${currentPath}`;
+  if (canRunCargo(next)) return next;
+
+  process.stderr.write(
+    `${[
+      "@rezi-ui/native: cargo exists on disk but still isn't runnable from this npm script environment.",
+      "",
+      `Found cargo at: ${cargoExe}`,
+      "",
+      "Try running the build from a fresh terminal, or set PATH so it includes your Rust bin directory.",
+      "On Windows with rustup, that's usually:",
+      `  ${join(String(env.USERPROFILE ?? "C:\\Users\\<you>"), ".cargo", "bin")}`,
+    ].join("\n")}\n`,
+  );
+  process.exit(1);
+}
+
+function withRustToolchainOnPath(env) {
+  const next = { ...env };
+  const currentPath = typeof next.PATH === "string" ? next.PATH : "";
+
+  // When npm is configured to run scripts via Git Bash on Windows, PATH may not
+  // include the Rust toolchain even if it exists on disk. The napi CLI shells
+  // out to `cargo`, so ensure it's discoverable.
+  const cargoHome =
+    typeof next.CARGO_HOME === "string" && next.CARGO_HOME.length > 0
+      ? next.CARGO_HOME
+      : typeof next.USERPROFILE === "string" && next.USERPROFILE.length > 0
+        ? join(next.USERPROFILE, ".cargo")
+        : null;
+
+  if (cargoHome) {
+    const cargoBin = join(cargoHome, "bin");
+    const cargoExe =
+      process.platform === "win32" ? join(cargoBin, "cargo.exe") : join(cargoBin, "cargo");
+    if (existsSync(cargoExe) && !currentPath.toLowerCase().includes(cargoBin.toLowerCase())) {
+      next.PATH = `${cargoBin}${delimiter}${currentPath}`;
+    }
+  }
+
+  // Ensure `napi` can find cargo even if it shells out through cmd.exe with a
+  // different PATH resolution behavior.
+  if (typeof next.CARGO !== "string" || next.CARGO.length === 0) {
+    const cargoExe = getCargoExePath(next);
+    if (cargoExe) next.CARGO = cargoExe;
+  }
+
+  return next;
+}
+
+function buildWithCargoDirectly(env, host) {
+  const cargoExe = getCargoExePath(env) ?? "cargo";
+  try {
+    execFileSync(cargoExe, ["build", "--release", "--target", host], { stdio: "inherit", env });
+  } catch (err) {
+    if (process.platform === "win32") {
+      process.stderr.write(
+        `${[
+          "",
+          "@rezi-ui/native: cargo build failed on Windows.",
+          "If you see linker errors like `LNK1104: cannot open file 'msvcrt.lib'` or missing headers like `stdint.h`,",
+          "install Visual Studio Build Tools (MSVC v143 + Windows 10/11 SDK) and run the build from a VS Developer shell.",
+          "",
+        ].join("\n")}\n`,
+      );
+    }
+    throw err;
+  }
+
+  const crateName = "rezi_ui_native";
+  const targetDir = join(process.cwd(), "target", host, "release");
+  const built =
+    process.platform === "win32"
+      ? join(targetDir, `${crateName}.dll`)
+      : process.platform === "darwin"
+        ? join(targetDir, `lib${crateName}.dylib`)
+        : join(targetDir, `lib${crateName}.so`);
+
+  if (!existsSync(built)) {
+    throw new Error(`@rezi-ui/native: cargo build succeeded but output was not found: ${built}`);
+  }
+
+  // Node loads addons as .node (they are native shared libraries under the hood).
+  // Keep both filenames as candidates for the JS loader.
+  copyFileSync(built, join(process.cwd(), "rezi_ui_native.node"));
+  copyFileSync(built, join(process.cwd(), "index.node"));
+}
+
+function getHostTargetTriple() {
+  let out;
+  try {
+    out = execFileSync("rustc", ["-vV"], { encoding: "utf8" });
+  } catch (err) {
+    const hint =
+      process.platform === "win32"
+        ? "Install Rust from https://rustup.rs/ (or ensure `rustc.exe` is on PATH)."
+        : "Install Rust via rustup (https://rustup.rs/) and ensure `rustc` is on PATH.";
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`@rezi-ui/native: rustc not found or not runnable.\n${hint}\n\n${detail}`);
+  }
+  const line = out
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l.startsWith("host: "));
+  if (!line) throw new Error("Failed to determine Rust host triple from `rustc -vV`");
+  return line.slice("host: ".length).trim();
+}
+
+let host;
+try {
+  host = getHostTargetTriple();
+} catch (err) {
+  process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+}
+
+const scriptEnv = ensureCargoOnPath(
+  withWindowsSdkEnv(withMsvcDevEnv(withRustToolchainOnPath(process.env), host), host),
+);
+
+// @napi-rs/cli parses Cargo.toml by running `cargo metadata` through cmd.exe on Windows.
+// Some environments can run `cargo` fine from PowerShell, but cmd.exe fails to resolve it.
+// Use a direct cargo build path on Windows to avoid that failure mode.
+if (process.platform === "win32") {
+  try {
+    buildWithCargoDirectly(scriptEnv, host);
+  } catch (err) {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+  }
+} else {
+  const res = spawnNpm(
+    ["exec", "--", "napi", "build", "--platform", "--release", "--target", host, "--js", "false"],
+    {
+      stdio: "inherit",
+      env: scriptEnv,
+    },
+  );
+
+  if (res?.error) {
+    const detail = res.error instanceof Error ? res.error.message : String(res.error);
+    process.stderr.write(`@rezi-ui/native: failed to invoke npm.\n\n${detail}\n`);
+    process.exit(1);
+  }
+
+  if (res.status !== 0) {
+    process.exit(res.status ?? 1);
+  }
+}
+
+if (existsSync("./index.d.ts")) {
+  const biomeArgs = ["format", "index.d.ts", "--write"];
+
+  // On Windows, npm may be configured to run scripts via Git Bash, which can end up
+  // selecting the POSIX `.bin/biome` shim that relies on `node` being resolvable via
+  // a POSIX-style PATH. Run the Biome entrypoint with Node directly to avoid that.
+  const fmt =
+    process.platform === "win32"
+      ? (() => {
+          const initCwd = process.env.INIT_CWD;
+          const roots = [
+            typeof initCwd === "string" && initCwd.length > 0 ? initCwd : null,
+            join(process.cwd(), "..", ".."),
+          ].filter(Boolean);
+
+          for (const root of roots) {
+            const biomeEntrypoint = join(root, "node_modules", "@biomejs", "biome", "bin", "biome");
+            if (existsSync(biomeEntrypoint)) {
+              return spawnSync(process.execPath, [biomeEntrypoint, ...biomeArgs], {
+                stdio: "inherit",
+                env: scriptEnv,
+              });
+            }
+          }
+
+          // Fall back to `npm exec` if the entrypoint isn't where we expect.
+          return spawnNpm(["exec", "--", "biome", ...biomeArgs], {
+            stdio: "inherit",
+            env: scriptEnv,
+          });
+        })()
+      : spawnNpm(["exec", "--", "biome", ...biomeArgs], {
+          stdio: "inherit",
+          env: scriptEnv,
+        });
+  if (fmt?.error) {
+    const detail = fmt.error instanceof Error ? fmt.error.message : String(fmt.error);
+    process.stderr.write(
+      `@rezi-ui/native: warning: failed to invoke npm for formatting index.d.ts (continuing).\n\n${detail}\n`,
+    );
+  }
+  if (fmt.status !== 0) {
+    process.stderr.write(
+      `@rezi-ui/native: warning: biome format returned non-zero status (${fmt.status ?? "unknown"}); continuing.\n`,
+    );
+  }
+}

package/scripts/smoke-worker.mjs

@@ -0,0 +1,36 @@
+import { parentPort, workerData } from "node:worker_threads";
+import {
+  engineDebugDisable,
+  enginePostUserEvent,
+  enginePresent,
+  engineSetConfig,
+} from "../index.js";
+
+const { engineId } = workerData;
+
+if (!parentPort) {
+  throw new Error("smoke-worker: missing parentPort");
+}
+
+if (workerData?.phase === "loadOnly") {
+  parentPort.postMessage({ phase: "loadOnly" });
+  parentPort.close();
+} else {
+  const res1 = enginePresent(engineId);
+  const res2 = enginePostUserEvent(engineId, 123, new Uint8Array([1, 2, 3]));
+  const res3 = engineSetConfig(engineId, { targetFps: 33 });
+  const res4 = engineDebugDisable(engineId);
+  parentPort.postMessage({
+    phase: "alive",
+    present: res1,
+    postUserEvent: res2,
+    setConfig: res3,
+    debugDisable: res4,
+  });
+
+  parentPort.on("message", (msg) => {
+    if (msg?.type !== "afterDestroy") return;
+    const res = enginePostUserEvent(engineId, 456, new Uint8Array([9]));
+    parentPort.postMessage({ phase: "destroyed", postUserEvent: res });
+  });
+}

package/scripts/smoke.mjs

@@ -0,0 +1,337 @@
+import { Worker } from "node:worker_threads";
+import {
+  engineCreate,
+  engineDebugDisable,
+  engineDebugEnable,
+  engineDebugExport,
+  engineDebugGetPayload,
+  engineDebugGetStats,
+  engineDebugQuery,
+  engineDebugReset,
+  engineDestroy,
+  engineGetMetrics,
+  enginePostUserEvent,
+  enginePresent,
+  engineSetConfig,
+} from "../index.js";
+
+const ZR_OK = 0;
+const ZR_ERR_INVALID_ARGUMENT = -1;
+const ZR_ERR_PLATFORM = -6;
+const INVALID_ARG_ERROR_RE = /INVALID_ARGUMENT|InvalidArg|ZR_ERR_INVALID_ARGUMENT/i;
+
+function assert(cond, msg) {
+  if (!cond) throw new Error(msg);
+}
+
+function assertThrows(fn, pattern, msg) {
+  let threw = false;
+  try {
+    fn();
+  } catch (err) {
+    threw = true;
+    if (pattern) {
+      const detail = err instanceof Error ? err.message : String(err);
+      assert(pattern.test(detail), `${msg}: wrong error detail: ${detail}`);
+    }
+  }
+  assert(threw, `${msg}: expected throw`);
+}
+
+function assertMetricsShape(metrics) {
+  assert(metrics && typeof metrics === "object", "engineGetMetrics must return an object");
+  assert(typeof metrics.frameIndex === "bigint", "metrics.frameIndex must be bigint");
+  assert(typeof metrics.bytesEmittedTotal === "bigint", "metrics.bytesEmittedTotal must be bigint");
+  assert(
+    typeof metrics.arenaFrameHighWaterBytes === "bigint",
+    "metrics.arenaFrameHighWaterBytes must be bigint",
+  );
+  assert(typeof metrics.fps === "number", "metrics.fps must be number");
+  assert(
+    typeof metrics.negotiatedDrawlistVersion === "number",
+    "metrics.negotiatedDrawlistVersion must be number",
+  );
+  assert(
+    typeof metrics.negotiatedEventBatchVersion === "number",
+    "metrics.negotiatedEventBatchVersion must be number",
+  );
+}
+
+function assertDebugStatsShape(stats) {
+  assert(stats && typeof stats === "object", "engineDebugGetStats must return an object");
+  assert(typeof stats.totalRecords === "bigint", "debug stats totalRecords must be bigint");
+  assert(typeof stats.totalDropped === "bigint", "debug stats totalDropped must be bigint");
+  assert(typeof stats.errorCount === "number", "debug stats errorCount must be number");
+  assert(typeof stats.warnCount === "number", "debug stats warnCount must be number");
+  assert(typeof stats.currentRingUsage === "number", "debug stats currentRingUsage must be number");
+  assert(typeof stats.ringCapacity === "number", "debug stats ringCapacity must be number");
+}
+
+function readU64LE(bytes, offset) {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return dv.getBigUint64(offset, true);
+}
+
+async function assertWorkerLoadExitCleanly() {
+  const worker = new Worker(new URL("./smoke-worker.mjs", import.meta.url), {
+    workerData: { phase: "loadOnly" },
+    type: "module",
+  });
+  const exitPromise = new Promise((resolve) => worker.once("exit", resolve));
+
+  const loadResult = await new Promise((resolve, reject) => {
+    const onExit = (code) => reject(new Error(`load-only worker exited with ${code}`));
+    const onError = (err) => reject(err);
+    const onMessage = (msg) => {
+      worker.off("exit", onExit);
+      worker.off("error", onError);
+      resolve(msg);
+    };
+    worker.once("exit", onExit);
+    worker.once("error", onError);
+    worker.once("message", onMessage);
+  });
+
+  assert(loadResult.phase === "loadOnly", "worker load-only phase must complete");
+  const exitCode = await exitPromise;
+  assert(exitCode === 0, `load-only worker must exit cleanly, got: ${String(exitCode)}`);
+}
+
+await assertWorkerLoadExitCleanly();
+
+// Unknown / stale id behavior (result-returning functions).
+assert(
+  enginePresent(0) === ZR_ERR_INVALID_ARGUMENT,
+  "enginePresent(0) must return ZR_ERR_INVALID_ARGUMENT",
+);
+assert(
+  enginePresent(0x7fff_fffe) === ZR_ERR_INVALID_ARGUMENT,
+  "enginePresent(unknown) must return ZR_ERR_INVALID_ARGUMENT",
+);
+assert(
+  engineSetConfig(0, { targetFps: 30 }) === ZR_ERR_INVALID_ARGUMENT,
+  "engineSetConfig(0) must return ZR_ERR_INVALID_ARGUMENT",
+);
+assert(
+  enginePostUserEvent(0, 1, new Uint8Array([1])) === ZR_ERR_INVALID_ARGUMENT,
+  "enginePostUserEvent(0) must return ZR_ERR_INVALID_ARGUMENT",
+);
+assert(
+  engineDebugEnable(0, { enabled: true }) === ZR_ERR_INVALID_ARGUMENT,
+  "engineDebugEnable(0) must return ZR_ERR_INVALID_ARGUMENT",
+);
+assert(
+  engineDebugDisable(0) === ZR_ERR_INVALID_ARGUMENT,
+  "engineDebugDisable(0) must return ZR_ERR_INVALID_ARGUMENT",
+);
+assert(
+  engineDebugExport(0, new Uint8Array(64)) === ZR_ERR_INVALID_ARGUMENT,
+  "engineDebugExport(0) must return ZR_ERR_INVALID_ARGUMENT",
+);
+assert(
+  engineDebugReset(0) === ZR_ERR_INVALID_ARGUMENT,
+  "engineDebugReset(0) must return ZR_ERR_INVALID_ARGUMENT",
+);
+assertThrows(
+  () => engineGetMetrics(0),
+  INVALID_ARG_ERROR_RE,
+  "engineGetMetrics(0) must throw invalid-arg",
+);
+assertThrows(
+  () => engineDebugQuery(0, null, new Uint8Array(40)),
+  INVALID_ARG_ERROR_RE,
+  "engineDebugQuery(0) must throw invalid-arg",
+);
+assertThrows(
+  () => engineDebugGetStats(0),
+  INVALID_ARG_ERROR_RE,
+  "engineDebugGetStats(0) must throw invalid-arg",
+);
+assertThrows(
+  () => engineDebugGetPayload(0, 0n, new Uint8Array(16)),
+  INVALID_ARG_ERROR_RE,
+  "engineDebugGetPayload(0) must throw invalid-arg",
+);
+
+const engineId = engineCreate({});
+
+assert(typeof engineId === "number", "engineCreate must return a number");
+if (engineId === ZR_ERR_PLATFORM || engineId === ZR_ERR_INVALID_ARGUMENT) {
+  process.stdout.write(
+    `native-smoke: SKIP engineCreate() deep checks (engineCreate returned ${engineId}; stdout.isTTY=${String(process.stdout.isTTY)} stdin.isTTY=${String(process.stdin.isTTY)})\n`,
+  );
+  process.exit(0);
+}
+assert(engineId > 0, `engineCreate must return a non-zero engineId, got: ${engineId}`);
+
+assert(
+  engineSetConfig(engineId, null) === ZR_ERR_INVALID_ARGUMENT,
+  "engineSetConfig(null) must return ZR_ERR_INVALID_ARGUMENT",
+);
+assertThrows(
+  () => engineSetConfig(engineId, { plat: 1 }),
+  /plat must be an object/i,
+  "engineSetConfig must reject non-object plat values",
+);
+assertThrows(
+  () => engineSetConfig(engineId, { unknownKey: 1 }),
+  /unknown key/i,
+  "engineSetConfig with unknown key must throw",
+);
+assert(
+  engineSetConfig(engineId, {
+    targetFps: 30,
+    enableScrollOptimizations: true,
+    waitForOutputDrain: false,
+    plat: { enableMouse: true, enableBracketedPaste: true },
+  }) === ZR_OK,
+  "engineSetConfig(valid config) must return ZR_OK",
+);
+
+const metricsBefore = engineGetMetrics(engineId);
+assertMetricsShape(metricsBefore);
+assert(
+  enginePresent(engineId) === ZR_OK,
+  "enginePresent(owner-thread) must return ZR_OK after successful create",
+);
+const metricsAfter = engineGetMetrics(engineId);
+assertMetricsShape(metricsAfter);
+assert(metricsAfter.frameIndex >= metricsBefore.frameIndex, "metrics.frameIndex must be monotonic");
+
+assert(
+  engineDebugEnable(engineId, {
+    enabled: true,
+    ringCapacity: 256,
+    minSeverity: 0,
+    categoryMask: 0xffff_ffff,
+  }) === ZR_OK,
+  "engineDebugEnable(valid config) must return ZR_OK",
+);
+assertThrows(
+  () => engineDebugQuery(engineId, { bogus: true }, new Uint8Array(40)),
+  /unknown key/i,
+  "engineDebugQuery with unknown key must throw",
+);
+assertThrows(
+  () => engineDebugQuery(engineId, { maxRecords: 1 }, new Uint8Array(new ArrayBuffer(41), 1, 40)),
+  /align/i,
+  "engineDebugQuery with misaligned outHeaders must throw",
+);
+
+assert(
+  enginePostUserEvent(engineId, 0xbeef, new Uint8Array([1, 2, 3, 4])) === ZR_OK,
+  "enginePostUserEvent(owner-thread) must return ZR_OK",
+);
+
+const headers = new Uint8Array(40 * 8);
+const query = engineDebugQuery(engineId, { maxRecords: 8 }, headers);
+assert(query && typeof query === "object", "engineDebugQuery must return an object");
+assert(
+  typeof query.recordsReturned === "number" &&
+    query.recordsReturned >= 0 &&
+    query.recordsReturned <= 8,
+  "engineDebugQuery.recordsReturned must be in [0, 8]",
+);
+assert(
+  typeof query.recordsAvailable === "number" && query.recordsAvailable >= 0,
+  "engineDebugQuery.recordsAvailable must be non-negative",
+);
+assert(typeof query.oldestRecordId === "bigint", "engineDebugQuery.oldestRecordId must be bigint");
+assert(typeof query.newestRecordId === "bigint", "engineDebugQuery.newestRecordId must be bigint");
+assert(
+  typeof query.recordsDropped === "number" && query.recordsDropped >= 0,
+  "engineDebugQuery.recordsDropped must be non-negative",
+);
+
+const payloadOut = new Uint8Array(1024);
+const firstRecordId = query.recordsReturned > 0 ? readU64LE(headers, 0) : 0n;
+assertThrows(
+  () => engineDebugGetPayload(engineId, 1n << 64n, new Uint8Array(16)),
+  /u64/i,
+  "engineDebugGetPayload with out-of-range recordId must throw",
+);
+const payloadBytes = engineDebugGetPayload(engineId, firstRecordId, payloadOut);
+assert(
+  Number.isInteger(payloadBytes),
+  "engineDebugGetPayload must return an integer byte count/result code",
+);
+if (payloadBytes >= 0) {
+  assert(
+    payloadBytes <= payloadOut.byteLength,
+    "engineDebugGetPayload bytes must fit output buffer",
+  );
+}
+
+const debugStats = engineDebugGetStats(engineId);
+assertDebugStatsShape(debugStats);
+
+const exportedBytes = engineDebugExport(engineId, new Uint8Array(64 * 1024));
+assert(Number.isInteger(exportedBytes), "engineDebugExport must return integer bytes/result code");
+if (exportedBytes >= 0) {
+  assert(exportedBytes <= 64 * 1024, "engineDebugExport bytes must fit output buffer");
+}
+
+assert(engineDebugReset(engineId) === ZR_OK, "engineDebugReset must return ZR_OK");
+assert(engineDebugDisable(engineId) === ZR_OK, "engineDebugDisable must return ZR_OK");
+
+const worker = new Worker(new URL("./smoke-worker.mjs", import.meta.url), {
+  workerData: { engineId },
+  type: "module",
+});
+
+const alive = await new Promise((resolve, reject) => {
+  const onExit = (code) => reject(new Error(`worker exited with ${code}`));
+  const onError = (err) => reject(err);
+  const onMessage = (msg) => {
+    worker.off("exit", onExit);
+    worker.off("error", onError);
+    resolve(msg);
+  };
+  worker.once("exit", onExit);
+  worker.once("error", onError);
+  worker.once("message", onMessage);
+});
+
+assert(alive.phase === "alive", "worker must send alive phase");
+assert(
+  alive.present === ZR_ERR_INVALID_ARGUMENT,
+  `wrong-thread enginePresent must return ZR_ERR_INVALID_ARGUMENT, got: ${alive.present}`,
+);
+assert(
+  alive.postUserEvent === ZR_ERR_INVALID_ARGUMENT,
+  `wrong-thread enginePostUserEvent must return ZR_ERR_INVALID_ARGUMENT, got: ${alive.postUserEvent}`,
+);
+assert(
+  alive.setConfig === ZR_ERR_INVALID_ARGUMENT,
+  `wrong-thread engineSetConfig must return ZR_ERR_INVALID_ARGUMENT, got: ${alive.setConfig}`,
+);
+assert(
+  alive.debugDisable === ZR_ERR_INVALID_ARGUMENT,
+  `wrong-thread engineDebugDisable must return ZR_ERR_INVALID_ARGUMENT, got: ${alive.debugDisable}`,
+);
+
+engineDestroy(engineId);
+engineDestroy(engineId); // idempotent
+
+worker.postMessage({ type: "afterDestroy" });
+
+const destroyed = await new Promise((resolve, reject) => {
+  const onExit = (code) => reject(new Error(`worker exited with ${code}`));
+  const onError = (err) => reject(err);
+  const onMessage = (msg) => {
+    worker.off("exit", onExit);
+    worker.off("error", onError);
+    resolve(msg);
+  };
+  worker.once("exit", onExit);
+  worker.once("error", onError);
+  worker.once("message", onMessage);
+});
+
+assert(destroyed.phase === "destroyed", "worker must send destroyed phase");
+assert(
+  destroyed.postUserEvent === ZR_ERR_INVALID_ARGUMENT,
+  `postUserEvent after destroy must return ZR_ERR_INVALID_ARGUMENT, got: ${destroyed.postUserEvent}`,
+);
+
+await worker.terminate();