@termwright/conformance 0.2.0

package/dist/index.js

@@ -0,0 +1,1129 @@
+// src/adapter-conformance.ts
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join3 } from "path";
+import { ADAPTER_CAPABILITIES, validateSnapshot, DEFAULT_LIMITS as DEFAULT_LIMITS3 } from "@termwright/protocol";
+
+// src/support/probe.ts
+import { createServer } from "net";
+import { readFileSync } from "fs";
+import { mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { join as join2 } from "path";
+import { randomBytes, randomUUID } from "crypto";
+import {
+  DEFAULT_LIMITS as DEFAULT_LIMITS2,
+  ENV_ENDPOINT as ENV_ENDPOINT2,
+  ENV_PROTOCOL,
+  ENV_TOKEN as ENV_TOKEN2,
+  MARKER_OSC_CODE,
+  MARKER_OSC_PREFIX,
+  parseAdapterMessage,
+  PROTOCOL_ID,
+  PROTOCOL_VERSION,
+  applyTreeDelta,
+  createFrameDecoder,
+  encodeFrame,
+  generateToken,
+  verifyMarkerPayload
+} from "@termwright/protocol";
+import xh from "@xterm/headless";
+import { createNodePtyBackend as createNodePtyBackend2 } from "@termwright/driver";
+
+// src/support/pty.ts
+import { spawnSync } from "child_process";
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { launchTerminal, createNodePtyBackend } from "@termwright/driver";
+
+// ../probe-ink/dist/chunk-4KCXY7SI.js
+import { validateProbeAnnotations } from "@termwright/protocol";
+
+// ../recognizers/dist/index.js
+import {
+  DEFAULT_LIMITS,
+  resolveNodeBounds,
+  SEMANTIC_ROLES
+} from "@termwright/protocol";
+var HOST_ROLES = Object.freeze({
+  "ink-root": "application",
+  "ink-text": "text",
+  "ink-virtual-text": "text",
+  "ink-box": "generic"
+});
+function roleForInkHost(host) {
+  return HOST_ROLES[host];
+}
+var ARIA_ROLES = Object.freeze({
+  button: "button",
+  checkbox: "checkbox",
+  combobox: "generic",
+  list: "list",
+  listbox: "list",
+  listitem: "listitem",
+  menu: "menu",
+  menuitem: "menuitem",
+  option: "listitem",
+  progressbar: "progressbar",
+  radio: "radio",
+  radiogroup: "generic",
+  tab: "tab",
+  tablist: "generic",
+  table: "table",
+  textbox: "textbox",
+  timer: "status",
+  toolbar: "generic"
+});
+var ROLE_BY_CLASS = Object.freeze({
+  RootRenderable: "application",
+  TextRenderable: "text",
+  TextNodeRenderable: "text",
+  RootTextNodeRenderable: "text",
+  CodeRenderable: "text",
+  MarkdownRenderable: "text",
+  ASCIIFontRenderable: "text",
+  InputRenderable: "textbox",
+  TextareaRenderable: "textbox",
+  EditBufferRenderable: "textbox",
+  SelectRenderable: "list",
+  TextTableRenderable: "table",
+  ScrollBarRenderable: "scrollbar"
+});
+function roleForOpenTuiClass(frameworkType) {
+  return Object.hasOwn(ROLE_BY_CLASS, frameworkType) ? ROLE_BY_CLASS[frameworkType] : void 0;
+}
+var ROLES = new Set(SEMANTIC_ROLES);
+var UTF8_ENCODER = new TextEncoder();
+var ROLE_MAPS = Object.freeze({ ink: roleForInkHost, opentui: roleForOpenTuiClass });
+
+// ../probe-ink/dist/chunk-IUFXTMZ7.js
+var INSTRUMENT_URL = new URL("./instrument.js", import.meta.url).href;
+
+// ../probe-ink/dist/chunk-LO7YF74P.js
+import { ENV_ENDPOINT, ENV_TOKEN } from "@termwright/protocol";
+
+// ../probe-ink/dist/index.js
+import { fileURLToPath, pathToFileURL } from "url";
+var PROBE_ENTRIES = {
+  bun: fileURLToPath(new URL("./bun-preload.js", import.meta.url)),
+  node: fileURLToPath(new URL("./node-hook.js", import.meta.url))
+};
+function withProbe(runtime, argv) {
+  if (argv.length === 0) throw new Error("withProbe needs an interpreter in argv");
+  const [interpreter, ...rest] = argv;
+  const flag = runtime === "bun" ? "--preload" : "--import";
+  return {
+    command: [
+      interpreter,
+      flag,
+      pathToFileURL(PROBE_ENTRIES[runtime]).href,
+      ...rest
+    ],
+    runtime
+  };
+}
+
+// src/support/pty.ts
+function fixturePath(name) {
+  return join(packageRoot(), "src", "fixtures", name);
+}
+var cachedRoot = null;
+function packageRoot() {
+  if (cachedRoot !== null) return cachedRoot;
+  let directory = dirname(fileURLToPath2(import.meta.url));
+  for (; ; ) {
+    if (existsSync(join(directory, "package.json"))) {
+      cachedRoot = directory;
+      return directory;
+    }
+    const parent = dirname(directory);
+    if (parent === directory) {
+      throw new Error("@termwright/conformance: could not locate the package root from this module");
+    }
+    directory = parent;
+  }
+}
+var CONFORMANCE_FIXTURES = Object.freeze({
+  /** Uninstrumented app: proves the generic fallback (§20.1). */
+  generic: () => fixturePath("generic-app.mjs"),
+  /** Shell-shaped app emitting OSC 133 marks; `--marks=off` suppresses them. */
+  prompt: () => fixturePath("prompt-app.mjs"),
+  /** Normal-render Ink app used to exercise launch-time probe attachment. */
+  inkProbe: () => fixturePath("ink-probe-app.mjs"),
+  /** Hostile wire peer; takes a scenario name as its first argument (§20.3). */
+  adversarialPeer: () => fixturePath("adversarial-peer.mjs")
+});
+var cachedPty = null;
+function ptyAvailable() {
+  if (cachedPty !== null) return cachedPty;
+  if (process.env["TERMWRIGHT_SKIP_PTY"] === "1") {
+    cachedPty = false;
+    return cachedPty;
+  }
+  try {
+    const pty = createNodePtyBackend().spawn({
+      command: [process.execPath, "-e", "process.exit(0)"],
+      env: environment(),
+      columns: 20,
+      rows: 4
+    });
+    pty.dispose();
+    cachedPty = true;
+  } catch {
+    cachedPty = false;
+  }
+  return cachedPty;
+}
+function environment(extra) {
+  const env = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== void 0) env[key] = value;
+  }
+  return { ...env, ...extra };
+}
+function createSessionPool() {
+  const open = [];
+  return {
+    async launch(fixture, options = {}) {
+      const { args = [], probe, ready: _ready, ...launchOptions } = options;
+      const base = [process.execPath, fixture, ...args];
+      const terminal = await launchTerminal({
+        command: probe === "ink" ? withProbe("node", base).command : base,
+        columns: 80,
+        rows: 24,
+        // No `env` and no `envMode`: the suites run against the secret-safe
+        // 'replace' default, which is what a user gets. Forwarding the runner's
+        // whole environment here would quietly make every suite an 'inherit'
+        // test and leave the default uncovered.
+        // Conformance runs start a fresh Node process, a pseudo-terminal and a
+        // socket per test, and several suites run beside other builds. The
+        // driver's defaults are tight enough that machine load, rather than the
+        // implementation, would decide the result — a genuine failure still
+        // fails here, just later.
+        timeouts: { text: 3e4, action: 3e4, exit: 3e4, idle: 1e4 },
+        ...launchOptions
+      });
+      open.push(terminal);
+      if (options.ready !== void 0) await waitForStart(terminal, options.ready, fixture);
+      return terminal;
+    },
+    async closeAll() {
+      while (open.length > 0) {
+        const terminal = open.pop();
+        await terminal?.close();
+      }
+    }
+  };
+}
+async function waitForStart(terminal, ready, fixture) {
+  let bytes = 0;
+  const off = terminal.events.on("output", ({ data }) => {
+    bytes += data.length;
+  });
+  try {
+    await terminal.waitForText(ready);
+  } catch (error) {
+    const exit = await Promise.race([terminal.exit, Promise.resolve(null)]);
+    const detail = bytes === 0 ? `it produced no output at all${exit === null ? " and is still running" : `; it exited ${JSON.stringify(exit)}`}` : `it produced ${bytes} bytes but never drew ${String(ready)}`;
+    throw new Error(`conformance: ${fixture.split("/").pop() ?? fixture} did not start \u2014 ${detail}`, {
+      cause: error
+    });
+  } finally {
+    off();
+  }
+}
+function commandAvailable(command, options = {}) {
+  const [binary, ...args] = command;
+  if (binary === void 0) return false;
+  const printable = command.join(" ");
+  try {
+    const result = spawnSync(binary, args, {
+      ...options.cwd === void 0 ? {} : { cwd: options.cwd },
+      timeout: options.timeoutMs ?? 12e4,
+      encoding: "utf8",
+      env: environment()
+    });
+    if (result.status === 0) return true;
+    if (options.quiet === true) return false;
+    const reason = result.error?.message ?? (result.signal === null ? `exit ${String(result.status)}` : `signal ${result.signal}`);
+    process.stderr.write(
+      `conformance: probe \`${printable}\` failed (${reason})
+${(result.stderr ?? "").trim().split("\n").slice(-3).join("\n")}
+`
+    );
+    return false;
+  } catch (error) {
+    if (options.quiet !== true) {
+      process.stderr.write(
+        `conformance: probe \`${printable}\` could not run: ${error instanceof Error ? error.message : String(error)}
+`
+      );
+    }
+    return false;
+  }
+}
+
+// src/support/probe.ts
+var LOG_BUDGET = Object.freeze({ enabled: true, maxRecordsPerSecond: 200, burst: 400 });
+var MARKER_PATTERN = new RegExp(
+  `\\x1b\\]${MARKER_OSC_CODE};(${MARKER_OSC_PREFIX}[0-9]+;[A-Za-z0-9_-]+)(?:\\x07|\\x1b\\\\)`,
+  "gu"
+);
+var AdapterProbe = class _AdapterProbe {
+  sessionId;
+  token;
+  #server;
+  #directory;
+  #pty;
+  #subscribe;
+  #terminal;
+  #startedAt = performance.now();
+  #messages = [];
+  #markers = [];
+  #faults = [];
+  #logs = [];
+  #deltas = [];
+  #composed = null;
+  #compositionError = null;
+  #requestId = 0;
+  #chunks = [];
+  #bytes = 0;
+  #text = "";
+  #markerScanFrom = 0;
+  #connections = 0;
+  #socket = null;
+  #exit = null;
+  /** Where the adapter writes its own account of attaching, if it writes one. */
+  #debugFile = null;
+  #stopped = false;
+  constructor(identity, server, directory, pty, size, subscribe) {
+    this.#subscribe = subscribe;
+    this.sessionId = identity.sessionId;
+    this.token = identity.token;
+    this.#server = server;
+    this.#directory = directory;
+    this.#pty = pty;
+    this.#terminal = new xh.Terminal({
+      cols: size.columns,
+      rows: size.rows,
+      allowProposedApi: true,
+      scrollback: 1e3
+    });
+  }
+  /** Creates the endpoint (unless dormant), then spawns the fixture. */
+  static async start(command, options = {}) {
+    const instrument = options.instrument ?? true;
+    const sessionId = randomUUID();
+    const token = generateToken();
+    let server = null;
+    let directory = null;
+    let endpoint = null;
+    if (instrument) {
+      server = createServer();
+      if (process.platform === "win32") {
+        endpoint = `\\\\.\\pipe\\termwright-probe-${randomBytes(16).toString("hex")}`;
+      } else {
+        directory = await mkdtemp(join2(tmpdir(), "termwright-probe-"));
+        endpoint = join2(directory, "semantic.sock");
+      }
+      const listening = server;
+      const address = endpoint;
+      await new Promise((resolve, reject) => {
+        listening.once("error", reject);
+        listening.listen(address, () => {
+          listening.removeListener("error", reject);
+          resolve();
+        });
+      });
+    }
+    const env = environment(command.env);
+    delete env[ENV_ENDPOINT2];
+    delete env[ENV_TOKEN2];
+    delete env[ENV_PROTOCOL];
+    if (endpoint !== null) {
+      env[ENV_ENDPOINT2] = endpoint;
+      env[ENV_TOKEN2] = token;
+      env[ENV_PROTOCOL] = String(PROTOCOL_VERSION);
+    }
+    const debugFile = join2(tmpdir(), `termwright-adapter-debug-${randomBytes(8).toString("hex")}.log`);
+    env["TERMWRIGHT_DEBUG_FILE"] = debugFile;
+    const size = { columns: options.columns ?? 80, rows: options.rows ?? 24 };
+    const pty = createNodePtyBackend2().spawn({
+      command: command.command,
+      ...command.cwd === void 0 ? {} : { cwd: command.cwd },
+      env,
+      columns: size.columns,
+      rows: size.rows
+    });
+    const probe = new _AdapterProbe(
+      { sessionId, token },
+      server,
+      directory,
+      pty,
+      size,
+      options.subscribe ?? "snapshots"
+    );
+    probe.#debugFile = debugFile;
+    pty.onData((data) => probe.#onData(data));
+    pty.onExit((status) => {
+      probe.#exit = status;
+    });
+    server?.on("connection", (socket) => probe.#onConnection(socket));
+    return probe;
+  }
+  /** Everything observed so far. Safe to call at any point. */
+  observe() {
+    return {
+      messages: [...this.#messages],
+      markers: [...this.#markers],
+      faults: [...this.#faults],
+      connections: this.#connections,
+      stdout: this.#stdout(),
+      text: this.#text,
+      screen: this.screenText(),
+      logs: this.#logs.map((entry) => entry),
+      deltas: this.#deltas.map((entry) => entry),
+      composed: this.#composed,
+      compositionError: this.#compositionError
+    };
+  }
+  /** The visible grid as text, trailing whitespace trimmed per row. */
+  screenText() {
+    const buffer = this.#terminal.buffer.active;
+    const rows = [];
+    for (let row = 0; row < this.#terminal.rows; row += 1) {
+      rows.push(buffer.getLine(buffer.viewportY + row)?.translateToString(true) ?? "");
+    }
+    return rows.join("\n");
+  }
+  /** The child's exit status, or `null` while it is still running. */
+  get exitStatus() {
+    return this.#exit;
+  }
+  /** Writes raw bytes to the child, exactly as a terminal would. */
+  async write(input) {
+    this.#pty.write(new TextEncoder().encode(input));
+    await Promise.resolve();
+  }
+  /**
+   * Resolves once `needle` appears on the rendered grid.
+   *
+   * Matching the byte stream instead would only work for adapters that happen
+   * to write their text contiguously: a framework that positions each run of
+   * cells never emits `focus: reject` as those twelve bytes in a row.
+   */
+  async waitForText(needle, timeoutMs = 1e4) {
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const screen = this.screenText();
+      if (needle instanceof RegExp ? needle.test(screen) : screen.includes(needle)) return;
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `adapter conformance: ${String(needle)} never appeared on the fixture's screen
+screen was:
+${screen}`
+        );
+      }
+      await delay(20);
+    }
+  }
+  /**
+   * Resolves once `predicate` holds over the current observation.
+   *
+   * `what` names the thing being waited for, and the failure carries what the
+   * probe could see when it gave up. "Condition never became true" is not a
+   * result anybody can act on: an adapter that never connected, one that
+   * connected and published nothing, and one whose binary died all produce it,
+   * and only the observation tells them apart.
+   */
+  async waitFor(predicate, timeoutMs = 1e4, what = "the condition") {
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      if (predicate(this.observe())) return;
+      if (Date.now() >= deadline) {
+        throw new Error(`adapter conformance: ${what} never happened \u2014 ${this.describe()}`);
+      }
+      await delay(20);
+    }
+  }
+  /** What the probe has seen so far, for a failure that has to explain itself. */
+  describe() {
+    const { messages, connections } = this.observe();
+    const kinds = /* @__PURE__ */ new Map();
+    for (const recorded of messages) {
+      const kind = recorded.message.type;
+      kinds.set(kind, (kinds.get(kind) ?? 0) + 1);
+    }
+    const traffic = kinds.size === 0 ? "no messages" : [...kinds].map(([kind, n]) => `${kind}\xD7${n}`).join(", ");
+    const screen = this.screenText().trimEnd().split("\n").filter((line) => line.trim() !== "");
+    const exit = this.#exit === null ? "still running" : `exited ${JSON.stringify(this.#exit)}`;
+    return `${connections} connection(s) to the endpoint, ${traffic}; the child is ${exit}; last screen line: ${JSON.stringify(screen.at(-1) ?? "")}
+${this.#adapterAccount()}`;
+  }
+  /**
+   * What the adapter says about its own attach, if the client writes it.
+   *
+   * The outside view cannot tell "dialled the wrong transport" from "the driver
+   * was not listening" from "the process never started" — all three look like
+   * no connection. The clients write that distinction to `TERMWRIGHT_DEBUG_FILE`,
+   * so it is quoted here rather than left in a file nobody opens. An adapter
+   * that writes nothing is itself an answer, and says so.
+   */
+  #adapterAccount() {
+    if (this.#debugFile === null) return "adapter debug log: not requested";
+    let contents;
+    try {
+      contents = readFileSync(this.#debugFile, "utf8");
+    } catch {
+      return `adapter debug log: nothing written to ${this.#debugFile} \u2014 the client either predates the log or never ran`;
+    }
+    const lines = contents.trimEnd().split("\n").slice(-12);
+    return `adapter debug log (last ${lines.length} line(s)):
+  ${lines.join("\n  ")}`;
+  }
+  /** Waits for the child to exit and returns its status. */
+  async waitForExit(timeoutMs = 1e4) {
+    const deadline = Date.now() + timeoutMs;
+    while (this.#exit === null) {
+      if (Date.now() >= deadline) throw new Error("adapter conformance: the fixture never exited");
+      await delay(20);
+    }
+    return this.#exit;
+  }
+  /** Cuts the semantic channel without touching the child: the disconnect case. */
+  cutChannel() {
+    this.#socket?.destroy();
+    this.#socket = null;
+  }
+  /** Stops the child and releases the endpoint. Idempotent. */
+  async stop() {
+    if (this.#stopped) return;
+    this.#stopped = true;
+    this.#socket?.destroy();
+    this.#pty.dispose();
+    this.#terminal.dispose();
+    if (this.#server !== null) await new Promise((resolve) => this.#server?.close(() => resolve()));
+    if (this.#directory !== null) await rm(this.#directory, { recursive: true, force: true }).catch(() => {
+    });
+    if (this.#debugFile !== null) await rm(this.#debugFile, { force: true }).catch(() => {
+    });
+  }
+  // -------------------------------------------------------------------------
+  #stdout() {
+    const out = new Uint8Array(this.#bytes);
+    let offset = 0;
+    for (const chunk of this.#chunks) {
+      out.set(chunk, offset);
+      offset += chunk.length;
+    }
+    this.#chunks = [out];
+    return out;
+  }
+  #onData(data) {
+    this.#chunks.push(data);
+    this.#bytes += data.length;
+    this.#text += Buffer.from(data).toString("utf8");
+    this.#terminal.write(data);
+    this.#scanMarkers();
+  }
+  /** Finds render markers in the byte stream and verifies each against the token. */
+  #scanMarkers() {
+    MARKER_PATTERN.lastIndex = this.#markerScanFrom;
+    for (; ; ) {
+      const match = MARKER_PATTERN.exec(this.#text);
+      if (match === null) break;
+      const payload = match[1] ?? "";
+      const verified = verifyMarkerPayload(payload, this.token, this.sessionId);
+      if (verified === null) {
+        this.#faults.push({ code: "marker", detail: `marker did not verify: ${JSON.stringify(payload)}` });
+      } else {
+        this.#markers.push({ revision: verified.revision, offset: match.index, atMs: this.#now() });
+      }
+      this.#markerScanFrom = match.index + match[0].length;
+    }
+    MARKER_PATTERN.lastIndex = 0;
+  }
+  #onConnection(socket) {
+    this.#connections += 1;
+    if (this.#socket !== null) {
+      this.#faults.push({ code: "second-connection", detail: "the adapter opened a second channel" });
+      socket.destroy();
+      return;
+    }
+    this.#socket = socket;
+    const decoder = createFrameDecoder(DEFAULT_LIMITS2.maxFrameBytes);
+    socket.on("data", (chunk) => {
+      let frames;
+      try {
+        frames = decoder.push(chunk);
+      } catch (error) {
+        this.#faults.push({ code: "framing", detail: error instanceof Error ? error.message : String(error) });
+        socket.destroy();
+        return;
+      }
+      for (const frame of frames) this.#onFrame(socket, frame);
+    });
+    socket.on("error", () => socket.destroy());
+    socket.on("close", () => {
+      if (this.#socket === socket) this.#socket = null;
+    });
+  }
+  #onFrame(socket, frame) {
+    const parsed = parseAdapterMessage(frame, DEFAULT_LIMITS2);
+    if (!parsed.ok) {
+      this.#faults.push({ code: parsed.code, detail: parsed.detail });
+      return;
+    }
+    this.#messages.push({ message: parsed.message, stdoutBytes: this.#bytes, atMs: this.#now() });
+    if (parsed.message.type === "log") this.#logs.push(parsed.message.record);
+    if (parsed.message.type === "snapshot") this.#composed = parsed.message.snapshot;
+    if (parsed.message.type === "tree-delta") this.#compose(parsed.message);
+    if (parsed.message.type !== "hello") return;
+    const ack = {
+      type: "hello-ack",
+      protocol: PROTOCOL_ID,
+      sessionId: this.sessionId,
+      limits: DEFAULT_LIMITS2,
+      // Deltas are only ever sent to a driver that asked for them.
+      subscribe: this.#subscribe === "diffs" && parsed.message.capabilities.includes("tree-diffs") ? "diffs" : "snapshots",
+      marker: { enabled: parsed.message.capabilities.includes("render-revisions") },
+      // Granted only to an adapter that asked: an adapter that never announced
+      // `logs` must not be handed a budget it can then claim it was given.
+      ...parsed.message.capabilities.includes("logs") ? { logs: LOG_BUDGET } : {}
+    };
+    socket.write(encodeFrame(ack, DEFAULT_LIMITS2.maxFrameBytes));
+  }
+  /** Applies one delta to the held tree, recording the first failure. */
+  #compose(delta) {
+    const { type: _type, ...body } = delta;
+    this.#deltas.push(body);
+    const base = this.#composed;
+    if (base === null) {
+      this.#compositionError ??= `delta ${body.baseRevision}\u2192${body.revision} arrived before any full tree`;
+      return;
+    }
+    const result = applyTreeDelta(base, body, DEFAULT_LIMITS2);
+    if (!result.ok) {
+      this.#compositionError ??= `delta ${body.baseRevision}\u2192${body.revision} did not compose (${result.code}): ${result.detail}`;
+      return;
+    }
+    this.#composed = result.snapshot;
+  }
+  /**
+   * Asks the adapter for a full tree and resolves with it.
+   *
+   * This is what turns composition into a check rather than a belief: the
+   * locally composed tree is compared against one the adapter built itself.
+   */
+  async requestTree(timeoutMs = 1e4) {
+    const socket = this.#socket;
+    if (socket === null) return null;
+    this.#requestId += 1;
+    const requestId = this.#requestId;
+    socket.write(encodeFrame({ type: "get-tree", requestId }, DEFAULT_LIMITS2.maxFrameBytes));
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const reply = this.#messages.find(
+        (entry) => entry.message.type === "get-tree-result" && entry.message.requestId === requestId
+      );
+      if (reply !== void 0) {
+        return reply.message.snapshot ?? null;
+      }
+      if (Date.now() >= deadline) return null;
+      await delay(20);
+    }
+  }
+  #now() {
+    return performance.now() - this.#startedAt;
+  }
+};
+var MARKER_TEXT_PREFIX = `\x1B]${MARKER_OSC_CODE};${MARKER_OSC_PREFIX}`;
+function delay(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
+
+// src/adapter-conformance.ts
+async function assertDeltasCompose(probe, timeoutMs) {
+  const { expect } = await import("vitest");
+  const observation = probe.observe();
+  expect(observation.compositionError, "the adapter produced a delta nobody could apply").toBeNull();
+  expect(observation.composed).not.toBeNull();
+  expect(observation.deltas.length).toBeGreaterThan(0);
+  const authoritative = await probe.requestTree(timeoutMs);
+  expect(authoritative, "the adapter answered no get-tree").not.toBeNull();
+  const composed = observation.composed;
+  const truth = authoritative;
+  const byId = (nodes) => [...nodes].sort((left, right) => left.id.localeCompare(right.id));
+  expect(byId(truth.nodes)).toEqual(byId(composed.nodes));
+  expect([...truth.rootIds].sort()).toEqual([...composed.rootIds].sort());
+}
+var CONVENTION_SUMMARY_DIR = join3(tmpdir2(), "termwright-conformance-conventions");
+function writeConventionSummary(name, declared, outcomes) {
+  try {
+    mkdirSync(CONVENTION_SUMMARY_DIR, { recursive: true });
+    const file = join3(CONVENTION_SUMMARY_DIR, `${name.replace(/[^\w.-]+/gu, "_")}.json`);
+    writeFileSync(
+      file,
+      JSON.stringify(
+        {
+          adapter: name,
+          declared: Object.fromEntries(declared),
+          outcomes,
+          // A rule declared in the README that no check covers: the suite
+          // cannot confirm or refute it, and saying so is more honest than
+          // letting it read as verified.
+          unverified: [...declared.keys()].filter(
+            (rule) => !outcomes.some((outcome) => outcome.rule === rule)
+          )
+        },
+        null,
+        2
+      ),
+      "utf8"
+    );
+  } catch {
+  }
+}
+function delay2(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
+async function settle(probe, quietMs = 250, budgetMs = 5e3) {
+  const deadline = Date.now() + budgetMs;
+  let seen = -1;
+  for (; ; ) {
+    const length = probe.observe().stdout.length;
+    if (length === seen) return;
+    seen = length;
+    if (Date.now() >= deadline) return;
+    await new Promise((resolve) => {
+      setTimeout(resolve, quietMs);
+    });
+  }
+}
+function parseDeclaredDeviations(readme) {
+  const declared = /* @__PURE__ */ new Map();
+  const start = readme.indexOf("## Deviations");
+  if (start < 0) return declared;
+  const rest = readme.slice(start + "## Deviations".length);
+  const end = rest.indexOf("\n## ");
+  const section = end < 0 ? rest : rest.slice(0, end);
+  for (const line of section.split("\n")) {
+    for (const match of line.matchAll(/\*\*Rule (\d+)\s*—\s*([^*]+?)\.?\*\*/gu)) {
+      add(declared, match[1], match[2].trim());
+    }
+    for (const match of line.matchAll(/\*\*(.+?)\*\*\s*\(rule (\d+)\)/gu)) {
+      add(declared, match[2], match[1].trim());
+    }
+    const trimmed = line.trim();
+    if (trimmed.startsWith("|") && !/^\|[\s:|-]*\|?$/u.test(trimmed) && !/^\|\s*rule\s*\|/iu.test(trimmed)) {
+      const cells = trimmed.split("|").slice(1, -1).map((cell) => cell.trim());
+      const numbered = /^(\d+)\s*[—-]\s*(.+)$/u.exec(cells[0] ?? "");
+      if (numbered !== null) {
+        add(declared, numbered[1], numbered[2].trim());
+      } else if ((cells[1] ?? "").length > 0) {
+        add(declared, "other", cells[1]);
+      }
+    }
+  }
+  return declared;
+}
+function add(map, key, value) {
+  map.set(key, [...map.get(key) ?? [], value]);
+}
+var CONTAINER_ROLES = /* @__PURE__ */ new Set([
+  "region",
+  "dialog",
+  "list",
+  "table",
+  "application",
+  "menu"
+]);
+var snapshotsOf = (observation) => observation.messages.filter((entry) => entry.message.type === "snapshot").map((entry) => entry.message.snapshot);
+async function runAdapterConformance(options) {
+  const { afterAll, beforeAll, describe, expect, it } = await import("vitest");
+  const timeout = options.timeoutMs ?? 1e4;
+  const toolchain = options.requires === void 0 || commandAvailable(options.requires.probe, {
+    ...options.requires.cwd === void 0 ? {} : { cwd: options.requires.cwd },
+    ...options.requires.timeoutMs === void 0 ? {} : { timeoutMs: options.requires.timeoutMs }
+  });
+  const probeOptions = {
+    ...options.columns === void 0 ? {} : { columns: options.columns },
+    ...options.rows === void 0 ? {} : { rows: options.rows }
+  };
+  const title = !ptyAvailable() ? `adapter conformance: ${options.name} (skipped: no pseudo-terminal here)` : toolchain ? `adapter conformance: ${options.name}` : `adapter conformance: ${options.name} (skipped: ${options.requires?.label ?? "toolchain"} unavailable)`;
+  describe.skipIf(!ptyAvailable() || !toolchain)(title, { timeout: timeout * 4 }, () => {
+    describe("the dormant rule", () => {
+      it("opens nothing and emits no marker without an endpoint", async () => {
+        const probe = await AdapterProbe.start(options.spawn(), { ...probeOptions, instrument: false });
+        try {
+          await probe.waitForText(options.ready, timeout);
+          await probe.write(options.interaction.input);
+          await probe.waitForText(options.interaction.expect, timeout);
+          const observation = probe.observe();
+          expect(observation.connections).toBe(0);
+          expect(observation.messages).toHaveLength(0);
+          expect(observation.text).not.toContain(MARKER_TEXT_PREFIX);
+        } finally {
+          await probe.stop();
+        }
+      });
+      it.skipIf(options.baseline === void 0)(
+        "produces the same bytes as a build without the adapter",
+        async () => {
+          const startup = async (command) => {
+            const probe = await AdapterProbe.start(command, { ...probeOptions, instrument: false });
+            try {
+              await probe.waitForText(options.ready, timeout);
+              await settle(probe);
+              const observation = probe.observe();
+              return { stdout: observation.stdout, screen: observation.screen };
+            } finally {
+              await probe.stop();
+            }
+          };
+          const instrumented = await startup(options.spawn());
+          const plain = await startup(options.baseline());
+          if (process.platform === "win32") {
+            expect(instrumented.screen).toBe(plain.screen);
+          } else {
+            expect(Buffer.from(instrumented.stdout).toString("binary")).toBe(
+              Buffer.from(plain.stdout).toString("binary")
+            );
+          }
+        }
+      );
+    });
+    describe("an instrumented session", () => {
+      let probe;
+      let beforeInput;
+      beforeAll(
+        async () => {
+          probe = await AdapterProbe.start(options.spawn(), probeOptions);
+          await probe.waitForText(options.ready, timeout);
+          await probe.waitFor(
+            (observation) => snapshotsOf(observation).length > 0,
+            timeout,
+            "a first snapshot from the adapter"
+          );
+          beforeInput = probe.observe();
+        },
+        // Starting the process, waiting for its first frame, and completing the
+        // adapter handshake are separate bounded operations. Vitest otherwise
+        // applies its 10-second hook default even though the suite has a larger
+        // timeout, which makes real adapters flaky under a parallel root run.
+        timeout * 4
+      );
+      afterAll(async () => {
+        await probe?.stop();
+      });
+      it("completes the handshake before anything else", async () => {
+        const { messages, connections } = probe.observe();
+        const first = messages[0];
+        expect(connections).toBe(1);
+        expect(first?.message.type).toBe("hello");
+        const hello = first?.message;
+        expect(hello.protocol).toBe("termwright/1");
+        expect(hello.adapter.name.length).toBeGreaterThan(0);
+        expect(hello.adapter.version.length).toBeGreaterThan(0);
+        expect(hello.capabilities.every((entry) => ADAPTER_CAPABILITIES.includes(entry))).toBe(true);
+        expect(hello.capabilities).toContain("tree");
+        expect(messages.filter((entry) => entry.message.type === "hello")).toHaveLength(1);
+        const firstLog = messages.findIndex((entry) => entry.message.type === "log");
+        expect(firstLog === -1 || firstLog > 0).toBe(true);
+      });
+      it(
+        options.treeBeforeInput === void 0 ? "publishes a usable tree before any input" : `publishes a usable tree before any input (exempt: ${options.treeBeforeInput.reason})`,
+        { skip: options.treeBeforeInput !== void 0 },
+        () => {
+          const latest = snapshotsOf(beforeInput).at(-1);
+          expect(latest, "no snapshot arrived before any input was sent").toBeDefined();
+          expect(latest?.nodes.length ?? 0).toBeGreaterThan(0);
+          expect(latest?.rootIds.length ?? 0).toBeGreaterThan(0);
+          const addressable = (latest?.nodes ?? []).filter(
+            (node) => node.name.length > 0 || node.testId !== void 0
+          );
+          expect(addressable.length, "the tree has no node that a locator could address").toBeGreaterThan(0);
+        }
+      );
+      it("publishes only valid snapshots, bound to this session", async () => {
+        const observation = probe.observe();
+        const snapshots = snapshotsOf(observation);
+        expect(observation.faults).toEqual([]);
+        expect(snapshots.length).toBeGreaterThan(0);
+        for (const snapshot of snapshots) {
+          expect(validateSnapshot(snapshot, DEFAULT_LIMITS3)).toMatchObject({ ok: true });
+          expect(snapshot.sessionId).toBe(probe.sessionId);
+          expect(snapshot.v).toBe(1);
+          const ids = new Set(snapshot.nodes.map((node) => node.id));
+          for (const node of snapshot.nodes) {
+            if (node.parentId === void 0) expect(snapshot.rootIds).toContain(node.id);
+            else expect(ids.has(node.parentId)).toBe(true);
+          }
+        }
+        const revisions = snapshots.map((snapshot) => snapshot.revision);
+        expect([...revisions]).toEqual([...new Set(revisions)].sort((left, right) => left - right));
+      });
+      it.skipIf(options.expectAbsoluteBounds !== true)("publishes viewport-absolute bounds", () => {
+        const snapshots = snapshotsOf(probe.observe());
+        const latest = snapshots[snapshots.length - 1];
+        expect(latest).toBeDefined();
+        const bounded = latest?.nodes.filter((node) => node.bounds !== void 0) ?? [];
+        expect(bounded.length).toBeGreaterThan(0);
+        for (const node of bounded) {
+          const bounds = node.bounds;
+          expect(bounds.row).toBeGreaterThanOrEqual(0);
+          expect(bounds.column).toBeGreaterThanOrEqual(0);
+          expect(bounds.row).toBeLessThan(latest?.rows ?? 0);
+          expect(bounds.column).toBeLessThan(latest?.columns ?? 0);
+        }
+      });
+      it("orders every revision as snapshot, then commit, then marker", async () => {
+        await probe.write(options.interaction.input);
+        await probe.waitForText(options.interaction.expect, timeout);
+        await probe.waitFor(
+          (observation2) => observation2.markers.length >= 2,
+          timeout,
+          "a second render marker"
+        );
+        const complete = (observation2) => observation2.markers.every(
+          (marker) => observation2.messages.some(
+            (entry) => entry.message.type === "snapshot" && entry.message.snapshot.revision === marker.revision
+          ) && observation2.messages.some(
+            (entry) => entry.message.type === "revision-commit" && entry.message.revision === marker.revision
+          )
+        );
+        await probe.waitFor(complete, timeout, "every marker paired with a snapshot and a commit");
+        const observation = probe.observe();
+        const markers = observation.markers;
+        expect(markers.length).toBeGreaterThan(0);
+        expect(markers.map((marker) => marker.revision)).toEqual(
+          [...markers.map((marker) => marker.revision)].sort((left, right) => left - right)
+        );
+        for (const marker of markers) {
+          const snapshot = observation.messages.find(
+            (entry) => entry.message.type === "snapshot" && entry.message.snapshot.revision === marker.revision
+          );
+          const commit = observation.messages.find(
+            (entry) => entry.message.type === "revision-commit" && entry.message.revision === marker.revision
+          );
+          expect(snapshot, `no snapshot for revision ${marker.revision}`).toBeDefined();
+          expect(commit, `no commit for revision ${marker.revision}`).toBeDefined();
+          const snapshotIndex = observation.messages.indexOf(snapshot);
+          expect(snapshotIndex).toBeLessThan(observation.messages.indexOf(commit));
+        }
+        let previousEnd = 0;
+        for (const marker of markers) {
+          expect(marker.offset).toBeGreaterThan(previousEnd);
+          previousEnd = marker.offset;
+        }
+      });
+      const conventions = options.conventions ?? {};
+      const readme = conventions.readmePath !== void 0 && existsSync2(conventions.readmePath) ? readFileSync2(conventions.readmePath, "utf8") : "";
+      const declared = parseDeclaredDeviations(readme);
+      const outcomes = [];
+      it("reads the deviations its README declares", () => {
+        if (conventions.readmePath === void 0) return;
+        if (!readme.includes("## Deviations")) return;
+        const start = readme.indexOf("## Deviations");
+        const rest = readme.slice(start + "## Deviations".length);
+        const end = rest.indexOf("\n## ");
+        const section = end < 0 ? rest : rest.slice(0, end);
+        const structured = /^\s*[-*|]/mu.test(section) || section.includes("**");
+        if (!structured) return;
+        expect(
+          declared.size,
+          `${options.name} has a "## Deviations" section with entries this suite could not read; its declarations would be invisible and its documented limitations would report as errors. Teach \`parseDeclaredDeviations\` the shape it uses.`
+        ).toBeGreaterThan(0);
+      });
+      const convention = (rule, what, check) => {
+        const failure = check();
+        const titles = declared.get(rule) ?? [];
+        if (failure === null) {
+          outcomes.push(
+            titles.length === 0 ? { rule, what, status: "compliant" } : { rule, what, status: "checked-despite-declaration", detail: titles.join("; ") }
+          );
+          return;
+        }
+        if (titles.length > 0) {
+          outcomes.push({ rule, what, status: "documented", detail: `${titles.join("; ")} \u2014 ${failure}` });
+          return;
+        }
+        outcomes.push({ rule, what, status: "violation", detail: failure });
+        expect.fail(`convention ${rule} (${what}): ${failure}`);
+      };
+      afterAll(() => {
+        writeConventionSummary(options.name, declared, outcomes);
+      });
+      it("convention 3: an author-annotated test id reaches the wire", () => {
+        if (conventions.annotatedTestId === void 0) return;
+        const wanted = conventions.annotatedTestId;
+        convention("3", "an annotated test id reaches the wire", () => {
+          const latest = snapshotsOf(beforeInput).at(-1);
+          const node = latest?.nodes.find((entry) => entry.testId === wanted);
+          return node === void 0 ? `no node carries the test id ${JSON.stringify(wanted)}` : null;
+        });
+      });
+      it("convention 5: an empty textbox publishes an empty value", () => {
+        if (conventions.emptyTextboxTestId === void 0) return;
+        const wanted = conventions.emptyTextboxTestId;
+        convention("5", "an empty textbox publishes an empty value", () => {
+          const latest = snapshotsOf(beforeInput).at(-1);
+          const node = latest?.nodes.find((entry) => entry.testId === wanted);
+          if (node === void 0) return `no node carries the test id ${JSON.stringify(wanted)}`;
+          return node.value === "" ? null : `the value is ${JSON.stringify(node.value)}, not an empty string`;
+        });
+      });
+      it("convention 5: value is derived only for value-bearing roles", () => {
+        convention("5", "value is derived only for value-bearing roles", () => {
+          const annotated = new Set(conventions.annotatedValues ?? []);
+          const nodes = snapshotsOf(beforeInput).at(-1)?.nodes ?? [];
+          const offenders = nodes.filter(
+            (node) => node.value !== void 0 && node.role !== "textbox" && node.role !== "progressbar" && !(node.testId !== void 0 && annotated.has(node.testId))
+          );
+          if (offenders.length > 0) {
+            return `derived a value outside {textbox, progressbar}: ${offenders.map((node) => `${node.role} ${JSON.stringify(node.name)}`).join(", ")}`;
+          }
+          const booleans = nodes.filter((node) => node.value === "true" || node.value === "false");
+          return booleans.length === 0 ? null : `published a boolean as a value on ${booleans.map((node) => node.role).join(", ")}`;
+        });
+      });
+      it("convention 2: no container is named from the text it contains", () => {
+        convention("2", "no container is named from the text it contains", () => {
+          const nodes = snapshotsOf(beforeInput).at(-1)?.nodes ?? [];
+          const children = /* @__PURE__ */ new Map();
+          for (const node of nodes) {
+            if (node.parentId === void 0) continue;
+            children.set(node.parentId, [...children.get(node.parentId) ?? [], node.id]);
+          }
+          const descendantText = (id) => {
+            const out = [];
+            const pending = [...children.get(id) ?? []];
+            while (pending.length > 0) {
+              const next = nodes.find((node) => node.id === pending.pop());
+              if (next === void 0) continue;
+              if (next.name.length > 0) out.push(next.name);
+              pending.push(...children.get(next.id) ?? []);
+            }
+            return out;
+          };
+          const offenders = nodes.filter((node) => CONTAINER_ROLES.has(node.role) && node.name.length > 0).filter((node) => {
+            const texts = descendantText(node.id);
+            const joined = texts.join(" ").replace(/\s+/gu, " ").trim();
+            return texts.includes(node.name) || joined.length > 0 && joined === node.name;
+          });
+          return offenders.length === 0 ? null : `named from content: ${offenders.map((node) => `${node.role} ${JSON.stringify(node.name)}`).join(", ")}`;
+        });
+      });
+      it("convention 2: a container with no label of its own has an empty name", () => {
+        if (conventions.unnamedContainerTestId === void 0) return;
+        const wanted = conventions.unnamedContainerTestId;
+        convention("2", "an unlabelled container has an empty name", () => {
+          const node = snapshotsOf(beforeInput).at(-1)?.nodes.find((entry) => entry.testId === wanted);
+          if (node === void 0) return `no node carries the test id ${JSON.stringify(wanted)}`;
+          return node.name === "" ? null : `the container is named ${JSON.stringify(node.name)}`;
+        });
+      });
+      it.skipIf(conventions.readmePath === void 0)(
+        "declares its deviations in its README (advisory)",
+        () => {
+          const path = conventions.readmePath;
+          const text = existsSync2(path) ? readFileSync2(path, "utf8") : "";
+          if (!text.includes("## Deviations")) {
+            process.stderr.write(
+              `conformance: ${options.name} has no "## Deviations" section in ${path}; rules 1, 2 and 4 are unverifiable from outside, so an undeclared difference is invisible
+`
+            );
+          }
+          expect(true).toBe(true);
+        }
+      );
+      it("sends log records only if it negotiated the channel", async () => {
+        const hello = beforeInput.messages[0]?.message;
+        if (hello.capabilities.includes("logs")) return;
+        await probe.write(options.interaction.input);
+        await probe.waitForText(options.interaction.expect, timeout);
+        expect(
+          probe.observe().logs,
+          "the adapter sent log records without announcing the logs capability"
+        ).toEqual([]);
+      });
+      it.skipIf(options.logs === void 0)("carries a log record without printing it", async () => {
+        const logs = options.logs;
+        const hello = probe.observe().messages[0]?.message;
+        expect(
+          hello.capabilities.includes("logs"),
+          "the registration declares logs, but the adapter never announced the capability"
+        ).toBe(true);
+        const before = probe.observe().logs.length;
+        if (logs.input !== void 0) await probe.write(logs.input);
+        await probe.waitFor(
+          (observation2) => observation2.logs.length > (logs.input === void 0 ? 0 : before),
+          timeout,
+          "a log record over the negotiated channel"
+        );
+        const observation = probe.observe();
+        const record = observation.logs.find((entry) => entry.message.includes(logs.expect));
+        expect(record, `no log record matched ${JSON.stringify(logs.expect)}`).toBeDefined();
+        expect(record?.seq).toBeGreaterThanOrEqual(0);
+        const seqs = observation.logs.map((entry) => entry.seq);
+        expect(seqs).toEqual([...seqs].sort((left, right) => left - right));
+        expect(new Set(seqs).size).toBe(seqs.length);
+        expect(observation.screen).not.toContain(logs.expect);
+        expect(observation.text).not.toContain(logs.expect);
+      });
+      it("produces deltas that compose to the tree it would have sent", async () => {
+        const announced = (beforeInput.messages[0]?.message).capabilities;
+        if (!announced.includes("tree-diffs")) return;
+        const diffs = await AdapterProbe.start(options.spawn(), { ...probeOptions, subscribe: "diffs" });
+        try {
+          await diffs.waitForText(options.ready, timeout);
+          await diffs.waitFor((observation) => observation.composed !== null, timeout);
+          for (let press = 0; press < 3; press += 1) {
+            await diffs.write(options.interaction.input);
+            await delay2(150);
+          }
+          await diffs.waitFor((observation) => observation.deltas.length > 0, timeout);
+          await assertDeltasCompose(diffs, timeout);
+        } finally {
+          await diffs.stop();
+        }
+      });
+      it("keeps the application alive when the channel is cut", async () => {
+        const before = probe.observe();
+        probe.cutChannel();
+        await probe.write(options.interaction.input);
+        await probe.waitFor(
+          (observation) => observation.text.length > before.text.length,
+          timeout,
+          "any further output from the child"
+        );
+        const after = probe.observe();
+        expect(after.text.length).toBeGreaterThan(before.text.length);
+        expect(after.connections).toBe(1);
+        expect(probe.exitStatus).toBeNull();
+        await probe.write(options.quit.input);
+        const status = await probe.waitForExit(timeout);
+        if (options.quit.exitCode !== void 0) expect(status.code).toBe(options.quit.exitCode);
+      });
+    });
+  });
+}
+export {
+  AdapterProbe,
+  CONFORMANCE_FIXTURES,
+  MARKER_TEXT_PREFIX,
+  createSessionPool,
+  environment,
+  fixturePath,
+  parseDeclaredDeviations,
+  ptyAvailable,
+  runAdapterConformance
+};
+//# sourceMappingURL=index.js.map