@adhdev/ghostty-vt-node 1.0.78 → 1.0.82-rc.38

package/index.js

@@ -2,6 +2,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const ADDON_FILE = 'ghostty_vt_node.node';
+const { orderPrebuiltTriplets } = require('./binding-candidates.js');
 const PREBUILT_ROOT = path.join(__dirname, 'prebuilt');
 
 function getTriplet() {
@@ -19,9 +20,10 @@ function getTriplet() {
 // Consequently the loader resolves in three tiers:
 //   1. an explicit override dir (ADHDEV_GHOSTTY_VT_PREBUILT_DIR),
 //   2. a locally compiled build/ output,
-//   3. an exact `platform-arch-nodeABI` prebuilt, and finally
-//   4. ANY prebuilt for the same `platform-arch` (N-API portability fallback).
-// Tier 4 is what makes a brand-new Node ABI (e.g. a future node26) work without
+//   3. same-`platform-arch` prebuilts ranked by manifest apiLevel (highest
+//      first), exact ABI as tie-breaker (see binding-candidates.js).
+// Not preferring the exact ABI is deliberate: stale API-level-1 binaries for
+// ABI 115/127 once shadowed the current API-level-2 build. This is what makes a brand-new Node ABI (e.g. a future node26) work without
 // shipping a new directory — the previous failure mode where node137 runtimes
 // hit "binding unavailable" purely because no `node137` directory existed.
 
@@ -38,66 +40,69 @@ function listAvailablePrebuiltTriplets() {
     }
 }
 
-function samePlatformArchTriplets(triplet) {
-    // triplet === `${platform}-${arch}-node${abi}` → prefix is `${platform}-${arch}-`
-    const prefix = `${process.platform}-${process.arch}-`;
-    return listAvailablePrebuiltTriplets().filter(
-        (name) => name.startsWith(prefix) && name !== triplet,
-    );
-}
-
-// Last-resort: every other installed prebuilt, regardless of platform/arch.
-// Requiring a foreign-OS `.node` throws a load error (ELF/PE mismatch,
-// "invalid ELF header", "not a valid Win32 application"), which loadBinding()
-// simply skips — so this tier is inert on a correctly-addressed runtime. Its
-// sole purpose is test isolation: suites that mock `process.platform` (e.g.
-// win32 PTY-write / submit driver coverage) corrupt getTriplet() into an
-// address for which no loadable binary exists on the CI runner; walking the
-// remaining triplets lets the real host binary (the one that actually loads)
-// still resolve, instead of the whole ProviderCliAdapter construction throwing.
-function otherInstalledTriplets(triplet, alreadyTried) {
-    return listAvailablePrebuiltTriplets().filter(
-        (name) => name !== triplet && !alreadyTried.has(name),
-    );
+function readManifestApiLevel(name) {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(PREBUILT_ROOT, name, 'manifest.json'), 'utf8'));
+        return Number.isFinite(manifest.apiLevel) ? manifest.apiLevel : 0;
+    } catch {
+        return 0;
+    }
 }
 
+// Selection rule (see binding-candidates.js): among same platform-arch
+// prebuilts the highest manifest apiLevel wins, then the exact running ABI.
+// Foreign-platform dirs are a last-resort test-isolation fallback (requiring a
+// foreign-OS `.node` throws and is skipped; it matters only for suites that
+// mock process.platform).
+//
+// A locally compiled build/ output is tried before the prebuilts, but only
+// accepted if it reports apiLevel >= the best prebuilt manifest level — a stale
+// build/ directory must not shadow a newer prebuilt. A rejected build is kept
+// as the very last resort.
 function loadBinding() {
-    const triplet = getTriplet();
+    const abi = process.versions.modules;
     const explicitPrebuiltDir = process.env.ADHDEV_GHOSTTY_VT_PREBUILT_DIR
         ? path.resolve(process.env.ADHDEV_GHOSTTY_VT_PREBUILT_DIR)
         : null;
+    const triplet = getTriplet();
+    const ordered = orderPrebuiltTriplets({
+        names: listAvailablePrebuiltTriplets(),
+        platform: process.platform,
+        arch: process.arch,
+        abi,
+        readApiLevel: readManifestApiLevel,
+    });
+    const prebuiltFile = (name) => path.join(PREBUILT_ROOT, name, ADDON_FILE);
 
+    // { file, minApiLevel } — minApiLevel > 0 means "verify after load".
     const candidates = [
-        // 1. explicit override
-        explicitPrebuiltDir ? path.join(explicitPrebuiltDir, triplet, ADDON_FILE) : null,
-        explicitPrebuiltDir ? path.join(explicitPrebuiltDir, ADDON_FILE) : null,
-        // 2. locally compiled output
-        path.join(__dirname, 'build', 'Release', ADDON_FILE),
-        path.join(__dirname, 'build', 'Debug', ADDON_FILE),
-        // 3. exact-ABI prebuilt
-        path.join(PREBUILT_ROOT, triplet, ADDON_FILE),
-        // 4. N-API portability fallback: any same platform-arch prebuilt
-        ...samePlatformArchTriplets(triplet).map((name) =>
-            path.join(PREBUILT_ROOT, name, ADDON_FILE),
-        ),
-        // 5. test-isolation fallback: any remaining installed triplet (see
-        //    otherInstalledTriplets). Foreign-OS binaries throw on require and
-        //    are skipped; the real host binary still resolves under a mocked
-        //    process.platform.
-        ...otherInstalledTriplets(
-            triplet,
-            new Set([triplet, ...samePlatformArchTriplets(triplet)]),
-        ).map((name) => path.join(PREBUILT_ROOT, name, ADDON_FILE)),
+        explicitPrebuiltDir ? { file: path.join(explicitPrebuiltDir, triplet, ADDON_FILE) } : null,
+        explicitPrebuiltDir ? { file: path.join(explicitPrebuiltDir, ADDON_FILE) } : null,
+        { file: path.join(__dirname, 'build', 'Release', ADDON_FILE), minApiLevel: ordered.bestApiLevel },
+        { file: path.join(__dirname, 'build', 'Debug', ADDON_FILE), minApiLevel: ordered.bestApiLevel },
+        ...ordered.samePlatform.map((name) => ({ file: prebuiltFile(name) })),
+        ...ordered.otherPlatform.map((name) => ({ file: prebuiltFile(name) })),
     ].filter(Boolean);
 
     const errors = [];
+    const rejected = [];
     for (const candidate of candidates) {
         try {
-            return require(candidate);
+            const loaded = require(candidate.file);
+            if (candidate.minApiLevel) {
+                const level = describeBinding(loaded).apiLevel;
+                if (level < candidate.minApiLevel) {
+                    errors.push(`${candidate.file}: apiLevel ${level} < best prebuilt ${candidate.minApiLevel}`);
+                    rejected.push(loaded);
+                    continue;
+                }
+            }
+            return loaded;
         } catch (error) {
-            errors.push(`${candidate}: ${error && error.message ? error.message : String(error)}`);
+            errors.push(`${candidate.file}: ${error && error.message ? error.message : String(error)}`);
         }
     }
+    if (rejected.length) return rejected[0];
 
     const available = listAvailablePrebuiltTriplets();
     throw new Error(
@@ -108,4 +113,43 @@ function loadBinding() {
     );
 }
 
-module.exports = loadBinding();
+// Surface added at API level 2. A binary built before it (an older prebuilt or
+// a stale build/ output that shadows the prebuilt) still loads and still
+// serves the legacy methods; it simply lacks these. Consumers feature-detect
+// via `capabilities.viewport` (or `typeof handle.getViewport === 'function'`)
+// and must treat the exact-read path as unavailable rather than falling back
+// to formatter output.
+const VIEWPORT_METHODS = ['getViewport', 'readRow', 'scrollViewport'];
+
+function describeBinding(binding) {
+    if (typeof binding.getBindingInfo === 'function') {
+        const info = binding.getBindingInfo();
+        return {
+            apiLevel: info.apiLevel,
+            sourceDigest: info.sourceDigest || null,
+            ghosttyRevision: info.ghosttyRevision || null,
+            napiVersion: info.napiVersion ?? null,
+        };
+    }
+    return { apiLevel: 1, sourceDigest: null, ghosttyRevision: null, napiVersion: null };
+}
+
+function probeViewportSupport(binding, info) {
+    if (info.apiLevel < 2 || typeof binding.createTerminal !== 'function') return false;
+    let terminal;
+    try {
+        terminal = binding.createTerminal({ cols: 1, rows: 1, scrollback: 0 });
+        return VIEWPORT_METHODS.every((name) => typeof terminal[name] === 'function');
+    } catch {
+        return false;
+    } finally {
+        try { terminal?.dispose(); } catch { /* best effort */ }
+    }
+}
+
+const binding = loadBinding();
+const bindingInfo = describeBinding(binding);
+binding.bindingInfo = bindingInfo;
+binding.capabilities = Object.freeze({ viewport: probeViewportSupport(binding, bindingInfo) });
+
+module.exports = binding;

package/package.json

@@ -1,22 +1,26 @@
 {
   "name": "@adhdev/ghostty-vt-node",
-  "version": "1.0.78",
+  "version": "1.0.82-rc.38",
   "description": "Native Node binding for libghostty-vt",
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
     "index.js",
+    "binding-candidates.js",
     "index.d.ts",
     "prebuilt",
     "scripts",
     "CMakeLists.txt",
+    "toolchain.json",
     "src",
     "README.md"
   ],
   "scripts": {
     "build": "node ./scripts/build-or-use-prebuilt.mjs",
     "rebuild": "cmake-js rebuild",
-    "clean": "cmake-js clean"
+    "clean": "cmake-js clean",
+    "test": "node --import ../../scripts/test-tmp-guard.mjs --test test/*.test.mjs",
+    "check:prebuilts": "node scripts/check-prebuilts.mjs"
   },
   "author": "vilmire",
   "dependencies": {

package/prebuilt/darwin-arm64-node137/manifest.json

@@ -0,0 +1,34 @@
+{
+  "schema": 2,
+  "platform": "darwin",
+  "arch": "arm64",
+  "apiLevel": 2,
+  "sourceDigest": "e4ca3372235a1289373e172996a5e7804bc4d5f3eac630d91d9160dd932e0627",
+  "ghosttyRevision": "d4a38c8661453026bd1b1bb022ba2c37b347adce",
+  "napiVersion": 8,
+  "builtWithNode": "v22.17.0",
+  "release": true,
+  "provenance": {
+    "problems": [],
+    "ghosttySourceRevision": "d4a38c8661453026bd1b1bb022ba2c37b347adce",
+    "ghosttySourceClean": true,
+    "zigVersion": "0.15.2",
+    "cCompiler": "AppleClang 17.0.0.17000316",
+    "cxxCompiler": "AppleClang 17.0.0.17000316",
+    "buildType": "Release"
+  },
+  "files": {
+    "ghostty_vt_node.node": {
+      "sha256": "fbdbf5e197b99d43b609b875d3621ce3e873ac8e0e04608cd057fba987a8555a",
+      "size": 100536
+    },
+    "libghostty-vt.0.1.0.dylib": {
+      "sha256": "d2f92f4bdbaa734b014fe8d38615ccaa5a97f9f07847e5476e87a4c7a64f3c00",
+      "size": 1528392
+    },
+    "libghostty-vt.dylib": {
+      "sha256": "d2f92f4bdbaa734b014fe8d38615ccaa5a97f9f07847e5476e87a4c7a64f3c00",
+      "size": 1528392
+    }
+  }
+}

package/prebuilt/linux-x64-node137/manifest.json

@@ -0,0 +1,38 @@
+{
+  "schema": 2,
+  "platform": "linux",
+  "arch": "x64",
+  "apiLevel": 2,
+  "sourceDigest": "e4ca3372235a1289373e172996a5e7804bc4d5f3eac630d91d9160dd932e0627",
+  "ghosttyRevision": "d4a38c8661453026bd1b1bb022ba2c37b347adce",
+  "napiVersion": 8,
+  "builtWithNode": "v22.22.0",
+  "release": true,
+  "provenance": {
+    "problems": [],
+    "ghosttySourceRevision": "d4a38c8661453026bd1b1bb022ba2c37b347adce",
+    "ghosttySourceClean": true,
+    "zigVersion": "0.15.2",
+    "cCompiler": "GNU 13.3.0",
+    "cxxCompiler": "GNU 13.3.0",
+    "buildType": "Release"
+  },
+  "files": {
+    "ghostty_vt_node.node": {
+      "sha256": "aefc9e332147bc2980f3810558d4f80ad3d407dfb3b19fcd9dd0d416e62c38bc",
+      "size": 130096
+    },
+    "libghostty-vt.so": {
+      "sha256": "2dc10d68318c378a35584ee36580f836c91d64428fcd5bf4466b08f3716c3c23",
+      "size": 7496328
+    },
+    "libghostty-vt.so.0": {
+      "sha256": "2dc10d68318c378a35584ee36580f836c91d64428fcd5bf4466b08f3716c3c23",
+      "size": 7496328
+    },
+    "libghostty-vt.so.0.1.0": {
+      "sha256": "2dc10d68318c378a35584ee36580f836c91d64428fcd5bf4466b08f3716c3c23",
+      "size": 7496328
+    }
+  }
+}

package/prebuilt/win32-x64-node137/manifest.json

@@ -0,0 +1,30 @@
+{
+  "schema": 2,
+  "platform": "win32",
+  "arch": "x64",
+  "apiLevel": 2,
+  "sourceDigest": "e4ca3372235a1289373e172996a5e7804bc4d5f3eac630d91d9160dd932e0627",
+  "ghosttyRevision": "d4a38c8661453026bd1b1bb022ba2c37b347adce",
+  "napiVersion": 8,
+  "builtWithNode": "v22.14.0",
+  "release": true,
+  "provenance": {
+    "problems": [],
+    "ghosttySourceRevision": "d4a38c8661453026bd1b1bb022ba2c37b347adce",
+    "ghosttySourceClean": true,
+    "zigVersion": "0.15.2",
+    "cCompiler": "MSVC 19.44.35229.0",
+    "cxxCompiler": "MSVC 19.44.35229.0",
+    "buildType": "Release"
+  },
+  "files": {
+    "ghostty-vt.dll": {
+      "sha256": "7d2ce8845d559a7279bde0080c99ccf795dd9f13d4236add3bf0c4e312fdad7a",
+      "size": 1305600
+    },
+    "ghostty_vt_node.node": {
+      "sha256": "6d29fd06b15d1f05930ce5c969ee316f0135c42d334763c4a07ff584e3fb9a6d",
+      "size": 70656
+    }
+  }
+}

package/scripts/binding-digest.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Binding source digest: the identity of the sources a native binary was
+// compiled from. CMakeLists.txt computes the same value at configure time and
+// embeds it in the addon (getBindingInfo().sourceDigest), so a prebuilt can be
+// checked against the sources in this checkout.
+//
+// Algorithm (keep in sync with CMakeLists.txt): for each input in order,
+// "<path>:<sha256 of content with CRLF -> LF>\n"; digest = sha256 of the
+// concatenation. LF normalization keeps a win32 autocrlf checkout from
+// reporting a different digest for identical sources.
+//
+//   node scripts/binding-digest.mjs        # prints the digest
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const PACKAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+export const BINDING_DIGEST_INPUTS = [
+    'CMakeLists.txt',
+    'toolchain.json',
+    'src/addon.cc',
+    'src/ghostty_bridge.c',
+    'src/ghostty_bridge.h',
+    'scripts/clean-dir.cjs',
+];
+
+const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+
+export function computeBindingDigest(packageDir = PACKAGE_DIR) {
+    let manifest = '';
+    for (const input of BINDING_DIGEST_INPUTS) {
+        const content = readFileSync(join(packageDir, input), 'utf8').replace(/\r\n/g, '\n');
+        manifest += `${input}:${sha256(Buffer.from(content, 'utf8'))}\n`;
+    }
+    return sha256(Buffer.from(manifest, 'utf8'));
+}
+
+// The zig version toolchain.json pins: the single source the native workflow
+// installs, CMakeLists.txt enforces and the release gate compares against.
+export function pinnedZigVersion(packageDir = PACKAGE_DIR) {
+    const { zig } = JSON.parse(readFileSync(join(packageDir, 'toolchain.json'), 'utf8'));
+    if (typeof zig !== 'string' || !/^\d+\.\d+\.\d+$/.test(zig)) throw new Error('toolchain.json does not pin "zig" to x.y.z');
+    return zig;
+}
+
+// The ghostty revision CMakeLists.txt pins by default.
+export function pinnedGhosttyRevision(packageDir = PACKAGE_DIR) {
+    const cmake = readFileSync(join(packageDir, 'CMakeLists.txt'), 'utf8');
+    const match = cmake.match(/set\(GHOSTTY_GIT_TAG "([0-9a-f]{40})"/);
+    const pin = cmake.match(/set\(ADHDEV_GHOSTTY_PINNED_REVISION "([0-9a-f]{40})"\)/);
+    if (!match || !pin) throw new Error('CMakeLists.txt does not pin GHOSTTY_GIT_TAG / ADHDEV_GHOSTTY_PINNED_REVISION to a 40-hex revision');
+    if (match[1] !== pin[1]) throw new Error(`CMakeLists.txt pins disagree: GHOSTTY_GIT_TAG ${match[1]} != ADHDEV_GHOSTTY_PINNED_REVISION ${pin[1]}`);
+    return pin[1];
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+    console.log(computeBindingDigest());
+}

package/scripts/build-or-use-prebuilt.mjs

@@ -3,6 +3,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { emitPrebuilt } from './prebuilt-manifest.mjs';
+
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const packageDir = path.resolve(scriptDir, '..');
 const outputDir = path.join(packageDir, 'build', 'Release');
@@ -10,9 +12,11 @@ const outputFile = path.join(outputDir, 'ghostty_vt_node.node');
 const triplet = `${process.platform}-${process.arch}-node${process.versions.modules}`;
 const sourceInputs = [
   path.join(packageDir, 'CMakeLists.txt'),
+  path.join(packageDir, 'toolchain.json'),
   path.join(packageDir, 'src', 'addon.cc'),
   path.join(packageDir, 'src', 'ghostty_bridge.c'),
   path.join(packageDir, 'src', 'ghostty_bridge.h'),
+  path.join(packageDir, 'scripts', 'clean-dir.cjs'),
 ];
 
 function safeMtime(filePath) {
@@ -117,45 +121,76 @@ function installPrebuilt(candidateFile) {
   if (!fs.existsSync(outputFile)) fs.copyFileSync(candidateFile, outputFile);
 }
 
-function installPrebuiltIfPresent(sourceMtime) {
+// ADHDEV_GHOSTTY_VT_FORCE_COMPILE=1 always compiles from source: no existing
+// build output, no prebuilt. The native CI build uses it — in a fresh checkout
+// the sources are never "locally modified", so without it the tracked
+// prebuilt is copied and a binary that predates the current sources ships.
+// `--plan` prints the decision and exits without touching anything.
+const forceCompile = process.env.ADHDEV_GHOSTTY_VT_FORCE_COMPILE === '1';
+const planOnly = process.argv.includes('--plan');
+
+function decide() {
+  if (forceCompile) return { action: 'compile', mode: 'rebuild', reason: 'ADHDEV_GHOSTTY_VT_FORCE_COMPILE=1' };
+  const sourceMtime = latestSourceMtime();
+  const outputMtime = safeMtime(outputFile);
+  // A local build output is something this machine compiled, so its mtime
+  // against the sources is meaningful: keep it while it is not older.
+  if (outputMtime >= sourceMtime && outputMtime > 0) return { action: 'keep-local', file: outputFile };
   for (const candidate of candidatePrebuiltPaths()) {
     if (!fs.existsSync(candidate.file)) continue;
     if (!isUsablePrebuilt(candidate, sourceMtime)) {
       console.log(`[ghostty-vt-node] skipping prebuilt ${candidate.file}: sources were modified locally after it was built`);
       continue;
     }
-    installPrebuilt(candidate.file);
-    console.log(`[ghostty-vt-node] using prebuilt native binding from ${candidate.file}`);
-    return true;
+    return { action: 'use-prebuilt', file: candidate.file };
   }
-  return false;
+  if (process.env.ADHDEV_SKIP_GHOSTTY_VT_BUILD === '1') return { action: 'skip', reason: 'ADHDEV_SKIP_GHOSTTY_VT_BUILD=1' };
+  return { action: 'compile', reason: 'no usable local build or prebuilt' };
 }
 
-const sourceMtime = latestSourceMtime();
-const outputMtime = safeMtime(outputFile);
+const decision = decide();
+if (planOnly) {
+  console.log(`[ghostty-vt-node] plan: ${decision.action}${decision.mode ? ` (cmake-js ${decision.mode})` : ''}${decision.file ? ` ${decision.file}` : ''}${decision.reason ? ` (${decision.reason})` : ''}`);
+  process.exit(0);
+}
 
-// A local build output is something this machine compiled, so its mtime
-// against the sources is meaningful: keep it while it is not older.
-if (outputMtime >= sourceMtime && outputMtime > 0) {
+if (decision.action === 'keep-local') {
   console.log(`[ghostty-vt-node] keeping existing local build at ${outputFile}`);
   process.exit(0);
 }
 
-if (installPrebuiltIfPresent(sourceMtime)) {
+if (decision.action === 'use-prebuilt') {
+  installPrebuilt(decision.file);
+  console.log(`[ghostty-vt-node] using prebuilt native binding from ${decision.file}`);
   process.exit(0);
 }
 
-if (process.env.ADHDEV_SKIP_GHOSTTY_VT_BUILD === '1') {
+if (decision.action === 'skip') {
   console.log(`[ghostty-vt-node] skipping native build for ${triplet} (ADHDEV_SKIP_GHOSTTY_VT_BUILD=1)`);
   process.exit(0);
 }
 
+// A forced compile is a CLEAN rebuild (fresh configure, fresh FetchContent
+// clone, zig-out regenerated): an incremental `compile` would reuse whatever
+// the previous build directory holds. Other compiles stay incremental.
+const cmakeJsCommand = forceCompile ? 'rebuild' : 'compile';
 const isWindows = process.platform === 'win32';
 const command = isWindows ? (process.env.ComSpec || 'cmd.exe') : 'npm';
 const args = isWindows
-  ? ['/d', '/s', '/c', 'npm exec -- cmake-js compile']
-  : ['exec', '--', 'cmake-js', 'compile'];
-console.log(`[ghostty-vt-node] compiling ${triplet} via ${command} ${args.join(' ')}`);
+  ? ['/d', '/s', '/c', `npm exec -- cmake-js ${cmakeJsCommand}`]
+  : ['exec', '--', 'cmake-js', cmakeJsCommand];
+// cmake-js' own clean (`cmake -E remove_directory`) has the same Windows
+// trailing-dot problem as file(REMOVE_RECURSE), so a forced rebuild removes
+// build/ itself first and refuses to continue on a partial removal.
+if (forceCompile) {
+  const buildDir = path.join(packageDir, 'build');
+  const clean = spawnSync(process.execPath, [path.join(scriptDir, 'clean-dir.cjs'), buildDir], { stdio: 'inherit', windowsHide: true });
+  if (clean.status !== 0 || fs.existsSync(buildDir)) {
+    console.error(`[ghostty-vt-node] could not remove ${buildDir}; refusing to rebuild on top of it`);
+    process.exit(1);
+  }
+}
+console.log(`[ghostty-vt-node] compiling ${triplet} (${decision.reason}) via ${command} ${args.join(' ')}`);
 const result = spawnSync(command, args, {
   cwd: packageDir,
   env: process.env,
@@ -166,26 +201,20 @@ if (result.error) {
   console.error(`[ghostty-vt-node] failed to launch native build for ${triplet}:`, result.error);
 }
 
-// Mirror a successful local build into prebuilt/<triplet>/ so CI (or a developer)
-// can produce a shippable prebuilt reproducibly: build once on the target
-// platform, then commit prebuilt/<triplet>/. Set ADHDEV_GHOSTTY_VT_EMIT_PREBUILT=1
-// to enable (off by default so ordinary `npm run build` does not churn the dir).
-// The binding is Node-API (ABI-stable), so a single emitted triplet is enough for
-// the running platform-arch; the runtime loader (index.js) falls back across ABIs.
+// Mirror a successful local build into the committed prebuilt for this
+// platform-arch (prebuilt/<platform>-<arch>-node137, whatever Node runs the
+// build — the binding is Node-API, so the ABI in the name is only an address)
+// and stamp its manifest.json from the compiled binary. Set
+// ADHDEV_GHOSTTY_VT_EMIT_PREBUILT=1 to enable (off by default so ordinary
+// `npm run build` does not churn the dir). Combine with
+// ADHDEV_GHOSTTY_VT_FORCE_COMPILE=1 to rebuild a prebuilt from source.
 if ((result.status ?? 1) === 0 && process.env.ADHDEV_GHOSTTY_VT_EMIT_PREBUILT === '1') {
   try {
-    const prebuiltDir = path.join(packageDir, 'prebuilt', triplet);
-    fs.mkdirSync(prebuiltDir, { recursive: true });
-    for (const entry of fs.readdirSync(outputDir)) {
-      // Ship the addon plus its co-located runtime libs (.dylib/.so/.dll),
-      // skip intermediate build artifacts.
-      if (/\.(node|dylib|so|so\.\d.*|dll)$/.test(entry)) {
-        fs.copyFileSync(path.join(outputDir, entry), path.join(prebuiltDir, entry));
-      }
-    }
-    console.log(`[ghostty-vt-node] emitted prebuilt for ${triplet} → ${prebuiltDir}`);
+    const { target, manifest } = emitPrebuilt(outputDir);
+    console.log(`[ghostty-vt-node] emitted prebuilt → ${target} (source digest ${manifest.sourceDigest})`);
   } catch (emitError) {
     console.error(`[ghostty-vt-node] failed to emit prebuilt for ${triplet}:`, emitError);
+    process.exit(1);
   }
 }