@promptbook/cli 0.114.0-0 → 0.114.0-10

package/src/remote-server/createRemoteClient.ts

@@ -1,10 +1,19 @@
 import type { Socket } from 'socket.io-client';
-import { io } from 'socket.io-client';
 import { spaceTrim } from 'spacetrim';
 import { CONNECTION_RETRIES_LIMIT, CONNECTION_TIMEOUT_MS } from '../config';
+import { createLazyModuleLoader } from '../utils/misc/createLazyModuleLoader';
 import { isValidUrl } from '../utils/validators/url/isValidUrl';
 import type { RemoteClientOptions } from './types/RemoteClientOptions';
 
+/**
+ * Loads the Socket.io client (`socket.io-client`) on demand
+ *
+ * Note: [🐌] Loaded lazily to keep the startup of the `ptbk` CLI utility fast
+ *
+ * @private internal utility of `createRemoteClient`
+ */
+const loadSocketIoClientModule = createLazyModuleLoader(() => import('socket.io-client'));
+
 /**
  * Creates a connection to the remote proxy server.
  *
@@ -44,6 +53,8 @@ export async function createRemoteClient<TCustomOptions = undefined>(
         );
     }
 
+    const { io } = await loadSocketIoClientModule();
+
     return new Promise((resolve, reject) => {
         const socket = io(remoteServerUrl, {
             retries: CONNECTION_RETRIES_LIMIT,

package/src/{commitments/USE_BROWSER → scrapers/_common/utils}/fetchUrlContent.ts

@@ -1,9 +1,9 @@
 import { spaceTrim } from 'spacetrim';
-import type { LlmExecutionTools } from '../../execution/LlmExecutionTools';
-import { $provideFilesystemForNode } from '../../scrapers/_common/register/$provideFilesystemForNode';
-import type { ScraperSourceHandler } from '../../scrapers/_common/Scraper';
-import { promptbookFetch } from '../../scrapers/_common/utils/promptbookFetch';
-import { WebsiteScraper } from '../../scrapers/website/WebsiteScraper';
+import type { LlmExecutionTools } from '../../../execution/LlmExecutionTools';
+import { $provideFilesystemForNode } from '../register/$provideFilesystemForNode';
+import type { ScraperSourceHandler } from '../Scraper';
+import { WebsiteScraper } from '../../website/WebsiteScraper';
+import { promptbookFetch } from './promptbookFetch';
 
 /**
  * Fetches and scrapes content from a URL (SERVER-SIDE ONLY)
@@ -15,13 +15,12 @@ import { WebsiteScraper } from '../../scrapers/website/WebsiteScraper';
  * 4. Returns the scraped markdown content
  *
  * WARNING: This function should NOT be used directly in browser environments.
- * For browser environments, use fetchUrlContentViaBrowser which proxies through
- * the Agents Server API endpoint at /api/scrape
+ * For browser environments, proxy the request through the Agents Server API endpoint at /api/scrape
  *
  * @param url The URL to fetch and scrape
  * @returns Markdown content from the URL
  *
- * @private internal utility for USE BROWSER commitment
+ * @private internal scraping utility
  */
 export async function fetchUrlContent(url: string): Promise<string> {
     try {
@@ -137,4 +136,4 @@ export async function fetchUrlContent(url: string): Promise<string> {
     }
 }
 
-// Note: [🟢] Code for Node browser-fetch helper [fetchUrlContent](src/commitments/USE_BROWSER/fetchUrlContent.ts) should never be published into packages that could be imported into browser environment
+// Note: [🟢] Code for Node fetch-and-scrape helper [fetchUrlContent](src/scrapers/_common/utils/fetchUrlContent.ts) should never be published into packages that could be imported into browser environment

package/src/scrapers/website/WebsiteScraper.ts

@@ -4,8 +4,6 @@ import type { Converter } from '../_common/Converter';
 import type { Scraper, ScraperSourceHandler } from '../_common/Scraper';
 // TODO: [🏳‍🌈] Finally take pick of .json vs .ts
 // import PipelineCollection from '../../../books/books';
-import { Readability } from '@mozilla/readability';
-import { JSDOM } from 'jsdom';
 import type { Converter as ShowdownConverter } from 'showdown';
 import { DEFAULT_INTERMEDIATE_FILES_STRATEGY, DEFAULT_IS_VERBOSE, DEFAULT_SCRAPE_CACHE_DIRNAME } from '../../config';
 import { EnvironmentMismatchError } from '../../errors/EnvironmentMismatchError';
@@ -13,6 +11,7 @@ import { KnowledgeScrapeError } from '../../errors/KnowledgeScrapeError';
 import { UnexpectedError } from '../../errors/UnexpectedError';
 import type { ExecutionTools } from '../../execution/ExecutionTools';
 import type { PrepareAndScrapeOptions } from '../../prepare/PrepareAndScrapeOptions';
+import { createLazyModuleLoader } from '../../utils/misc/createLazyModuleLoader';
 import { MarkdownScraper } from '../markdown/MarkdownScraper';
 import type { ScraperAndConverterMetadata } from '../_common/register/ScraperAndConverterMetadata';
 import type { ScraperIntermediateSource } from '../_common/ScraperIntermediateSource';
@@ -20,6 +19,25 @@ import { getScraperIntermediateSource } from '../_common/utils/getScraperInterme
 import { websiteScraperMetadata } from './register-metadata';
 import { createShowdownConverter } from './utils/createShowdownConverter';
 
+/**
+ * Loads `jsdom` on demand
+ *
+ * Note: [🐌] `jsdom` is by far the heaviest dependency of Promptbook, loading it eagerly would slow down every single
+ *       run of the `ptbk` CLI utility even when no website is scraped
+ *
+ * @private internal utility of `WebsiteScraper`
+ */
+const loadJsdomModule = createLazyModuleLoader(() => import('jsdom'));
+
+/**
+ * Loads `@mozilla/readability` on demand
+ *
+ * Note: [🐌] Loaded lazily to keep the startup of the `ptbk` CLI utility fast
+ *
+ * @private internal utility of `WebsiteScraper`
+ */
+const loadReadabilityModule = createLazyModuleLoader(() => import('@mozilla/readability'));
+
 /**
  * Scraper for websites
  *
@@ -77,6 +95,8 @@ export class WebsiteScraper implements Converter, Scraper {
             throw new EnvironmentMismatchError('Can not scrape websites without filesystem tools');
         }
 
+        const [{ JSDOM }, { Readability }] = await Promise.all([loadJsdomModule(), loadReadabilityModule()]);
+
         const jsdom = new JSDOM(await source.asText(), {
             url: source.url,
         });

package/src/utils/agent-message-runtime/resolveAgentMessageRuntimeActivity.ts

@@ -5,6 +5,72 @@
  */
 const MAX_RUNTIME_ACTIVITY_LENGTH = 160;
 
+/**
+ * One safe, concrete category of a command emitted by the Codex runtime.
+ *
+ * @private internal type of agent-message runtime activity
+ */
+type CodexCommandActivity = {
+    readonly pattern: RegExp;
+    readonly running: string;
+    readonly completed: string;
+};
+
+/**
+ * Ordered command categories that can be described truthfully without showing raw commands,
+ * arguments, file names, or other private runtime details.
+ *
+ * The local runner can execute on either Unix or Windows. Keeping the variants together here
+ * ensures that equivalent shell commands yield the same concise status in the chat.
+ *
+ * @private internal constant of agent-message runtime activity
+ */
+const CODEX_COMMAND_ACTIVITIES: ReadonlyArray<CodexCommandActivity> = [
+    {
+        pattern:
+            /(^|\s)(npm\s+(?:run\s+)?test|pnpm\s+(?:run\s+)?test|yarn\s+test|jest|vitest|pytest)\b/u,
+        running: 'Running tests.',
+        completed: 'Finished running tests.',
+    },
+    {
+        pattern: /(^|\s)(npm\s+run\s+build|pnpm\s+(?:run\s+)?build|yarn\s+build|next\s+build)\b/u,
+        running: 'Building the project.',
+        completed: 'Finished building the project.',
+    },
+    {
+        pattern: /(^|\s)(npm|pnpm|yarn)\s+(?:install|add)\b/u,
+        running: 'Installing dependencies.',
+        completed: 'Finished installing dependencies.',
+    },
+    {
+        pattern: /(^|\s)(npm\s+(?:run\s+)?lint|pnpm\s+(?:run\s+)?lint|yarn\s+lint|eslint|prettier)\b/u,
+        running: 'Checking the implementation.',
+        completed: 'Finished checking the implementation.',
+    },
+    {
+        pattern: /(^|\s)git\s+(?:status|diff|log|show)\b/u,
+        running: 'Reviewing changes.',
+        completed: 'Finished reviewing changes.',
+    },
+    {
+        pattern:
+            /(^|\s)(apply_patch|set-content|add-content|out-file|new-item|copy-item|move-item|set-item)\b/u,
+        running: 'Updating relevant files.',
+        completed: 'Finished updating relevant files.',
+    },
+    {
+        pattern:
+            /(^|\s)(ls|find|rg|grep|sed|cat|head|tail|get-content|get-childitem|get-item|select-string|findstr|type)\b/u,
+        running: 'Inspecting relevant files.',
+        completed: 'Finished inspecting relevant files.',
+    },
+    {
+        pattern: /(^|\s)(curl|wget|invoke-webrequest)\b/u,
+        running: 'Looking up information.',
+        completed: 'Finished looking up information.',
+    },
+];
+
 /**
  * Minimal shape of one coding-harness `stream-json` event relevant to progress extraction.
  *
@@ -21,6 +87,11 @@ type RuntimeLogEvent = {
             readonly text?: string;
         }>;
     };
+    readonly item?: {
+        readonly type?: string;
+        readonly command?: string;
+        readonly exit_code?: number | null;
+    };
 };
 
 /**
@@ -30,9 +101,9 @@ type RuntimeLogEvent = {
  * Claude Code `--output-format stream-json`) into a live runtime log file next to the queued
  * message. This helper extracts the most recent natural-language assistant narration so the
  * durable chat can show what the agent is doing right now instead of a generic thinking
- * placeholder. Only plain assistant text is surfaced; raw tool payloads, JSON envelopes and
- * other technical details are intentionally ignored, and harnesses that do not stream
- * structured text simply resolve to `null` so the caller keeps its existing behavior.
+ * placeholder. Only concrete, safe activity is surfaced; raw tool payloads, JSON envelopes,
+ * and private reasoning are intentionally ignored. When no concrete activity is known, this
+ * resolves to `null` so the caller keeps the browser's rotating generic thinking state.
  *
  * @param logText - Raw runtime log content.
  * @returns Latest human-readable activity snippet, or `null` when none can be resolved.
@@ -89,6 +160,11 @@ function parseRuntimeLogEvent(line: string): RuntimeLogEvent | null {
  * @private internal helper of `resolveAgentMessageRuntimeActivity`
  */
 function resolveRuntimeLogEventActivity(event: RuntimeLogEvent): string | null {
+    const codexActivity = resolveCodexRuntimeLogEventActivity(event);
+    if (codexActivity) {
+        return codexActivity;
+    }
+
     if (event.type !== 'assistant' || !Array.isArray(event.message?.content)) {
         return null;
     }
@@ -103,6 +179,84 @@ function resolveRuntimeLogEventActivity(event: RuntimeLogEvent): string | null {
     return assistantText.length > 0 ? assistantText : null;
 }
 
+/**
+ * Resolves one short user-facing status from a structured Codex JSONL event.
+ *
+ * Codex reasoning and raw command text deliberately remain private. The event type tells us
+ * enough to report a useful action without exposing the internal trace or a command payload.
+ * Reasoning events are intentionally not a progress update: while they are the only signal,
+ * the chat retains its configured generic thinking rotation. Once a concrete action arrives,
+ * it becomes the latest user-facing status instead.
+ *
+ * @private internal helper of `resolveAgentMessageRuntimeActivity`
+ */
+function resolveCodexRuntimeLogEventActivity(event: RuntimeLogEvent): string | null {
+    if (!event.item || !isCodexItemEvent(event.type)) {
+        return null;
+    }
+
+    const isCompleted = event.type === 'item.completed';
+
+    switch (event.item.type) {
+        case 'reasoning':
+            return null;
+        case 'command_execution':
+            return resolveCodexCommandActivity(event.item.command, isCompleted, event.item.exit_code);
+        case 'file_change':
+            return isCompleted ? 'Updated relevant files.' : 'Updating relevant files.';
+        case 'web_search':
+            return isCompleted ? 'Finished searching the web.' : 'Searching the web.';
+        case 'mcp_tool_call':
+            return isCompleted ? 'Finished using an integration.' : 'Using an integration.';
+        case 'plan_update':
+            return isCompleted ? 'Updated the plan.' : 'Planning the work.';
+        default:
+            return null;
+    }
+}
+
+/**
+ * Returns whether one runtime event is a Codex item lifecycle event.
+ *
+ * @private internal helper of `resolveAgentMessageRuntimeActivity`
+ */
+function isCodexItemEvent(eventType: string | undefined): boolean {
+    return eventType === 'item.started' || eventType === 'item.updated' || eventType === 'item.completed';
+}
+
+/**
+ * Maps one Codex command event to a concise action without revealing the command itself.
+ *
+ * @private internal helper of `resolveAgentMessageRuntimeActivity`
+ */
+function resolveCodexCommandActivity(
+    command: string | undefined,
+    isCompleted: boolean,
+    exitCode: number | null | undefined,
+): string | null {
+    if (isCompleted && exitCode !== undefined && exitCode !== null && exitCode !== 0) {
+        return 'A command needs attention.';
+    }
+
+    const activity = resolveCodexCommandActivityLabel(command);
+    if (!activity) {
+        return null;
+    }
+
+    return isCompleted ? activity.completed : activity.running;
+}
+
+/**
+ * Resolves the short running/completed labels for one safe command category.
+ *
+ * @private internal helper of `resolveAgentMessageRuntimeActivity`
+ */
+function resolveCodexCommandActivityLabel(command: string | undefined): CodexCommandActivity | null {
+    const normalizedCommand = command?.toLowerCase() || '';
+
+    return CODEX_COMMAND_ACTIVITIES.find((activity) => activity.pattern.test(normalizedCommand)) ?? null;
+}
+
 /**
  * Collapses one activity string to a single trimmed line, truncated for the progress card.
  *

package/src/utils/agents/terminalAgentAvatarVisual.ts

@@ -6,6 +6,7 @@ import type { ResolvedAvatarRenderDefinition } from '../../avatars/renderAvatarV
 import { resolveAvatarRenderDefinition } from '../../avatars/renderAvatarVisual';
 import type { CreateCanvasForAsciiArt } from '../../avatars/renderAvatarVisualAsciiArt';
 import { renderAvatarVisualAsciiArt } from '../../avatars/renderAvatarVisualAsciiArt';
+import { renderAvatarVisualTerminalTextLines } from '../../avatars/renderAvatarVisualTerminalText';
 import type { AvatarDefinition } from '../../avatars/types/AvatarDefinition';
 import type { AvatarVisualId } from '../../avatars/types/AvatarVisualDefinition';
 import { resolveAvatarVisualId } from '../../avatars/visuals/avatarVisualRegistry';
@@ -127,9 +128,12 @@ export type CreateTerminalAgentAvatarVisualOptions = {
     readonly colorDepth?: AsciiArtColorDepth;
 
     /**
-     * Platform-specific canvas factory used to rasterize the visual.
+     * Platform-specific canvas factory used to rasterize pixel-based visuals.
+     *
+     * Character-based visuals such as `AsciiOctopus` paint the terminal grid directly, so they
+     * render without any canvas; a pixel-based visual renders an empty frame when it is missing.
      */
-    readonly createCanvas: CreateCanvasForAsciiArt;
+    readonly createCanvas?: CreateCanvasForAsciiArt;
 };
 
 /**
@@ -251,15 +255,39 @@ function resolveTerminalAgentAvatarVisualIdFromAgentBasicInformation(
 /**
  * Renders one terminal avatar frame through the shared avatar-to-ASCII pipeline.
  *
+ * Visuals which are made of characters themselves, for example `AsciiOctopus`, paint the terminal
+ * character grid directly, because rasterizing them into half-block ASCII art averages every glyph
+ * away and makes them indistinguishable from the other blob-shaped visuals.
+ *
  * @private shared helper for terminal avatar rendering
  */
 function renderTerminalAgentAvatarVisualFrame(
     options: TerminalAgentAvatarVisualRenderInputs & {
         readonly animationTimeMs: number;
         readonly colorDepth?: AsciiArtColorDepth;
-        readonly createCanvas: CreateCanvasForAsciiArt;
+        readonly createCanvas?: CreateCanvasForAsciiArt;
     },
 ): ReadonlyArray<string> {
+    const terminalTextLines = renderAvatarVisualTerminalTextLines({
+        avatarDefinition: options.avatarDefinition,
+        visualId: options.avatarVisualId,
+        surface: 'transparent',
+        columns: TERMINAL_AGENT_AVATAR_VISUAL_COLUMNS,
+        rows: TERMINAL_AGENT_AVATAR_VISUAL_ROWS,
+        colorDepth: options.colorDepth,
+        timeMs: options.animationTimeMs,
+        resolvedAvatarRenderDefinition: options.resolvedAvatarRenderDefinition,
+    });
+
+    if (terminalTextLines !== null) {
+        return terminalTextLines;
+    }
+
+    if (options.createCanvas === undefined) {
+        // Note: A pixel-based visual cannot be rasterized without a canvas, so the caller keeps its default banner
+        return [];
+    }
+
     return renderAvatarVisualAsciiArt({
         avatarDefinition: options.avatarDefinition,
         visualId: options.avatarVisualId,

package/src/utils/ascii-art/convertImageDataToAsciiArt.ts

@@ -1,5 +1,7 @@
 import { spaceTrim } from 'spacetrim';
 import { UnexpectedError } from '../../errors/UnexpectedError';
+import type { AnsiRgbColor } from './createAnsiColorCode';
+import { ANSI_RESET, createAnsiBackgroundColorCode, createAnsiForegroundColorCode } from './createAnsiColorCode';
 
 /**
  * Color depth of the ANSI escape codes emitted by the ASCII-art conversion.
@@ -75,11 +77,11 @@ export type ConvertImageDataToAsciiArtOptions = {
 };
 
 /**
- * Default alpha channel value below which a half-cell is rendered as terminal background.
+ * Default alpha channel value below which a cell is rendered as terminal background.
  *
  * @private within the repository
  */
-const DEFAULT_ALPHA_THRESHOLD = 32;
+export const DEFAULT_ALPHA_THRESHOLD = 32;
 
 /**
  * Number of channels per pixel in an RGBA buffer.
@@ -102,57 +104,12 @@ const UPPER_HALF_BLOCK = '▀'; // <- ▀
  */
 const LOWER_HALF_BLOCK = '▄'; // <- ▄
 
-/**
- * ANSI escape sequence that resets all colors and attributes.
- *
- * @private within the repository
- */
-const ANSI_RESET = '\u001b[0m';
-
-/**
- * Maximum spread between RGB channels for a color to be treated as (nearly) achromatic gray.
- *
- * @private within the repository
- */
-const ANSI_256_ACHROMATIC_CHANNEL_SPREAD = 12;
-
-/**
- * Gray level above which an achromatic color maps to the pure white color-cube entry.
- *
- * @private within the repository
- */
-const ANSI_256_NEAR_WHITE_GRAY_LEVEL = 246;
-
-/**
- * Index of pure white inside the 6×6×6 ANSI color cube.
- *
- * @private within the repository
- */
-const ANSI_256_WHITE_INDEX = 231;
-
-/**
- * Brightness of the lightest entry of the ANSI 256 grayscale ramp.
- *
- * @private within the repository
- */
-const ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL = 238;
-
-/**
- * Number of grayscale ramp steps above its first entry (ANSI indexes 232-255).
- *
- * @private within the repository
- */
-const ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN = 23;
-
 /**
  * Area-averaged color of one half of a character cell.
  *
  * @private helper of `convertImageDataToAsciiArt`
  */
-type HalfCellColor = {
-    readonly red: number;
-    readonly green: number;
-    readonly blue: number;
+type HalfCellColor = AnsiRgbColor & {
     readonly isOpaque: boolean;
 };
 
@@ -231,15 +188,15 @@ export function convertImageDataToAsciiArt(options: ConvertImageDataToAsciiArtOp
 
             if (topHalfColor.isOpaque && bottomHalfColor.isOpaque) {
                 character = UPPER_HALF_BLOCK;
-                nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
-                nextBackgroundCode = createBackgroundColorCode(bottomHalfColor, colorDepth);
+                nextForegroundCode = createAnsiForegroundColorCode(topHalfColor, colorDepth);
+                nextBackgroundCode = createAnsiBackgroundColorCode(bottomHalfColor, colorDepth);
             } else if (topHalfColor.isOpaque) {
                 character = UPPER_HALF_BLOCK;
-                nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
+                nextForegroundCode = createAnsiForegroundColorCode(topHalfColor, colorDepth);
                 nextBackgroundCode = undefined;
             } else if (bottomHalfColor.isOpaque) {
                 character = LOWER_HALF_BLOCK;
-                nextForegroundCode = createForegroundColorCode(bottomHalfColor, colorDepth);
+                nextForegroundCode = createAnsiForegroundColorCode(bottomHalfColor, colorDepth);
                 nextBackgroundCode = undefined;
             } else {
                 character = ' ';
@@ -337,60 +294,3 @@ function computeHalfCellColor(
         isOpaque: true,
     };
 }
-
-/**
- * Creates the ANSI escape code that sets the foreground color of following characters.
- *
- * @private helper of `convertImageDataToAsciiArt`
- */
-function createForegroundColorCode(color: HalfCellColor, colorDepth: AsciiArtColorDepth): string {
-    if (colorDepth === 'TRUE_COLOR') {
-        return `\u001b[38;2;${color.red};${color.green};${color.blue}m`;
-    }
-
-    return `\u001b[38;5;${mapColorToAnsi256(color)}m`;
-}
-
-/**
- * Creates the ANSI escape code that sets the background color of following characters.
- *
- * @private helper of `convertImageDataToAsciiArt`
- */
-function createBackgroundColorCode(color: HalfCellColor, colorDepth: AsciiArtColorDepth): string {
-    if (colorDepth === 'TRUE_COLOR') {
-        return `\u001b[48;2;${color.red};${color.green};${color.blue}m`;
-    }
-
-    return `\u001b[48;5;${mapColorToAnsi256(color)}m`;
-}
-
-/**
- * Maps a 24-bit color onto the closest entry of the 256-color ANSI palette.
- *
- * Uses the 6×6×6 color cube (entries 16-231) and the grayscale ramp (entries 232-255).
- *
- * @private helper of `convertImageDataToAsciiArt`
- */
-function mapColorToAnsi256(color: HalfCellColor): number {
-    const { red, green, blue } = color;
-
-    // Note: Prefer the finer grayscale ramp when the color is (nearly) achromatic
-    const maxChannel = Math.max(red, green, blue);
-    const minChannel = Math.min(red, green, blue);
-    if (maxChannel - minChannel < ANSI_256_ACHROMATIC_CHANNEL_SPREAD) {
-        const gray = Math.round((red + green + blue) / 3);
-        if (gray < 4) {
-            return 16; // <- Note: Pure black lives in the color cube
-        }
-        if (gray > ANSI_256_NEAR_WHITE_GRAY_LEVEL) {
-            return ANSI_256_WHITE_INDEX; // <- Note: Pure white lives in the color cube
-        }
-        return 232 + Math.round(((gray - 8) / ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL) * ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN);
-    }
-
-    const redIndex = Math.round((red / 255) * 5);
-    const greenIndex = Math.round((green / 255) * 5);
-    const blueIndex = Math.round((blue / 255) * 5);
-
-    return 16 + 36 * redIndex + 6 * greenIndex + blueIndex;
-}

package/src/utils/ascii-art/createAnsiColorCode.ts

@@ -0,0 +1,132 @@
+import type { AsciiArtColorDepth } from './convertImageDataToAsciiArt';
+
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
+/**
+ * ANSI escape sequence that resets all colors and attributes.
+ *
+ * @private within the repository
+ */
+export const ANSI_RESET = '\u001b[0m';
+
+/**
+ * Maximum spread between RGB channels for a color to be treated as (nearly) achromatic gray.
+ *
+ * @private within the repository
+ */
+const ANSI_256_ACHROMATIC_CHANNEL_SPREAD = 12;
+
+/**
+ * Gray level above which an achromatic color maps to the pure white color-cube entry.
+ *
+ * @private within the repository
+ */
+const ANSI_256_NEAR_WHITE_GRAY_LEVEL = 246;
+
+/**
+ * Index of pure white inside the 6×6×6 ANSI color cube.
+ *
+ * @private within the repository
+ */
+const ANSI_256_WHITE_INDEX = 231;
+
+/**
+ * Brightness of the lightest entry of the ANSI 256 grayscale ramp.
+ *
+ * @private within the repository
+ */
+const ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL = 238;
+
+/**
+ * Number of grayscale ramp steps above its first entry (ANSI indexes 232-255).
+ *
+ * @private within the repository
+ */
+const ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN = 23;
+
+/**
+ * One opaque 24-bit color which should be written into an ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export type AnsiRgbColor = {
+    /**
+     * Red channel in the range `[0, 255]`.
+     */
+    readonly red: number;
+
+    /**
+     * Green channel in the range `[0, 255]`.
+     */
+    readonly green: number;
+
+    /**
+     * Blue channel in the range `[0, 255]`.
+     */
+    readonly blue: number;
+};
+
+/**
+ * Creates the ANSI escape code that sets the foreground color of following characters.
+ *
+ * @param color Color painted onto the characters.
+ * @param colorDepth Color depth supported by the target terminal.
+ * @returns ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export function createAnsiForegroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string {
+    if (colorDepth === 'TRUE_COLOR') {
+        return `\u001b[38;2;${color.red};${color.green};${color.blue}m`;
+    }
+
+    return `\u001b[38;5;${mapColorToAnsi256(color)}m`;
+}
+
+/**
+ * Creates the ANSI escape code that sets the background color of following characters.
+ *
+ * @param color Color painted behind the characters.
+ * @param colorDepth Color depth supported by the target terminal.
+ * @returns ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export function createAnsiBackgroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string {
+    if (colorDepth === 'TRUE_COLOR') {
+        return `\u001b[48;2;${color.red};${color.green};${color.blue}m`;
+    }
+
+    return `\u001b[48;5;${mapColorToAnsi256(color)}m`;
+}
+
+/**
+ * Maps a 24-bit color onto the closest entry of the 256-color ANSI palette.
+ *
+ * Uses the 6×6×6 color cube (entries 16-231) and the grayscale ramp (entries 232-255).
+ *
+ * @private helper of `createAnsiForegroundColorCode` and `createAnsiBackgroundColorCode`
+ */
+function mapColorToAnsi256(color: AnsiRgbColor): number {
+    const { red, green, blue } = color;
+
+    // Note: Prefer the finer grayscale ramp when the color is (nearly) achromatic
+    const maxChannel = Math.max(red, green, blue);
+    const minChannel = Math.min(red, green, blue);
+    if (maxChannel - minChannel < ANSI_256_ACHROMATIC_CHANNEL_SPREAD) {
+        const gray = Math.round((red + green + blue) / 3);
+        if (gray < 4) {
+            return 16; // <- Note: Pure black lives in the color cube
+        }
+        if (gray > ANSI_256_NEAR_WHITE_GRAY_LEVEL) {
+            return ANSI_256_WHITE_INDEX; // <- Note: Pure white lives in the color cube
+        }
+        return 232 + Math.round(((gray - 8) / ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL) * ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN);
+    }
+
+    const redIndex = Math.round((red / 255) * 5);
+    const greenIndex = Math.round((green / 255) * 5);
+    const blueIndex = Math.round((blue / 255) * 5);
+
+    return 16 + 36 * redIndex + 6 * greenIndex + blueIndex;
+}