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

package/CMakeLists.txt

@@ -16,21 +16,270 @@ execute_process(
 string(REPLACE "\"" "" NODE_ADDON_API_DIR "${NODE_ADDON_API_DIR}")
 
 set(GHOSTTY_GIT_TAG "d4a38c8661453026bd1b1bb022ba2c37b347adce" CACHE STRING "Ghostty git revision for libghostty-vt")
+# The pin itself, independent of the overridable cache entry above.
+set(ADHDEV_GHOSTTY_PINNED_REVISION "d4a38c8661453026bd1b1bb022ba2c37b347adce")
 
 if(DEFINED ENV{ZIG_EXECUTABLE} AND NOT DEFINED ZIG_EXECUTABLE)
   set(ZIG_EXECUTABLE "$ENV{ZIG_EXECUTABLE}" CACHE FILEPATH "Path to zig executable")
 endif()
 
+# --- Build provenance ---------------------------------------------------------
+# A release binary must be built from exactly the pinned ghostty revision, in a
+# clean FetchContent-managed clone, with the pinned zig, and its libghostty-vt
+# must be built by THIS build from fresh, private zig caches (see "Runtime
+# freshness" below). Each violation
+# is a problem code; any problem fails the configure step unless the explicit
+# developer override ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD=1 (cache variable or
+# environment) is set. The override ALWAYS makes the build non-release, even
+# with nothing else wrong: the binary reports releaseEligible=false and the
+# prebuilt release gates refuse it. Only problem codes are embedded, never paths.
+#
+# toolchain.json is the single zig pin: the native workflow installs that
+# version and the release gate compares against it. It is a binding digest
+# input, so changing the pin invalidates every existing prebuilt.
+file(READ "${CMAKE_CURRENT_SOURCE_DIR}/toolchain.json" ADHDEV_TOOLCHAIN_JSON)
+string(JSON ADHDEV_PINNED_ZIG_VERSION GET "${ADHDEV_TOOLCHAIN_JSON}" zig)
+
+set(ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD OFF CACHE BOOL "Allow a non-release build from an unverified ghostty source or toolchain")
+if("$ENV{ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD}" STREQUAL "1")
+  set(ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD ON)
+endif()
+set(ADHDEV_PROVENANCE_PROBLEMS "")
+if(ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD)
+  list(APPEND ADHDEV_PROVENANCE_PROBLEMS "unverified-dev-build")
+endif()
+if(NOT GHOSTTY_GIT_TAG STREQUAL ADHDEV_GHOSTTY_PINNED_REVISION)
+  list(APPEND ADHDEV_PROVENANCE_PROBLEMS "ghostty-tag-override")
+endif()
+# A substituted checkout is not under this build's control (it may be shared,
+# reused or written to while building). Release builds use the managed clone.
+if(FETCHCONTENT_SOURCE_DIR_GHOSTTY)
+  list(APPEND ADHDEV_PROVENANCE_PROBLEMS "ghostty-source-override")
+endif()
+
+# User-supplied extra zig flags change the library ghostty builds.
+if(NOT "${GHOSTTY_ZIG_BUILD_FLAGS}" STREQUAL "")
+  list(APPEND ADHDEV_PROVENANCE_PROBLEMS "extra-zig-build-flags")
+endif()
+
+# Resolve zig and record the version that actually builds libghostty-vt. The whole output, with
+# only surrounding whitespace/CRLF trimmed, must equal the pin exactly.
+find_program(ZIG_EXECUTABLE zig REQUIRED)
+execute_process(
+  COMMAND "${ZIG_EXECUTABLE}" version
+  OUTPUT_VARIABLE zig_version_output
+  RESULT_VARIABLE zig_version_result
+  ERROR_QUIET
+)
+string(STRIP "${zig_version_output}" zig_version_output)
+if(zig_version_result EQUAL 0 AND zig_version_output STREQUAL ADHDEV_PINNED_ZIG_VERSION)
+  set(ADHDEV_ZIG_VERSION "${ADHDEV_PINNED_ZIG_VERSION}")
+else()
+  list(APPEND ADHDEV_PROVENANCE_PROBLEMS "zig-version-mismatch")
+  # Recorded for diagnostics only, and only if it is a plain version token.
+  if(zig_version_output MATCHES "^[0-9A-Za-z.+-]+$")
+    set(ADHDEV_ZIG_VERSION "${zig_version_output}")
+  else()
+    set(ADHDEV_ZIG_VERSION "unrecognized")
+  endif()
+endif()
+
+# Only the SOURCE is taken from the clone. Upstream's CMakeLists.txt is not
+# added (SOURCE_SUBDIR points at a directory without one): it builds through an
+# OUTPUT-only custom command with the ambient zig caches and installs into the
+# git-ignored zig-out/ of the source tree, none of which this build can vouch
+# for. libghostty-vt is built by adhdev_ghostty_runtime below instead.
 FetchContent_Declare(ghostty
   GIT_REPOSITORY https://github.com/ghostty-org/ghostty.git
   GIT_TAG ${GHOSTTY_GIT_TAG}
+  SOURCE_SUBDIR adhdev-no-upstream-cmake
 )
 FetchContent_MakeAvailable(ghostty)
 
+# The DECLARED tag proves nothing: FETCHCONTENT_SOURCE_DIR_GHOSTTY can point at
+# any checkout. Verify the source that is actually built.
+find_package(Git QUIET)
+find_program(ADHDEV_NODE_EXECUTABLE node REQUIRED)
+set(ADHDEV_GHOSTTY_SOURCE_REVISION "")
+set(ADHDEV_GHOSTTY_SOURCE_CLEAN 0)
+if(GIT_EXECUTABLE)
+  execute_process(
+    COMMAND "${GIT_EXECUTABLE}" -C "${ghostty_SOURCE_DIR}" rev-parse HEAD
+    OUTPUT_VARIABLE ghostty_head
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    RESULT_VARIABLE ghostty_head_result
+    ERROR_QUIET
+  )
+  execute_process(
+    COMMAND "${GIT_EXECUTABLE}" -C "${ghostty_SOURCE_DIR}" status --porcelain
+    OUTPUT_VARIABLE ghostty_status
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    RESULT_VARIABLE ghostty_status_result
+    ERROR_QUIET
+  )
+  if(ghostty_head_result EQUAL 0 AND ghostty_head MATCHES "^[0-9a-f]+$")
+    set(ADHDEV_GHOSTTY_SOURCE_REVISION "${ghostty_head}")
+  endif()
+  if(ghostty_status_result EQUAL 0 AND ghostty_status STREQUAL "")
+    set(ADHDEV_GHOSTTY_SOURCE_CLEAN 1)
+  endif()
+endif()
+if(ADHDEV_GHOSTTY_SOURCE_REVISION STREQUAL "")
+  list(APPEND ADHDEV_PROVENANCE_PROBLEMS "ghostty-source-not-a-git-checkout")
+elseif(NOT ADHDEV_GHOSTTY_SOURCE_REVISION STREQUAL ADHDEV_GHOSTTY_PINNED_REVISION)
+  list(APPEND ADHDEV_PROVENANCE_PROBLEMS "ghostty-head-mismatch")
+endif()
+if(NOT ADHDEV_GHOSTTY_SOURCE_CLEAN)
+  list(APPEND ADHDEV_PROVENANCE_PROBLEMS "ghostty-source-dirty")
+endif()
+
+set(ADHDEV_VERIFY_GHOSTTY_SCRIPT "${CMAKE_CURRENT_BINARY_DIR}/adhdev-verify-ghostty-source.cmake")
+file(WRITE "${ADHDEV_VERIFY_GHOSTTY_SCRIPT}" [==[
+# Generated by ghostty-vt-node/CMakeLists.txt: re-verify at build time that the
+# ghostty source is still the pinned revision with a clean tree.
+execute_process(COMMAND "${GIT}" -C "${SRC}" rev-parse HEAD
+  OUTPUT_VARIABLE head OUTPUT_STRIP_TRAILING_WHITESPACE RESULT_VARIABLE head_result ERROR_QUIET)
+execute_process(COMMAND "${GIT}" -C "${SRC}" status --porcelain
+  OUTPUT_VARIABLE status OUTPUT_STRIP_TRAILING_WHITESPACE RESULT_VARIABLE status_result ERROR_QUIET)
+if(NOT head_result EQUAL 0 OR NOT head STREQUAL PIN)
+  message(FATAL_ERROR "ghostty-vt-node: ghostty source HEAD is '${head}', not the pin ${PIN}; reconfigure")
+endif()
+if(NOT status_result EQUAL 0 OR NOT status STREQUAL "")
+  message(FATAL_ERROR "ghostty-vt-node: ghostty source tree changed since configure; reconfigure from a clean clone")
+endif()
+]==])
+
+if(ADHDEV_PROVENANCE_PROBLEMS)
+  if(NOT ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD)
+    message(FATAL_ERROR
+      "ghostty-vt-node build provenance check failed: ${ADHDEV_PROVENANCE_PROBLEMS}\n"
+      "  ghostty pin ${ADHDEV_GHOSTTY_PINNED_REVISION}, resolved '${ADHDEV_GHOSTTY_SOURCE_REVISION}' (clean=${ADHDEV_GHOSTTY_SOURCE_CLEAN})\n"
+      "  zig pin ${ADHDEV_PINNED_ZIG_VERSION} (toolchain.json), found '${ADHDEV_ZIG_VERSION}'\n"
+      "Fix the toolchain/source, or set ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD=1 for a local NON-RELEASE build "
+      "(the prebuilt release gates refuse it).")
+  endif()
+  message(WARNING "ghostty-vt-node: NON-RELEASE build (${ADHDEV_PROVENANCE_PROBLEMS})")
+  set(ADHDEV_GHOSTTY_RELEASE_ELIGIBLE 0)
+else()
+  set(ADHDEV_GHOSTTY_RELEASE_ELIGIBLE 1)
+endif()
+string(REPLACE ";" "," ADHDEV_PROVENANCE_PROBLEMS_TEXT "${ADHDEV_PROVENANCE_PROBLEMS}")
+message(STATUS "ghostty-vt-node provenance: ghostty ${ADHDEV_GHOSTTY_SOURCE_REVISION} clean=${ADHDEV_GHOSTTY_SOURCE_CLEAN} zig ${ADHDEV_ZIG_VERSION} release=${ADHDEV_GHOSTTY_RELEASE_ELIGIBLE}")
+
+# --- Runtime freshness --------------------------------------------------------
+# HEAD/status/zig checks describe the INPUTS; the runtime must also be built
+# from them and nothing else. Everything zig reads or writes besides the
+# verified source and the pinned zig lives in this build tree:
+#   ghostty-zig/global-cache  zig's global cache, incl. fetched packages (p/)
+#   ghostty-zig/local-cache   zig's local cache (compiled artifacts)
+#   ghostty-zig/prefix        the install prefix the addon links and ships
+# They are passed as --global-cache-dir / --cache-dir / --prefix, which take
+# precedence over ZIG_GLOBAL_CACHE_DIR / ZIG_LOCAL_CACHE_DIR, so ambient caches
+# are never read: overriding them (rather than refusing a build with them set)
+# keeps CI and developer environments working while removing their influence.
+# Zig accepts an existing package directory in a cache without re-hashing it,
+# and reuses cache hits as-is, so for a RELEASE build all three are deleted at
+# every configure: dependencies are fetched afresh (zig verifies each package
+# hash on fetch) and everything is compiled from scratch. A non-release
+# (ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD) build keeps them between configures.
+#
+# adhdev_ghostty_runtime runs `zig build` on EVERY build, before the addon links
+# and copies the runtime, so a library left in the prefix is re-installed from
+# this build's cache; for a release build it re-verifies the pinned, clean
+# source before and after.
+#
+# LIMITATION: these checks are check-then-use, not atomic. A release build
+# assumes exclusive ownership of the build tree, the ghostty clone and the zig
+# installation for the whole configure + build: a concurrent writer could
+# change an input between a check and its use. Build release prebuilts on a
+# machine and in directories no other process writes to.
+set(ADHDEV_GHOSTTY_ZIG_DIR "${CMAKE_CURRENT_BINARY_DIR}/ghostty-zig")
+set(ADHDEV_ZIG_GLOBAL_CACHE "${ADHDEV_GHOSTTY_ZIG_DIR}/global-cache")
+set(ADHDEV_ZIG_LOCAL_CACHE "${ADHDEV_GHOSTTY_ZIG_DIR}/local-cache")
+set(ADHDEV_GHOSTTY_PREFIX "${ADHDEV_GHOSTTY_ZIG_DIR}/prefix")
+if(ADHDEV_GHOSTTY_RELEASE_ELIGIBLE)
+  # Not file(REMOVE_RECURSE): on Windows it stops part-way on names Win32
+  # normalizes away (zig extracts macOS `._.` files into the package cache),
+  # silently keeping cached packages. scripts/clean-dir.cjs removes them, and a
+  # clean that leaves anything behind fails the configure; a release build never
+  # proceeds on a partially emptied cache.
+  execute_process(
+    COMMAND "${ADHDEV_NODE_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/clean-dir.cjs" "${ADHDEV_GHOSTTY_ZIG_DIR}"
+    RESULT_VARIABLE adhdev_clean_result
+    OUTPUT_VARIABLE adhdev_clean_output
+    ERROR_VARIABLE adhdev_clean_output
+  )
+  if(NOT adhdev_clean_result EQUAL 0 OR EXISTS "${ADHDEV_GHOSTTY_ZIG_DIR}")
+    message(FATAL_ERROR
+      "ghostty-vt-node: could not empty the private zig caches in ${ADHDEV_GHOSTTY_ZIG_DIR} "
+      "(exit ${adhdev_clean_result}): ${adhdev_clean_output}\n"
+      "A release build must start from empty caches. Remove the directory by hand, "
+      "and make sure no other process is using it.")
+  endif()
+endif()
+file(MAKE_DIRECTORY "${ADHDEV_ZIG_GLOBAL_CACHE}" "${ADHDEV_ZIG_LOCAL_CACHE}" "${ADHDEV_GHOSTTY_PREFIX}/include")
+if(DEFINED ENV{ZIG_GLOBAL_CACHE_DIR} OR DEFINED ENV{ZIG_LOCAL_CACHE_DIR})
+  message(STATUS "ghostty-vt-node: ZIG_GLOBAL_CACHE_DIR / ZIG_LOCAL_CACHE_DIR are ignored; zig uses the private caches in ${ADHDEV_GHOSTTY_ZIG_DIR}")
+endif()
+
+# Upstream's zig flags: build types with optimization map to ReleaseFast.
+set(ADHDEV_GHOSTTY_ZIG_FLAGS -Demit-lib-vt ${GHOSTTY_ZIG_BUILD_FLAGS})
+string(TOUPPER "${CMAKE_BUILD_TYPE}" adhdev_build_type)
+if(adhdev_build_type STREQUAL "RELEASE" OR adhdev_build_type STREQUAL "MINSIZEREL" OR adhdev_build_type STREQUAL "RELWITHDEBINFO")
+  list(APPEND ADHDEV_GHOSTTY_ZIG_FLAGS "-Doptimize=ReleaseFast")
+endif()
+
+# The library names upstream's CMake wrapper uses at the pinned revision.
+if(APPLE)
+  set(GHOSTTY_VT_SONAME "libghostty-vt.0.dylib")
+  set(GHOSTTY_VT_SHARED_LIBRARY "${ADHDEV_GHOSTTY_PREFIX}/lib/libghostty-vt.0.1.0.dylib")
+elseif(WIN32)
+  set(GHOSTTY_VT_SHARED_LIBRARY "${ADHDEV_GHOSTTY_PREFIX}/bin/ghostty-vt.dll")
+  set(GHOSTTY_VT_IMPLIB "${ADHDEV_GHOSTTY_PREFIX}/lib/ghostty-vt.lib")
+else()
+  set(GHOSTTY_VT_SONAME "libghostty-vt.so.0")
+  set(GHOSTTY_VT_SHARED_LIBRARY "${ADHDEV_GHOSTTY_PREFIX}/lib/libghostty-vt.so.0.1.0")
+endif()
+
+if(ADHDEV_GHOSTTY_RELEASE_ELIGIBLE)
+  set(ADHDEV_VERIFY_GHOSTTY_COMMAND
+    "${CMAKE_COMMAND}" "-DGIT=${GIT_EXECUTABLE}" "-DSRC=${ghostty_SOURCE_DIR}"
+    "-DPIN=${ADHDEV_GHOSTTY_PINNED_REVISION}" -P "${ADHDEV_VERIFY_GHOSTTY_SCRIPT}")
+else()
+  set(ADHDEV_VERIFY_GHOSTTY_COMMAND "${CMAKE_COMMAND}" -E echo "ghostty-vt-node: non-release build, source not re-verified")
+endif()
+add_custom_target(adhdev_ghostty_runtime
+  COMMAND ${ADHDEV_VERIFY_GHOSTTY_COMMAND}
+  COMMAND "${ZIG_EXECUTABLE}" build ${ADHDEV_GHOSTTY_ZIG_FLAGS}
+    --prefix "${ADHDEV_GHOSTTY_PREFIX}"
+    --cache-dir "${ADHDEV_ZIG_LOCAL_CACHE}"
+    --global-cache-dir "${ADHDEV_ZIG_GLOBAL_CACHE}"
+  COMMAND ${ADHDEV_VERIFY_GHOSTTY_COMMAND}
+  BYPRODUCTS "${GHOSTTY_VT_SHARED_LIBRARY}" ${GHOSTTY_VT_IMPLIB}
+  WORKING_DIRECTORY "${ghostty_SOURCE_DIR}"
+  COMMENT "Building libghostty-vt with zig (always; private caches and prefix)"
+  VERBATIM
+)
+
+add_library(ghostty-vt SHARED IMPORTED GLOBAL)
+set_target_properties(ghostty-vt PROPERTIES
+  IMPORTED_LOCATION "${GHOSTTY_VT_SHARED_LIBRARY}"
+  INTERFACE_INCLUDE_DIRECTORIES "${ADHDEV_GHOSTTY_PREFIX}/include"
+)
+if(APPLE)
+  set_target_properties(ghostty-vt PROPERTIES IMPORTED_SONAME "@rpath/${GHOSTTY_VT_SONAME}")
+elseif(WIN32)
+  set_target_properties(ghostty-vt PROPERTIES IMPORTED_IMPLIB "${GHOSTTY_VT_IMPLIB}")
+else()
+  set_target_properties(ghostty-vt PROPERTIES IMPORTED_SONAME "${GHOSTTY_VT_SONAME}")
+endif()
+add_dependencies(ghostty-vt adhdev_ghostty_runtime)
+
 add_library(${PROJECT_NAME} SHARED
   src/addon.cc
   src/ghostty_bridge.c
 )
+add_dependencies(${PROJECT_NAME} adhdev_ghostty_runtime)
 
 set(GHOSTTY_VT_RUNTIME_ALIAS "${CMAKE_SHARED_LIBRARY_PREFIX}ghostty-vt${CMAKE_SHARED_LIBRARY_SUFFIX}")
 
@@ -39,9 +288,44 @@ target_include_directories(${PROJECT_NAME} PRIVATE
   ${NODE_ADDON_API_DIR}
 )
 
+# Binding source digest, embedded so a compiled binary can be matched against
+# the sources it was built from. scripts/binding-digest.mjs implements the same
+# algorithm: per file "<path>:<sha256 of LF-normalized content>\n", in this
+# order, then sha256 of the concatenation. Reconfigure whenever an input
+# changes so an incremental compile never embeds a stale digest.
+set(ADHDEV_BINDING_DIGEST_INPUTS
+  CMakeLists.txt
+  toolchain.json
+  src/addon.cc
+  src/ghostty_bridge.c
+  src/ghostty_bridge.h
+  scripts/clean-dir.cjs
+)
+set(ADHDEV_BINDING_DIGEST_MANIFEST "")
+foreach(input IN LISTS ADHDEV_BINDING_DIGEST_INPUTS)
+  file(READ "${CMAKE_CURRENT_SOURCE_DIR}/${input}" input_content)
+  string(REPLACE "\r\n" "\n" input_content "${input_content}")
+  string(SHA256 input_hash "${input_content}")
+  string(APPEND ADHDEV_BINDING_DIGEST_MANIFEST "${input}:${input_hash}\n")
+  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/${input}")
+endforeach()
+string(SHA256 ADHDEV_BINDING_SOURCE_DIGEST "${ADHDEV_BINDING_DIGEST_MANIFEST}")
+message(STATUS "ghostty-vt-node binding source digest: ${ADHDEV_BINDING_SOURCE_DIGEST}")
+
 target_compile_definitions(${PROJECT_NAME} PRIVATE
   NAPI_DISABLE_CPP_EXCEPTIONS
+  NAPI_VERSION=8
   GHOSTTY_STATIC
+  ADHDEV_GHOSTTY_SOURCE_DIGEST="${ADHDEV_BINDING_SOURCE_DIGEST}"
+  ADHDEV_GHOSTTY_GIT_TAG="${GHOSTTY_GIT_TAG}"
+  ADHDEV_GHOSTTY_RELEASE_ELIGIBLE=${ADHDEV_GHOSTTY_RELEASE_ELIGIBLE}
+  ADHDEV_GHOSTTY_PROVENANCE_PROBLEMS="${ADHDEV_PROVENANCE_PROBLEMS_TEXT}"
+  ADHDEV_GHOSTTY_SOURCE_REVISION="${ADHDEV_GHOSTTY_SOURCE_REVISION}"
+  ADHDEV_GHOSTTY_SOURCE_CLEAN=${ADHDEV_GHOSTTY_SOURCE_CLEAN}
+  ADHDEV_GHOSTTY_ZIG_VERSION="${ADHDEV_ZIG_VERSION}"
+  ADHDEV_GHOSTTY_C_COMPILER="${CMAKE_C_COMPILER_ID} ${CMAKE_C_COMPILER_VERSION}"
+  ADHDEV_GHOSTTY_CXX_COMPILER="${CMAKE_CXX_COMPILER_ID} ${CMAKE_CXX_COMPILER_VERSION}"
+  ADHDEV_GHOSTTY_BUILD_TYPE="${CMAKE_BUILD_TYPE}"
 )
 
 target_link_libraries(${PROJECT_NAME} PRIVATE

package/README.md

@@ -52,28 +52,170 @@ Unable to load @adhdev/ghostty-vt-node native binding for running triplet
 linux-x64-node137, win32-x64-node137]. ...
 ```
 
+## Viewport / cursor / cell reads (API level 2)
+
+Each terminal handle also exposes an exact-read API. All rows and the cursor are
+in an explicit coordinate space; nothing is derived from formatter strings.
+
+- `getViewport({ includeRows: 'none' | 'cursor' | 'all', cells })` — one native
+  snapshot: `cursorRow`/`cursorCol` (ACTIVE space), `activeScreen`
+  (`'primary'`/`'alternate'`), `scrollbar` (`total`/`offset`/`len`), the derived
+  `scrollbackRows` / `activeOriginRow` / `viewportOriginRow` /
+  `viewportScrollbackOffset` / `cursorViewportRow`, a per-terminal `revision`,
+  and the requested ACTIVE rows. Metadata and rows come from the same call.
+- `readRow(row, { space: 'active' | 'viewport', cells, expectedRevision })` — one
+  row with `wrapped` / `wrapContinuation`; with `cells`, exactly `cols` cells of
+  `{ col, text, width, wideKind }` (`text` is the full stored grapheme).
+- `scrollViewport('top' | 'bottom' | delta)` — moves the VIEWPORT only; ACTIVE
+  rows and `cursorRow` do not change.
+
+**ACTIVE vs VIEWPORT.** ACTIVE is the rows x cols area the cursor moves in.
+VIEWPORT is what is visible and differs only while scrolled into history.
+`formatPlainText()` output is SCREEN-origin (history + active, trailing blank
+rows dropped): the cursor's row is at index `activeOriginRow + cursorRow` there,
+not at `cursorRow`. The legacy `formatPlainText` / `formatVT` /
+`getCursorPosition` outputs are unchanged (see `test/fixtures/legacy-golden.json`).
+
+**Feature detection.** A binary built before API level 2 still loads and serves
+the legacy methods but has no `getViewport`/`readRow`/`scrollViewport`. Check
+`require('@adhdev/ghostty-vt-node').capabilities.viewport` (or `typeof
+handle.getViewport === 'function'`) and treat exact reads as unavailable —
+never fall back to guessing from formatter output. `bindingInfo` reports the
+loaded binary's `apiLevel`, embedded `sourceDigest` and `ghosttyRevision`.
+
+Every method on a terminal handle owns a share of the native state, so a method
+taken off the handle (`const get = t.getViewport`) keeps working after the
+handle is garbage-collected; the terminal is freed when the last of them is.
+After `dispose()` every method throws `ERR_GHOSTTY_DISPOSED`.
+
 ## Producing / refreshing a prebuilt
 
 Build on the **target platform/arch** (cross-builds are not wired here) with the
-toolchain present (`cmake`, a C/C++ compiler, and `zig` for `libghostty`; set
-`ZIG_EXECUTABLE` if zig is not on `PATH`):
+toolchain present (`cmake`, `git`, a C/C++ compiler, and the zig version pinned
+in `toolchain.json` for `libghostty`; set `ZIG_EXECUTABLE` if zig is not on
+`PATH`).
+
+The configure step verifies the build's provenance and fails on any problem:
+ghostty must come from the FetchContent-managed clone (a
+`FETCHCONTENT_SOURCE_DIR_GHOSTTY` substitute or a `GHOSTTY_GIT_TAG` override is
+refused) at the pinned revision with a clean tree; `zig version` must print
+exactly the `toolchain.json` version (only surrounding whitespace is trimmed);
+and `GHOSTTY_ZIG_BUILD_FLAGS` must be empty. Upstream's CMake wrapper is not
+used: the `adhdev_ghostty_runtime` target runs `zig build` itself on every
+build, with a private global cache, local cache and install prefix inside the
+build tree (`build/ghostty-zig/`; passed as `--global-cache-dir`, `--cache-dir`
+and `--prefix`, so `ZIG_GLOBAL_CACHE_DIR` / `ZIG_LOCAL_CACHE_DIR` are ignored),
+and re-verifies the pinned, clean source before and after. For a release build
+configure empties those caches first (with `scripts/clean-dir.cjs`, because
+CMake's own removal stops on the `._.` files zig extracts on Windows; if
+anything survives, configure fails), so every dependency is fetched afresh
+(zig verifies its package hash on fetch) and everything is compiled from
+scratch: a stale `zig-out/`, a reused build directory or a poisoned shared zig
+cache cannot reach the shipped runtime. What this does NOT cover: the zig
+installation itself (only its version is checked) and concurrent writers.
+The checks are check-then-use, so a release build needs exclusive ownership of
+its build tree, the ghostty clone and the zig installation for the whole
+configure + build; build release prebuilts where no other process writes to
+them. For local experiments only, `ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD=1` turns
+a failure into a warning, and ALWAYS makes the build non-release: the binary
+reports `releaseEligible: false` with its problem codes (at least
+`unverified-dev-build`), and every release gate refuses it (`non-release`). The
+addon also records the zig version, C/C++ compiler id and version, and build
+type (`getBindingInfo()`, copied into the manifest).
+`scripts/probe-build-provenance.mjs <dir>` exercises all of this against a
+configured build in `<dir>/build`: stale runtime, poisoned ambient and private
+zig caches (including a control showing the poison breaks a build that keeps
+them), reconfigure, source edit, dev override, zig output parsing and source
+override. It rebuilds twice from empty caches, so it needs network access and
+about 1 GiB of free disk. Two fresh builds differ only in per-build debug
+metadata (cache object paths, mtimes, image id, signature), so it compares
+runtimes from different builds by their loaded sections.
 
 ```bash
-# Build for the running platform-arch and emit it into prebuilt/<triplet>/
-ADHDEV_GHOSTTY_VT_EMIT_PREBUILT=1 npm run build -w oss/packages/ghostty-vt-node
+# Compile from source and emit into the committed prebuilt for this
+# platform-arch (prebuilt/<platform>-<arch>-node137/, whatever Node version runs
+# the build), stamping prebuilt/<triplet>/manifest.json from the built binary:
+ADHDEV_GHOSTTY_VT_FORCE_COMPILE=1 ADHDEV_GHOSTTY_VT_EMIT_PREBUILT=1 npm run build -w oss/packages/ghostty-vt-node
+
+# Or, after any build: copy build/Release into the committed triplet + stamp
+node oss/packages/ghostty-vt-node/scripts/prebuilt-manifest.mjs emit
 
-# Then keep the node137-named dir (per ABI-portability) and commit it:
-#   git add oss/packages/ghostty-vt-node/prebuilt/<platform>-<arch>-node137/
+# Verify exactly that directory, then the whole set
+node oss/packages/ghostty-vt-node/scripts/verify-prebuilt.mjs oss/packages/ghostty-vt-node/prebuilt/<triplet>
+node oss/packages/ghostty-vt-node/scripts/check-prebuilts.mjs
 ```
 
-Because the output is ABI-portable, you only need to build **once per
-platform/arch**; rename/keep the directory as the `node137` triplet and the
-runtime fallback covers all other Node versions on that platform.
+With `ADHDEV_GHOSTTY_VT_FORCE_COMPILE=1` the build is a clean `cmake-js
+rebuild` (fresh configure and clone); `build/` is removed with
+`scripts/clean-dir.cjs` first, and the build stops if that fails. Without it, `npm run build` keeps an
+existing local build or copies a usable prebuilt, or compiles incrementally
+(`--plan` prints which it would do).
+
+Binaries embed absolute build paths (the private zig caches live in the build
+tree), so a prebuilt you commit must be built outside any home directory, from
+a fresh clone of the commit being stamped. Copy the package to a neutral
+directory and point `HOME` there for cmake-js' Node headers (shown for
+macOS/Linux; on Windows use e.g. `C:\gvn` and `C:\gvn-home` for
+`HOME`/`USERPROFILE`, with zig installed outside the user profile). The zig
+caches need no setup: the build always uses fresh private ones. Do not set
+`FETCHCONTENT_SOURCE_DIR_GHOSTTY`, `GHOSTTY_GIT_TAG`, `GHOSTTY_ZIG_BUILD_FLAGS`
+or `ADHDEV_GHOSTTY_UNVERIFIED_DEV_BUILD`, and let nothing else write to these
+directories during the build. On Windows, remove a previous `C:\gvn` with
+`node oss\packages\ghostty-vt-node\scripts\clean-dir.cjs C:\gvn`: `rmdir /s`
+and CMake cannot delete the `._.` files an earlier build's zig cache holds.
+
+```bash
+rm -rf /tmp/gvn /tmp/gvn-home && mkdir -p /tmp/gvn/node_modules /tmp/gvn-home
+rsync -a --exclude node_modules --exclude prebuilt --exclude build oss/packages/ghostty-vt-node/ /tmp/gvn/
+cp -R oss/node_modules/node-addon-api /tmp/gvn/node_modules/   # or the package-local copy
+(cd /tmp/gvn && HOME=/tmp/gvn-home node "$OLDPWD/oss/node_modules/cmake-js/bin/cmake-js" rebuild)
+node oss/packages/ghostty-vt-node/scripts/probe-build-provenance.mjs /tmp/gvn   # optional, expect 13/13
+node oss/packages/ghostty-vt-node/scripts/prebuilt-manifest.mjs emit /tmp/gvn/build/Release
+node oss/packages/ghostty-vt-node/scripts/check-prebuilts.mjs
+```
 
 - macOS arm64 and Linux x64 can be produced on the corresponding native runner.
 - Windows x64 must be built on a Windows runner (MSVC; see the `if(MSVC)` block in
   `CMakeLists.txt` for the required dynamic-CRT link flags).
 
+### Release-safety gate (`scripts/check-prebuilts.mjs`)
+
+CMake embeds a **binding source digest** (sha256 over `CMakeLists.txt`,
+`toolchain.json` and `src/*`, LF-normalized; `scripts/binding-digest.mjs`
+reproduces it) and the build provenance into the addon. Each shipped prebuilt
+carries a `manifest.json` (schema 2) stamped from the binary itself plus file
+hashes. The gate fails unless:
+
+- (a) all three shipped triplets carry a manifest matching the current digest,
+  API level, ghostty pin and zig pin, with matching file hashes, stamped as a
+  release build from the pinned, clean ghostty checkout. A triplet built from
+  older sources, another zig, or an older manifest schema reports
+  **pending-rebuild**: after any bridge/addon/toolchain change the tree is not
+  shippable until every platform is rebuilt and re-stamped. Without loading
+  anything (release CI runs on Linux), the manifest's platform/arch must match
+  the directory, the platform's runtime set must be complete (darwin: addon +
+  `libghostty-vt.dylib` + `libghostty-vt.X.Y.Z.dylib`; linux: addon +
+  `libghostty-vt.so`, `.so.0`, `.so.0.X.Y`; win32: addon + `ghostty-vt.dll`),
+  and every file must be a thin Mach-O arm64 / ELF x86-64 (SONAME
+  `libghostty-vt.so.0`, NEEDed by the addon) / PE32+ x64 DLL
+  (`scripts/native-format.mjs`).
+- (b) the host platform's committed prebuilt, loaded by path, embeds the
+  current digest and release provenance, and its viewport API behaves.
+- (c) the native CI build compiles from source (`ADHDEV_GHOSTTY_VT_FORCE_COMPILE`)
+  as a clean `cmake-js rebuild` with the zig read from `toolchain.json` and no
+  restored zig cache (`setup-zig` `use-cache: false`, no `ZIG_*_CACHE_DIR`),
+  verifies + stamps the exact staged
+  artifact, and the release job checks every prebuilt it publishes
+  (`--all-present`).
+- (d) no shipped native file (`.node`/`.dylib`/`.so*`/`.dll`) embeds a
+  home-directory path (`/Users/<name>/`, `/home/<name>/`, `X:\Users\<name>\`),
+  scanned as raw bytes in ASCII and UTF-16LE (`scripts/host-path-scan.mjs`; CI
+  accounts `runner`/`runneradmin` are allowed). Build prebuilts from a neutral
+  directory with a neutral zig cache (`ZIG_GLOBAL_CACHE_DIR`). Extra literals
+  (hostnames) can be denied from an untracked file named by
+  `ADHDEV_GHOSTTY_HOST_PATH_DENYLIST` or `.host-path-denylist` in this package.
+  `verify-prebuilt.mjs` runs the same scan on the directory it verifies.
+
 ## Skipping the native build
 
 Set `ADHDEV_SKIP_GHOSTTY_VT_BUILD=1` to skip compilation when no prebuilt matches

package/binding-candidates.js

@@ -0,0 +1,40 @@
+'use strict';
+// Pure candidate-ordering logic for the native binding loader (index.js).
+// No native loading happens here so the selection rules are unit-testable with
+// fake directory listings.
+//
+// Selection rule for prebuilt triplet directories of the host platform-arch:
+//   1. highest manifest `apiLevel` first (a directory without a readable
+//      manifest counts as level 0 — never preferred over a manifest-bearing
+//      one, which is how a stale pre-API-2 binary loses to the current one even
+//      when its Node ABI number matches the running Node exactly),
+//   2. then the exact running ABI (`...-node<abi>`),
+//   3. then the higher ABI number, then name, for determinism.
+// Foreign platform/arch directories (test-isolation fallback) come last.
+
+function parseAbi(name) {
+    const match = /-node(\d+)$/.exec(name);
+    return match ? Number(match[1]) : -1;
+}
+
+function orderPrebuiltTriplets({ names, platform, arch, abi, readApiLevel }) {
+    const prefix = `${platform}-${arch}-`;
+    const exact = `${platform}-${arch}-node${abi}`;
+    const level = (name) => {
+        const value = readApiLevel(name);
+        return Number.isFinite(value) ? value : 0;
+    };
+    const rank = (list) =>
+        list
+            .map((name) => ({ name, level: level(name), exact: name === exact ? 1 : 0, abi: parseAbi(name) }))
+            .sort((a, b) => b.level - a.level || b.exact - a.exact || b.abi - a.abi || a.name.localeCompare(b.name));
+    const same = names.filter((name) => name.startsWith(prefix));
+    const other = names.filter((name) => !name.startsWith(prefix));
+    return {
+        samePlatform: rank(same).map((entry) => entry.name),
+        bestApiLevel: same.length ? Math.max(...same.map(level)) : 0,
+        otherPlatform: other.slice().sort(),
+    };
+}
+
+module.exports = { orderPrebuiltTriplets };

package/index.d.ts

@@ -8,6 +8,97 @@ export type GhosttyPlainTextFormatOptions = {
   trim?: boolean;
 };
 
+/**
+ * Coordinate space of a row index.
+ * - `active`: the rows x cols area the cursor moves in. `cursorRow` is in this
+ *   space, and it does not move when the user scrolls through history.
+ * - `viewport`: the visible area. Equal to `active` unless the viewport is
+ *   scrolled into history (`viewportScrollbackOffset > 0`).
+ */
+export type GhosttyCoordinateSpace = 'active' | 'viewport';
+
+export type GhosttyCellWideKind = 'narrow' | 'wide' | 'spacer-tail' | 'spacer-head';
+
+export type GhosttyCell = {
+  /** Physical cell column, 0-based. */
+  col: number;
+  /** The cell's full grapheme cluster as stored natively; '' for empty cells and spacers. */
+  text: string;
+  /** 2 for a wide lead cell, 0 for spacers, 1 otherwise. */
+  width: 0 | 1 | 2;
+  wideKind: GhosttyCellWideKind;
+};
+
+export type GhosttyRow = {
+  /** Row index, 0-based, in `coordinateSpace`. */
+  row: number;
+  coordinateSpace: GhosttyCoordinateSpace;
+  /**
+   * Row text. Empty cells before content read as U+0020; the trailing run of
+   * content-less cells is omitted; spacer cells contribute nothing. For
+   * readability only — `cells` is the authority for columns.
+   */
+  text: string;
+  /** This row soft-wraps into the next physical row. */
+  wrapped: boolean;
+  /** This row continues a soft-wrap from the previous physical row. */
+  wrapContinuation: boolean;
+  /** Exactly `cols` entries, present when requested. */
+  cells?: GhosttyCell[];
+};
+
+export type GhosttyViewportOptions = {
+  /** Rows to include: none (default), the cursor's row, or all ACTIVE rows. */
+  includeRows?: 'none' | 'cursor' | 'all';
+  cells?: boolean;
+};
+
+export type GhosttyScrollbar = {
+  /** Rows in the selected screen: retained history + active area. */
+  total: number;
+  /** Row of `total` at which the visible viewport starts. */
+  offset: number;
+  /** Visible rows. */
+  len: number;
+};
+
+/** One native snapshot; every field describes the same terminal state. */
+export type GhosttyViewport = {
+  /** Per-terminal mutation counter (write/resize/scrollViewport). */
+  revision: number;
+  /** Space of `cursorRow` and of every entry in `lines`. Always 'active'. */
+  coordinateSpace: 'active';
+  rows: number;
+  cols: number;
+  cursorRow: number;
+  cursorCol: number;
+  cursorPendingWrap: boolean;
+  /** DEC mode 25; says nothing about whether the cursor is in the viewport. */
+  cursorVisible: boolean;
+  activeScreen: 'primary' | 'alternate';
+  scrollbar: GhosttyScrollbar;
+  /** Retained history rows of the selected screen (scrollbar.total - scrollbar.len). */
+  scrollbackRows: number;
+  /** Screen row at which the ACTIVE area starts. */
+  activeOriginRow: number;
+  /** Screen row at which the VIEWPORT starts (scrollbar.offset). */
+  viewportOriginRow: number;
+  /** How many rows the viewport is scrolled up from the active area. */
+  viewportScrollbackOffset: number;
+  /** Cursor row in VIEWPORT space, or null when the cursor is scrolled out of view. */
+  cursorViewportRow: number | null;
+  /** ACTIVE rows: all of them, or just the cursor's row, per `includeRows`. */
+  lines?: GhosttyRow[];
+};
+
+export type GhosttyReadRowOptions = {
+  cells?: boolean;
+  /** Defaults to 'active'. */
+  space?: GhosttyCoordinateSpace;
+  /** Throw ERR_GHOSTTY_STALE_REVISION unless the terminal is still at this revision. */
+  expectedRevision?: number;
+};
+
 export interface GhosttyTerminalHandle {
   write(data: string | Uint8Array): void;
   resize(cols: number, rows: number): void;
@@ -15,6 +106,22 @@ export interface GhosttyTerminalHandle {
   formatVT(): string;
   getCursorPosition(): { col: number; row: number };
   dispose(): void;
+  // API level 2. Absent on older binaries: check `capabilities.viewport`.
+  getViewport?(options?: GhosttyViewportOptions): GhosttyViewport;
+  readRow?(row: number, options?: GhosttyReadRowOptions): GhosttyRow & { revision: number };
+  scrollViewport?(target: 'top' | 'bottom' | number): void;
 }
 
+export type GhosttyBindingInfo = {
+  /** 1 for binaries that predate getBindingInfo. */
+  apiLevel: number;
+  /** Binding source digest embedded at compile time (scripts/binding-digest.mjs). */
+  sourceDigest: string | null;
+  ghosttyRevision: string | null;
+  napiVersion: number | null;
+};
+
 export function createTerminal(options: GhosttyTerminalOptions): GhosttyTerminalHandle;
+
+export const bindingInfo: GhosttyBindingInfo;
+export const capabilities: Readonly<{ viewport: boolean }>;