@termwright/probe-ink 0.2.0 → 0.3.0

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":[]}