@xterm/addon-fit 0.10.0: FitAddon.fit

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 FitAddon.fit in pkg:npm/%40xterm/addon-fit@0.10.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40xterm/addon-fit@0.10.0
Demonstrate these symbols/APIs:
  - FitAddon.fit
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - 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:4d1d669a9ce6a6a0af0b0a5ca94ebb222450bbfc6423119036975a2c59ee0bfd","constraints":{"executionContext":"node"},"contract":["FitAddon exports a constructor class with activate, dispose, fit, and proposeDimensions methods","proposeDimensions returns undefined when unattached or when terminal element is not in DOM","proposeDimensions returns undefined when renderService cell dimensions are zero","proposeDimensions calculates cols and rows based on container dimensions, cell dimensions, and scrollbar width","FitAddon.fit resizes terminal and clears render service when proposed dimensions differ from current terminal dimensions","FitAddon.fit is a no-op when proposed dimensions match current terminal dimensions or cannot be computed","FitAddon.dispose completes cleanly without error"],"goal":"verify FitAddon.fit in pkg:npm/%40xterm/addon-fit@0.10.0","kind":"HOW","packages":["pkg:npm/%40xterm/addon-fit@0.10.0"],"schemaVersion":1,"symbols":["FitAddon.fit"]},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","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/addon-fit@0.10.0"],"schemaVersion":1,"subject":"pkg:npm/%40xterm/addon-fit@0.10.0","symbols":["FitAddon.fit"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-xterm-addon-fit",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-xterm-addon-fit",
      "version": "1.0.0",
      "dependencies": {
        "@xterm/addon-fit": "0.10.0"
      }
    },
    "node_modules/@xterm/addon-fit": {
      "version": "0.10.0",
      "resolved": "https://registry.npmjs.org/@xterm/addon-fit/-/addon-fit-0.10.0.tgz",
      "integrity": "sha512-UFYkDm4HUahf2lnEyHvio51TNGiLK66mqP2JoATy7hRZeXaGMRDr00JiSF7m63vR5WKATF605yEggJKsw0JpMQ==",
      "license": "MIT",
      "peerDependencies": {
        "@xterm/xterm": "^5.0.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",
      "peer": true
    }
  }
}

{
  "name": "sample-xterm-addon-fit",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of @xterm/addon-fit",
  "main": "src/index.js",
  "dependencies": {
    "@xterm/addon-fit": "0.10.0"
  }
}

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

// Ensure self is defined in Node.js environments prior to loading @xterm/addon-fit
if (typeof self === 'undefined') {
  globalThis.self = globalThis;
}

const { FitAddon } = require('@xterm/addon-fit');

/**
 * Creates and returns a new FitAddon instance.
 *
 * @returns {FitAddon}
 */
function createFitAddon() {
  return new FitAddon();
}

/**
 * Attaches a FitAddon to a terminal instance.
 *
 * @param {FitAddon} addon
 * @param {object} terminal
 */
function activateFitAddon(addon, terminal) {
  if (!addon || typeof addon.activate !== 'function') {
    throw new TypeError('Expected addon with activate method');
  }
  addon.activate(terminal);
}

/**
 * Proposes dimensions or fits the terminal to the parent container dimensions.
 *
 * @param {FitAddon} addon
 * @returns {{ cols: number, rows: number } | undefined}
 */
function fitTerminal(addon) {
  if (!addon || typeof addon.fit !== 'function') {
    throw new TypeError('Expected addon with fit method');
  }
  addon.fit();
  return addon.proposeDimensions();
}

module.exports = {
  FitAddon,
  createFitAddon,
  activateFitAddon,
  fitTerminal
};

const assert = require('node:assert/strict');
const { FitAddon, createFitAddon, activateFitAddon, fitTerminal } = require('../src/index.js');

// 1. FitAddon exports a constructor class with activate, dispose, fit, and proposeDimensions methods
assert.equal(typeof FitAddon, 'function', 'FitAddon must be a constructor function/class');
const addon = new FitAddon();
assert.equal(typeof addon.activate, 'function', 'addon.activate must be a function');
assert.equal(typeof addon.dispose, 'function', 'addon.dispose must be a function');
assert.equal(typeof addon.fit, 'function', 'addon.fit must be a function');
assert.equal(typeof addon.proposeDimensions, 'function', 'addon.proposeDimensions must be a function');

assert.equal(typeof createFitAddon, 'function', 'createFitAddon helper must be a function');
assert.equal(typeof activateFitAddon, 'function', 'activateFitAddon helper must be a function');
assert.equal(typeof fitTerminal, 'function', 'fitTerminal helper must be a function');

// 2. proposeDimensions returns undefined when unattached or when terminal element is not in DOM
assert.equal(addon.proposeDimensions(), undefined, 'proposeDimensions should return undefined before activate');

// Terminal without element or parentElement
const unattachedTerminal = {
  rows: 24,
  cols: 80,
  options: { scrollback: 1000 },
  _core: {
    viewport: { scrollBarWidth: 15 },
    _renderService: {
      dimensions: { css: { cell: { width: 10, height: 20 } } },
      clear: () => {}
    }
  },
  resize: () => {}
};
addon.activate(unattachedTerminal);
assert.equal(addon.proposeDimensions(), undefined, 'proposeDimensions should return undefined without DOM element');

// 3. proposeDimensions returns undefined when renderService cell dimensions are zero
globalThis.window = {
  getComputedStyle: (elem) => elem.style || { getPropertyValue: () => '0' }
};

const zeroCellTerminal = {
  rows: 24,
  cols: 80,
  options: { scrollback: 1000 },
  element: {
    parentElement: {
      style: {
        getPropertyValue: (prop) => {
          if (prop === 'height') return '400px';
          if (prop === 'width') return '800px';
          return '0px';
        }
      }
    },
    style: { getPropertyValue: () => '0px' }
  },
  _core: {
    viewport: { scrollBarWidth: 15 },
    _renderService: {
      dimensions: { css: { cell: { width: 0, height: 0 } } },
      clear: () => {}
    }
  },
  resize: () => {}
};
addon.activate(zeroCellTerminal);
assert.equal(addon.proposeDimensions(), undefined, 'proposeDimensions should return undefined when cell dimensions are 0');

// 4. proposeDimensions calculates cols and rows based on container dimensions, cell dimensions, and scrollbar width
let clearCount = 0;
let lastResized = null;

const activeTerminal = {
  rows: 24,
  cols: 80,
  options: { scrollback: 1000 },
  element: {
    parentElement: {
      style: {
        getPropertyValue: (prop) => {
          if (prop === 'height') return '600px';
          if (prop === 'width') return '1000px';
          return '0px';
        }
      }
    },
    style: {
      getPropertyValue: (prop) => {
        if (prop === 'padding-top') return '10px';
        if (prop === 'padding-bottom') return '10px';
        if (prop === 'padding-left') return '5px';
        if (prop === 'padding-right') return '5px';
        return '0px';
      }
    }
  },
  _core: {
    viewport: { scrollBarWidth: 14 },
    _renderService: {
      dimensions: {
        css: {
          cell: { width: 9, height: 18 }
        }
      },
      clear: () => { clearCount++; }
    }
  },
  resize: (cols, rows) => {
    lastResized = { cols, rows };
    activeTerminal.cols = cols;
    activeTerminal.rows = rows;
  }
};

addon.activate(activeTerminal);
// Available height: 600 - (10 + 10) = 580 -> rows: Math.floor(580 / 18) = 32
// Available width: 1000 - (5 + 5) - 14 = 976 -> cols: Math.floor(976 / 9) = 108
const calculatedDims = addon.proposeDimensions();
assert.deepEqual(calculatedDims, { cols: 108, rows: 32 });

// 5. FitAddon.fit resizes terminal and clears render service when proposed dimensions differ from current terminal dimensions
addon.fit();
assert.equal(clearCount, 1, 'clear() should be called on render service');
assert.deepEqual(lastResized, { cols: 108, rows: 32 }, 'resize() should be called with proposed dimensions');
assert.equal(activeTerminal.cols, 108);
assert.equal(activeTerminal.rows, 32);

// Also verify fitTerminal helper
const helperAddon = createFitAddon();
activateFitAddon(helperAddon, activeTerminal);
const helperDims = fitTerminal(helperAddon);
assert.deepEqual(helperDims, { cols: 108, rows: 32 });

// 6. FitAddon.fit is a no-op when proposed dimensions match current terminal dimensions or cannot be computed
addon.fit();
assert.equal(clearCount, 1, 'clear() should not be called again if dimensions match');

const freshAddon = createFitAddon();
freshAddon.fit(); // Should not throw on unattached addon

// 7. FitAddon.dispose completes cleanly without error
assert.doesNotThrow(() => {
  addon.dispose();
  freshAddon.dispose();
  helperAddon.dispose();
}, 'dispose should complete cleanly without throwing');

console.log('All contract assertions passed successfully.');