progressimo 1.0.0

package/README.md

@@ -0,0 +1,298 @@
+# progressimo
+
+![npm version](https://img.shields.io/npm/v/progressimo)
+![license](https://img.shields.io/npm/l/progressimo)
+![bundle size](https://img.shields.io/bundlephobia/min/progressimo)
+
+A lightweight, animated, themeable CLI progress bar for Node.js.  
+Zero config to start — full customization when needed.
+
+- 🎨 **6 built-in themes** — default, minimal, retro, blocks, dots, arrows
+- ♿ **Colorblind-friendly palettes** — deuteranopia, protanopia, tritanopia
+- 🎭 **Custom JSON themes** — load your own theme from a file
+- ✨ **Smooth animation** — animated fill with configurable speed
+- 📦 **Tiny footprint** — only 2 dependencies (`chalk`, `cli-cursor`)
+
+---
+
+## Quick Start
+
+```bash
+npm install progressimo
+```
+
+```javascript
+import ProgressBar from 'progressimo';
+
+// Zero config — works out of the box
+const bar = new ProgressBar({ total: 100 });
+bar.update(50);    // 50% done
+bar.complete();    // jump to 100%, clean up
+```
+
+That's it — two lines to get a working progress bar.
+
+---
+
+## Theme Previews
+
+```
+ default    [████████████████████░░░░░░░░░░] 60%
+
+ minimal    [##################------------] 60%
+
+ retro      [=================>------------] 60%
+
+ blocks     [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░] 60%
+
+ dots       [••••••••••••••••••············] 60%
+
+ arrows     [▸▸▸▸▸▸▸▸▸▸▸▸▸▸▸▸▸▸▹▹▹▹▹▹▹▹▹▹▹▹] 60%
+```
+
+---
+
+## Usage Examples
+
+### With a Built-in Theme
+
+```javascript
+import ProgressBar from 'progressimo';
+
+const bar = new ProgressBar({ total: 100, theme: 'retro' });
+bar.update(60);
+// retro [===============>--------------] 60%
+```
+
+### With a Colorblind Palette
+
+```javascript
+const bar = new ProgressBar({
+  total: 100,
+  palette: 'deuteranopia',  // blue + orange — safe for red/green CVD
+});
+bar.update(75);
+```
+
+### Fully Custom Config
+
+```javascript
+const bar = new ProgressBar({
+  total: 100,
+  width: 40,
+  label: 'Uploading',
+  fill: '▰',
+  empty: '▱',
+  color: 'magentaBright',
+});
+bar.update(30);
+// Uploading [▰▰▰▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱] 30%
+```
+
+### Load a Custom JSON Theme
+
+Create a JSON file like `themes/my-theme.json`:
+
+```json
+{
+  "fill": "★",
+  "empty": "☆",
+  "head": "",
+  "leftBracket": "[",
+  "rightBracket": "]",
+  "color": "yellow"
+}
+```
+
+Then use it:
+
+```javascript
+const bar = new ProgressBar({
+  total: 100,
+  theme: './themes/my-theme.json',
+});
+bar.update(50);
+// [★★★★★★★★★★★★★★★☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆] 50%
+```
+
+### Smooth Animation
+
+```javascript
+const bar = new ProgressBar({ total: 100, label: 'Installing' });
+
+// The bar will smoothly slide from 0 → 80 instead of jumping
+bar.update(80, { animate: true });
+```
+
+### Using with Async Tasks
+
+```javascript
+import ProgressBar from 'progressimo';
+
+async function downloadFiles(files) {
+  const bar = new ProgressBar({
+    total: files.length,
+    label: 'Downloading',
+    theme: 'dots',
+  });
+
+  for (let i = 0; i < files.length; i++) {
+    await downloadFile(files[i]);
+    bar.update(i + 1);
+  }
+  bar.complete();
+}
+```
+
+### Increment Shortcut
+
+```javascript
+const bar = new ProgressBar({ total: 200 });
+
+bar.increment();     // 1/200
+bar.increment(10);   // 11/200
+bar.increment();     // 12/200
+bar.complete();      // 200/200, done
+```
+
+---
+
+## Config Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `total` | `number` | `100` | Value that represents 100% |
+| `theme` | `string` | `'default'` | Built-in theme name or path to a `.json` theme file |
+| `palette` | `string` | — | Colorblind palette: `'deuteranopia'`, `'protanopia'`, `'tritanopia'` |
+| `width` | `number` | `30` | Character width of the bar (excluding brackets/label) |
+| `label` | `string` | `''` | Text label before the bar |
+| `fill` | `string` | `'█'` | Fill character (overrides theme) |
+| `empty` | `string` | `'░'` | Empty character (overrides theme) |
+| `head` | `string` | `''` | Leading edge character (overrides theme) |
+| `color` | `string` | `'cyan'` | Chalk color name for the filled portion |
+| `animationInterval` | `number` | `50` | Milliseconds between frames during smooth animation |
+| `stream` | `WriteStream` | `process.stderr` | Output stream |
+
+---
+
+## Built-in Themes
+
+| Theme | Fill | Empty | Head | Color |
+|---|---|---|---|---|
+| `default` | `█` | `░` | — | cyan |
+| `minimal` | `#` | `-` | — | white |
+| `retro` | `=` | `-` | `>` | green |
+| `blocks` | `▓` | `░` | — | magenta |
+| `dots` | `•` | `·` | — | yellow |
+| `arrows` | `▸` | `▹` | — | blue |
+
+---
+
+## Colorblind Palettes
+
+These palettes remap colors to combinations that are distinguishable for people with color vision deficiencies.
+
+| Palette | Fill Color | Empty Color | Target |
+|---|---|---|---|
+| `deuteranopia` | blue | bright yellow | Reduced green sensitivity (most common) |
+| `protanopia` | bright blue | yellow | Reduced red sensitivity |
+| `tritanopia` | red | bright cyan | Reduced blue sensitivity |
+
+---
+
+## API Reference
+
+### `new ProgressBar(options?)`
+
+Create a new progress bar instance. All options are optional — zero config works out of the box.
+
+### `.update(value, options?)`
+
+Set progress to an absolute value (clamped to 0–total).  
+Pass `{ animate: true }` for smooth animation.
+
+### `.increment(delta?)`
+
+Add `delta` (default `1`) to the current progress.
+
+### `.complete()`
+
+Jump to 100%, render the final frame, restore the cursor, and print a newline.
+
+---
+
+## Advanced: Accessing Themes & Palettes
+
+```javascript
+import { themes, palettes } from 'progressimo';
+
+console.log(Object.keys(themes));
+// ['default', 'minimal', 'retro', 'blocks', 'dots', 'arrows']
+
+console.log(palettes.deuteranopia);
+// { fill: 'blue', empty: 'yellowBright', label: 'white', percentage: 'blueBright' }
+```
+
+---
+
+## Demo
+
+Run the interactive demo that cycles through all themes and palettes:
+
+```bash
+npx progressimo-demo
+# or
+node node_modules/progressimo/bin/demo.js
+```
+
+---
+
+## How It Works
+
+The "animation" trick is simple: instead of printing new lines, we overwrite the same terminal line on every update.
+
+1. `readline.cursorTo(stream, 0)` — moves the cursor back to column 0
+2. `readline.clearLine(stream, 0)` — erases the current line
+3. `stream.write(barString)` — writes the new bar
+
+Because we never print a `\n`, the cursor stays on the same line. `cli-cursor` hides the blinking cursor during animation for a clean look.
+
+Progress output goes to `stderr` by default so `stdout` stays clean for piping.
+
+---
+
+## Publishing to npm
+
+```bash
+# Login to your npm account
+npm login
+
+# Publish (first time)
+npm publish
+
+# After making changes, bump the version
+npm version patch   # 1.0.0 → 1.0.1
+npm publish
+```
+
+**Key concepts:**
+- `"main"` in package.json tells Node.js which file to load on `import`
+- `"bin"` registers CLI commands (like `progressimo-demo`)
+- `"type": "module"` enables ES Module syntax (`import`/`export`)
+- `"files"` controls which files are included in the published tarball
+
+---
+
+## Contributing
+
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feature/my-theme`)
+3. Commit your changes (`git commit -m 'Add new theme'`)
+4. Push to the branch (`git push origin feature/my-theme`)
+5. Open a Pull Request
+
+---
+
+## License
+
+MIT

package/bin/demo.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+// ─── progressimo Demo ─────────────────────────────────────────────────────────
+// Run: node bin/demo.js   (or: npm run demo)
+//
+// Cycles through every built-in theme and colorblind palette so you can see
+// what each one looks like in your terminal.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import chalk from 'chalk';
+import ProgressBar from '../src/ProgressBar.js';
+import themes from '../src/themes.js';
+import palettes from '../src/palettes.js';
+
+/** Promise-based sleep helper. */
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Animate a single bar from 0 → 100 with a label.
+ * @param {object} opts — ProgressBar options.
+ * @param {string} heading — section heading printed above the bar.
+ */
+async function showcase(opts, heading) {
+  if (heading) {
+    process.stderr.write(`\n${chalk.bold.underline(heading)}\n`);
+  }
+
+  const bar = new ProgressBar({ total: 100, width: 30, ...opts });
+
+  // Simulate work: tick from 0 to 100
+  for (let i = 0; i <= 100; i += 2) {
+    bar.update(i);
+    await sleep(25);          // 25 ms × 50 ticks = ~1.25 s per bar
+  }
+  bar.complete();
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log(chalk.bold.cyan('\n✨  progressimo — Theme & Palette Demo\n'));
+  console.log(chalk.gray('Each bar animates from 0 → 100 %.\n'));
+
+  // 1. Built-in themes
+  console.log(chalk.bold('━━━ Built-in Themes ━━━'));
+  for (const name of Object.keys(themes)) {
+    await showcase(
+      { theme: name, label: name.padEnd(10) },
+      null,
+    );
+  }
+
+  // 2. Colorblind palettes (using default theme characters)
+  console.log(chalk.bold('\n━━━ Colorblind Palettes ━━━'));
+  for (const name of Object.keys(palettes)) {
+    await showcase(
+      { palette: name, label: name.padEnd(14) },
+      null,
+    );
+  }
+
+  // 3. Custom JSON theme
+  console.log(chalk.bold('\n━━━ Custom JSON Theme ━━━'));
+  await showcase(
+    { theme: './themes/custom-example.json', label: 'custom-json'.padEnd(14) },
+    null,
+  );
+
+  // 4. Fully custom config (no theme, all overrides)
+  console.log(chalk.bold('\n━━━ Fully Custom Config ━━━'));
+  await showcase(
+    {
+      fill: '▰',
+      empty: '▱',
+      color: 'magentaBright',
+      label: 'uploading'.padEnd(14),
+      width: 35,
+    },
+    null,
+  );
+
+  console.log(chalk.bold.cyan('\n✅  Demo complete!\n'));
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/index.js

@@ -0,0 +1,10 @@
+// ─── progressimo — Library Entry Point ────────────────────────────────────────
+// Usage:
+//   import ProgressBar from 'progressimo';
+//   import { themes, palettes } from 'progressimo';
+// ─────────────────────────────────────────────────────────────────────────────
+
+export { default as default } from './src/ProgressBar.js';
+export { default as ProgressBar } from './src/ProgressBar.js';
+export { default as themes } from './src/themes.js';
+export { default as palettes } from './src/palettes.js';

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "progressimo",
+  "version": "1.0.0",
+  "description": "A lightweight, animated, themeable CLI progress bar for Node.js — zero config to start, full customization when needed.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "bin": {
+    "progressimo-demo": "./bin/demo.js"
+  },
+  "files": [
+    "src/",
+    "themes/",
+    "bin/",
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "demo": "node bin/demo.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "progress",
+    "progress-bar",
+    "cli",
+    "terminal",
+    "animation",
+    "colorblind",
+    "accessibility",
+    "themes"
+  ],
+  "author": "realsahilsaini",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/realsahilsaini/clibar.git"
+  },
+  "homepage": "https://github.com/realsahilsaini/clibar#readme",
+  "bugs": {
+    "url": "https://github.com/realsahilsaini/clibar/issues"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "cli-cursor": "^5.0.0"
+  }
+}

package/src/ProgressBar.js

@@ -0,0 +1,229 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import Renderer from './renderer.js';
+import themes from './themes.js';
+import palettes from './palettes.js';
+
+// ─── ProgressBar ─────────────────────────────────────────────────────────────
+// The main class consumers interact with.
+//
+// Quick start (zero config):
+//   const bar = new ProgressBar({ total: 100 });
+//   bar.update(50);          // jump to 50 %
+//   bar.increment();         // 51 %
+//   bar.complete();          // 100 %, done
+//
+// With a theme:
+//   new ProgressBar({ total: 100, theme: 'retro' });
+//
+// With a colorblind palette:
+//   new ProgressBar({ total: 100, palette: 'deuteranopia' });
+//
+// Custom JSON theme:
+//   new ProgressBar({ total: 100, theme: './themes/my-theme.json' });
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Allowed keys in a theme object — used for validation when loading JSON.
+const ALLOWED_THEME_KEYS = new Set([
+  'fill', 'empty', 'head', 'leftBracket', 'rightBracket', 'color',
+]);
+
+/**
+ * Load and validate a theme from a JSON file.
+ * @param {string} filePath — absolute or relative path to a .json theme file.
+ * @returns {object} — validated theme object.
+ */
+function loadThemeFromFile(filePath) {
+  const resolved = path.resolve(filePath);
+  const raw = fs.readFileSync(resolved, 'utf-8');
+  const parsed = JSON.parse(raw);
+
+  // Only allow expected string keys — prevents prototype pollution / injection.
+  const safe = {};
+  for (const key of ALLOWED_THEME_KEYS) {
+    if (key in parsed) {
+      if (typeof parsed[key] !== 'string') {
+        throw new TypeError(`Theme key "${key}" must be a string, got ${typeof parsed[key]}`);
+      }
+      safe[key] = parsed[key];
+    }
+  }
+  return safe;
+}
+
+export default class ProgressBar {
+  /**
+   * Create a new progress bar.
+   *
+   * @param {object}  [opts]                    — configuration (all optional).
+   * @param {number}  [opts.total=100]          — value that represents 100 %.
+   * @param {string}  [opts.theme='default']    — built-in theme name OR path to a .json theme file.
+   * @param {string}  [opts.palette]            — colorblind palette name ('deuteranopia' | 'protanopia' | 'tritanopia').
+   * @param {number}  [opts.width=30]           — character width of the bar (excluding brackets/label).
+   * @param {string}  [opts.label='']           — text label shown before the bar.
+   * @param {string}  [opts.fill]               — override fill character.
+   * @param {string}  [opts.empty]              — override empty character.
+   * @param {string}  [opts.head]               — override head character.
+   * @param {string}  [opts.color]              — override chalk color for the filled portion.
+   * @param {number}  [opts.animationInterval=50] — ms between frames when animating.
+   * @param {NodeJS.WriteStream} [opts.stream]  — output stream (defaults to stderr).
+   */
+  constructor(opts = {}) {
+    // ── Resolve theme ──────────────────────────────────────────────────────
+    let baseTheme;
+    const themeName = opts.theme ?? 'default';
+
+    if (typeof themeName === 'string' && themeName.endsWith('.json')) {
+      // External JSON theme file
+      baseTheme = loadThemeFromFile(themeName);
+    } else if (themes[themeName]) {
+      baseTheme = { ...themes[themeName] };
+    } else {
+      baseTheme = { ...themes.default };
+    }
+
+    // ── Merge: base theme → user overrides ─────────────────────────────────
+    this.fill          = opts.fill          ?? baseTheme.fill          ?? '█';
+    this.empty         = opts.empty         ?? baseTheme.empty         ?? '░';
+    this.head          = opts.head          ?? baseTheme.head          ?? '';
+    this.leftBracket   = opts.leftBracket   ?? baseTheme.leftBracket   ?? '[';
+    this.rightBracket  = opts.rightBracket  ?? baseTheme.rightBracket  ?? ']';
+    this.color         = opts.color         ?? baseTheme.color         ?? 'cyan';
+
+    // ── Resolve palette (overrides colors when set) ────────────────────────
+    this.palette = null;
+    if (opts.palette && palettes[opts.palette]) {
+      this.palette = palettes[opts.palette];
+      // Palette's fill color wins over theme color if not explicitly set by user.
+      if (!opts.color) {
+        this.color = this.palette.fill;
+      }
+    }
+
+    // ── Other settings ─────────────────────────────────────────────────────
+    this.total             = opts.total             ?? 100;
+    this.width             = opts.width             ?? 30;
+    this.label             = opts.label             ?? '';
+    this.animationInterval = opts.animationInterval ?? 50;
+
+    // ── Internal state ─────────────────────────────────────────────────────
+    this.current      = 0;     // actual logical value
+    this.displayValue = 0;     // smoothly-animated visual value
+    this._timer       = null;  // setInterval id for animation
+
+    // ── Renderer ───────────────────────────────────────────────────────────
+    this.renderer = new Renderer(opts.stream);
+  }
+
+  // ─── Public API ──────────────────────────────────────────────────────────
+
+  /**
+   * Set the progress to an absolute value and redraw.
+   * @param {number} value — progress value (clamped to 0…total).
+   * @param {object} [opts]
+   * @param {boolean} [opts.animate=false] — smoothly animate to the new value.
+   */
+  update(value, { animate = false } = {}) {
+    this.current = Math.max(0, Math.min(value, this.total));
+
+    if (animate) {
+      this._animateTo(this.current);
+    } else {
+      this.displayValue = this.current;
+      this._draw();
+    }
+  }
+
+  /**
+   * Increment progress by `delta` and redraw.
+   * @param {number} [delta=1] — amount to add.
+   */
+  increment(delta = 1) {
+    this.update(this.current + delta);
+  }
+
+  /**
+   * Jump to 100 %, render the final frame, and clean up.
+   */
+  complete() {
+    this._clearTimer();
+    this.current = this.total;
+    this.displayValue = this.total;
+    this._draw();
+    this.renderer.finish();
+  }
+
+  // ─── Internal ────────────────────────────────────────────────────────────
+
+  /**
+   * Smoothly animate `displayValue` toward `target`.
+   *
+   * HOW IT WORKS:
+   *   setInterval fires a callback on a repeating timer. Each tick we nudge
+   *   displayValue closer to the target by a small step. On each tick _draw()
+   *   repaints the bar — so the user sees the fill sliding smoothly instead
+   *   of jumping. When displayValue reaches the target, we clear the interval.
+   *
+   * @param {number} target — the value to animate toward.
+   * @private
+   */
+  _animateTo(target) {
+    this._clearTimer();
+
+    const step = Math.max(1, Math.round(this.total / this.width));
+
+    this._timer = setInterval(() => {
+      if (this.displayValue < target) {
+        this.displayValue = Math.min(this.displayValue + step, target);
+      } else if (this.displayValue > target) {
+        this.displayValue = Math.max(this.displayValue - step, target);
+      }
+
+      this._draw();
+
+      if (this.displayValue === target) {
+        this._clearTimer();
+      }
+    }, this.animationInterval);
+  }
+
+  /**
+   * Compute the bar string and hand it to the renderer.
+   * @private
+   */
+  _draw() {
+    const ratio  = Math.min(this.displayValue / this.total, 1);
+    const filled = Math.round(ratio * this.width);
+    const empty  = this.width - filled;
+    const pct    = Math.round(ratio * 100);
+
+    // Build character segments
+    let fillStr  = this.fill.repeat(Math.max(0, filled - (this.head ? 1 : 0)));
+    let headStr  = (filled > 0 && this.head) ? this.head : '';
+    let emptyStr = this.empty.repeat(empty);
+
+    // Apply colors via chalk
+    const colorFn    = chalk[this.color] || chalk.cyan;
+    const emptyColor = this.palette ? (chalk[this.palette.empty] || chalk.gray) : chalk.gray;
+    const labelColor = this.palette ? (chalk[this.palette.label] || chalk.white) : chalk.white;
+    const pctColor   = this.palette ? (chalk[this.palette.percentage] || chalk.white) : chalk.white;
+
+    const coloredFill  = colorFn(fillStr + headStr);
+    const coloredEmpty = emptyColor(emptyStr);
+    const coloredLabel = this.label ? labelColor(this.label) + ' ' : '';
+    const coloredPct   = pctColor(`${pct}%`);
+
+    const bar = `${coloredLabel}${this.leftBracket}${coloredFill}${coloredEmpty}${this.rightBracket} ${coloredPct}`;
+
+    this.renderer.render(bar);
+  }
+
+  /** Clear the animation interval if running. @private */
+  _clearTimer() {
+    if (this._timer !== null) {
+      clearInterval(this._timer);
+      this._timer = null;
+    }
+  }
+}

package/src/palettes.js

@@ -0,0 +1,37 @@
+// ─── Colorblind-Friendly Palette Presets ─────────────────────────────────────
+// Each palette maps semantic roles to chalk color names that are safe
+// for a specific type of color vision deficiency.
+//
+//   fill       — color applied to the filled/completed portion
+//   empty      — color applied to the remaining/empty portion
+//   label      — color applied to the label text
+//   percentage — color applied to the percentage number
+// ─────────────────────────────────────────────────────────────────────────────
+
+const palettes = {
+  /** Deuteranopia — reduced green sensitivity (most common CVD) */
+  deuteranopia: {
+    fill: 'blue',
+    empty: 'yellowBright',
+    label: 'white',
+    percentage: 'blueBright',
+  },
+
+  /** Protanopia — reduced red sensitivity */
+  protanopia: {
+    fill: 'blueBright',
+    empty: 'yellow',
+    label: 'white',
+    percentage: 'blue',
+  },
+
+  /** Tritanopia — reduced blue sensitivity (rarest form) */
+  tritanopia: {
+    fill: 'red',
+    empty: 'cyanBright',
+    label: 'white',
+    percentage: 'redBright',
+  },
+};
+
+export default palettes;

package/src/renderer.js

@@ -0,0 +1,60 @@
+import readline from 'readline';
+import cliCursor from 'cli-cursor';
+
+// ─── Renderer ────────────────────────────────────────────────────────────────
+// Handles all direct terminal I/O — clearing, redrawing and cursor visibility.
+//
+// HOW IT WORKS (key concept):
+//   Terminals print text left-to-right, line-by-line. Normally each write
+//   appends new content. To "animate" a progress bar we need to *overwrite*
+//   the same line repeatedly. We do that in two steps every frame:
+//
+//     1. readline.cursorTo(stream, 0)  — moves the cursor back to column 0
+//     2. readline.clearLine(stream, 0) — erases everything on the current line
+//
+//   Then we write the new bar string. Because we never print a newline (\n)
+//   the cursor stays on the same line, ready for the next overwrite.
+//
+//   cli-cursor hides the blinking cursor during animation so it doesn't
+//   flicker over the bar characters — purely cosmetic but looks much cleaner.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export default class Renderer {
+  /**
+   * @param {NodeJS.WriteStream} [stream=process.stderr] — output stream.
+   *   stderr is the convention for progress indicators so stdout stays
+   *   clean for actual program output (important when piping).
+   */
+  constructor(stream = process.stderr) {
+    this.stream = stream;
+    this.started = false;
+  }
+
+  /** Hide the cursor and mark the renderer as active. */
+  start() {
+    if (this.started) return;
+    cliCursor.hide(this.stream);
+    this.started = true;
+  }
+
+  /**
+   * Overwrite the current terminal line with `text`.
+   * @param {string} text — the fully-assembled bar string to display.
+   */
+  render(text) {
+    if (!this.started) this.start();
+
+    // Move cursor to column 0, clear the line, then write the new text.
+    readline.cursorTo(this.stream, 0);
+    readline.clearLine(this.stream, 0);
+    this.stream.write(text);
+  }
+
+  /** Print a final newline, restore the cursor, and mark done. */
+  finish() {
+    if (!this.started) return;
+    this.stream.write('\n');
+    cliCursor.show(this.stream);
+    this.started = false;
+  }
+}

package/src/themes.js

@@ -0,0 +1,68 @@
+// ─── Built-in Theme Presets ───────────────────────────────────────────────────
+// Each theme defines the characters and color used to render the progress bar.
+//
+//   fill          — character for the completed portion
+//   empty         — character for the remaining portion
+//   head          — character at the leading edge of the fill (optional)
+//   leftBracket   — left wrapper around the bar
+//   rightBracket  — right wrapper around the bar
+//   color         — chalk color name applied to the filled portion
+// ─────────────────────────────────────────────────────────────────────────────
+
+const themes = {
+  default: {
+    fill: '█',
+    empty: '░',
+    head: '',
+    leftBracket: '[',
+    rightBracket: ']',
+    color: 'cyan',
+  },
+
+  minimal: {
+    fill: '#',
+    empty: '-',
+    head: '',
+    leftBracket: '[',
+    rightBracket: ']',
+    color: 'white',
+  },
+
+  retro: {
+    fill: '=',
+    empty: '-',
+    head: '>',
+    leftBracket: '[',
+    rightBracket: ']',
+    color: 'green',
+  },
+
+  blocks: {
+    fill: '▓',
+    empty: '░',
+    head: '',
+    leftBracket: '[',
+    rightBracket: ']',
+    color: 'magenta',
+  },
+
+  dots: {
+    fill: '•',
+    empty: '·',
+    head: '',
+    leftBracket: '[',
+    rightBracket: ']',
+    color: 'yellow',
+  },
+
+  arrows: {
+    fill: '▸',
+    empty: '▹',
+    head: '',
+    leftBracket: '[',
+    rightBracket: ']',
+    color: 'blue',
+  },
+};
+
+export default themes;

package/themes/custom-example.json

@@ -0,0 +1,8 @@
+{
+  "fill": "★",
+  "empty": "☆",
+  "head": "",
+  "leftBracket": "[",
+  "rightBracket": "]",
+  "color": "yellow"
+}