@xterm/addon-fit 0.10.0

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 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

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:9bef68aa3df7635ae5c134da9ca1da728a73ac3ae9d62bff3b6d792e71837a08","contract":["FitAddon constructor creates an instance with activate, dispose, fit, and proposeDimensions methods","proposeDimensions returns undefined when the addon is not yet activated on a terminal","proposeDimensions returns undefined when terminal element has no parent element","proposeDimensions returns undefined when cell dimensions width or height are 0","proposeDimensions calculates cols and rows based on parent element dimensions and terminal padding","proposeDimensions subtracts scrollbar width when scrollback is non-zero and ignores scrollbar width when scrollback is zero","proposeDimensions clamps cols to at least 2 and rows to at least 1","fit resizes terminal and clears render service when proposed dimensions differ from current dimensions","fit does not resize or clear when terminal dimensions already match proposed dimensions","dispose cleanly disposes the addon instance"],"goal":"verify pkg:npm/%40xterm/addon-fit@0.10.0","kind":"HOW","packages":["pkg:npm/%40xterm/addon-fit@0.10.0"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","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","verifierAdapter":"node-typescript@1"}

// Polyfill global self if running in Node.js environment where Webpack UMD bundle expects self
if (typeof globalThis.self === 'undefined') {
  globalThis.self = globalThis;
}

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

export { FitAddon };

export function createFitAddon() {
  return new FitAddon();
}

export function fitTerminal(terminal, addon) {
  if (!addon) {
    addon = new FitAddon();
    if (typeof terminal.loadAddon === 'function') {
      terminal.loadAddon(addon);
    } else {
      addon.activate(terminal);
    }
  }
  addon.fit();
  return addon;
}

{
  "name": "verify-xterm-addon-fit",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "verify-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": "verify-xterm-addon-fit",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "@xterm/addon-fit": "0.10.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40xterm/addon-fit@0.10.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40xterm/addon-fit@0.10.0"
  ]
}

import assert from 'node:assert/strict';

// In Node.js environment, the Webpack UMD bundle for @xterm/addon-fit expects global `self`.
// Static ESM imports are evaluated prior to module body execution;
// setting globalThis.self before dynamic import ensures safe execution in Node.js.
if (typeof globalThis.self === 'undefined') {
  globalThis.self = globalThis;
}

const { FitAddon } = await import('@xterm/addon-fit');
const { createFitAddon, fitTerminal } = await import('../index.mjs');

// Setup DOM mock for terminal fit calculation
function setupDOMMock() {
  globalThis.window = {
    getComputedStyle(elem) {
      return {
        getPropertyValue(prop) {
          return (elem.styles && elem.styles[prop]) || '0px';
        }
      };
    }
  };
}

setupDOMMock();

function createMockTerminal({
  parentWidth = '800px',
  parentHeight = '600px',
  paddingLeft = '10px',
  paddingRight = '10px',
  paddingTop = '5px',
  paddingBottom = '5px',
  scrollback = 500,
  scrollBarWidth = 15,
  cellWidth = 10,
  cellHeight = 20,
  initialCols = 80,
  initialRows = 24,
  hasElement = true,
  hasParentElement = true
} = {}) {
  let cleared = false;
  let resizedCols = initialCols;
  let resizedRows = initialRows;

  let parentElement = null;
  if (hasParentElement) {
    parentElement = {
      styles: {
        width: parentWidth,
        height: parentHeight
      }
    };
  }

  let element = null;
  if (hasElement) {
    element = {
      parentElement,
      styles: {
        'padding-left': paddingLeft,
        'padding-right': paddingRight,
        'padding-top': paddingTop,
        'padding-bottom': paddingBottom
      }
    };
  }

  const terminal = {
    element,
    options: { scrollback },
    cols: initialCols,
    rows: initialRows,
    _core: {
      viewport: { scrollBarWidth },
      _renderService: {
        dimensions: {
          css: {
            cell: {
              width: cellWidth,
              height: cellHeight
            }
          }
        },
        clear() {
          cleared = true;
        }
      }
    },
    resize(cols, rows) {
      this.cols = cols;
      this.rows = rows;
      resizedCols = cols;
      resizedRows = rows;
    },
    get isCleared() {
      return cleared;
    },
    resetCleared() {
      cleared = false;
    }
  };

  return terminal;
}

// Contract 1: FitAddon constructor creates an instance with activate, dispose, fit, and proposeDimensions methods
{
  const addon = new FitAddon();
  assert.strictEqual(typeof addon.activate, 'function', 'activate must be a function');
  assert.strictEqual(typeof addon.dispose, 'function', 'dispose must be a function');
  assert.strictEqual(typeof addon.fit, 'function', 'fit must be a function');
  assert.strictEqual(typeof addon.proposeDimensions, 'function', 'proposeDimensions must be a function');

  const helperAddon = createFitAddon();
  assert.ok(helperAddon instanceof FitAddon, 'createFitAddon must return an instance of FitAddon');
}

// Contract 2: proposeDimensions returns undefined when the addon is not yet activated on a terminal
{
  const addon = new FitAddon();
  const dims = addon.proposeDimensions();
  assert.strictEqual(dims, undefined, 'proposeDimensions should return undefined before activate()');
}

// Contract 3: proposeDimensions returns undefined when terminal element has no parent element
{
  const addon = new FitAddon();
  const termNoElem = createMockTerminal({ hasElement: false });
  addon.activate(termNoElem);
  assert.strictEqual(addon.proposeDimensions(), undefined, 'proposeDimensions should return undefined when terminal has no element');

  const termNoParent = createMockTerminal({ hasParentElement: false });
  addon.activate(termNoParent);
  assert.strictEqual(addon.proposeDimensions(), undefined, 'proposeDimensions should return undefined when terminal element has no parent');
}

// Contract 4: proposeDimensions returns undefined when cell dimensions width or height are 0
{
  const addon = new FitAddon();
  const termZeroWidth = createMockTerminal({ cellWidth: 0, cellHeight: 20 });
  addon.activate(termZeroWidth);
  assert.strictEqual(addon.proposeDimensions(), undefined, 'proposeDimensions should return undefined when cell width is 0');

  const termZeroHeight = createMockTerminal({ cellWidth: 10, cellHeight: 0 });
  addon.activate(termZeroHeight);
  assert.strictEqual(addon.proposeDimensions(), undefined, 'proposeDimensions should return undefined when cell height is 0');
}

// Contract 5: proposeDimensions calculates cols and rows based on parent element dimensions and terminal padding
{
  const addon = new FitAddon();
  // Parent: 800x600, padding-left: 10, padding-right: 10, padding-top: 5, padding-bottom: 5
  // scrollback: 500 (scrollBarWidth: 15)
  // cell: 10x20
  // availableWidth = 800 - (10 + 10) - 15 = 765 -> cols = floor(765 / 10) = 76
  // availableHeight = 600 - (5 + 5) = 590 -> rows = floor(590 / 20) = 29
  const term = createMockTerminal({
    parentWidth: '800px',
    parentHeight: '600px',
    paddingLeft: '10px',
    paddingRight: '10px',
    paddingTop: '5px',
    paddingBottom: '5px',
    scrollback: 500,
    scrollBarWidth: 15,
    cellWidth: 10,
    cellHeight: 20
  });

  addon.activate(term);
  const dims = addon.proposeDimensions();
  assert.deepStrictEqual(dims, { cols: 76, rows: 29 }, 'proposeDimensions should calculate cols and rows correctly');
}

// Contract 6: proposeDimensions subtracts scrollbar width when scrollback is non-zero and ignores scrollbar width when scrollback is zero
{
  const addon = new FitAddon();
  // With scrollback = 0:
  // availableWidth = 800 - (10 + 10) - 0 = 780 -> cols = floor(780 / 10) = 78
  // availableHeight = 600 - (5 + 5) = 590 -> rows = floor(590 / 20) = 29
  const term = createMockTerminal({
    parentWidth: '800px',
    parentHeight: '600px',
    paddingLeft: '10px',
    paddingRight: '10px',
    paddingTop: '5px',
    paddingBottom: '5px',
    scrollback: 0,
    scrollBarWidth: 15,
    cellWidth: 10,
    cellHeight: 20
  });

  addon.activate(term);
  const dims = addon.proposeDimensions();
  assert.deepStrictEqual(dims, { cols: 78, rows: 29 }, 'proposeDimensions with scrollback 0 should ignore scrollBarWidth');
}

// Contract 7: proposeDimensions clamps cols to at least 2 and rows to at least 1
{
  const addon = new FitAddon();
  const tinyTerm = createMockTerminal({
    parentWidth: '5px',
    parentHeight: '5px',
    cellWidth: 10,
    cellHeight: 20
  });

  addon.activate(tinyTerm);
  const dims = addon.proposeDimensions();
  assert.deepStrictEqual(dims, { cols: 2, rows: 1 }, 'proposeDimensions should clamp cols >= 2 and rows >= 1');
}

// Contract 8: fit resizes terminal and clears render service when proposed dimensions differ from current dimensions
{
  const addon = new FitAddon();
  const term = createMockTerminal({
    parentWidth: '800px',
    parentHeight: '600px',
    initialCols: 80,
    initialRows: 24,
    scrollback: 500,
    scrollBarWidth: 15,
    cellWidth: 10,
    cellHeight: 20
  });

  addon.activate(term);
  assert.strictEqual(term.cols, 80);
  assert.strictEqual(term.rows, 24);
  assert.strictEqual(term.isCleared, false);

  addon.fit();
  assert.strictEqual(term.cols, 76, 'fit should resize terminal cols to 76');
  assert.strictEqual(term.rows, 29, 'fit should resize terminal rows to 29');
  assert.strictEqual(term.isCleared, true, 'fit should call clear() on render service');
}

// Contract 9: fit does not resize or clear when terminal dimensions already match proposed dimensions
{
  const addon = new FitAddon();
  const term = createMockTerminal({
    parentWidth: '800px',
    parentHeight: '600px',
    initialCols: 76,
    initialRows: 29,
    scrollback: 500,
    scrollBarWidth: 15,
    cellWidth: 10,
    cellHeight: 20
  });

  addon.activate(term);
  addon.fit();
  assert.strictEqual(term.cols, 76);
  assert.strictEqual(term.rows, 29);
  assert.strictEqual(term.isCleared, false, 'fit should not clear render service when already at target size');
}

// Contract 10: dispose cleanly disposes the addon instance
{
  const addon = new FitAddon();
  const term = createMockTerminal();
  addon.activate(term);
  assert.doesNotThrow(() => addon.dispose(), 'dispose should not throw');
}

console.log('All @xterm/addon-fit contract tests passed successfully.');