@termwright/probe-ink 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @termwright/probe-ink
 
-Zero-config semantics for an Ink 7 application that imports nothing from
+Zero-config semantics for an exact-certified Ink application that imports nothing from
 termwright. The application keeps its normal `import {render} from 'ink'` and
 normal `render(<App />)` call; the launcher adds one preload flag.
 
@@ -10,12 +10,15 @@ normal `render(<App />)` call; the launcher adds one preload flag.
 npm install --save-dev @termwright/probe-ink
 ```
 
-Peers: `ink >= 7.1 < 8`, React >= 19.2. Node >= 22, or Bun.
+Peers: an exact Ink version listed in the compatibility registry, React >= 19.2,
+Node >= 22, or Bun. The Ink version is exact:
+the preload verifies both instrumented upstream modules by SHA-256 before it
+negotiates semantic capabilities.
 
 ```ts
-import {withProbe} from '@termwright/probe-ink';
+import { withProbe } from '@termwright/probe-ink';
 
-const {command} = withProbe('node', ['node', 'app.mjs']);
+const { command } = withProbe('node', ['node', 'app.mjs']);
 await launchTerminal({
   command,
   env: {
@@ -27,7 +30,9 @@ await launchTerminal({
 
 For Bun, pass `withProbe('bun', ['bun', 'app.tsx'])`; the launcher places
 `--preload` before the application entry, where Bun requires it. Node uses
-`--import`. The returned preload path is a `file://` URL, including on Windows.
+`--import`. Node receives a `file://` preload URL, including on Windows; Bun
+receives a native absolute path because its Windows preload resolver does not
+load `file://` entries.
 
 Early Node 22 releases do not have `module.registerHooks`; the preload detects
 that case and uses `module.register`. It does not change Node's warning policy.
@@ -37,10 +42,10 @@ without the probe, and byte parity retains it.
 ## Dormant and failure behaviour
 
 Without both `TERMWRIGHT_ENDPOINT` and `TERMWRIGHT_TOKEN`, the preload installs
-no loader hook and `ink.render` is untouched. If the driver is unavailable or
-the observed Ink internals move, semantics disable themselves and the
-application continues. Process tests assert byte identity for dormant and
-faulted runs under both Node and Bun.
+no loader hook and `ink.render` is untouched. If either Ink artifact does not
+match 7.1.1 exactly, the adapter does not attach or advertise a partial
+contract. An unreachable driver remains isolated from the application. Process
+tests assert byte identity for dormant and faulted runs under Node and Bun.
 
 ## What is observed
 
@@ -68,12 +73,25 @@ marker last. A newer render that arrives during drain suppresses the stale
 marker. Instrumented output is byte-identical to vanilla output after those
 markers are removed.
 
-Bounds are published only when Ink runs interactively in the alternate screen
-buffer and no `<Static>` content shifts the live region. Otherwise coordinates
-are omitted rather than reported as terminal-absolute when they are not.
-With `TERMWRIGHT_PROTOCOL=termwright/2`, those facts use tagged observations:
-display is known, intended bounds are known or explicitly unsupported, and
-visible clipping plus pointer ownership are unsupported rather than inferred.
+The checksummed renderer hook records Yoga rectangles and the same nested
+overflow intersections used by `render-node-to-output`. A paired output tracker
+maps those relative rectangles into the committed normal or alternate VT
+viewport. It handles terminal wrapping, wide cells, resize, fullscreen scroll,
+and `<Static>` output retained above the live region. Hidden nodes publish
+authoritative absence instead of fabricated zero-sized boxes. Every marker is
+written only after the corresponding output bytes drain.
+
+Ink does not expose pointer ownership. Bounds therefore do not enable click,
+hover, or drag by themselves. Those actions require an application evidence
+provider that publishes revision-bound pointer regions and a native hit test;
+device input still travels through the real PTY.
+
+Ink instrumentation also does not automatically certify terminal input modes.
+Its output shadow sees JavaScript `stream.write` calls, but direct descriptor or
+native writes and inherited descendant output bypass that surface. On ConPTY,
+where the transport hides DEC mouse/focus negotiation, an opaque Ink child
+therefore remains fail-closed. Hidden-mode pointer/focus input requires an
+explicit provider backed by the application's production input-mode state.
 
 ## Deliberate limits
 

package/dist/bun-preload.js

@@ -2,12 +2,19 @@ import {
   INK_ENTRY_PATTERN,
   buildShimSource,
   shouldShim
-} from "./chunk-IUFXTMZ7.js";
+} from "./chunk-CLY2SLYH.js";
 import {
   isInstrumented
-} from "./chunk-LO7YF74P.js";
+} from "./chunk-67M2GX5S.js";
+import {
+  INK_CORE_PATTERN,
+  INK_RENDERER_PATTERN,
+  instrumentInkCore,
+  instrumentInkRenderer
+} from "./chunk-SLKX554P.js";
 
 // src/bun-preload.ts
+import { readFile } from "fs/promises";
 function installBunPreload(env = process.env) {
   if (!isInstrumented(env)) return false;
   const bun = globalThis.Bun;
@@ -19,6 +26,16 @@ function installBunPreload(env = process.env) {
         if (!shouldShim(args.path)) return void 0;
         return { loader: "js", contents: buildShimSource(args.path) };
       });
+      build.onLoad({ filter: INK_RENDERER_PATTERN }, async (args) => {
+        const source = await readFile(args.path, "utf8");
+        const contents = instrumentInkRenderer(args.path, source);
+        return contents === void 0 ? void 0 : { loader: "js", contents };
+      });
+      build.onLoad({ filter: INK_CORE_PATTERN }, async (args) => {
+        const source = await readFile(args.path, "utf8");
+        const contents = instrumentInkCore(args.path, source);
+        return contents === void 0 ? void 0 : { loader: "js", contents };
+      });
     }
   });
   return true;

package/dist/bun-preload.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/bun-preload.ts"],"sourcesContent":["/** Bun entry: `bun --preload @termwright/probe-ink/bun-preload app.js`. */\n\nimport { buildShimSource, INK_ENTRY_PATTERN, shouldShim } from './shim.js';\nimport { isInstrumented } from './runtime.js';\n\ninterface BunPluginBuild {\n  onLoad(\n    options: { filter: RegExp },\n    callback: (args: { path: string }) => Promise<{ loader: string; contents: string } | undefined>,\n  ): void;\n}\n\ninterface BunGlobal {\n  plugin(definition: { name: string; setup(build: BunPluginBuild): void }): void;\n}\n\n/** Register the Ink entry replacement before the application's first import. */\nexport function installBunPreload(\n  env: Record<string, string | undefined> = process.env,\n): boolean {\n  if (!isInstrumented(env)) return false;\n  const bun = (globalThis as { Bun?: BunGlobal }).Bun;\n  if (bun === undefined) return false;\n\n  bun.plugin({\n    name: 'termwright-ink',\n    setup(build) {\n      build.onLoad({ filter: INK_ENTRY_PATTERN }, async (args) => {\n        if (!shouldShim(args.path)) return undefined;\n        return { loader: 'js', contents: buildShimSource(args.path) };\n      });\n    },\n  });\n  return true;\n}\n\ninstallBunPreload();\n"],"mappings":";;;;;;;;;;AAiBO,SAAS,kBACd,MAA0C,QAAQ,KACzC;AACT,MAAI,CAAC,eAAe,GAAG,EAAG,QAAO;AACjC,QAAM,MAAO,WAAmC;AAChD,MAAI,QAAQ,OAAW,QAAO;AAE9B,MAAI,OAAO;AAAA,IACT,MAAM;AAAA,IACN,MAAM,OAAO;AACX,YAAM,OAAO,EAAE,QAAQ,kBAAkB,GAAG,OAAO,SAAS;AAC1D,YAAI,CAAC,WAAW,KAAK,IAAI,EAAG,QAAO;AACnC,eAAO,EAAE,QAAQ,MAAM,UAAU,gBAAgB,KAAK,IAAI,EAAE;AAAA,MAC9D,CAAC;AAAA,IACH;AAAA,EACF,CAAC;AACD,SAAO;AACT;AAEA,kBAAkB;","names":[]}
+{"version":3,"sources":["../src/bun-preload.ts"],"sourcesContent":["/** Bun entry: `bun --preload @termwright/probe-ink/bun-preload app.js`. */\n\nimport { buildShimSource, INK_ENTRY_PATTERN, shouldShim } from './shim.js';\nimport { readFile } from 'node:fs/promises';\nimport {\n  instrumentInkCore,\n  instrumentInkRenderer,\n  INK_CORE_PATTERN,\n  INK_RENDERER_PATTERN,\n} from './instrumentation.js';\nimport { isInstrumented } from './runtime.js';\n\ninterface BunPluginBuild {\n  onLoad(\n    options: { filter: RegExp },\n    callback: (args: { path: string }) => Promise<{ loader: string; contents: string } | undefined>,\n  ): void;\n}\n\ninterface BunGlobal {\n  plugin(definition: { name: string; setup(build: BunPluginBuild): void }): void;\n}\n\n/** Register the Ink entry replacement before the application's first import. */\nexport function installBunPreload(env: Record<string, string | undefined> = process.env): boolean {\n  if (!isInstrumented(env)) return false;\n  const bun = (globalThis as { Bun?: BunGlobal }).Bun;\n  if (bun === undefined) return false;\n\n  bun.plugin({\n    name: 'termwright-ink',\n    setup(build) {\n      build.onLoad({ filter: INK_ENTRY_PATTERN }, async (args) => {\n        if (!shouldShim(args.path)) return undefined;\n        return { loader: 'js', contents: buildShimSource(args.path) };\n      });\n      build.onLoad({ filter: INK_RENDERER_PATTERN }, async (args) => {\n        const source = await readFile(args.path, 'utf8');\n        const contents = instrumentInkRenderer(args.path, source);\n        return contents === undefined ? undefined : { loader: 'js', contents };\n      });\n      build.onLoad({ filter: INK_CORE_PATTERN }, async (args) => {\n        const source = await readFile(args.path, 'utf8');\n        const contents = instrumentInkCore(args.path, source);\n        return contents === undefined ? undefined : { loader: 'js', contents };\n      });\n    },\n  });\n  return true;\n}\n\ninstallBunPreload();\n"],"mappings":";;;;;;;;;;;;;;;;AAGA,SAAS,gBAAgB;AAqBlB,SAAS,kBAAkB,MAA0C,QAAQ,KAAc;AAChG,MAAI,CAAC,eAAe,GAAG,EAAG,QAAO;AACjC,QAAM,MAAO,WAAmC;AAChD,MAAI,QAAQ,OAAW,QAAO;AAE9B,MAAI,OAAO;AAAA,IACT,MAAM;AAAA,IACN,MAAM,OAAO;AACX,YAAM,OAAO,EAAE,QAAQ,kBAAkB,GAAG,OAAO,SAAS;AAC1D,YAAI,CAAC,WAAW,KAAK,IAAI,EAAG,QAAO;AACnC,eAAO,EAAE,QAAQ,MAAM,UAAU,gBAAgB,KAAK,IAAI,EAAE;AAAA,MAC9D,CAAC;AACD,YAAM,OAAO,EAAE,QAAQ,qBAAqB,GAAG,OAAO,SAAS;AAC7D,cAAM,SAAS,MAAM,SAAS,KAAK,MAAM,MAAM;AAC/C,cAAM,WAAW,sBAAsB,KAAK,MAAM,MAAM;AACxD,eAAO,aAAa,SAAY,SAAY,EAAE,QAAQ,MAAM,SAAS;AAAA,MACvE,CAAC;AACD,YAAM,OAAO,EAAE,QAAQ,iBAAiB,GAAG,OAAO,SAAS;AACzD,cAAM,SAAS,MAAM,SAAS,KAAK,MAAM,MAAM;AAC/C,cAAM,WAAW,kBAAkB,KAAK,MAAM,MAAM;AACpD,eAAO,aAAa,SAAY,SAAY,EAAE,QAAQ,MAAM,SAAS;AAAA,MACvE,CAAC;AAAA,IACH;AAAA,EACF,CAAC;AACD,SAAO;AACT;AAEA,kBAAkB;","names":[]}

package/dist/{chunk-LO7YF74P.js → chunk-67M2GX5S.js}

@@ -9,4 +9,4 @@ function isInstrumented(env) {
 export {
   isInstrumented
 };
-//# sourceMappingURL=chunk-LO7YF74P.js.map
+//# sourceMappingURL=chunk-67M2GX5S.js.map

package/dist/{chunk-LO7YF74P.js.map → chunk-67M2GX5S.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/runtime.ts"],"sourcesContent":["/** Runtime activation shared by the two preload entry points. */\n\nimport { ENV_ENDPOINT, ENV_TOKEN } from '@termwright/protocol';\n\n/** Runtimes into which the Ink probe can be injected. */\nexport type ProbeRuntime = 'bun' | 'node';\n\n/** Read-only environment view, so activation is testable without mutation. */\nexport type EnvSource = Readonly<Record<string, string | undefined>>;\n\n/** Both secrets are required. A partial environment remains fully dormant. */\nexport function isInstrumented(env: EnvSource): boolean {\n  const endpoint = env[ENV_ENDPOINT];\n  const token = env[ENV_TOKEN];\n  return typeof endpoint === 'string' && endpoint.length > 0\n    && typeof token === 'string' && token.length > 0;\n}\n"],"mappings":";AAEA,SAAS,cAAc,iBAAiB;AASjC,SAAS,eAAe,KAAyB;AACtD,QAAM,WAAW,IAAI,YAAY;AACjC,QAAM,QAAQ,IAAI,SAAS;AAC3B,SAAO,OAAO,aAAa,YAAY,SAAS,SAAS,KACpD,OAAO,UAAU,YAAY,MAAM,SAAS;AACnD;","names":[]}
+{"version":3,"sources":["../src/runtime.ts"],"sourcesContent":["/** Runtime activation shared by the two preload entry points. */\n\nimport { ENV_ENDPOINT, ENV_TOKEN } from '@termwright/protocol';\n\n/** Runtimes into which the Ink probe can be injected. */\nexport type ProbeRuntime = 'bun' | 'node';\n\n/** Read-only environment view, so activation is testable without mutation. */\nexport type EnvSource = Readonly<Record<string, string | undefined>>;\n\n/** Both secrets are required. A partial environment remains fully dormant. */\nexport function isInstrumented(env: EnvSource): boolean {\n  const endpoint = env[ENV_ENDPOINT];\n  const token = env[ENV_TOKEN];\n  return (\n    typeof endpoint === 'string' &&\n    endpoint.length > 0 &&\n    typeof token === 'string' &&\n    token.length > 0\n  );\n}\n"],"mappings":";AAEA,SAAS,cAAc,iBAAiB;AASjC,SAAS,eAAe,KAAyB;AACtD,QAAM,WAAW,IAAI,YAAY;AACjC,QAAM,QAAQ,IAAI,SAAS;AAC3B,SACE,OAAO,aAAa,YACpB,SAAS,SAAS,KAClB,OAAO,UAAU,YACjB,MAAM,SAAS;AAEnB;","names":[]}

package/dist/{chunk-IUFXTMZ7.js → chunk-CLY2SLYH.js}

@@ -9,14 +9,23 @@ function shouldShim(urlOrPath) {
 function originalUrl(urlOrPath) {
   return `${urlOrPath}${urlOrPath.includes("?") ? "&" : "?"}${ORIGINAL_MARKER}`;
 }
+function reconcilerUrl(urlOrPath) {
+  const [path] = urlOrPath.split("?");
+  if (path === void 0 || !INK_ENTRY_PATTERN.test(path)) {
+    throw new Error(`Cannot resolve Ink reconciler beside ${urlOrPath}`);
+  }
+  return path.replace(/index\.js$/u, "reconciler.js");
+}
 function buildShimSource(target, instrumentUrl = INSTRUMENT_URL) {
   const original = JSON.stringify(originalUrl(target));
+  const reconciler = JSON.stringify(reconcilerUrl(target));
   const instrument = JSON.stringify(instrumentUrl);
   return `import * as __termwright_original from ${original};
+import __termwright_reconciler from ${reconciler};
 import {wrapInkRender as __termwright_wrap} from ${instrument};
 export * from ${original};
 
-export const render = __termwright_wrap(__termwright_original);
+export const render = __termwright_wrap(__termwright_original, {reconciler: __termwright_reconciler});
 `;
 }
 
@@ -26,6 +35,7 @@ export {
   INSTRUMENT_URL,
   shouldShim,
   originalUrl,
+  reconcilerUrl,
   buildShimSource
 };
-//# sourceMappingURL=chunk-IUFXTMZ7.js.map
+//# sourceMappingURL=chunk-CLY2SLYH.js.map

package/dist/chunk-CLY2SLYH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shim.ts"],"sourcesContent":["/** Replacement source for Ink's public entry module. */\n\n/** Marker on the shim's re-import of the untouched module. */\nexport const ORIGINAL_MARKER = 'termwright-original=1';\n\n/**\n * Ink's ESM entry under ordinary node_modules and Bun's versioned cache.\n * Matching the resolved path, rather than the bare specifier, is required by\n * both loader APIs used here.\n */\nexport const INK_ENTRY_PATTERN = /[\\\\/](?:ink|ink@[^\\\\/]+)[\\\\/]build[\\\\/]index\\.js$/u;\n\n/** The separately-built runtime imported by replacement module source. */\nexport const INSTRUMENT_URL = new URL('./instrument.js', import.meta.url).href;\n\nexport function shouldShim(urlOrPath: string): boolean {\n  if (urlOrPath.includes(ORIGINAL_MARKER)) return false;\n  return INK_ENTRY_PATTERN.test(urlOrPath.split('?')[0] ?? '');\n}\n\nexport function originalUrl(urlOrPath: string): string {\n  return `${urlOrPath}${urlOrPath.includes('?') ? '&' : '?'}${ORIGINAL_MARKER}`;\n}\n\n/** Ink's renderer instance, resolved beside the intercepted public entry. */\nexport function reconcilerUrl(urlOrPath: string): string {\n  const [path] = urlOrPath.split('?');\n  if (path === undefined || !INK_ENTRY_PATTERN.test(path)) {\n    throw new Error(`Cannot resolve Ink reconciler beside ${urlOrPath}`);\n  }\n  return path.replace(/index\\.js$/u, 'reconciler.js');\n}\n\n/**\n * Forward the complete Ink namespace and shadow only `render`.\n *\n * The wrapper receives the already-marked original namespace, so the runtime\n * never imports `ink` itself and cannot recurse through the loader hook.\n */\nexport function buildShimSource(target: string, instrumentUrl = INSTRUMENT_URL): string {\n  const original = JSON.stringify(originalUrl(target));\n  const reconciler = JSON.stringify(reconcilerUrl(target));\n  const instrument = JSON.stringify(instrumentUrl);\n  return `import * as __termwright_original from ${original};\nimport __termwright_reconciler from ${reconciler};\nimport {wrapInkRender as __termwright_wrap} from ${instrument};\nexport * from ${original};\n\nexport const render = __termwright_wrap(__termwright_original, {reconciler: __termwright_reconciler});\n`;\n}\n"],"mappings":";AAGO,IAAM,kBAAkB;AAOxB,IAAM,oBAAoB;AAG1B,IAAM,iBAAiB,IAAI,IAAI,mBAAmB,YAAY,GAAG,EAAE;AAEnE,SAAS,WAAW,WAA4B;AACrD,MAAI,UAAU,SAAS,eAAe,EAAG,QAAO;AAChD,SAAO,kBAAkB,KAAK,UAAU,MAAM,GAAG,EAAE,CAAC,KAAK,EAAE;AAC7D;AAEO,SAAS,YAAY,WAA2B;AACrD,SAAO,GAAG,SAAS,GAAG,UAAU,SAAS,GAAG,IAAI,MAAM,GAAG,GAAG,eAAe;AAC7E;AAGO,SAAS,cAAc,WAA2B;AACvD,QAAM,CAAC,IAAI,IAAI,UAAU,MAAM,GAAG;AAClC,MAAI,SAAS,UAAa,CAAC,kBAAkB,KAAK,IAAI,GAAG;AACvD,UAAM,IAAI,MAAM,wCAAwC,SAAS,EAAE;AAAA,EACrE;AACA,SAAO,KAAK,QAAQ,eAAe,eAAe;AACpD;AAQO,SAAS,gBAAgB,QAAgB,gBAAgB,gBAAwB;AACtF,QAAM,WAAW,KAAK,UAAU,YAAY,MAAM,CAAC;AACnD,QAAM,aAAa,KAAK,UAAU,cAAc,MAAM,CAAC;AACvD,QAAM,aAAa,KAAK,UAAU,aAAa;AAC/C,SAAO,0CAA0C,QAAQ;AAAA,sCACrB,UAAU;AAAA,mDACG,UAAU;AAAA,gBAC7C,QAAQ;AAAA;AAAA;AAAA;AAIxB;","names":[]}