@visulima/task-runner 1.0.0-alpha.3 → 1.0.0-alpha.5

package/dist/flow-controllers/log-timings.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Log timings flow controller.
+ *
+ * Prints a summary table of all command durations after completion.
+ */
+import type { ConcurrentCloseEvent } from "../types.d.ts";
+/**
+ * Generate a timing summary table string from close events.
+ * @param closeEvents Close events from the concurrent run (in completion order)
+ * @returns Formatted table string
+ */
+export declare const formatTimingTable: (closeEvents: ConcurrentCloseEvent[]) => string;
+/**
+ * Print timing summary to a writable stream.
+ * @param closeEvents Close events from the concurrent run
+ * @param output Output stream (default: process.stdout)
+ */
+export declare const logTimings: (closeEvents: ConcurrentCloseEvent[], output?: NodeJS.WritableStream) => void;

package/dist/flow-controllers/restart-process.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Restart flow controller.
+ *
+ * Re-runs failed commands with configurable retry count and delay.
+ * Supports fixed delay or exponential backoff.
+ */
+import type { ConcurrentCommandConfig, ConcurrentRunnerOptions, ConcurrentRunResult } from "../types.d.ts";
+export interface RestartOptions {
+    /** Delay between restarts in milliseconds. "exponential" for 2^attempt * 1000ms. */
+    delay: number | "exponential";
+    /** Maximum number of restart attempts per command. 0 = no restarts. -1 = infinite. */
+    tries: number;
+}
+/**
+ * Wraps a runner function to add restart-on-failure behavior.
+ * @param runFn The underlying runner function (runConcurrently or runConcurrentFallback)
+ * @param commands The original command configs
+ * @param options Runner options
+ * @param restartOptions Restart-specific options
+ */
+export declare const withRestart: (runFunction: (commands: ConcurrentCommandConfig[], options: ConcurrentRunnerOptions) => Promise<ConcurrentRunResult>, commands: ConcurrentCommandConfig[], options: ConcurrentRunnerOptions, restartOptions: RestartOptions) => Promise<ConcurrentRunResult>;

package/dist/flow-controllers/teardown.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Teardown flow controller.
+ *
+ * Runs cleanup commands sequentially after all concurrent processes complete.
+ * Each teardown command inherits stdio (output goes directly to terminal).
+ *
+ * Commands are sourced from configuration (trusted, not user input).
+ * Shell execution is intentional for pipe/redirect support.
+ */
+export interface TeardownOptions {
+    /** Commands to run in sequence after all processes complete. */
+    commands: string[];
+    /** Working directory for teardown commands. */
+    cwd?: string;
+}
+/**
+ * Run teardown commands sequentially.
+ * Each command runs in the shell with inherited stdio.
+ * If a command fails, subsequent commands are still attempted.
+ * @returns Array of exit codes for each teardown command
+ */
+export declare const runTeardown: (options: TeardownOptions) => Promise<number[]>;

package/dist/index.d.ts

@@ -1,12 +1,19 @@
 export type { AffectedOptions, AffectedResult } from "./affected.d.ts";
-export { filterAffectedTasks, getAffectedProjects, getChangedFiles } from "./affected.d.ts";
+export { buildForwardDependencyMap, buildReverseDependencyMap, expandAffected, filterAffectedTasks, getAffectedProjects, getChangedFiles } from "./affected.d.ts";
 export type { CachedResult, CacheOptions } from "./cache.d.ts";
-export { Cache, formatCacheSize, parseCacheSize } from "./cache.d.ts";
+export { Cache, DEFAULT_CACHE_DIRECTORY_NAME, formatCacheSize, parseCacheSize } from "./cache.d.ts";
+export type { ParseCommandsOptions } from "./command-parser/index.d.ts";
+export { expandArguments, expandShortcut, expandWildcard, parseCommands, stripQuotes } from "./command-parser/index.d.ts";
+export { runConcurrently } from "./concurrent.d.ts";
+export { runConcurrentFallback } from "./concurrent-fallback.d.ts";
 export { defaultTaskRunner } from "./default-task-runner.d.ts";
+export { detectScriptShell } from "./detect-shell.d.ts";
 export type { FileAccess, TrackingResult } from "./file-access-tracker.d.ts";
 export { FileAccessTracker, generatePreloadScript } from "./file-access-tracker.d.ts";
 export type { CacheMissReason, TaskFingerprint } from "./fingerprint.d.ts";
 export { FingerprintManager } from "./fingerprint.d.ts";
+export type { InputHandlerOptions, RestartOptions, TeardownOptions } from "./flow-controllers/index.d.ts";
+export { createInputHandler, formatTimingTable, logTimings, runTeardown, withRestart } from "./flow-controllers/index.d.ts";
 export type { DetectedFramework } from "./framework-inference.d.ts";
 export { detectFrameworks, getFrameworkEnvVariables, inferFrameworkEnvPatterns } from "./framework-inference.d.ts";
 export type { GraphFormat, GraphJson, GraphVisualizerOptions } from "./graph-visualizer.d.ts";
@@ -17,6 +24,7 @@ export { CompositeLifeCycle, ConsoleLifeCycle, EmptyLifeCycle } from "./life-cyc
 export type { PackageLockfileHash, ResolvedDependency } from "./lockfile-hasher.d.ts";
 export { extractPackageName, LockfileHasher, parseNpmLockfile, parsePnpmLockfile, parseYarnLockfile } from "./lockfile-hasher.d.ts";
 export { isNativeAvailable, loadNativeBindings } from "./native-binding.d.ts";
+export { enforceProjectConstraints } from "./project-constraints.d.ts";
 export type { RemoteCacheOptions } from "./remote-cache.d.ts";
 export { RemoteCache } from "./remote-cache.d.ts";
 export type { RunSummary, TaskSummary } from "./run-summary.d.ts";
@@ -27,8 +35,10 @@ export type { TaskHasher, TaskHasherOptions } from "./task-hasher.d.ts";
 export { computeTaskHash, InProcessTaskHasher } from "./task-hasher.d.ts";
 export type { TaskOrchestratorOptions } from "./task-orchestrator.d.ts";
 export { TaskOrchestrator } from "./task-orchestrator.d.ts";
-export { TaskScheduler } from "./task-scheduler.d.ts";
+export type { PartitionOptions } from "./task-scheduler.d.ts";
+export { parsePartition, TaskScheduler } from "./task-scheduler.d.ts";
+export { TerminalBuffer } from "./terminal-buffer.d.ts";
 export type { TrackedExecutionResult } from "./tracked-executor.d.ts";
 export { TrackedTaskExecutor } from "./tracked-executor.d.ts";
-export type { EnvironmentInput, ExternalDependencyInput, FileSetInput, InputDefinition, LifeCycleInterface, NamedInputs, ProjectConfiguration, ProjectGraph, ProjectGraphDependency, ProjectGraphProjectNode, RuntimeInput, TargetConfiguration, TargetDependencyConfig, Task, TaskExecutionOptions, TaskExecutor, TaskGraph, TaskHashDetails, TaskResult, TaskResults, TaskRunnerContext, TaskRunnerOptions, TasksRunner, TaskStatus, TaskTarget, WorkspaceConfiguration, } from "./types.d.ts";
+export type { AffectedScope, ConcurrentCloseEvent, ConcurrentCommandConfig, ConcurrentCommandInput, ConcurrentRunnerOptions, ConcurrentRunResult, ConstraintsConfig, ConstraintViolation, DependencyKindRules, DependencyType, EnvironmentInput, ExternalDependencyInput, FileSetInput, InputDefinition, LifeCycleInterface, NamedInputs, ProcessEvent, ProjectConfiguration, ProjectGraph, ProjectGraphDependency, ProjectGraphProjectNode, RuntimeInput, TagRelationships, TargetConfiguration, TargetDependencyConfig, Task, TaskExecutionOptions, TaskExecutor, TaskGraph, TaskHashDetails, TaskResult, TaskResults, TaskRunnerContext, TaskRunnerOptions, TasksRunner, TaskStatus, TaskTarget, TypeBoundaries, WorkspaceConfiguration, } from "./types.d.ts";
 export { collectFiles, createFailureResult, hashFile, hashStrings, readPackageDeps, resolveTaskCwd, sortObjectKeys, uniqueId } from "./utils.d.ts";

package/dist/index.js

@@ -1,20 +1,34 @@
-export { filterAffectedTasks, getAffectedProjects, getChangedFiles } from './packem_shared/filterAffectedTasks-I-18zPg6.js';
-export { Cache, formatCacheSize, parseCacheSize } from './packem_shared/Cache-IYpTYVUC.js';
-export { defaultTaskRunner } from './packem_shared/defaultTaskRunner-CrW4v5Ye.js';
+export { buildForwardDependencyMap, buildReverseDependencyMap, expandAffected, filterAffectedTasks, getAffectedProjects, getChangedFiles } from './packem_shared/buildForwardDependencyMap-0BJFMMPv.js';
+export { Cache, DEFAULT_CACHE_DIRECTORY_NAME, formatCacheSize, parseCacheSize } from './packem_shared/Cache-iAjRMV2d.js';
+export { parseCommands } from './packem_shared/parseCommands-D-IgF8Zh.js';
+export { runConcurrently } from './packem_shared/runConcurrently-qrkWyzXW.js';
+export { runConcurrentFallback } from './packem_shared/runConcurrentFallback-CGHz_f-Q.js';
+export { defaultTaskRunner } from './packem_shared/defaultTaskRunner-BdFTifsh.js';
+export { detectScriptShell } from './packem_shared/detectScriptShell-CR-xXKA4.js';
 export { FileAccessTracker, generatePreloadScript } from './packem_shared/FileAccessTracker-CrtBAt5D.js';
-export { FingerprintManager } from './packem_shared/FingerprintManager-D6Y0erg-.js';
+export { FingerprintManager } from './packem_shared/FingerprintManager-Cu-ta9ee.js';
 export { detectFrameworks, getFrameworkEnvVariables, inferFrameworkEnvPatterns } from './packem_shared/detectFrameworks-CeFzKE6J.js';
-export { projectGraphToDot, toGraphAscii, toGraphHtml, toGraphJson, toGraphvizDot } from './packem_shared/projectGraphToDot-VdTjHcVp.js';
-export { IncrementalFileHasher } from './packem_shared/IncrementalFileHasher-Ds3J6dgb.js';
+export { projectGraphToDot, toGraphAscii, toGraphHtml, toGraphJson, toGraphvizDot } from './packem_shared/projectGraphToDot-C8uYeaPo.js';
+export { IncrementalFileHasher } from './packem_shared/IncrementalFileHasher-Cm_kJY5V.js';
 export { CompositeLifeCycle, ConsoleLifeCycle, EmptyLifeCycle } from './packem_shared/CompositeLifeCycle-7AtYw1dv.js';
 export { LockfileHasher, extractPackageName, parseNpmLockfile, parsePnpmLockfile, parseYarnLockfile } from './packem_shared/extractPackageName-CbVNW-dr.js';
-export { isNativeAvailable, loadNativeBindings } from './packem_shared/isNativeAvailable-BWhnZ4ES.js';
-export { RemoteCache } from './packem_shared/RemoteCache-BDqrnDEi.js';
+export { isNativeAvailable, loadNativeBindings } from './packem_shared/isNativeAvailable-BpD28A6Z.js';
+export { enforceProjectConstraints } from './packem_shared/enforceProjectConstraints-C5Jp_C3u.js';
+export { RemoteCache } from './packem_shared/RemoteCache-BFceSe4a.js';
 export { generateRunSummary, writeRunSummary } from './packem_shared/generateRunSummary-qn-_jKwt.js';
 export { createTaskGraph, getTaskId, parseTaskId } from './packem_shared/createTaskGraph-CcsFaSrz.js';
-export { findCycle, findCycles, getDependentTasks, getLeafTasks, getTransitiveDependencies, makeAcyclic, reverseTaskGraph, walkTaskGraph } from './packem_shared/findCycle-DF4_BRdO.js';
-export { InProcessTaskHasher, computeTaskHash } from './packem_shared/computeTaskHash-BoCnnvIJ.js';
-export { TaskOrchestrator } from './packem_shared/TaskOrchestrator-BvYs3ONw.js';
-export { TaskScheduler } from './packem_shared/TaskScheduler-CJilHDta.js';
+export { findCycle, findCycles, getDependentTasks, getLeafTasks, getTransitiveDependencies, makeAcyclic, reverseTaskGraph, walkTaskGraph } from './packem_shared/findCycle-DefgNYhg.js';
+export { InProcessTaskHasher, computeTaskHash } from './packem_shared/computeTaskHash-B2SVZqgp.js';
+export { TaskOrchestrator } from './packem_shared/TaskOrchestrator-lLn-PH1m.js';
+export { TaskScheduler, parsePartition } from './packem_shared/parsePartition-C4-P5RjK.js';
+export { TerminalBuffer } from './packem_shared/TerminalBuffer-CnPyFgPB.js';
 export { TrackedTaskExecutor } from './packem_shared/TrackedTaskExecutor-BGUKFE-7.js';
 export { c as collectFiles, a as createFailureResult, h as hashFile, b as hashStrings, r as readPackageDeps, d as resolveTaskCwd, s as sortObjectKeys, u as uniqueId } from './packem_shared/utils-zO0ZRgtf.js';
+export { createInputHandler } from './packem_shared/createInputHandler-DTfePcTG.js';
+export { expandArguments } from './packem_shared/expandArguments-0AwD2BIA.js';
+export { expandShortcut } from './packem_shared/expandShortcut-BVG05ee4.js';
+export { expandWildcard } from './packem_shared/expandWildcard-B0xN_knq.js';
+export { formatTimingTable, logTimings } from './packem_shared/formatTimingTable-3qtCM552.js';
+export { runTeardown } from './packem_shared/runTeardown-BAezH79J.js';
+export { stripQuotes } from './packem_shared/stripQuotes-Cey-zwFf.js';
+export { withRestart } from './packem_shared/withRestart-BREjRJa4.js';

package/dist/native-binding.d.ts

@@ -30,6 +30,44 @@ interface NativeCycleResult {
     cycle: string[];
     has_cycle: boolean;
 }
+interface NativeConcurrentCommandConfig {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    name?: string;
+    shell?: boolean;
+    stdin?: string;
+}
+interface NativeConcurrentRunnerOptions {
+    killOthers?: string[];
+    killSignal?: string;
+    killTimeout?: number;
+    maxProcesses?: number;
+    shellPath?: string;
+    successCondition?: string;
+}
+interface NativeProcessEvent {
+    commandName?: string;
+    durationMs?: number;
+    exitCode?: number;
+    index: number;
+    killed?: boolean;
+    kind: string;
+    message?: string;
+    text?: string;
+}
+interface NativeConcurrentCloseEvent {
+    command: string;
+    durationMs: number;
+    exitCode: number;
+    index: number;
+    killed: boolean;
+    name?: string;
+}
+interface NativeConcurrentRunResult {
+    closeEvents: NativeConcurrentCloseEvent[];
+    success: boolean;
+}
 interface NativeBindings {
     collectFiles: (directory: string) => string[];
     computeTaskHash: (details: NativeTaskHashDetails) => string;
@@ -45,6 +83,8 @@ interface NativeBindings {
     hashFilesInDirectory: (directory: string, workspaceRoot: string) => NativeFileHash[];
     hashString: (input: string) => string;
     hashStrings: (inputs: string[]) => string;
+    runConcurrent: (commands: NativeConcurrentCommandConfig[], options: NativeConcurrentRunnerOptions, onEvent: (event: NativeProcessEvent) => void) => Promise<NativeConcurrentRunResult>;
+    runConcurrentBatch: (commands: NativeConcurrentCommandConfig[], options: NativeConcurrentRunnerOptions) => Promise<NativeConcurrentRunResult>;
     topologicalSort: (graph: NativeTaskGraph) => string[];
 }
 /**
@@ -52,13 +92,15 @@ interface NativeBindings {
  * The result is cached after the first attempt.
  *
  * napi v3 outputs the .node file to the package root as
- * `task-runner-native.&lt;platform>.node`. The napi-generated binding.js
+ * `task-runner-native.&lt;platform>.node`. The napi-generated index.js
  * handles platform detection automatically.
+ *
+ * Uses createRequire because the napi-generated index.js is CJS.
  */
 declare const loadNativeBindings: () => NativeBindings | undefined;
 /**
  * Returns true if the native addon is loaded and available.
  */
 declare const isNativeAvailable: () => boolean;
-export type { NativeBindings, NativeCycleResult, NativeFileHash, NativeTaskGraph, NativeTaskHashDetails };
+export type { NativeBindings, NativeConcurrentCloseEvent, NativeConcurrentCommandConfig, NativeConcurrentRunnerOptions, NativeConcurrentRunResult, NativeCycleResult, NativeFileHash, NativeProcessEvent, NativeTaskGraph, NativeTaskHashDetails, };
 export { isNativeAvailable, loadNativeBindings };

package/dist/packem_shared/{Cache-IYpTYVUC.js → Cache-iAjRMV2d.js}

@@ -27,11 +27,12 @@ const {
   cp,
   readdir
 } = __cjs_getBuiltinModule("node:fs/promises");
-import { join, resolve, dirname } from '@visulima/path';
 import { formatBytes, parseBytes } from '@visulima/humanizer';
+import { join, resolve, dirname } from '@visulima/path';
 import { u as uniqueId } from './utils-zO0ZRgtf.js';
 
 const DEFAULT_MAX_CACHE_AGE = 7 * 24 * 60 * 60 * 1e3;
+const DEFAULT_CACHE_DIRECTORY_NAME = ".task-runner-cache";
 const removeEntry = async (entryPath) => {
   try {
     await rm(entryPath, { force: true, recursive: true });
@@ -58,7 +59,7 @@ const getDirectorySize = async (directoryPath) => {
 const parseCacheSize = (sizeString) => {
   const result = parseBytes(sizeString.trim());
   if (Number.isNaN(result)) {
-    throw new Error(`Invalid cache size format: "${sizeString}". Expected format like "500MB" or "1GB".`);
+    throw new TypeError(`Invalid cache size format: "${sizeString}". Expected format like "500MB" or "1GB".`);
   }
   return result;
 };
@@ -72,7 +73,7 @@ class Cache {
   #indexWriteQueue = Promise.resolve();
   constructor(options) {
     this.#workspaceRoot = options.workspaceRoot;
-    this.#cacheDirectory = options.cacheDirectory ?? join(options.workspaceRoot, ".task-runner-cache");
+    this.#cacheDirectory = options.cacheDirectory ?? join(options.workspaceRoot, DEFAULT_CACHE_DIRECTORY_NAME);
     this.#maxCacheAge = options.maxCacheAge ?? DEFAULT_MAX_CACHE_AGE;
     this.#maxCacheSize = options.maxCacheSize ? parseCacheSize(options.maxCacheSize) : void 0;
   }
@@ -222,7 +223,6 @@ class Cache {
    * Removes old cache entries that exceed the maximum age,
    * and enforces the maximum cache size by evicting oldest entries.
    */
-  // eslint-disable-next-line sonarjs/cognitive-complexity
   async removeOldEntries() {
     try {
       const entries = await readdir(this.#cacheDirectory);
@@ -295,4 +295,4 @@ class Cache {
   }
 }
 
-export { Cache, formatCacheSize, parseCacheSize };
+export { Cache, DEFAULT_CACHE_DIRECTORY_NAME, formatCacheSize, parseCacheSize };

package/dist/packem_shared/{FingerprintManager-D6Y0erg-.js → FingerprintManager-Cu-ta9ee.js}

@@ -30,7 +30,6 @@ class FingerprintManager {
   constructor(workspaceRoot) {
     this.#workspaceRoot = resolve(workspaceRoot);
   }
-  // eslint-disable-next-line sonarjs/cognitive-complexity
   async createFingerprint(accesses, command, args, envVariables, envPatterns = [], untrackedEnvVariables = []) {
     const fileHashes = {};
     const missingPaths = /* @__PURE__ */ new Set();

package/dist/packem_shared/{IncrementalFileHasher-Ds3J6dgb.js → IncrementalFileHasher-Cm_kJY5V.js}

@@ -118,7 +118,7 @@ class IncrementalFileHasher {
         return void 0;
       }
       const cached = this.#snapshot.get(filePath);
-      if (cached && cached.mtimeMs === fileStat.mtimeMs && cached.size === fileStat.size) {
+      if (cached?.mtimeMs === fileStat.mtimeMs && cached.size === fileStat.size) {
         return cached.hash;
       }
       const content = await readFile(filePath);

package/dist/packem_shared/{TaskOrchestrator-BvYs3ONw.js → TaskOrchestrator-lLn-PH1m.js}

@@ -1,8 +1,8 @@
 import { d as resolveTaskCwd, a as createFailureResult, e as createXxh3Hasher } from './utils-zO0ZRgtf.js';
 import { join } from '@visulima/path';
-import { FingerprintManager } from './FingerprintManager-D6Y0erg-.js';
+import { FingerprintManager } from './FingerprintManager-Cu-ta9ee.js';
 import { generateRunSummary, writeRunSummary } from './generateRunSummary-qn-_jKwt.js';
-import { computeTaskHash } from './computeTaskHash-BoCnnvIJ.js';
+import { computeTaskHash } from './computeTaskHash-B2SVZqgp.js';
 import { TrackedTaskExecutor } from './TrackedTaskExecutor-BGUKFE-7.js';
 
 const hashFingerprint = (fingerprint) => {
@@ -107,7 +107,6 @@ class TaskOrchestrator {
     }
     return this.#results;
   }
-  // eslint-disable-next-line sonarjs/cognitive-complexity
   async #executionLoop() {
     while (!this.#scheduler.isComplete() && !this.#aborted) {
       const batch = this.#scheduler.getNextBatch();
@@ -153,7 +152,6 @@ class TaskOrchestrator {
       await Promise.all(this.#inFlightTasks.values());
     }
   }
-  // eslint-disable-next-line sonarjs/cognitive-complexity
   async #processTask(task) {
     const startTime = Date.now();
     const hashDetails = await this.#taskHasher.hashTask(task);
@@ -186,7 +184,6 @@ class TaskOrchestrator {
     }
     return result;
   }
-  // eslint-disable-next-line sonarjs/cognitive-complexity
   async #processTaskWithFingerprint(task) {
     const startTime = Date.now();
     if (!this.#skipCache && task.cache !== false) {

package/dist/packem_shared/TerminalBuffer-CnPyFgPB.js

@@ -0,0 +1,266 @@
+class TerminalBuffer {
+  #lines = [""];
+  #row = 0;
+  #col = 0;
+  #maxBytes;
+  constructor(maxBytes = 256 * 1024) {
+    this.#maxBytes = maxBytes;
+  }
+  /**
+   * Process raw PTY output data.
+   */
+  write(data) {
+    let i = 0;
+    while (i < data.length) {
+      const ch = data[i];
+      if (ch === "\x1B") {
+        if (i + 1 >= data.length) {
+          i++;
+          continue;
+        }
+        if (data[i + 1] === "[") {
+          const consumed = this.#processCsi(data, i + 2);
+          i = consumed;
+          continue;
+        }
+        i += data[i + 1] === "(" || data[i + 1] === ")" ? 3 : 2;
+        continue;
+      }
+      if (ch === "\r") {
+        this.#col = 0;
+        i++;
+        continue;
+      }
+      if (ch === "\n") {
+        this.#row++;
+        this.#col = 0;
+        this.#ensureRow(this.#row);
+        i++;
+        continue;
+      }
+      this.#ensureRow(this.#row);
+      this.#putChar(ch);
+      this.#col++;
+      i++;
+    }
+    this.#trimToMaxBytes();
+  }
+  /** Get the current buffer content as a string. */
+  toString() {
+    return this.#lines.join("\n");
+  }
+  /**
+   * Process a CSI sequence starting after "ESC [".
+   * Returns the index to continue parsing from.
+   */
+  #processCsi(data, start) {
+    let j = start;
+    let params = "";
+    while (j < data.length && (data[j] >= "0" && data[j] <= "9" || data[j] === ";")) {
+      params += data[j];
+      j++;
+    }
+    if (j >= data.length) {
+      return j;
+    }
+    const cmd = data[j];
+    const n = Number.parseInt(params, 10) || 1;
+    switch (cmd) {
+      case "A": {
+        this.#row = Math.max(0, this.#row - n);
+        break;
+      }
+      case "B": {
+        this.#row = Math.min(this.#lines.length - 1, this.#row + n);
+        break;
+      }
+      case "C": {
+        this.#col += n;
+        break;
+      }
+      case "D": {
+        this.#col = Math.max(0, this.#col - n);
+        break;
+      }
+      case "f":
+      case "H": {
+        const parts = params.split(";");
+        this.#row = Math.max(0, (Number.parseInt(parts[0] ?? "1", 10) || 1) - 1);
+        this.#col = Math.max(0, (Number.parseInt(parts[1] ?? "1", 10) || 1) - 1);
+        this.#ensureRow(this.#row);
+        break;
+      }
+      case "G": {
+        this.#col = Math.max(0, n - 1);
+        break;
+      }
+      case "J": {
+        this.#eraseDisplay(Number.parseInt(params, 10) || 0);
+        break;
+      }
+      case "K": {
+        this.#eraseLine(Number.parseInt(params, 10) || 0);
+        break;
+      }
+      case "m": {
+        const seq = `\x1B[${params}m`;
+        this.#ensureRow(this.#row);
+        this.#appendAtCursor(seq);
+        break;
+      }
+    }
+    return j + 1;
+  }
+  /** Write a visible character at the cursor position (overwrites). */
+  #putChar(ch) {
+    const line = this.#lines[this.#row] ?? "";
+    const visCol = this.#col;
+    let strIndex = 0;
+    let vis = 0;
+    while (strIndex < line.length && vis < visCol) {
+      if (line[strIndex] === "\x1B" && line[strIndex + 1] === "[") {
+        strIndex += 2;
+        while (strIndex < line.length && !(line[strIndex] >= "A" && line[strIndex] <= "Z" || line[strIndex] >= "a" && line[strIndex] <= "z")) {
+          strIndex++;
+        }
+        if (strIndex < line.length) {
+          strIndex++;
+        }
+      } else {
+        strIndex++;
+        vis++;
+      }
+    }
+    if (vis < visCol) {
+      this.#lines[this.#row] = line + " ".repeat(visCol - vis) + ch;
+    } else {
+      let endIndex = strIndex;
+      if (endIndex < line.length && line[endIndex] !== "\x1B") {
+        endIndex++;
+      }
+      this.#lines[this.#row] = line.slice(0, strIndex) + ch + line.slice(endIndex);
+    }
+  }
+  /** Append a zero-width sequence (SGR) at the current cursor position. */
+  #appendAtCursor(seq) {
+    const line = this.#lines[this.#row] ?? "";
+    let strIndex = 0;
+    let vis = 0;
+    while (strIndex < line.length && vis < this.#col) {
+      if (line[strIndex] === "\x1B" && line[strIndex + 1] === "[") {
+        strIndex += 2;
+        while (strIndex < line.length && !(line[strIndex] >= "A" && line[strIndex] <= "Z" || line[strIndex] >= "a" && line[strIndex] <= "z")) {
+          strIndex++;
+        }
+        if (strIndex < line.length) {
+          strIndex++;
+        }
+      } else {
+        strIndex++;
+        vis++;
+      }
+    }
+    this.#lines[this.#row] = line.slice(0, strIndex) + seq + line.slice(strIndex);
+  }
+  #eraseDisplay(mode) {
+    switch (mode) {
+      case 0: {
+        this.#ensureRow(this.#row);
+        this.#truncateLineAtCol(this.#row, this.#col);
+        this.#lines.length = this.#row + 1;
+        break;
+      }
+      case 1: {
+        for (let r = 0; r < this.#row; r++) {
+          this.#lines[r] = "";
+        }
+        this.#ensureRow(this.#row);
+        this.#fillLineToCol(this.#row, this.#col);
+        break;
+      }
+      case 2: {
+        this.#lines = [""];
+        this.#row = 0;
+        this.#col = 0;
+        break;
+      }
+    }
+  }
+  #eraseLine(mode) {
+    this.#ensureRow(this.#row);
+    switch (mode) {
+      case 0: {
+        this.#truncateLineAtCol(this.#row, this.#col);
+        break;
+      }
+      case 1: {
+        this.#fillLineToCol(this.#row, this.#col);
+        break;
+      }
+      case 2: {
+        this.#lines[this.#row] = "";
+        break;
+      }
+    }
+  }
+  /** Truncate a line at the given visual column. */
+  #truncateLineAtCol(row, col) {
+    const line = this.#lines[row] ?? "";
+    let strIndex = 0;
+    let vis = 0;
+    while (strIndex < line.length && vis < col) {
+      if (line[strIndex] === "\x1B" && line[strIndex + 1] === "[") {
+        strIndex += 2;
+        while (strIndex < line.length && !(line[strIndex] >= "A" && line[strIndex] <= "Z" || line[strIndex] >= "a" && line[strIndex] <= "z")) {
+          strIndex++;
+        }
+        if (strIndex < line.length) {
+          strIndex++;
+        }
+      } else {
+        strIndex++;
+        vis++;
+      }
+    }
+    this.#lines[row] = line.slice(0, strIndex);
+  }
+  /** Fill a line with spaces from start to the given visual column. */
+  #fillLineToCol(row, col) {
+    const line = this.#lines[row] ?? "";
+    let strIndex = 0;
+    let vis = 0;
+    while (strIndex < line.length && vis < col) {
+      if (line[strIndex] === "\x1B" && line[strIndex + 1] === "[") {
+        strIndex += 2;
+        while (strIndex < line.length && !(line[strIndex] >= "A" && line[strIndex] <= "Z" || line[strIndex] >= "a" && line[strIndex] <= "z")) {
+          strIndex++;
+        }
+        if (strIndex < line.length) {
+          strIndex++;
+        }
+      } else {
+        strIndex++;
+        vis++;
+      }
+    }
+    this.#lines[row] = " ".repeat(col) + line.slice(strIndex);
+  }
+  #ensureRow(row) {
+    while (this.#lines.length <= row) {
+      this.#lines.push("");
+    }
+  }
+  #trimToMaxBytes() {
+    let totalSize = 0;
+    for (const line of this.#lines) {
+      totalSize += line.length + 1;
+    }
+    while (totalSize > this.#maxBytes && this.#lines.length > 1) {
+      const removed = this.#lines.shift();
+      totalSize -= removed.length + 1;
+      this.#row = Math.max(0, this.#row - 1);
+    }
+  }
+}
+
+export { TerminalBuffer };