@nomicfoundation/hardhat-utils 3.0.2 → 3.0.4

package/dist/src/internal/panic-errors.js

@@ -0,0 +1,24 @@
+export function panicErrorCodeToReason(errorCode) {
+    // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- we are only covering some of the integer range
+    switch (errorCode) {
+        case 0x1n:
+            return "Assertion error";
+        case 0x11n:
+            return "Arithmetic operation overflowed outside of an unchecked block";
+        case 0x12n:
+            return "Division or modulo division by zero";
+        case 0x21n:
+            return "Tried to convert a value into an enum, but the value was too big or negative";
+        case 0x22n:
+            return "Incorrectly encoded storage byte array";
+        case 0x31n:
+            return ".pop() was called on an empty array";
+        case 0x32n:
+            return "Array accessed at an out-of-bounds or negative index";
+        case 0x41n:
+            return "Too much memory was allocated, or an array was created that is too large";
+        case 0x51n:
+            return "Called a zero-initialized variable of internal function type";
+    }
+}
+//# sourceMappingURL=panic-errors.js.map

package/dist/src/internal/panic-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"panic-errors.js","sourceRoot":"","sources":["../../../src/internal/panic-errors.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,sBAAsB,CAAC,SAAiB;IACtD,4HAA4H;IAC5H,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,IAAI;YACP,OAAO,iBAAiB,CAAC;QAC3B,KAAK,KAAK;YACR,OAAO,+DAA+D,CAAC;QACzE,KAAK,KAAK;YACR,OAAO,qCAAqC,CAAC;QAC/C,KAAK,KAAK;YACR,OAAO,8EAA8E,CAAC;QACxF,KAAK,KAAK;YACR,OAAO,wCAAwC,CAAC;QAClD,KAAK,KAAK;YACR,OAAO,qCAAqC,CAAC;QAC/C,KAAK,KAAK;YACR,OAAO,sDAAsD,CAAC;QAChE,KAAK,KAAK;YACR,OAAO,0EAA0E,CAAC;QACpF,KAAK,KAAK;YACR,OAAO,8DAA8D,CAAC;IAC1E,CAAC;AACH,CAAC"}

package/dist/src/panic-errors.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Converts a Solidity panic error code into a human-readable revert message.
+ *
+ * Solidity defines a set of standardized panic codes (0x01, 0x11, etc.)
+ * that represent specific runtime errors (e.g. arithmetic overflow).
+ * This function looks up the corresponding reason string and formats it
+ * into a message similar to what clients like Hardhat or ethers.js display.
+ *
+ * @param errorCode The panic error code returned by the EVM as a bigint.
+ * @returns A formatted message string:
+ * - `"reverted with panic code <hex> (<reason>)"` if the code is recognized.
+ * - `"reverted with unknown panic code <hex>"` if the code is not recognized.
+ */
 export declare function panicErrorCodeToMessage(errorCode: bigint): string;
 //# sourceMappingURL=panic-errors.d.ts.map

package/dist/src/panic-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"panic-errors.d.ts","sourceRoot":"","sources":["../../src/panic-errors.ts"],"names":[],"mappings":"AAEA,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQjE"}
+{"version":3,"file":"panic-errors.d.ts","sourceRoot":"","sources":["../../src/panic-errors.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQjE"}

package/dist/src/panic-errors.js

@@ -1,4 +1,18 @@
 import { numberToHexString } from "./hex.js";
+import { panicErrorCodeToReason } from "./internal/panic-errors.js";
+/**
+ * Converts a Solidity panic error code into a human-readable revert message.
+ *
+ * Solidity defines a set of standardized panic codes (0x01, 0x11, etc.)
+ * that represent specific runtime errors (e.g. arithmetic overflow).
+ * This function looks up the corresponding reason string and formats it
+ * into a message similar to what clients like Hardhat or ethers.js display.
+ *
+ * @param errorCode The panic error code returned by the EVM as a bigint.
+ * @returns A formatted message string:
+ * - `"reverted with panic code <hex> (<reason>)"` if the code is recognized.
+ * - `"reverted with unknown panic code <hex>"` if the code is not recognized.
+ */
 export function panicErrorCodeToMessage(errorCode) {
     const reason = panicErrorCodeToReason(errorCode);
     if (reason !== undefined) {
@@ -6,27 +20,4 @@ export function panicErrorCodeToMessage(errorCode) {
     }
     return `reverted with unknown panic code ${numberToHexString(errorCode)}`;
 }
-function panicErrorCodeToReason(errorCode) {
-    // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- we are only covering some of the integer range
-    switch (errorCode) {
-        case 0x1n:
-            return "Assertion error";
-        case 0x11n:
-            return "Arithmetic operation overflowed outside of an unchecked block";
-        case 0x12n:
-            return "Division or modulo division by zero";
-        case 0x21n:
-            return "Tried to convert a value into an enum, but the value was too big or negative";
-        case 0x22n:
-            return "Incorrectly encoded storage byte array";
-        case 0x31n:
-            return ".pop() was called on an empty array";
-        case 0x32n:
-            return "Array accessed at an out-of-bounds or negative index";
-        case 0x41n:
-            return "Too much memory was allocated, or an array was created that is too large";
-        case 0x51n:
-            return "Called a zero-initialized variable of internal function type";
-    }
-}
 //# sourceMappingURL=panic-errors.js.map

package/dist/src/panic-errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"panic-errors.js","sourceRoot":"","sources":["../../src/panic-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C,MAAM,UAAU,uBAAuB,CAAC,SAAiB;IACvD,MAAM,MAAM,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAEjD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,4BAA4B,iBAAiB,CAAC,SAAS,CAAC,KAAK,MAAM,GAAG,CAAC;IAChF,CAAC;IAED,OAAO,oCAAoC,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;AAC5E,CAAC;AAED,SAAS,sBAAsB,CAAC,SAAiB;IAC/C,4HAA4H;IAC5H,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,IAAI;YACP,OAAO,iBAAiB,CAAC;QAC3B,KAAK,KAAK;YACR,OAAO,+DAA+D,CAAC;QACzE,KAAK,KAAK;YACR,OAAO,qCAAqC,CAAC;QAC/C,KAAK,KAAK;YACR,OAAO,8EAA8E,CAAC;QACxF,KAAK,KAAK;YACR,OAAO,wCAAwC,CAAC;QAClD,KAAK,KAAK;YACR,OAAO,qCAAqC,CAAC;QAC/C,KAAK,KAAK;YACR,OAAO,sDAAsD,CAAC;QAChE,KAAK,KAAK;YACR,OAAO,0EAA0E,CAAC;QACpF,KAAK,KAAK;YACR,OAAO,8DAA8D,CAAC;IAC1E,CAAC;AACH,CAAC"}
+{"version":3,"file":"panic-errors.js","sourceRoot":"","sources":["../../src/panic-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CAAC,SAAiB;IACvD,MAAM,MAAM,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAEjD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,4BAA4B,iBAAiB,CAAC,SAAS,CAAC,KAAK,MAAM,GAAG,CAAC;IAChF,CAAC;IAED,OAAO,oCAAoC,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;AAC5E,CAAC"}

package/dist/src/spinner.d.ts

@@ -0,0 +1,46 @@
+export declare const FRAME_INTERVAL_MS = 80;
+export interface ISpinner {
+    readonly isEnabled: boolean;
+    start(): void;
+    stop(): void;
+}
+/**
+ * Optional settings when creating a spinner.
+ */
+export interface SpinnerOptions {
+    /**
+     * Text shown next to the spinner.
+     */
+    text?: string;
+    /**
+     * Stream used to write frames.
+     */
+    stream?: NodeJS.WriteStream;
+    /**
+     * Whether the spinner is enabled.
+     */
+    enabled?: boolean;
+}
+/**
+ * Create a spinner instance.
+ *
+ * @example
+ * ```typescript
+ * const spinner = createSpinner({ text: "Compiling…" });
+ * spinner.start();
+ *
+ * try {
+ *   await compileContracts();
+ *   spinner.stop();
+ *   console.log("Compiled 12 contracts");
+ * } catch (error) {
+ *   spinner.stop();
+ *   console.error("Compilation failed");
+ * }
+ * ```
+ *
+ * @param options  Optional spinner configuration.
+ * @returns {Spinner} A spinner instance.
+ */
+export declare function createSpinner(options?: SpinnerOptions): ISpinner;
+//# sourceMappingURL=spinner.d.ts.map

package/dist/src/spinner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../../src/spinner.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;IAE5B;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAmED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,QAAQ,CAcpE"}

package/dist/src/spinner.js

@@ -0,0 +1,91 @@
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export const FRAME_INTERVAL_MS = 80;
+/**
+ * Spinner that writes frames to a stream.
+ */
+class Spinner {
+    isEnabled;
+    #text;
+    #interval = null;
+    #stream;
+    constructor(options) {
+        this.isEnabled = options.enabled;
+        this.#stream = options.stream;
+        this.#text = options.text;
+    }
+    /**
+     * Begin rendering frames when enabled.
+     */
+    start() {
+        if (!this.isEnabled) {
+            return;
+        }
+        this.#stopAnimation();
+        let frameIndex = 0;
+        this.#interval = setInterval(() => {
+            this.#render(FRAMES[frameIndex]);
+            frameIndex = (frameIndex + 1) % FRAMES.length;
+        }, FRAME_INTERVAL_MS);
+    }
+    /**
+     * Stop the spinner without printing a final line.
+     */
+    stop() {
+        this.#stopAnimation();
+    }
+    #clearLine() {
+        this.#stream.clearLine(0);
+        this.#stream.cursorTo(0);
+    }
+    #render(frame) {
+        if (!this.isEnabled) {
+            return;
+        }
+        this.#clearLine();
+        this.#stream.write(`${frame} ${this.#text}`);
+    }
+    #stopAnimation() {
+        if (this.#interval === null) {
+            return;
+        }
+        clearInterval(this.#interval);
+        this.#interval = null;
+        if (this.isEnabled) {
+            this.#clearLine();
+        }
+    }
+}
+/**
+ * Create a spinner instance.
+ *
+ * @example
+ * ```typescript
+ * const spinner = createSpinner({ text: "Compiling…" });
+ * spinner.start();
+ *
+ * try {
+ *   await compileContracts();
+ *   spinner.stop();
+ *   console.log("Compiled 12 contracts");
+ * } catch (error) {
+ *   spinner.stop();
+ *   console.error("Compilation failed");
+ * }
+ * ```
+ *
+ * @param options  Optional spinner configuration.
+ * @returns {Spinner} A spinner instance.
+ */
+export function createSpinner(options = {}) {
+    const stream = options.stream ?? process.stdout;
+    const enabled = stream.isTTY === true &&
+        process.env.TERM !== "dumb" &&
+        (options.enabled ?? true);
+    const text = options.text ?? "";
+    return new Spinner({
+        enabled,
+        stream,
+        text,
+    });
+}
+//# sourceMappingURL=spinner.js.map

package/dist/src/spinner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.js","sourceRoot":"","sources":["../../src/spinner.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAClE,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AA4BpC;;GAEG;AACH,MAAM,OAAO;IACK,SAAS,CAAU;IAC1B,KAAK,CAAS;IACvB,SAAS,GAA0B,IAAI,CAAC;IAC/B,OAAO,CAAqB;IAErC,YAAY,OAAiC;QAC3C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAC5B,CAAC;IACD;;OAEG;IACI,KAAK;QACV,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,UAAU,GAAG,CAAC,CAAC;QAEnB,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;YAChC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;YACjC,UAAU,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;QAChD,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACxB,CAAC;IAED;;OAEG;IACI,IAAI;QACT,IAAI,CAAC,cAAc,EAAE,CAAC;IACxB,CAAC;IAED,UAAU;QACR,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IAED,OAAO,CAAC,KAAa;QACnB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,cAAc;QACZ,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QAEtB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,aAAa,CAAC,UAA0B,EAAE;IACxD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAEhD,MAAM,OAAO,GACX,MAAM,CAAC,KAAK,KAAK,IAAI;QACrB,OAAO,CAAC,GAAG,CAAC,IAAI,KAAK,MAAM;QAC3B,CAAC,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC;IAE5B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;IAChC,OAAO,IAAI,OAAO,CAAC;QACjB,OAAO;QACP,MAAM;QACN,IAAI;KACL,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomicfoundation/hardhat-utils",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "Utilities for Hardhat and its plugins",
   "homepage": "https://github.com/nomicfoundation/hardhat/tree/v-next/v-next/hardhat-utils",
   "repository": {
@@ -23,6 +23,7 @@
     "./env": "./dist/src/env.js",
     "./error": "./dist/src/error.js",
     "./eth": "./dist/src/eth.js",
+    "./format": "./dist/src/format.js",
     "./fs": "./dist/src/fs.js",
     "./global-dir": "./dist/src/global-dir.js",
     "./hex": "./dist/src/hex.js",
@@ -35,7 +36,8 @@
     "./string": "./dist/src/string.js",
     "./stream": "./dist/src/stream.js",
     "./subprocess": "./dist/src/subprocess.js",
-    "./synchronization": "./dist/src/synchronization.js"
+    "./synchronization": "./dist/src/synchronization.js",
+    "./spinner": "./dist/src/spinner.js"
   },
   "keywords": [
     "ethereum",

package/src/format.ts

@@ -0,0 +1,267 @@
+import {
+  getColumnWidths,
+  getContentWidth,
+  getHeadingWidth,
+  getStringWidth,
+  renderContentLine,
+  renderHeaderOpen,
+  renderRowSeparator,
+  renderSectionClose,
+} from "./internal/format.js";
+
+export type TableRow = string[];
+export interface TableDivider {
+  type: "divider";
+}
+export type TableItem = TableRow | TableDivider;
+
+export const divider: TableDivider = { type: "divider" };
+
+/**
+ * Formats an array of rows and dividers into a table string.
+ *
+ * @param items An array of table rows (string arrays) and dividers.
+ * Dividers are objects with type: "divider" and will be rendered as table dividers.
+ * @returns The formatted table as a string, ready to be rendered.
+ *
+ * @example
+ * ```ts
+ * formatTable([
+ *   ["Name", "Age"],
+ *   divider,
+ *   ["Alice", "30"],
+ *   ["Bob", "25"],
+ *   divider,
+ *   ["Average", "27.5"]
+ * ]);
+ *
+ * // =>
+ * // | Name    | Age  |
+ * // | ------- | ---- |
+ * // | Alice   | 30   |
+ * // | Bob     | 25   |
+ * // | ------- | ---- |
+ * // | Average | 27.5 |
+ * ```
+ */
+export function formatTable(items: TableItem[]): string {
+  const widths: number[] = [];
+  const dataRows: string[][] = [];
+
+  for (const item of items) {
+    if (Array.isArray(item)) {
+      dataRows.push([...item]);
+    }
+  }
+
+  // Calculate maximum width for each column
+  for (const row of dataRows) {
+    for (let i = 0; i < row.length; i++) {
+      while (i >= widths.length) {
+        widths.push(0);
+      }
+      widths[i] = Math.max(widths[i], getStringWidth(row[i]));
+    }
+  }
+
+  const dividerRow = widths.map((width) => "-".repeat(width));
+  const outputRows: string[][] = [];
+
+  for (const item of items) {
+    if (Array.isArray(item)) {
+      const row = [...item];
+      // Pad the row to match the number of columns
+      while (row.length < widths.length) {
+        row.push("");
+      }
+      outputRows.push(row);
+    } else {
+      outputRows.push([...dividerRow]);
+    }
+  }
+
+  outputRows.forEach((row) => {
+    for (let i = 0; i < row.length; i++) {
+      const displayWidth = getStringWidth(row[i]);
+      const actualLength = row[i].length;
+      // Adjust padding to account for difference between display width and actual length
+      row[i] = row[i].padEnd(widths[i] + actualLength - displayWidth);
+    }
+  });
+
+  return outputRows.map((row) => `| ${row.join(" | ")} |`).join("\n");
+}
+
+export interface TableTitleV2 {
+  type: "title";
+  text: string;
+}
+
+export interface TableSectionHeaderV2 {
+  type: "section-header";
+  text: string;
+}
+
+export interface TableHeaderV2 {
+  type: "header";
+  cells: string[];
+}
+
+export interface TableRowV2 {
+  type: "row";
+  cells: string[];
+}
+
+export type TableItemV2 =
+  | TableTitleV2
+  | TableSectionHeaderV2
+  | TableHeaderV2
+  | TableRowV2;
+
+/**
+ * Formats an array of titles, section headers, headers, and rows into a table
+ * string with box-drawing characters.
+ *
+ * Features:
+ * - Titles are centered in a standalone box with double borders (╔═╗)
+ * - Section headers group related content with automatic closing
+ * - Headers and rows can have different numbers of cells
+ * - Rows with fewer cells than max columns are handled with special rendering
+ *
+ * @param items An array of table items (titles, section headers, headers, and rows).
+ * Sections are automatically closed when a new section-header or title appears, or
+ * at the end of the table.
+ * @returns The formatted table as a string, ready to be rendered.
+ *
+ * @example
+ * ```ts
+ * formatTableV2([
+ *   { type: "title", text: "My Table" },
+ *   { type: "section-header", text: "User Data" },
+ *   { type: "header", cells: ["Name", "Age", "City"] },
+ *   { type: "row", cells: ["Alice", "30", "NYC"] },
+ *   { type: "row", cells: ["Bob", "25", "LA"] },
+ *   { type: "section-header", text: "Summary" },
+ *   { type: "header", cells: ["Total", "Count"] },
+ *   { type: "row", cells: ["55", "2"] }
+ * ]);
+ *
+ * // =>
+ * // ╔═══════════════════╗
+ * // ║     My Table      ║
+ * // ╚═══════════════════╝
+ * // ╔═══════════════════╗
+ * // ║ User Data         ║
+ * // ╟───────┬─────┬─────╢
+ * // ║ Name  │ Age │ City║
+ * // ╟───────┼─────┼─────╢
+ * // ║ Alice │ 30  │ NYC ║
+ * // ╟───────┼─────┼─────╢
+ * // ║ Bob   │ 25  │ LA  ║
+ * // ╚═══════╧═════╧═════╝
+ * // ╔═══════════════════╗
+ * // ║ Summary           ║
+ * // ╟───────┬───────────╢
+ * // ║ Total │ Count     ║
+ * // ╟───────┼───────────╢
+ * // ║ 55    │ 2         ║
+ * // ╚═══════╧═══════════╝
+ * ```
+ */
+export function formatTableV2(items: TableItemV2[]): string {
+  if (items.length === 0) {
+    return "";
+  }
+
+  const columnWidths = getColumnWidths(items);
+  const contentWidth = getContentWidth(columnWidths);
+  const headingWidth = getHeadingWidth(items);
+
+  // If heading is wider than content, expand last column to fit
+  if (headingWidth > contentWidth && columnWidths.length > 0) {
+    const extraSpace = headingWidth - contentWidth;
+    columnWidths[columnWidths.length - 1] += extraSpace;
+  }
+
+  const tableWidth = Math.max(contentWidth, headingWidth);
+
+  const lines: string[] = [];
+  let previousCellCount = 0; // Keep track of previous row/header cell count
+  let inSection = false;
+
+  for (let i = 0; i < items.length; i++) {
+    const [previous, current] = [items[i - 1], items[i]];
+
+    if (current.type === "title") {
+      if (inSection) {
+        lines.push(renderSectionClose(columnWidths, previousCellCount));
+        inSection = false;
+      }
+
+      lines.push("╔" + "═".repeat(tableWidth) + "╗");
+      const titleDisplayWidth = getStringWidth(current.text);
+      const titleActualLength = current.text.length;
+      const centeredTitle = current.text
+        .padStart(
+          (tableWidth + titleDisplayWidth) / 2 +
+            (titleActualLength - titleDisplayWidth),
+        )
+        .padEnd(tableWidth + (titleActualLength - titleDisplayWidth));
+      lines.push("║" + centeredTitle + "║");
+      lines.push("╚" + "═".repeat(tableWidth) + "╝");
+    } else if (current.type === "section-header") {
+      if (inSection) {
+        lines.push(renderSectionClose(columnWidths, previousCellCount));
+      }
+
+      lines.push("╔" + "═".repeat(tableWidth) + "╗");
+      const headerDisplayWidth = getStringWidth(current.text);
+      const headerActualLength = current.text.length;
+      const paddedHeader = current.text.padEnd(
+        tableWidth - 2 + (headerActualLength - headerDisplayWidth),
+      );
+      lines.push("║ " + paddedHeader + " ║");
+      inSection = true;
+    } else if (current.type === "header") {
+      const currentCellCount = current.cells.length;
+      const innerJoiner =
+        previous !== undefined && previous.type === "section-header"
+          ? "┬"
+          : "┼";
+      const needsTransition =
+        previous !== undefined &&
+        previous.type !== "section-header" &&
+        currentCellCount < previousCellCount;
+
+      lines.push(
+        renderHeaderOpen(
+          columnWidths,
+          currentCellCount,
+          innerJoiner,
+          needsTransition,
+        ),
+      );
+      lines.push(
+        renderContentLine(current.cells, columnWidths, currentCellCount),
+      );
+      previousCellCount = currentCellCount;
+    } else if (current.type === "row") {
+      const currentCellCount = current.cells.length;
+
+      // Only add separator if previous wasn't a row
+      if (previous === undefined || previous.type !== "row") {
+        lines.push(renderRowSeparator(columnWidths, currentCellCount));
+      }
+      lines.push(
+        renderContentLine(current.cells, columnWidths, currentCellCount),
+      );
+      previousCellCount = currentCellCount;
+    }
+  }
+
+  if (inSection) {
+    lines.push(renderSectionClose(columnWidths, previousCellCount));
+  }
+
+  return lines.join("\n");
+}