@promptbook/utils 0.113.0-3 → 0.113.0-5

package/esm/index.es.js

@@ -17,7 +17,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.113.0-3';
+const PROMPTBOOK_ENGINE_VERSION = '0.113.0-5';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name

package/esm/src/avatars/renderAvatarVisualAsciiArt.d.ts

@@ -0,0 +1,75 @@
+import type { AsciiArtColorDepth } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type { AvatarVisualId } from './types/AvatarVisualDefinition';
+/**
+ * Default output width of the ASCII avatar in terminal character cells.
+ *
+ * @private within the repository
+ */
+export declare const DEFAULT_AVATAR_ASCII_ART_COLUMNS = 32;
+/**
+ * Factory creating a drawable canvas of the requested pixel size.
+ *
+ * In browsers this is typically `document.createElement('canvas')` (with width/height set),
+ * in Node.js an adapter around `createCanvas` of `@napi-rs/canvas` or a compatible library.
+ *
+ * @private within the repository
+ */
+export type CreateCanvasForAsciiArt = (width: number, height: number) => HTMLCanvasElement;
+/**
+ * Options for `renderAvatarVisualAsciiArt`.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualAsciiArtOptions = {
+    /**
+     * Stable visual identity of the rendered agent avatar.
+     */
+    readonly avatarDefinition: AvatarDefinition;
+    /**
+     * Built-in avatar visual to render, the same one used on the website.
+     */
+    readonly visualId: AvatarVisualId;
+    /**
+     * Output width in terminal character cells.
+     *
+     * @default `DEFAULT_AVATAR_ASCII_ART_COLUMNS`
+     */
+    readonly columns?: number;
+    /**
+     * Output height in terminal character cells.
+     *
+     * @default `columns / 2` so the square avatar stays visually square in a common terminal font
+     */
+    readonly rows?: number;
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     *
+     * @default 'TRUE_COLOR'
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+    /**
+     * Animation timestamp for animated visuals.
+     *
+     * @default `STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS`
+     */
+    readonly timeMs?: number;
+    /**
+     * Platform-specific canvas factory used to rasterize the visual.
+     */
+    readonly createCanvas: CreateCanvasForAsciiArt;
+};
+/**
+ * Renders one built-in avatar visual into ANSI-colored ASCII art for terminal display.
+ *
+ * This is the universal bridge between the canvas avatar visuals shown on the website and
+ * text-based terminal UIs: the visual is rasterized through the exact same `renderAvatarVisual`
+ * pipeline the web uses, then the resulting pixels are converted into colored half-block
+ * characters by `convertImageDataToAsciiArt`.
+ *
+ * @param options Avatar identity, visual selection, output grid size, and the platform canvas factory.
+ * @returns One ANSI-colored string per output row.
+ *
+ * @private within the repository
+ */
+export declare function renderAvatarVisualAsciiArt(options: RenderAvatarVisualAsciiArtOptions): ReadonlyArray<string>;

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

@@ -0,0 +1,15 @@
+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 declare function $detectTerminalAnsiColorDepth(): AsciiArtColorDepth;

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

@@ -0,0 +1,80 @@
+/**
+ * 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;
+};
+/**
+ * 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 declare function convertImageDataToAsciiArt(options: ConvertImageDataToAsciiArtOptions): ReadonlyArray<string>;

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.113.0-1`).
+ * It follows semantic versioning (e.g., `0.113.0-4`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/utils",
-    "version": "0.113.0-3",
+    "version": "0.113.0-5",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/umd/index.umd.js

@@ -23,7 +23,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-3';
+    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-5';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name

package/umd/src/avatars/renderAvatarVisualAsciiArt.d.ts

@@ -0,0 +1,75 @@
+import type { AsciiArtColorDepth } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type { AvatarVisualId } from './types/AvatarVisualDefinition';
+/**
+ * Default output width of the ASCII avatar in terminal character cells.
+ *
+ * @private within the repository
+ */
+export declare const DEFAULT_AVATAR_ASCII_ART_COLUMNS = 32;
+/**
+ * Factory creating a drawable canvas of the requested pixel size.
+ *
+ * In browsers this is typically `document.createElement('canvas')` (with width/height set),
+ * in Node.js an adapter around `createCanvas` of `@napi-rs/canvas` or a compatible library.
+ *
+ * @private within the repository
+ */
+export type CreateCanvasForAsciiArt = (width: number, height: number) => HTMLCanvasElement;
+/**
+ * Options for `renderAvatarVisualAsciiArt`.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualAsciiArtOptions = {
+    /**
+     * Stable visual identity of the rendered agent avatar.
+     */
+    readonly avatarDefinition: AvatarDefinition;
+    /**
+     * Built-in avatar visual to render, the same one used on the website.
+     */
+    readonly visualId: AvatarVisualId;
+    /**
+     * Output width in terminal character cells.
+     *
+     * @default `DEFAULT_AVATAR_ASCII_ART_COLUMNS`
+     */
+    readonly columns?: number;
+    /**
+     * Output height in terminal character cells.
+     *
+     * @default `columns / 2` so the square avatar stays visually square in a common terminal font
+     */
+    readonly rows?: number;
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     *
+     * @default 'TRUE_COLOR'
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+    /**
+     * Animation timestamp for animated visuals.
+     *
+     * @default `STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS`
+     */
+    readonly timeMs?: number;
+    /**
+     * Platform-specific canvas factory used to rasterize the visual.
+     */
+    readonly createCanvas: CreateCanvasForAsciiArt;
+};
+/**
+ * Renders one built-in avatar visual into ANSI-colored ASCII art for terminal display.
+ *
+ * This is the universal bridge between the canvas avatar visuals shown on the website and
+ * text-based terminal UIs: the visual is rasterized through the exact same `renderAvatarVisual`
+ * pipeline the web uses, then the resulting pixels are converted into colored half-block
+ * characters by `convertImageDataToAsciiArt`.
+ *
+ * @param options Avatar identity, visual selection, output grid size, and the platform canvas factory.
+ * @returns One ANSI-colored string per output row.
+ *
+ * @private within the repository
+ */
+export declare function renderAvatarVisualAsciiArt(options: RenderAvatarVisualAsciiArtOptions): ReadonlyArray<string>;

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

@@ -0,0 +1,15 @@
+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 declare function $detectTerminalAnsiColorDepth(): AsciiArtColorDepth;

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

@@ -0,0 +1,80 @@
+/**
+ * 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;
+};
+/**
+ * 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 declare function convertImageDataToAsciiArt(options: ConvertImageDataToAsciiArtOptions): ReadonlyArray<string>;

package/umd/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.113.0-1`).
+ * It follows semantic versioning (e.g., `0.113.0-4`).
  *
  * @generated
  */