@promptbook/cli 0.113.0-0 → 0.113.0-10

package/src/remote-server/startRemoteServer/registerExecutionRoutes.ts

@@ -4,8 +4,8 @@ import { serializeError } from '../../errors/utils/serializeError';
 import { createPipelineExecutor } from '../../execution/createPipelineExecutor/00-createPipelineExecutor';
 import type { AbstractTask, ExecutionTask } from '../../execution/ExecutionTask';
 import type { chococake } from '../../utils/organization/really_any';
-import type { RemoteServerRuntime } from './RemoteServerRuntime';
 import { getExecutionToolsFromIdentification } from './getExecutionToolsFromIdentification';
+import type { RemoteServerRuntime } from './RemoteServerRuntime';
 
 /**
  * Registers execution task listing, detail, and creation routes.

package/src/remote-server/startRemoteServer/registerServerIndexRoute.ts

@@ -1,9 +1,9 @@
 import { spaceTrim } from 'spacetrim';
 import { CLAIM } from '../../config';
+import type { chococake } from '../../utils/organization/really_any';
 import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../../version';
 import { renderServerIndexHtml } from '../ui/renderServerIndexHtml';
 import type { ServerInfo } from '../ui/types';
-import type { chococake } from '../../utils/organization/really_any';
 import type { RemoteServerRuntime } from './RemoteServerRuntime';
 
 /**

package/src/scrapers/_common/utils/makeKnowledgeSourceHandler.ts

@@ -4,12 +4,7 @@ import { dirname, isAbsolute, join } from 'path';
 import { spaceTrim } from 'spacetrim';
 import type { SetOptional } from 'type-fest';
 import { knowledgeSourceContentToName } from '../../../commands/KNOWLEDGE/utils/knowledgeSourceContentToName';
-import {
-    DEFAULT_DOWNLOAD_CACHE_DIRNAME,
-    DEFAULT_IS_VERBOSE,
-    DEFAULT_MAX_FILE_SIZE,
-    MAX_FILENAME_LENGTH,
-} from '../../../config';
+import { DEFAULT_DOWNLOAD_CACHE_DIRNAME, DEFAULT_IS_VERBOSE, DEFAULT_MAX_FILE_SIZE, MAX_FILENAME_LENGTH } from '../../../config';
 import { EnvironmentMismatchError } from '../../../errors/EnvironmentMismatchError';
 import { LimitReachedError } from '../../../errors/LimitReachedError';
 import { NotFoundError } from '../../../errors/NotFoundError';

package/src/speech-recognition/OpenAiSpeechRecognition.ts

@@ -1,9 +1,4 @@
-import type {
-    SpeechRecognition,
-    SpeechRecognitionEvent,
-    SpeechRecognitionStartOptions,
-    SpeechRecognitionState,
-} from '../types/SpeechRecognition';
+import type { SpeechRecognition, SpeechRecognitionEvent, SpeechRecognitionStartOptions, SpeechRecognitionState } from '../types/SpeechRecognition';
 
 /**
  * Options for OpenAiSpeechRecognition

package/src/transpilers/_common/prepareSdkTranspilerContext.ts

@@ -6,10 +6,7 @@ import type { string_book } from '../../book-2.0/agent-source/string_book';
 import { getAllCommitmentDefinitions } from '../../commitments/_common/getAllCommitmentDefinitions';
 import type { LlmToolDefinition } from '../../types/LlmToolDefinition';
 import type { BookTranspilerOptions } from './BookTranspilerOptions';
-import {
-    createTranspiledTeamAwareToolFunctions,
-    createTranspiledTeamExportForContext,
-} from './createTranspiledTeamRuntimeSection';
+import { createTranspiledTeamAwareToolFunctions, createTranspiledTeamExportForContext } from './createTranspiledTeamRuntimeSection';
 import type { TranspiledTeamExport } from './TranspiledTeamExport';
 
 /**

package/src/types/Prompt.ts

@@ -2,13 +2,7 @@ import type { ChatMessage } from '../book-components/Chat/types/ChatMessage';
 import type { FormatCommand } from '../commands/FORMAT/FormatCommand';
 import type { Expectations } from '../pipeline/PipelineJson/Expectations';
 import type { LlmToolDefinition } from './LlmToolDefinition';
-import type {
-    ChatModelRequirements,
-    CompletionModelRequirements,
-    EmbeddingModelRequirements,
-    ImageGenerationModelRequirements,
-    ModelRequirements,
-} from './ModelRequirements';
+import type { ChatModelRequirements, CompletionModelRequirements, EmbeddingModelRequirements, ImageGenerationModelRequirements, ModelRequirements } from './ModelRequirements';
 import type { Parameters } from './Parameters';
 import type { string_postprocessing_function_name } from './string_person_fullname';
 import type { string_pipeline_url_with_task_hash } from './string_pipeline_url';

package/src/types/string_host.ts

@@ -1,12 +1,4 @@
-import type {
-    string_domain_private,
-    string_hostname_private,
-    string_host_private,
-    string_ip_address_private,
-    string_origin_private,
-    string_protocol_private,
-    string_tdl_private,
-} from './string_host_private';
+import type { string_domain_private, string_hostname_private, string_host_private, string_ip_address_private, string_origin_private, string_protocol_private, string_tdl_private } from './string_host_private';
 
 /**
  * Semantic helper

package/src/types/string_pipeline_url.ts

@@ -1,7 +1,4 @@
-import type {
-    string_pipeline_url_private,
-    string_pipeline_url_with_task_hash_private,
-} from './string_pipeline_url_private';
+import type { string_pipeline_url_private, string_pipeline_url_with_task_hash_private } from './string_pipeline_url_private';
 
 /**
  * Semantic helper

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

@@ -0,0 +1,66 @@
+import { basename } from 'path';
+import { resolvePromptbookTemporaryPath } from '../filesystem/promptbookTemporaryPath';
+
+/**
+ * Temporary subdirectory used for agent-message runner shell scripts.
+ *
+ * @private internal constant of agent-message runtime paths
+ */
+export const AGENT_MESSAGE_SCRIPT_DIRECTORY_NAME = 'agent-messages';
+
+/**
+ * File extension used for temporary prompt-runner shell scripts.
+ *
+ * @private internal constant of agent-message runtime paths
+ */
+const AGENT_MESSAGE_SCRIPT_EXTENSION = '.sh';
+
+/**
+ * File extension used for temporary prompt-runner live logs.
+ *
+ * @private internal constant of agent-message runtime paths
+ */
+const AGENT_MESSAGE_RUNTIME_LOG_EXTENSION = '.log.txt';
+
+/**
+ * Builds the temporary shell script path used by one queued agent-message harness run.
+ *
+ * @param projectPath - Local agent project path containing the message queue.
+ * @param sourceFileName - Queued message filename used to name the temporary shell script.
+ * @returns Temporary shell script path.
+ * @private internal utility of agent-message runners
+ */
+export function buildAgentMessageScriptPathFromFileName(projectPath: string, sourceFileName: string): string {
+    const sourceFileBasename = basename(sourceFileName);
+    const scriptFileName = `${sourceFileBasename.replace(/\.[^.]+$/u, '')}${AGENT_MESSAGE_SCRIPT_EXTENSION}`;
+
+    return resolvePromptbookTemporaryPath(projectPath, AGENT_MESSAGE_SCRIPT_DIRECTORY_NAME, scriptFileName);
+}
+
+/**
+ * Builds the live runtime log path used by one queued agent-message harness run.
+ *
+ * @param projectPath - Local agent project path containing the message queue.
+ * @param sourceFileName - Queued message filename used to name the temporary shell script.
+ * @returns Temporary live runtime log path.
+ * @private internal utility of agent-message runners
+ */
+export function buildAgentMessageRuntimeLogPathFromFileName(projectPath: string, sourceFileName: string): string {
+    return buildAgentMessageScriptPathFromFileName(projectPath, sourceFileName).replace(
+        new RegExp(`${escapeRegExp(AGENT_MESSAGE_SCRIPT_EXTENSION)}$`, 'iu'),
+        AGENT_MESSAGE_RUNTIME_LOG_EXTENSION,
+    );
+}
+
+/**
+ * Escapes one literal string for safe `RegExp` construction.
+ *
+ * @param value - Literal string to escape.
+ * @returns Escaped regular-expression fragment.
+ * @private internal utility of agent-message runtime paths
+ */
+function escapeRegExp(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/utils/agents/resolveAgentAvatarImageUrl.ts

@@ -47,7 +47,7 @@ export type ResolveAgentAvatarOptions = {
 export type ResolveAgentAvatarImageUrlOptions = ResolveAgentAvatarOptions;
 
 /**
- * Default built-in avatar visual used when an agent does not define `META IMAGE`.
+ * Default built-in avatar visual used when an agent does not define `META IMAGE`, `META AVATAR`, or `META VISUAL`.
  *
  * @private shared avatar contract
  */
@@ -195,7 +195,7 @@ export function resolveAgentAvatarFallbackUrl(options: ResolveAgentAvatarOptions
 
 /**
  * Resolve the best avatar representation for an agent, preferring explicit `META IMAGE`
- * and otherwise returning the default deterministic canvas visual.
+ * and otherwise returning the selected deterministic canvas visual.
  *
  * @private utility of `<Chat/>`
  */

package/src/utils/ascii-art/$detectTerminalAnsiColorDepth.ts

@@ -0,0 +1,45 @@
+import type { AsciiArtColorDepth } from './convertImageDataToAsciiArt';
+
+/**
+ * Detects the ANSI color depth supported by the current terminal.
+ *
+ * Prefers 24-bit true color when the environment advertises it (modern terminals such as
+ * Windows Terminal, ConEmu, VS Code, mintty, iTerm2, and WezTerm) and falls back to the
+ * portable 256-color palette otherwise.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the process environment
+ *
+ * @returns Color depth usable by `convertImageDataToAsciiArt`
+ *
+ * @private within the repository
+ */
+export function $detectTerminalAnsiColorDepth(): AsciiArtColorDepth {
+    if (typeof process === 'undefined' || !process.env) {
+        return 'ANSI_256';
+    }
+
+    const colorTerm = (process.env.COLORTERM || '').toLowerCase();
+    if (colorTerm.includes('truecolor') || colorTerm.includes('24bit')) {
+        return 'TRUE_COLOR';
+    }
+
+    if (process.env.WT_SESSION !== undefined) {
+        return 'TRUE_COLOR'; // <- Note: Windows Terminal always supports true color but does not set COLORTERM
+    }
+
+    if (process.env.ConEmuANSI === 'ON') {
+        return 'TRUE_COLOR';
+    }
+
+    const termProgram = process.env.TERM_PROGRAM || '';
+    if (['vscode', 'iTerm.app', 'WezTerm', 'ghostty', 'Hyper'].includes(termProgram)) {
+        return 'TRUE_COLOR';
+    }
+
+    const term = (process.env.TERM || '').toLowerCase();
+    if (term.includes('truecolor') || term.includes('24bit') || term.includes('direct')) {
+        return 'TRUE_COLOR';
+    }
+
+    return 'ANSI_256';
+}

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

@@ -0,0 +1,396 @@
+import { spaceTrim } from 'spacetrim';
+import { UnexpectedError } from '../../errors/UnexpectedError';
+
+/**
+ * Color depth of the ANSI escape codes emitted by the ASCII-art conversion.
+ *
+ * - `TRUE_COLOR` emits 24-bit `38;2;r;g;b` / `48;2;r;g;b` sequences
+ * - `ANSI_256` approximates colors on the 256-color ANSI cube for older terminals
+ *
+ * @private within the repository
+ */
+export type AsciiArtColorDepth = 'TRUE_COLOR' | 'ANSI_256';
+
+/**
+ * Minimal structural subset of the DOM `ImageData` accepted by the ASCII-art conversion.
+ *
+ * Works with browser canvas `ImageData`, `@napi-rs/canvas` image data, or any raw RGBA buffer.
+ *
+ * @private within the repository
+ */
+export type AsciiArtImageData = {
+    /**
+     * Source image width in pixels.
+     */
+    readonly width: number;
+
+    /**
+     * Source image height in pixels.
+     */
+    readonly height: number;
+
+    /**
+     * Flat RGBA pixel buffer with 4 bytes per pixel.
+     */
+    readonly data: ArrayLike<number>;
+};
+
+/**
+ * Options for `convertImageDataToAsciiArt`.
+ *
+ * @private within the repository
+ */
+export type ConvertImageDataToAsciiArtOptions = {
+    /**
+     * Source pixels to convert.
+     */
+    readonly imageData: AsciiArtImageData;
+
+    /**
+     * Output width in terminal character cells.
+     */
+    readonly columns: number;
+
+    /**
+     * Output height in terminal character cells.
+     *
+     * Each character cell renders two vertically stacked pixels, so `rows = columns / 2`
+     * keeps a square image visually square in a common terminal font.
+     */
+    readonly rows: number;
+
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     *
+     * @default 'TRUE_COLOR'
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+
+    /**
+     * Alpha channel value (0-255) below which an averaged half-cell is treated as fully transparent.
+     *
+     * @default 32
+     */
+    readonly alphaThreshold?: number;
+};
+
+/**
+ * Default alpha channel value below which a half-cell is rendered as terminal background.
+ *
+ * @private within the repository
+ */
+const DEFAULT_ALPHA_THRESHOLD = 32;
+
+/**
+ * Number of channels per pixel in an RGBA buffer.
+ *
+ * @private within the repository
+ */
+const RGBA_CHANNEL_COUNT = 4;
+
+/**
+ * Upper half block character - foreground paints the top pixel, background paints the bottom pixel.
+ *
+ * @private within the repository
+ */
+const UPPER_HALF_BLOCK = '▀'; // <- ▀
+
+/**
+ * Lower half block character - foreground paints the bottom pixel while the top pixel stays transparent.
+ *
+ * @private within the repository
+ */
+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;
+    readonly isOpaque: boolean;
+};
+
+/**
+ * Converts raw RGBA image pixels into colored ASCII art for ANSI terminals.
+ *
+ * This is the universal image-to-terminal technique used across the repository:
+ * every output character cell covers a rectangular region of source pixels which is
+ * split into a top and bottom half; each half is area-averaged and rendered with
+ * half-block characters (`▀` / `▄`) so one character shows two "pixels" vertically.
+ * Transparent halves keep the terminal background so non-rectangular images
+ * (for example rounded avatar cards) compose naturally into any terminal UI.
+ *
+ * @param options Source pixels, output grid size, and ANSI color depth.
+ * @returns One ANSI-colored string per output row, each ending with a color reset.
+ *
+ * @private within the repository
+ */
+export function convertImageDataToAsciiArt(options: ConvertImageDataToAsciiArtOptions): ReadonlyArray<string> {
+    const { imageData, columns, rows, colorDepth = 'TRUE_COLOR', alphaThreshold = DEFAULT_ALPHA_THRESHOLD } = options;
+
+    if (!Number.isInteger(columns) || columns <= 0 || !Number.isInteger(rows) || rows <= 0) {
+        throw new UnexpectedError(
+            spaceTrim(`
+                ASCII-art grid size is invalid.
+
+                Both \`columns\` and \`rows\` must be positive integers but \`${columns}\` × \`${rows}\` was requested.
+            `),
+        );
+    }
+
+    if (
+        imageData.width <= 0 ||
+        imageData.height <= 0 ||
+        imageData.data.length < imageData.width * imageData.height * RGBA_CHANNEL_COUNT
+    ) {
+        throw new UnexpectedError(
+            spaceTrim(`
+                ASCII-art source image data is invalid.
+
+                Expected a RGBA buffer of at least \`${imageData.width} × ${imageData.height} × ${RGBA_CHANNEL_COUNT}\` bytes
+                but got \`${imageData.data.length}\` bytes.
+            `),
+        );
+    }
+
+    const halfCellRowCount = rows * 2;
+    const asciiArtLines: Array<string> = [];
+
+    for (let rowIndex = 0; rowIndex < rows; rowIndex++) {
+        let line = '';
+        let currentForegroundCode: string | undefined = undefined;
+        let currentBackgroundCode: string | undefined = undefined;
+
+        for (let columnIndex = 0; columnIndex < columns; columnIndex++) {
+            const topHalfColor = computeHalfCellColor(
+                imageData,
+                columnIndex,
+                rowIndex * 2,
+                columns,
+                halfCellRowCount,
+                alphaThreshold,
+            );
+            const bottomHalfColor = computeHalfCellColor(
+                imageData,
+                columnIndex,
+                rowIndex * 2 + 1,
+                columns,
+                halfCellRowCount,
+                alphaThreshold,
+            );
+
+            let character: string;
+            let nextForegroundCode: string | undefined;
+            let nextBackgroundCode: string | undefined;
+
+            if (topHalfColor.isOpaque && bottomHalfColor.isOpaque) {
+                character = UPPER_HALF_BLOCK;
+                nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
+                nextBackgroundCode = createBackgroundColorCode(bottomHalfColor, colorDepth);
+            } else if (topHalfColor.isOpaque) {
+                character = UPPER_HALF_BLOCK;
+                nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
+                nextBackgroundCode = undefined;
+            } else if (bottomHalfColor.isOpaque) {
+                character = LOWER_HALF_BLOCK;
+                nextForegroundCode = createForegroundColorCode(bottomHalfColor, colorDepth);
+                nextBackgroundCode = undefined;
+            } else {
+                character = ' ';
+                nextForegroundCode = undefined;
+                nextBackgroundCode = undefined;
+            }
+
+            if (nextForegroundCode !== currentForegroundCode || nextBackgroundCode !== currentBackgroundCode) {
+                // Note: A reset is required whenever a previously set color must be cleared,
+                //       otherwise stale background color would bleed into transparent cells.
+                const isResetNeeded =
+                    (currentForegroundCode !== undefined && nextForegroundCode === undefined) ||
+                    (currentBackgroundCode !== undefined && nextBackgroundCode === undefined);
+
+                if (isResetNeeded) {
+                    line += ANSI_RESET;
+                    currentForegroundCode = undefined;
+                    currentBackgroundCode = undefined;
+                }
+
+                if (nextForegroundCode !== undefined && nextForegroundCode !== currentForegroundCode) {
+                    line += nextForegroundCode;
+                }
+
+                if (nextBackgroundCode !== undefined && nextBackgroundCode !== currentBackgroundCode) {
+                    line += nextBackgroundCode;
+                }
+
+                currentForegroundCode = nextForegroundCode;
+                currentBackgroundCode = nextBackgroundCode;
+            }
+
+            line += character;
+        }
+
+        if (currentForegroundCode !== undefined || currentBackgroundCode !== undefined) {
+            line += ANSI_RESET;
+        }
+
+        asciiArtLines.push(line);
+    }
+
+    return asciiArtLines;
+}
+
+/**
+ * Computes the area-averaged color of one half-cell of the output grid.
+ *
+ * Color channels are alpha-weighted so semi-transparent edge pixels do not darken towards black.
+ *
+ * @private helper of `convertImageDataToAsciiArt`
+ */
+function computeHalfCellColor(
+    imageData: AsciiArtImageData,
+    columnIndex: number,
+    halfCellRowIndex: number,
+    columns: number,
+    halfCellRowCount: number,
+    alphaThreshold: number,
+): HalfCellColor {
+    const startX = Math.floor((columnIndex * imageData.width) / columns);
+    const endX = Math.max(startX + 1, Math.floor(((columnIndex + 1) * imageData.width) / columns));
+    const startY = Math.floor((halfCellRowIndex * imageData.height) / halfCellRowCount);
+    const endY = Math.max(startY + 1, Math.floor(((halfCellRowIndex + 1) * imageData.height) / halfCellRowCount));
+
+    let redSum = 0;
+    let greenSum = 0;
+    let blueSum = 0;
+    let alphaSum = 0;
+    let sampledPixelCount = 0;
+
+    for (let y = startY; y < endY && y < imageData.height; y++) {
+        for (let x = startX; x < endX && x < imageData.width; x++) {
+            const pixelOffset = (y * imageData.width + x) * RGBA_CHANNEL_COUNT;
+            const alpha = imageData.data[pixelOffset + 3]!;
+
+            redSum += imageData.data[pixelOffset]! * alpha;
+            greenSum += imageData.data[pixelOffset + 1]! * alpha;
+            blueSum += imageData.data[pixelOffset + 2]! * alpha;
+            alphaSum += alpha;
+            sampledPixelCount++;
+        }
+    }
+
+    const averageAlpha = sampledPixelCount === 0 ? 0 : alphaSum / sampledPixelCount;
+
+    if (averageAlpha < alphaThreshold || alphaSum === 0) {
+        return { red: 0, green: 0, blue: 0, isOpaque: false };
+    }
+
+    return {
+        red: Math.round(redSum / alphaSum),
+        green: Math.round(greenSum / alphaSum),
+        blue: Math.round(blueSum / alphaSum),
+        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/color/Color.ts

@@ -4,14 +4,14 @@ import { spaceTrim } from '../organization/spaceTrim';
 import { TODO_USE } from '../organization/TODO_USE';
 import type { WithTake } from '../take/interfaces/ITakeChain';
 import { take } from '../take/take';
-import { CSS_COLORS } from './css-colors';
 import { ColorValue } from './ColorValue';
+import { CSS_COLORS } from './css-colors';
 import { isHexColorString } from './isHexColorString';
+import { parseColorString } from './parseColorString';
 import type { ColorChannelSet } from './parsers/ColorChannelSet';
 import { parseHexColor } from './parsers/parseHexColor';
 import { parseHslColor } from './parsers/parseHslColor';
 import { parseRgbaColor, parseRgbColor } from './parsers/parseRgbColor';
-import { parseColorString } from './parseColorString';
 
 /**
  * Color object represents an RGB color with alpha channel

package/src/utils/markdown/parseMarkdownSection.ts

@@ -1,10 +1,6 @@
 import { spaceTrim } from 'spacetrim';
 import { ParseError } from '../../errors/ParseError';
-import type {
-    string_markdown_section,
-    string_markdown_section_content,
-    string_markdown_text,
-} from '../../types/string_markdown';
+import type { string_markdown_section, string_markdown_section_content, string_markdown_text } from '../../types/string_markdown';
 
 /**
  * Parsed markdown section

package/src/utils/random/$randomFullnameWithColor.ts

@@ -1,9 +1,4 @@
-import type {
-    string_color,
-    string_person_firstname,
-    string_person_fullname,
-    string_person_lastname,
-} from '../../types/string_person_fullname';
+import type { string_color, string_person_firstname, string_person_fullname, string_person_lastname } from '../../types/string_person_fullname';
 import { $randomItem } from './$randomItem';
 
 /**