@rezi-ui/native 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,29 @@
+# @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
+```
+
+## Design and constraints
+
+- Engine ownership lives on a worker thread (never the Node main thread).
+- All buffers across the boundary are caller-owned; binary formats are validated strictly.
+
+See:
+
+- [Native addon docs](../../docs/backend/native.md)
+- [Releasing](RELEASING.md)

package/index.d.ts

@@ -0,0 +1,94 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+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;
+  /** 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;
+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;

package/index.js

@@ -0,0 +1,50 @@
+import { readdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const rootDir = dirname(fileURLToPath(import.meta.url));
+
+const discoveredNodeFiles = readdirSync(rootDir).filter((f) => f.endsWith(".node"));
+
+const candidates = ["index.node", "rezi_ui_native.node", ...discoveredNodeFiles];
+
+let native = null;
+let lastErr = null;
+for (const file of new Set(candidates)) {
+  try {
+    native = require(join(rootDir, file));
+    break;
+  } catch (err) {
+    lastErr = err;
+  }
+}
+
+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(candidates)].join(", ")}${extra}`,
+  );
+}
+
+export const {
+  engineCreate,
+  engineDestroy,
+  engineSubmitDrawlist,
+  enginePresent,
+  enginePollEvents,
+  enginePostUserEvent,
+  engineGetMetrics,
+  engineSetConfig,
+  engineGetCaps,
+  // Debug trace API
+  engineDebugEnable,
+  engineDebugDisable,
+  engineDebugQuery,
+  engineDebugGetPayload,
+  engineDebugGetStats,
+  engineDebugExport,
+  engineDebugReset,
+} = native;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@rezi-ui/native",
+  "version": "0.1.0-alpha.1",
+  "description": "Native addon for Rezi (napi-rs + Zireael engine).",
+  "license": "Apache-2.0",
+  "homepage": "https://rtlzeromemory.github.io/Rezi/",
+  "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",
+    "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"
+  },
+  "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,18 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { enginePostUserEvent, enginePresent } from "../index.js";
+
+const { engineId } = workerData;
+
+if (!parentPort) {
+  throw new Error("smoke-worker: missing parentPort");
+}
+
+const res1 = enginePresent(engineId);
+const res2 = enginePostUserEvent(engineId, 123, new Uint8Array([1, 2, 3]));
+parentPort.postMessage({ phase: "alive", present: res1, postUserEvent: res2 });
+
+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,82 @@
+import { Worker } from "node:worker_threads";
+import { engineCreate, engineDestroy, enginePresent } from "../index.js";
+
+const ZR_ERR_INVALID_ARGUMENT = -1;
+const ZR_ERR_PLATFORM = -6;
+
+function assert(cond, msg) {
+  if (!cond) throw new Error(msg);
+}
+
+// Unknown / stale id behavior (result-returning fns).
+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",
+);
+
+const engineId = engineCreate({});
+
+assert(typeof engineId === "number", "engineCreate must return a number");
+if (engineId === ZR_ERR_PLATFORM && !(process.stdout.isTTY && process.stdin.isTTY)) {
+  process.stdout.write("native-smoke: SKIP engineCreate() (no TTY / platform init unavailable)\n");
+  process.exit(0);
+}
+assert(engineId > 0, `engineCreate must return a non-zero engineId, got: ${engineId}`);
+
+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 === 0,
+  `enginePostUserEvent must succeed cross-thread while alive (ZR_OK), got: ${alive.postUserEvent}`,
+);
+
+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();