@xterm/xterm 5.5.0: default

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify @xterm/xterm.default in pkg:npm/%40xterm/xterm@5.5.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40xterm/xterm@5.5.0
Demonstrate these symbols/APIs:
  - @xterm/xterm.default
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: esm
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:0f9666a724cdd5f02f17c2b18250d35e2ede5a6fb6bbae710ae0f877b8baa624","constraints":{"executionContext":"node"},"contract":["@xterm/xterm default export provides the Terminal constructor in ESM Node.js environment","Terminal instances initialize with specified cols and rows dimensions and custom options","Terminal.write asynchronously writes text to the terminal buffer and invokes the completion callback","Terminal buffer active lines can be retrieved and translated to strings via translateToString","Terminal.resize updates terminal dimensions to new column and row counts","Terminal.reset clears terminal buffer content and resets cursor position","Terminal.dispose tears down the terminal instance cleanly"],"goal":"verify @xterm/xterm.default in pkg:npm/%40xterm/xterm@5.5.0","kind":"HOW","packages":["pkg:npm/%40xterm/xterm@5.5.0"],"schemaVersion":1,"symbols":["@xterm/xterm.default"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40xterm/xterm@5.5.0"],"schemaVersion":1,"subject":"pkg:npm/%40xterm/xterm@5.5.0","symbols":["@xterm/xterm.default"],"verifierAdapter":"node-typescript@1"}

import xtermPkg from '@xterm/xterm';

const { Terminal } = xtermPkg;

/**
 * Creates a new xterm Terminal instance.
 * @param {import('@xterm/xterm').ITerminalOptions} [options]
 * @returns {Terminal}
 */
export function createTerminal(options = {}) {
  return new Terminal(options);
}

/**
 * Writes data to the terminal and returns a promise that resolves when the write is complete.
 * @param {Terminal} term
 * @param {string|Uint8Array} data
 * @returns {Promise<void>}
 */
export function writeToTerminal(term, data) {
  return new Promise((resolve) => {
    term.write(data, () => resolve());
  });
}

/**
 * Reads a single line from the active buffer as a string.
 * @param {Terminal} term
 * @param {number} lineIndex
 * @param {boolean} [trimRight=true]
 * @returns {string|undefined}
 */
export function readTerminalLine(term, lineIndex, trimRight = true) {
  const line = term.buffer.active.getLine(lineIndex);
  return line ? line.translateToString(trimRight) : undefined;
}

/**
 * Resizes the terminal.
 * @param {Terminal} term
 * @param {number} cols
 * @param {number} rows
 */
export function resizeTerminal(term, cols, rows) {
  term.resize(cols, rows);
}

/**
 * Resets the entire terminal buffer and state.
 * @param {Terminal} term
 */
export function resetTerminal(term) {
  term.reset();
}

/**
 * Disposes the terminal instance.
 * @param {Terminal} term
 */
export function disposeTerminal(term) {
  term.dispose();
}

export { Terminal, xtermPkg };

{
  "name": "sample-xterm-default",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-xterm-default",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@xterm/xterm": "5.5.0"
      }
    },
    "node_modules/@xterm/xterm": {
      "version": "5.5.0",
      "resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-5.5.0.tgz",
      "integrity": "sha512-hqJHYaQb5OptNunnyAnkHyM8aCjZ1MEIDTQu1iIbbTD/xops91NB5yq1ZK/dC2JDbVWtF23zUtl9JE2NqwT87A==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-xterm-default",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "description": "verify @xterm/xterm.default in pkg:npm/%40xterm/xterm@5.5.0",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@xterm/xterm": "5.5.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify @xterm/xterm.default in pkg:npm/%40xterm/xterm@5.5.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40xterm/xterm@5.5.0"
  ],
  "symbols": [
    "@xterm/xterm.default"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "esm",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

import assert from 'node:assert';
import xtermDefault from '@xterm/xterm';
import {
  createTerminal,
  writeToTerminal,
  readTerminalLine,
  resizeTerminal,
  resetTerminal,
  disposeTerminal,
  Terminal
} from '../index.js';

async function run() {
  // 1. Verify default export provides Terminal constructor
  assert.ok(xtermDefault, '@xterm/xterm default export must exist');
  assert.strictEqual(typeof xtermDefault.Terminal, 'function', 'xtermDefault.Terminal must be a constructor function/class');
  assert.strictEqual(Terminal, xtermDefault.Terminal, 'Named Terminal export should match default.Terminal');

  // 2. Initialize Terminal with custom dimensions and options
  const term = createTerminal({
    cols: 80,
    rows: 24,
    cursorBlink: false,
    scrollback: 100
  });

  assert.ok(term instanceof Terminal, 'Instance must be an instance of Terminal');
  assert.strictEqual(term.cols, 80, 'Terminal columns must match configuration');
  assert.strictEqual(term.rows, 24, 'Terminal rows must match configuration');
  assert.strictEqual(term.options.cursorBlink, false, 'Terminal options.cursorBlink must match configuration');
  assert.strictEqual(term.options.scrollback, 100, 'Terminal options.scrollback must match configuration');

  // 3. Test writing to terminal asynchronously
  await writeToTerminal(term, 'Hello CodeSampleX!\r\nLine 2 content');

  // 4. Verify buffer content reading
  const line0 = readTerminalLine(term, 0);
  const line1 = readTerminalLine(term, 1);
  assert.strictEqual(line0, 'Hello CodeSampleX!', 'Line 0 should contain the first written line');
  assert.strictEqual(line1, 'Line 2 content', 'Line 1 should contain the second written line');

  // 5. Verify direct buffer access and translateToString
  const bufferLine0 = term.buffer.active.getLine(0);
  assert.ok(bufferLine0, 'Active buffer line 0 must exist');
  assert.strictEqual(bufferLine0.translateToString(true), 'Hello CodeSampleX!', 'translateToString with trimRight=true should match line content');
  assert.strictEqual(bufferLine0.translateToString(false).length, 80, 'translateToString without trimming should match terminal width');

  // 6. Test resizing terminal
  resizeTerminal(term, 120, 40);
  assert.strictEqual(term.cols, 120, 'Terminal columns should be updated to 120 after resize');
  assert.strictEqual(term.rows, 40, 'Terminal rows should be updated to 40 after resize');

  // 7. Test terminal reset and write
  resetTerminal(term);
  assert.strictEqual(readTerminalLine(term, 0), '', 'Line 0 should be empty after reset');
  await writeToTerminal(term, 'After reset');
  const resetLine0 = readTerminalLine(term, 0);
  assert.strictEqual(resetLine0, 'After reset', 'Line 0 should contain new content after reset');

  // 8. Clean teardown with dispose
  assert.doesNotThrow(() => {
    disposeTerminal(term);
  }, 'disposeTerminal must succeed without throwing');

  // 9. Second instance with direct constructor to verify independence
  const term2 = new xtermDefault.Terminal({ cols: 40, rows: 10 });
  assert.strictEqual(term2.cols, 40, 'Second terminal cols must be 40');
  assert.strictEqual(term2.rows, 10, 'Second terminal rows must be 10');

  let callbackCalled = false;
  await new Promise((resolve) => {
    term2.write('Standalone terminal test', () => {
      callbackCalled = true;
      resolve();
    });
  });

  assert.strictEqual(callbackCalled, true, 'Terminal.write callback must be invoked');
  const term2Line0 = term2.buffer.active.getLine(0)?.translateToString(true);
  assert.strictEqual(term2Line0, 'Standalone terminal test', 'Standalone terminal buffer line 0 must match written data');

  term2.dispose();

  console.log('Contract tests passed successfully.');
}

run().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});