effective-progress 0.1.2 → 0.1.3

package/README.md

@@ -1,11 +1,23 @@
 # effective-progress
 
+[![npm version](https://img.shields.io/npm/v/effective-progress)](https://www.npmjs.com/package/effective-progress)
+
+> [!WARNING]
+> Pre-`1.0.0`, breaking changes may happen in any release. SemVer guarantees will begin at `1.0.0`.
+> I recommend using only the `Progress.all` and `Progress.forEach` APIs for now, as they will likely change the least. The lower-level APIs for manual progress bar control are more likely to see breaking changes as I iterate on the design.
+>
+> Please open an issue or reach out if you have any questions or want to contribute!
+> Feedback and contributions are very welcome!
+
+<img alt="Showcase output" src="docs/images/showcase.gif" width="600" />
+
 `effective-progress` is an [Effect](https://effect.website/)-first terminal progress library with:
 
 - multiple progress bars
 - nested child progress bars
 - spinner support for indeterminate work
 - clean log rendering alongside progress output, allowing you to simply use Effects `Console.log` or `Effect.logInfo`.
+- simple to use `.all` and `.forEach` APIs similar to the ones you already know and love from `effect`. Just swap `Effect` for `Progress` and get progress bars for free!
 
 ## Install
 
@@ -32,12 +44,7 @@ const program = Progress.all(
 Effect.runPromise(program);
 ```
 
-```bash
-bun run examples/basic.ts
-Completed task 1
-Completed task 2
-- Running tasks in parallel: ━━━━━━━━━━━━────────────────── 2/5  40%
-```
+<img alt="Basic example output" src="docs/images/basic.gif" width="600" />
 
 ## Nested example
 
@@ -68,25 +75,122 @@ const program = Progress.all(
 Effect.runPromise(program);
 ```
 
-```bash
-❯ bun run examples/nesting.ts
-- Running tasks in parallel: ━━━━━━━━━━━━────────────────── 2/5  40%
-  - Running subtasks for task 3: ━━━━━━━━────────────────────── 4/15  27%
-  - Running subtasks for task 4: ━━━━━━━━────────────────────── 4/15  27%
-```
+<img alt="Nested example output" src="docs/images/nesting.gif" width="600" />
 
 ## Other examples
 
 - `examples/simpleExample.ts` - low-boilerplate real-world flow
 - `examples/advancedExample.ts` - full API usage with custom config and manual task control
+- `examples/showcase.ts` - nested concurrent tasks, spinner workloads, and mixed Effect/Console logging
 
 ## Log retention
 
-- `maxLogLines` controls in-memory log retention.
-- `maxLogLines` omitted or set to `0` means no log history is kept in memory.
+- `maxLogLines` on `RendererConfig` controls in-memory log retention.
+- Omitted or set to `0` means no log history is kept in memory.
 - `maxLogLines > 0` keeps only the latest `N` log lines in memory.
 
+## Configuring renderer and progress bars
+
+Configure global renderer behavior once, and a global base progress bar style:
+
+```ts
+import { Effect } from "effect";
+import * as Progress from "effective-progress";
+
+const configured = program.pipe(
+  Effect.provideService(Progress.RendererConfig, {
+    maxLogLines: 12,
+    nonTtyUpdateStep: 2,
+  }),
+  Effect.provideService(Progress.ProgressBarConfig, {
+    barWidth: 36,
+    colors: {
+      fill: { kind: "hex", value: "#00b894" },
+      spinner: { kind: "ansi256", value: 214 },
+    },
+  }),
+);
+
+Effect.runPromise(configured);
+```
+
+Task-level `progressbar` config is optional and inherits from its parent task (or from global `ProgressBarConfig` for root tasks):
+
+```ts
+yield *
+  progress.withTask(
+    {
+      description: "Worker pipeline",
+      progressbar: {
+        barWidth: 20,
+        spinnerFrames: [".", "o", "O", "0"],
+        colors: {
+          spinner: { kind: "named", value: "magentaBright" },
+        },
+      },
+    },
+    () => Effect.sleep("1 second"),
+  );
+```
+
+For manual service usage, capture logs explicitly:
+
+```ts
+const program = Progress.provide(
+  Effect.gen(function* () {
+    const progress = yield* Progress.Progress;
+
+    yield* progress.withTask({ description: "Manual task" }, () =>
+      progress.withCapturedLogs(
+        Effect.gen(function* () {
+          yield* Console.log("This log is rendered through progress output");
+          yield* Effect.sleep("1 second");
+        }),
+      ),
+    );
+  }),
+);
+```
+
+## Progress bar colors
+
+`progressbar.colors` is configured with typed color tokens that are validated by Effect Schema.
+
+```ts
+progressbar: {
+  spinnerFrames: ["-", "\\", "|", "/"],
+  barWidth: 30,
+  fillChar: "━",
+  emptyChar: "─",
+  leftBracket: "",
+  rightBracket: "",
+  colors: {
+    fill: { kind: "named", value: "cyan" },
+    empty: { kind: "hex", value: "#9ca3af", modifiers: ["dim"] },
+    brackets: { kind: "rgb", value: { r: 156, g: 163, b: 175 } },
+    percent: { kind: "named", value: "whiteBright", modifiers: ["bold"] },
+    spinner: { kind: "ansi256", value: 214 },
+    done: { kind: "named", value: "greenBright" },
+    failed: { kind: "named", value: "redBright", modifiers: ["bold"] },
+  },
+}
+```
+
+Supported color styles:
+
+- `named` (for example `cyan`, `greenBright`)
+- `hex` (for example `#00b894`)
+- `rgb` (for example `{ r: 0, g: 184, b: 148 }`)
+- `ansi256` (for example `214`)
+
+Supported modifiers:
+
+- `bold`, `dim`, `italic`, `underline`, `inverse`, `hidden`, `strikethrough`
+
+## Dependencies & package size
+
+This library is designed for CLI workflows, where package size is typically a lower-priority concern. Alongside `effect`, it relies on two mature runtime dependencies: `chalk` and `es-toolkit`.
+
 ## Notes
 
-- This is a WIP library, so expect breaking changes. Feedback and contributions are very welcome!
 - As Effect 4.0 is around the corner with some changes to logging, there may be some adjustments needed to align with the new Effect APIs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effective-progress",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Effect-first terminal progress bars with nested multibar support",
   "homepage": "https://github.com/stromseng/effective-progress#readme",
   "bugs": {
@@ -31,7 +31,9 @@
   },
   "dependencies": {
     "chalk": "^5.6.2",
-    "effect": "^3.19.16"
+    "effect": "^3.19.16",
+    "es-toolkit": "^1.44.0",
+    "type-fest": "^5.4.4"
   },
   "devDependencies": {
     "@effect/language-service": "^0.73.1",

package/src/api.ts

@@ -1,6 +1,5 @@
-import { Console, Effect, Option } from "effect";
+import { Effect, Option } from "effect";
 import type { Concurrency } from "effect/Types";
-import { makeProgressConsole } from "./console";
 import { makeProgressService } from "./runtime";
 import { Progress } from "./types";
 import type { TrackOptions } from "./types";
@@ -32,23 +31,17 @@ export interface ForEachExecutionOptions extends EffectExecutionOptions {
 
 export type ForEachOptions = TrackOptions & ForEachExecutionOptions;
 
-export const withProgressService = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+export const provide = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
   Effect.gen(function* () {
-    const outerConsole = yield* Console.consoleWith((console) => Effect.succeed(console));
     const existing = yield* Effect.serviceOption(Progress);
     if (Option.isSome(existing)) {
-      const console = makeProgressConsole(existing.value, outerConsole);
-      return yield* Effect.withConsole(
-        Effect.provideService(effect, Progress, existing.value),
-        console,
-      );
+      return yield* Effect.provideService(effect, Progress, existing.value);
     }
 
     return yield* Effect.scoped(
       Effect.gen(function* () {
         const service = yield* makeProgressService;
-        const console = makeProgressConsole(service, outerConsole);
-        return yield* Effect.withConsole(Effect.provideService(effect, Progress, service), console);
+        return yield* Effect.provideService(effect, Progress, service);
       }),
     );
   });
@@ -60,7 +53,7 @@ export const all = <
   effects: Arg,
   options: Omit<TrackOptions, "total"> & O,
 ): AllReturn<Arg, O> =>
-  withProgressService(
+  provide(
     Effect.gen(function* () {
       const progress = yield* Progress;
       return yield* progress.withTask(
@@ -68,10 +61,13 @@ export const all = <
           description: options.description,
           total: effects.length,
           transient: options.transient,
+          progressbar: options.progressbar,
         },
         (taskId) =>
           Effect.all(
-            effects.map((effect) => Effect.tap(effect, () => progress.advanceTask(taskId, 1))),
+            effects.map((effect) =>
+              Effect.tap(progress.withCapturedLogs(effect), () => progress.advanceTask(taskId, 1)),
+            ),
             {
               concurrency: options.concurrency,
               batching: options.batching,
@@ -89,7 +85,7 @@ export const forEach = <A, B, E, R>(
   f: (item: A, index: number) => Effect.Effect<B, E, R>,
   options: ForEachOptions,
 ): Effect.Effect<ReadonlyArray<B>, E, Exclude<R, Progress>> =>
-  withProgressService(
+  provide(
     Effect.gen(function* () {
       const progress = yield* Progress;
 
@@ -98,11 +94,15 @@ export const forEach = <A, B, E, R>(
           description: options.description,
           total: options.total ?? inferTotal(iterable),
           transient: options.transient,
+          progressbar: options.progressbar,
         },
         (taskId) =>
           Effect.forEach(
             iterable,
-            (item, index) => Effect.tap(f(item, index), () => progress.advanceTask(taskId, 1)),
+            (item, index) =>
+              Effect.tap(progress.withCapturedLogs(f(item, index)), () =>
+                progress.advanceTask(taskId, 1),
+              ),
             {
               concurrency: options.concurrency,
               batching: options.batching,

package/src/colors.ts

@@ -0,0 +1,206 @@
+import chalk from "chalk";
+import type { ChalkInstance } from "chalk";
+import { Schema } from "effect";
+
+export const StyleModifierSchema = Schema.Literal(
+  "bold",
+  "dim",
+  "italic",
+  "underline",
+  "inverse",
+  "hidden",
+  "strikethrough",
+);
+export type StyleModifier = typeof StyleModifierSchema.Type;
+
+export const NamedColorSchema = Schema.Literal(
+  "black",
+  "red",
+  "green",
+  "yellow",
+  "blue",
+  "magenta",
+  "cyan",
+  "white",
+  "blackBright",
+  "redBright",
+  "greenBright",
+  "yellowBright",
+  "blueBright",
+  "magentaBright",
+  "cyanBright",
+  "whiteBright",
+);
+export type NamedColor = typeof NamedColorSchema.Type;
+
+const HexColorSchema = Schema.String.pipe(Schema.pattern(/^#(?:[A-Fa-f0-9]{3}|[A-Fa-f0-9]{6})$/));
+const ColorChannelSchema = Schema.Number.pipe(
+  Schema.int(),
+  Schema.greaterThanOrEqualTo(0),
+  Schema.lessThanOrEqualTo(255),
+);
+const Ansi256Schema = Schema.Number.pipe(
+  Schema.int(),
+  Schema.greaterThanOrEqualTo(0),
+  Schema.lessThanOrEqualTo(255),
+);
+const ModifiersSchema = Schema.optional(Schema.Array(StyleModifierSchema));
+
+export const NamedColorStyleSchema = Schema.Struct({
+  kind: Schema.Literal("named"),
+  value: NamedColorSchema,
+  modifiers: ModifiersSchema,
+});
+
+export const HexColorStyleSchema = Schema.Struct({
+  kind: Schema.Literal("hex"),
+  value: HexColorSchema,
+  modifiers: ModifiersSchema,
+});
+
+export const RgbColorStyleSchema = Schema.Struct({
+  kind: Schema.Literal("rgb"),
+  value: Schema.Struct({
+    r: ColorChannelSchema,
+    g: ColorChannelSchema,
+    b: ColorChannelSchema,
+  }),
+  modifiers: ModifiersSchema,
+});
+
+export const Ansi256ColorStyleSchema = Schema.Struct({
+  kind: Schema.Literal("ansi256"),
+  value: Ansi256Schema,
+  modifiers: ModifiersSchema,
+});
+
+export const ColorStyleSchema = Schema.Union(
+  NamedColorStyleSchema,
+  HexColorStyleSchema,
+  RgbColorStyleSchema,
+  Ansi256ColorStyleSchema,
+);
+export type ColorStyle = typeof ColorStyleSchema.Type;
+
+export const ProgressBarColorsSchema = Schema.Struct({
+  fill: ColorStyleSchema,
+  empty: ColorStyleSchema,
+  brackets: ColorStyleSchema,
+  percent: ColorStyleSchema,
+  spinner: ColorStyleSchema,
+  done: ColorStyleSchema,
+  failed: ColorStyleSchema,
+});
+export type ProgressBarColors = typeof ProgressBarColorsSchema.Type;
+
+export const defaultProgressBarColors: ProgressBarColors = {
+  fill: { kind: "named", value: "cyan" },
+  empty: { kind: "named", value: "white", modifiers: ["dim"] },
+  brackets: { kind: "named", value: "white", modifiers: ["dim"] },
+  percent: { kind: "named", value: "white", modifiers: ["bold"] },
+  spinner: { kind: "named", value: "yellow" },
+  done: { kind: "named", value: "green" },
+  failed: { kind: "named", value: "red" },
+};
+
+const applyModifier = (instance: ChalkInstance, modifier: StyleModifier): ChalkInstance => {
+  switch (modifier) {
+    case "bold":
+      return instance.bold;
+    case "dim":
+      return instance.dim;
+    case "italic":
+      return instance.italic;
+    case "underline":
+      return instance.underline;
+    case "inverse":
+      return instance.inverse;
+    case "hidden":
+      return instance.hidden;
+    case "strikethrough":
+      return instance.strikethrough;
+  }
+};
+
+const applyNamedColor = (instance: ChalkInstance, color: NamedColor): ChalkInstance => {
+  switch (color) {
+    case "black":
+      return instance.black;
+    case "red":
+      return instance.red;
+    case "green":
+      return instance.green;
+    case "yellow":
+      return instance.yellow;
+    case "blue":
+      return instance.blue;
+    case "magenta":
+      return instance.magenta;
+    case "cyan":
+      return instance.cyan;
+    case "white":
+      return instance.white;
+    case "blackBright":
+      return instance.blackBright;
+    case "redBright":
+      return instance.redBright;
+    case "greenBright":
+      return instance.greenBright;
+    case "yellowBright":
+      return instance.yellowBright;
+    case "blueBright":
+      return instance.blueBright;
+    case "magentaBright":
+      return instance.magentaBright;
+    case "cyanBright":
+      return instance.cyanBright;
+    case "whiteBright":
+      return instance.whiteBright;
+  }
+};
+
+const resolveBaseStyle = (style: ColorStyle): ChalkInstance => {
+  switch (style.kind) {
+    case "named":
+      return applyNamedColor(chalk, style.value);
+    case "hex":
+      return chalk.hex(style.value);
+    case "rgb":
+      return chalk.rgb(style.value.r, style.value.g, style.value.b);
+    case "ansi256":
+      return chalk.ansi256(style.value);
+  }
+};
+
+const applyModifiers = (instance: ChalkInstance, modifiers: ReadonlyArray<StyleModifier>) => {
+  let styled = instance;
+  for (const modifier of modifiers) {
+    styled = applyModifier(styled, modifier);
+  }
+  return styled;
+};
+
+export const applyColorStyle = (style: ColorStyle, text: string): string => {
+  const styled = applyModifiers(resolveBaseStyle(style), style.modifiers ?? []);
+  return styled(text);
+};
+
+export interface CompiledProgressBarColors {
+  readonly fill: (text: string) => string;
+  readonly empty: (text: string) => string;
+  readonly brackets: (text: string) => string;
+  readonly percent: (text: string) => string;
+  readonly spinner: (text: string) => string;
+  readonly done: (text: string) => string;
+  readonly failed: (text: string) => string;
+}
+
+export const compileProgressBarColors = (colors: ProgressBarColors): CompiledProgressBarColors => ({
+  fill: (text) => applyColorStyle(colors.fill, text),
+  empty: (text) => applyColorStyle(colors.empty, text),
+  brackets: (text) => applyColorStyle(colors.brackets, text),
+  percent: (text) => applyColorStyle(colors.percent, text),
+  spinner: (text) => applyColorStyle(colors.spinner, text),
+  done: (text) => applyColorStyle(colors.done, text),
+  failed: (text) => applyColorStyle(colors.failed, text),
+});

package/src/console.ts

@@ -1,14 +1,13 @@
 import { Console, Effect } from "effect";
 import { formatWithOptions } from "node:util";
-import type { ProgressService } from "./types";
 
 export const makeProgressConsole = (
-  progress: ProgressService,
+  progressLog: (...args: ReadonlyArray<unknown>) => Effect.Effect<void, never, never>,
   outerConsole: Console.Console,
 ): Console.Console => {
-  const log = (...args: ReadonlyArray<unknown>) => progress.log(...args);
+  const log = (...args: ReadonlyArray<unknown>) => progressLog(...args);
   const unsafeLog = (...args: ReadonlyArray<unknown>) => {
-    Effect.runFork(progress.log(...args));
+    Effect.runFork(progressLog(...args));
   };
 
   const delegate = (effect: Effect.Effect<void, never, never>) => effect;

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from "./api";
+export * from "./colors";
 export * from "./runtime";
 export * from "./types";

package/src/renderer.ts

@@ -1,49 +1,59 @@
-import { Effect, Ref } from "effect";
-import chalk from "chalk";
-import type { ProgressBarConfigShape } from "./types";
+import { Effect, Ref, Schema } from "effect";
+import {
+  type CompiledProgressBarColors,
+  compileProgressBarColors,
+  ProgressBarColorsSchema,
+} from "./colors";
+import type { ProgressBarConfigShape, RendererConfigShape } from "./types";
 import { DeterminateTaskUnits, TaskId, TaskSnapshot } from "./types";
 
 const HIDE_CURSOR = "\x1b[?25l";
 const SHOW_CURSOR = "\x1b[?25h";
 const CLEAR_LINE = "\x1b[2K";
 const MOVE_UP_ONE = "\x1b[1A";
-const RENDER_INTERVAL = "80 millis";
+const encodeProgressBarColorsKey = Schema.encodeSync(Schema.parseJson(ProgressBarColorsSchema));
 
-const renderDeterminate = (units: DeterminateTaskUnits, config: ProgressBarConfigShape): string => {
+const renderDeterminate = (
+  units: DeterminateTaskUnits,
+  progressbar: ProgressBarConfigShape,
+  colors: CompiledProgressBarColors,
+): string => {
   const safeTotal = units.total <= 0 ? 1 : units.total;
   const ratio = Math.min(1, Math.max(0, units.completed / safeTotal));
-  const filled = Math.round(ratio * config.barWidth);
-  const bar = `${chalk.cyan(config.fillChar.repeat(filled))}${chalk.dim(config.emptyChar.repeat(config.barWidth - filled))}`;
+  const filled = Math.round(ratio * progressbar.barWidth);
+  const bar = `${colors.fill(progressbar.fillChar.repeat(filled))}${colors.empty(progressbar.emptyChar.repeat(progressbar.barWidth - filled))}`;
   const percent = String(Math.round(ratio * 100)).padStart(3, " ");
-  return `${chalk.dim(config.leftBracket)}${bar}${chalk.dim(config.rightBracket)} ${units.completed}/${units.total} ${chalk.bold(percent + "%")}`;
+  return `${colors.brackets(progressbar.leftBracket)}${bar}${colors.brackets(progressbar.rightBracket)} ${units.completed}/${units.total} ${colors.percent(percent + "%")}`;
 };
 
 const buildTaskLine = (
   snapshot: TaskSnapshot,
   depth: number,
   tick: number,
-  config: ProgressBarConfigShape,
+  colors: CompiledProgressBarColors,
 ): string => {
+  const progressbar = snapshot.progressbar;
   const prefix = `${"  ".repeat(depth)}- ${snapshot.description}: `;
 
   if (snapshot.status === "failed") {
-    return `${prefix}${chalk.red("[failed]")}`;
+    return `${prefix}${colors.failed("[failed]")}`;
   }
 
   if (snapshot.status === "done") {
     if (snapshot.units._tag === "DeterminateTaskUnits") {
-      return `${prefix}${chalk.green("[done]")} ${snapshot.units.completed}/${snapshot.units.total}`;
+      return `${prefix}${colors.done("[done]")} ${snapshot.units.completed}/${snapshot.units.total}`;
     }
-    return `${prefix}${chalk.green("[done]")}`;
+    return `${prefix}${colors.done("[done]")}`;
   }
 
   if (snapshot.units._tag === "DeterminateTaskUnits") {
-    return prefix + renderDeterminate(snapshot.units, config);
+    return prefix + renderDeterminate(snapshot.units, progressbar, colors);
   }
 
-  const frames = config.spinnerFrames;
+  const frames = progressbar.spinnerFrames;
   const frameIndex = (snapshot.units.spinnerFrame + tick) % frames.length;
-  return `${prefix}${chalk.yellow(frames[frameIndex])}`;
+  const frame = frames[frameIndex] ?? frames[0]!;
+  return `${prefix}${colors.spinner(frame)}`;
 };
 
 const orderTasksForRender = (
@@ -74,17 +84,32 @@ export const runProgressServiceRenderer = (
   logsRef: Ref.Ref<ReadonlyArray<string>>,
   pendingLogsRef: Ref.Ref<ReadonlyArray<string>>,
   dirtyRef: Ref.Ref<boolean>,
-  config: ProgressBarConfigShape,
+  rendererConfig: RendererConfigShape,
   maxRetainedLogLines: number,
+  rendererLatch: Effect.Latch,
 ) => {
-  const isTTY = config.isTTY;
+  const isTTY = rendererConfig.isTTY;
   const retainLogHistory = maxRetainedLogLines > 0;
+  const colorCache = new Map<string, CompiledProgressBarColors>();
   let previousLineCount = 0;
   let previousTaskLineCount = 0;
   let nonTTYTaskSignatureById = new Map<number, string>();
   let tick = 0;
+  let rendererActive = false;
   let teardownInput: (() => void) | undefined;
 
+  const getCompiledColors = (progressbar: ProgressBarConfigShape): CompiledProgressBarColors => {
+    const key = encodeProgressBarColorsKey(progressbar.colors);
+    const cached = colorCache.get(key);
+    if (cached) {
+      return cached;
+    }
+
+    const compiled = compileProgressBarColors(progressbar.colors);
+    colorCache.set(key, compiled);
+    return compiled;
+  };
+
   const clearTTYLines = (lineCount: number) => {
     if (lineCount <= 0) {
       return;
@@ -103,7 +128,7 @@ export const runProgressServiceRenderer = (
   ) => {
     const nextTaskSignatureById = new Map<number, string>();
     const changedTaskLines: Array<string> = [];
-    const nonTtyUpdateStep = Math.max(1, Math.floor(config.nonTtyUpdateStep));
+    const nonTtyUpdateStep = Math.max(1, Math.floor(rendererConfig.nonTtyUpdateStep));
 
     for (let i = 0; i < ordered.length; i++) {
       const taskId = ordered[i]!.snapshot.id as number;
@@ -137,7 +162,7 @@ export const runProgressServiceRenderer = (
       const frameTick = mode === "final" ? tick + 1 : tick;
       const taskLines = ordered.map(({ snapshot, depth }) => {
         const lineTick = isTTY ? frameTick : 0;
-        return buildTaskLine(snapshot, depth, lineTick, config);
+        return buildTaskLine(snapshot, depth, lineTick, getCompiledColors(snapshot.progressbar));
       });
 
       if (isTTY) {
@@ -170,10 +195,13 @@ export const runProgressServiceRenderer = (
     });
 
   return Effect.gen(function* () {
+    yield* rendererLatch.await;
+    rendererActive = true;
+
     if (isTTY) {
       process.stderr.write(HIDE_CURSOR);
 
-      if (config.disableUserInput && process.stdin.isTTY) {
+      if (rendererConfig.disableUserInput && process.stdin.isTTY) {
         const stdin = process.stdin;
         const wasRaw = Boolean(stdin.isRaw);
         stdin.resume();
@@ -214,11 +242,15 @@ export const runProgressServiceRenderer = (
       }
 
       tick += 1;
-      yield* Effect.sleep(RENDER_INTERVAL);
+      yield* Effect.sleep(Math.max(1, Math.floor(rendererConfig.renderIntervalMillis)));
     }
   }).pipe(
     Effect.ensuring(
       Effect.gen(function* () {
+        if (!rendererActive) {
+          return;
+        }
+
         yield* renderFrame("final");
 
         if (isTTY) {

package/src/runtime.ts

@@ -1,13 +1,20 @@
-import { Effect, Exit, FiberRef, Option, Ref } from "effect";
+import { Console, Effect, Exit, FiberRef, Option, Ref } from "effect";
+import { mergeWith } from "es-toolkit/object";
 import { formatWithOptions } from "node:util";
+import type { PartialDeep } from "type-fest";
+import { makeProgressConsole } from "./console";
 import { runProgressServiceRenderer } from "./renderer";
 import type { AddTaskOptions, ProgressService, UpdateTaskOptions } from "./types";
 import {
+  decodeProgressBarConfigSync,
+  decodeRendererConfigSync,
   defaultProgressBarConfig,
+  defaultRendererConfig,
   DeterminateTaskUnits,
   IndeterminateTaskUnits,
   Progress,
   ProgressBarConfig,
+  RendererConfig,
   TaskId,
   TaskSnapshot,
 } from "./types";
@@ -15,6 +22,21 @@ import { inferTotal } from "./utils";
 
 const DIRTY_DEBOUNCE_INTERVAL = "10 millis";
 
+const mergeConfig = <T extends Record<PropertyKey, any>>(
+  base: T,
+  override: PartialDeep<T> | undefined,
+): T =>
+  mergeWith(
+    structuredClone(base),
+    (override ?? {}) as Record<PropertyKey, any>,
+    (_targetValue, sourceValue) => {
+      if (Array.isArray(sourceValue)) {
+        return sourceValue;
+      }
+      return undefined;
+    },
+  ) as T;
+
 const updatedSnapshot = (snapshot: TaskSnapshot, options: UpdateTaskOptions): TaskSnapshot => {
   const currentUnits = snapshot.units;
   const units = (() => {
@@ -54,13 +76,27 @@ const updatedSnapshot = (snapshot: TaskSnapshot, options: UpdateTaskOptions): Ta
     status: snapshot.status,
     transient: options.transient ?? snapshot.transient,
     units,
+    progressbar: snapshot.progressbar,
   });
 };
 
 export const makeProgressService = Effect.gen(function* () {
-  const configOption = yield* Effect.serviceOption(ProgressBarConfig);
-  const config = Option.getOrElse(configOption, () => defaultProgressBarConfig);
-  const maxRetainedLogLines = Math.max(0, Math.floor(config.maxLogLines ?? 0));
+  const rendererConfigOption = yield* Effect.serviceOption(RendererConfig);
+  const progressBarConfigOption = yield* Effect.serviceOption(ProgressBarConfig);
+
+  const rendererConfig = decodeRendererConfigSync(
+    mergeConfig(
+      defaultRendererConfig,
+      Option.isSome(rendererConfigOption) ? rendererConfigOption.value : undefined,
+    ),
+  );
+  const progressBarConfig = decodeProgressBarConfigSync(
+    mergeConfig(
+      defaultProgressBarConfig,
+      Option.isSome(progressBarConfigOption) ? progressBarConfigOption.value : undefined,
+    ),
+  );
+  const maxRetainedLogLines = Math.max(0, Math.floor(rendererConfig.maxLogLines ?? 0));
 
   const nextTaskIdRef = yield* Ref.make(0);
   const tasksRef = yield* Ref.make(new Map<TaskId, TaskSnapshot>());
@@ -68,17 +104,22 @@ export const makeProgressService = Effect.gen(function* () {
   const pendingLogsRef = yield* Ref.make<ReadonlyArray<string>>([]);
   const dirtyRef = yield* Ref.make(true);
   const dirtyScheduledRef = yield* Ref.make(false);
+  const rendererStartedRef = yield* Ref.make(false);
+  const rendererLatch = yield* Effect.makeLatch(false);
   const currentParentRef = yield* FiberRef.make(Option.none<TaskId>());
+  const scope = yield* Effect.scope;
 
-  yield* Effect.forkScoped(
+  yield* Effect.forkIn(
     runProgressServiceRenderer(
       tasksRef,
       logsRef,
       pendingLogsRef,
       dirtyRef,
-      config,
+      rendererConfig,
       maxRetainedLogLines,
+      rendererLatch,
     ),
+    scope,
   );
 
   const markDirty = Effect.gen(function* () {
@@ -109,6 +150,19 @@ export const makeProgressService = Effect.gen(function* () {
         options.total === undefined || options.total <= 0
           ? new IndeterminateTaskUnits({ spinnerFrame: 0 })
           : new DeterminateTaskUnits({ completed: 0, total: Math.max(0, options.total) });
+      const tasks = yield* Ref.get(tasksRef);
+      const parentSnapshot =
+        Option.isSome(parentId) ? tasks.get(parentId.value) : undefined;
+      const inheritedProgressBarConfig = parentSnapshot?.progressbar ?? progressBarConfig;
+      const resolvedProgressBarConfig = decodeProgressBarConfigSync(
+        mergeConfig(inheritedProgressBarConfig, options.progressbar),
+      );
+      const shouldOpenRenderer = yield* Ref.modify(rendererStartedRef, (started) =>
+        started ? [false, true] : [true, true],
+      );
+      if (shouldOpenRenderer) {
+        yield* rendererLatch.open;
+      }
 
       const snapshot = new TaskSnapshot({
         id: taskId,
@@ -117,6 +171,7 @@ export const makeProgressService = Effect.gen(function* () {
         status: "running",
         transient: options.transient ?? false,
         units,
+        progressbar: resolvedProgressBarConfig,
       });
 
       yield* Ref.update(tasksRef, (tasks) => {
@@ -156,8 +211,7 @@ export const makeProgressService = Effect.gen(function* () {
               total: snapshot.units.total,
             })
           : new IndeterminateTaskUnits({
-              spinnerFrame:
-                (snapshot.units.spinnerFrame + amount) % Math.max(1, config.spinnerFrames.length),
+              spinnerFrame: Math.max(0, snapshot.units.spinnerFrame + amount),
             });
 
       next.set(
@@ -169,6 +223,7 @@ export const makeProgressService = Effect.gen(function* () {
           status: snapshot.status,
           transient: snapshot.transient,
           units,
+          progressbar: snapshot.progressbar,
         }),
       );
 
@@ -203,6 +258,7 @@ export const makeProgressService = Effect.gen(function* () {
                   total: snapshot.units.total,
                 })
               : snapshot.units,
+          progressbar: snapshot.progressbar,
         }),
       );
       return next;
@@ -230,6 +286,7 @@ export const makeProgressService = Effect.gen(function* () {
           status: "failed",
           transient: snapshot.transient,
           units: snapshot.units,
+          progressbar: snapshot.progressbar,
         }),
       );
       return next;
@@ -241,9 +298,16 @@ export const makeProgressService = Effect.gen(function* () {
         return;
       }
 
+      const shouldOpenRenderer = yield* Ref.modify(rendererStartedRef, (started) =>
+        started ? [false, true] : [true, true],
+      );
+      if (shouldOpenRenderer) {
+        yield* rendererLatch.open;
+      }
+
       const message = formatWithOptions(
         {
-          colors: config.isTTY,
+          colors: rendererConfig.isTTY,
           depth: 6,
         },
         ...args,
@@ -263,6 +327,12 @@ export const makeProgressService = Effect.gen(function* () {
       yield* markDirty;
     });
 
+  const withCapturedLogs: ProgressService["withCapturedLogs"] = (effect) =>
+    Effect.gen(function* () {
+      const outerConsole = yield* Console.consoleWith((console) => Effect.succeed(console));
+      return yield* Effect.withConsole(effect, makeProgressConsole(log, outerConsole));
+    });
+
   const getTask = (taskId: TaskId) =>
     Ref.get(tasksRef).pipe(Effect.map((tasks) => Option.fromNullable(tasks.get(taskId))));
 
@@ -302,6 +372,7 @@ export const makeProgressService = Effect.gen(function* () {
         description: options.description,
         total: options.total ?? inferTotal(iterable),
         transient: options.transient,
+        progressbar: options.progressbar,
       },
       (taskId) => {
         return Effect.forEach(iterable, (item, index) =>
@@ -310,16 +381,19 @@ export const makeProgressService = Effect.gen(function* () {
       },
     );
 
-  return Progress.of({
+  const service: ProgressService = {
     addTask,
     updateTask,
     advanceTask,
     completeTask,
     failTask,
     log,
+    withCapturedLogs,
     getTask,
     listTasks,
     withTask,
     trackIterable,
-  });
+  };
+
+  return Progress.of(service);
 });

package/src/types.ts

@@ -1,39 +1,55 @@
 import { Brand, Context, Effect, Option, Schema } from "effect";
+import type { PartialDeep } from "type-fest";
+import { defaultProgressBarColors, ProgressBarColorsSchema } from "./colors";
 
-export const SPINNER_FRAMES = ["-", "\\", "|", "/"] as const;
-export const DEFAULT_PROGRESS_BAR_WIDTH = 30;
-
-export const ProgressBarConfigSchema = Schema.Struct({
+export const RendererConfigSchema = Schema.Struct({
   isTTY: Schema.Boolean,
   disableUserInput: Schema.Boolean,
+  renderIntervalMillis: Schema.Number,
+  maxLogLines: Schema.optional(Schema.Number),
+  nonTtyUpdateStep: Schema.Number,
+});
+export type RendererConfigShape = typeof RendererConfigSchema.Type;
+export const decodeRendererConfigSync = Schema.decodeUnknownSync(RendererConfigSchema);
+
+export const ProgressBarConfigSchema = Schema.Struct({
   spinnerFrames: Schema.NonEmptyArray(Schema.String),
   barWidth: Schema.Number,
   fillChar: Schema.String,
   emptyChar: Schema.String,
   leftBracket: Schema.String,
   rightBracket: Schema.String,
-  maxLogLines: Schema.optional(Schema.Number),
-  nonTtyUpdateStep: Schema.Number,
+  colors: ProgressBarColorsSchema,
 });
-
 export type ProgressBarConfigShape = typeof ProgressBarConfigSchema.Type;
+export const decodeProgressBarConfigSync = Schema.decodeUnknownSync(ProgressBarConfigSchema);
 
-export const defaultProgressBarConfig: ProgressBarConfigShape = {
+export const defaultRendererConfig: RendererConfigShape = {
   isTTY: Boolean(process.stderr.isTTY),
   disableUserInput: true,
-  spinnerFrames: SPINNER_FRAMES,
-  barWidth: DEFAULT_PROGRESS_BAR_WIDTH,
+  renderIntervalMillis: 50, // 20 FPS
+  maxLogLines: 0,
+  nonTtyUpdateStep: 5,
+};
+
+export const defaultProgressBarConfig: ProgressBarConfigShape = {
+  spinnerFrames: ["-", "\\", "|", "/"],
+  barWidth: 30,
   fillChar: "━",
   emptyChar: "─",
   leftBracket: "",
   rightBracket: "",
-  maxLogLines: 0,
-  nonTtyUpdateStep: 5,
+  colors: defaultProgressBarColors,
 };
 
+export class RendererConfig extends Context.Tag("stromseng.dev/RendererConfig")<
+  RendererConfig,
+  PartialDeep<RendererConfigShape>
+>() {}
+
 export class ProgressBarConfig extends Context.Tag("stromseng.dev/ProgressBarConfig")<
   ProgressBarConfig,
-  ProgressBarConfigShape
+  PartialDeep<ProgressBarConfigShape>
 >() {}
 
 const TaskIdSchema = Schema.Number.pipe(Schema.brand("TaskId"));
@@ -50,6 +66,7 @@ export interface AddTaskOptions {
   readonly total?: number;
   readonly transient?: boolean;
   readonly parentId?: TaskId;
+  readonly progressbar?: PartialDeep<ProgressBarConfigShape>;
 }
 
 export interface UpdateTaskOptions {
@@ -87,6 +104,7 @@ export class TaskSnapshot extends Schema.TaggedClass<TaskSnapshot>()("TaskSnapsh
   status: TaskStatusSchema,
   transient: Schema.Boolean,
   units: TaskUnitsSchema,
+  progressbar: ProgressBarConfigSchema,
 }) {}
 
 export interface ProgressService {
@@ -96,6 +114,7 @@ export interface ProgressService {
   readonly completeTask: (taskId: TaskId) => Effect.Effect<void>;
   readonly failTask: (taskId: TaskId) => Effect.Effect<void>;
   readonly log: (...args: ReadonlyArray<unknown>) => Effect.Effect<void>;
+  readonly withCapturedLogs: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
   readonly getTask: (taskId: TaskId) => Effect.Effect<Option.Option<TaskSnapshot>>;
   readonly listTasks: Effect.Effect<ReadonlyArray<TaskSnapshot>>;
   readonly withTask: <A, E, R>(