@promptbook/cli 0.114.0-3 → 0.114.0-30

package/esm/src/utils/agent-message-runtime/parseAgentMessageRuntimeLogEvents.d.ts

@@ -0,0 +1,62 @@
+/**
+ * One string-keyed payload of a coding-harness tool invocation.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+type RuntimeLogToolInput = Record<string, unknown>;
+/**
+ * One content block of a Claude Code `stream-json` assistant event.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+export type AgentMessageRuntimeLogContentBlock = {
+    readonly type?: string;
+    readonly text?: string;
+    readonly name?: string;
+    readonly input?: RuntimeLogToolInput;
+};
+/**
+ * One file path touched by a Codex `file_change` item.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+export type AgentMessageRuntimeLogFileChange = {
+    readonly path?: string;
+};
+/**
+ * Minimal shape of one coding-harness runtime log event.
+ *
+ * The runtime log mixes two harness formats — Claude Code `stream-json` (`type`/`message`) and
+ * Codex JSONL (`type`/`item`) — so both are described by one permissive structure and every
+ * consumer reads only the fields it understands.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+export type AgentMessageRuntimeLogEvent = {
+    readonly type?: string;
+    readonly message?: {
+        readonly content?: ReadonlyArray<AgentMessageRuntimeLogContentBlock>;
+    };
+    readonly item?: {
+        readonly type?: string;
+        readonly command?: string;
+        readonly exit_code?: number | null;
+        readonly changes?: ReadonlyArray<AgentMessageRuntimeLogFileChange>;
+        readonly server?: string;
+        readonly tool?: string;
+        readonly query?: string;
+    };
+};
+/**
+ * Parses every structured event out of one coding-harness runtime log.
+ *
+ * The local agent runner streams the answering harness output into a live runtime log file, one
+ * JSON event per line, optionally prefixed by shell noise. Lines without a usable JSON object are
+ * skipped so a partially written or interleaved log never breaks its consumers.
+ *
+ * @param logText - Raw runtime log content.
+ * @returns Structured events in the order they were streamed.
+ * @private internal utility of the agent-message runtime
+ */
+export declare function parseAgentMessageRuntimeLogEvents(logText: string | null | undefined): ReadonlyArray<AgentMessageRuntimeLogEvent>;
+export {};

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

@@ -5,9 +5,9 @@
  * 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.

package/esm/src/utils/agent-message-runtime/resolveAgentMessageTouchedExternalSources.d.ts

@@ -0,0 +1,18 @@
+import type { AgentMessageTouchedExternalSource } from './AgentMessageTouchedExternalSource';
+/**
+ * Resolves which sources outside the agent one coding harness touched while answering a single message.
+ *
+ * The runtime log streams what the harness really did, so a source counts as touched when the
+ * harness reached it in a tool invocation — calling an integration, fetching a web address,
+ * searching the web, or running a network client in the shell. Only tool payloads are inspected:
+ * tool results and assistant narration are ignored so a service merely mentioned in the
+ * conversation is never reported, and addresses of the machine the agent runs on are dropped
+ * because they are internal.
+ *
+ * @param options - Raw runtime log content of one answered message.
+ * @returns Touched external sources without duplicates, ordered by first appearance.
+ * @private internal utility of the agent-message runtime
+ */
+export declare function resolveAgentMessageTouchedExternalSources(options: {
+    readonly logText: string | null | undefined;
+}): ReadonlyArray<AgentMessageTouchedExternalSource>;

package/esm/src/utils/agent-message-runtime/resolveAgentMessageTouchedProjectNames.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolves which projects one coding harness touched while answering a single message.
+ *
+ * The runtime log streams what the harness really did, so a project counts as touched when the
+ * harness named it in a tool invocation — reading, searching, running, or editing files inside
+ * `projects/<project-name>/`. Only tool payloads are inspected: tool results and assistant
+ * narration are ignored so a project merely mentioned in the conversation is never reported.
+ *
+ * Every candidate is matched against the projects that really exist, which both filters prompt
+ * placeholders such as `projects/<project-name>/` and keeps the reported names canonical.
+ *
+ * @param options - Raw runtime log content and the project directory names of the agent.
+ * @returns Touched project names in the canonical spelling, ordered by first appearance.
+ * @private internal utility of the agent-message runtime
+ */
+export declare function resolveAgentMessageTouchedProjectNames(options: {
+    readonly logText: string | null | undefined;
+    readonly knownProjectNames: ReadonlyArray<string>;
+}): ReadonlyArray<string>;

package/esm/src/utils/agents/terminalAgentAvatarVisual.d.ts

@@ -75,9 +75,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;
 };
 /**
  * Resolves the built-in avatar visual selected for terminal rendering of one agent source.

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

@@ -62,6 +62,12 @@ export type ConvertImageDataToAsciiArtOptions = {
      */
     readonly alphaThreshold?: number;
 };
+/**
+ * Default alpha channel value below which a cell is rendered as terminal background.
+ *
+ * @private within the repository
+ */
+export declare const DEFAULT_ALPHA_THRESHOLD = 32;
 /**
  * Converts raw RGBA image pixels into colored ASCII art for ANSI terminals.
  *

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

@@ -0,0 +1,46 @@
+import type { AsciiArtColorDepth } from './convertImageDataToAsciiArt';
+/**
+ * ANSI escape sequence that resets all colors and attributes.
+ *
+ * @private within the repository
+ */
+export declare const ANSI_RESET = "\u001B[0m";
+/**
+ * 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 declare function createAnsiForegroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string;
+/**
+ * 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 declare function createAnsiBackgroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string;

package/esm/src/utils/misc/debounce.d.ts

@@ -1,7 +1,9 @@
 import type { TODO_any } from '../organization/TODO_any';
 /**
- * Handles debounce.
+ * Creates a debounced function that runs after calls have been quiet for the given delay.
  *
  * @public exported from `@promptbook/utils`
  */
-export declare function debounce<T extends (...args: TODO_any[]) => void>(fn: T, delay: number): (...args: Parameters<T>) => void;
+export declare function debounce<T extends (...args: TODO_any[]) => void>(fn: T, delay: number): ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};

package/esm/src/utils/misc/emojis.d.ts

@@ -10,9 +10,10 @@ import type { string_char_emoji } from '../../types/typeAliasEmoji';
  */
 export declare const EMOJIS_IN_CATEGORIES: Record<string, ReadonlyArray<string_char_emoji>>;
 /**
- * All possible emoji chars like "🍆", "🍡", "🍤"...
+ * Curated repository catalogue of emoji and legacy pictographic symbols.
  *
- * @deprecated Use /\p{Extended_Pictographic}/ instead
+ * Code that needs to generate a valid Unicode emoji should apply its own validation
+ * to this catalogue rather than assume every entry is an emoji.
  *
  * @private within the repository
  */

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.114.0-2`).
+ * It follows semantic versioning (e.g., `0.114.0-29`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.114.0-3",
+    "version": "0.114.0-30",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,
@@ -162,7 +162,7 @@
         "@xmldom/xmldom": "^0.9.10",
         "@xterm/addon-fit": "0.11.0",
         "@xterm/xterm": "6.0.0",
-        "better-sqlite3": "^11.10.0",
+        "better-sqlite3": "^12.11.1",
         "configchecker": "1.5.132",
         "cross-fetch": "4.0.0",
         "destroyable": "0.12.145",

package/src/_packages/components.index.ts

@@ -75,8 +75,10 @@ import type { CitationLabelResolver } from '../book-components/Chat/types/Citati
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import { parseMessageButtons } from '../book-components/Chat/utils/parseMessageButtons';
 import type { MarkdownInlineReference } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceIcon } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuStatus } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuOption } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuAction } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenu } from '../book-components/Chat/utils/renderMarkdown';
 import { ArrowIcon } from '../book-components/icons/ArrowIcon';
 import { MicIcon } from '../book-components/icons/MicIcon';
@@ -170,8 +172,10 @@ export type { CitationLabelResolver };
 export type { MessageButton };
 export { parseMessageButtons };
 export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceIcon };
 export type { MarkdownInlineReferenceMenuStatus };
 export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenuAction };
 export type { MarkdownInlineReferenceMenu };
 export { ArrowIcon };
 export { MicIcon };

package/src/_packages/components.readme.md

@@ -80,7 +80,7 @@ interface BookEditorProps {
     onChange?: (value: string) => void;
 
     // Explicit list of commitment keywords to highlight (case-insensitive).
-    // If omitted, a default set (PERSONA, KNOWLEDGE, MEMORY, STYLE, RULE, RULES, WRITING SAMPLE, WRITING RULES, SAMPLE, EXAMPLE, FORMAT, MODEL, ACTION, META IMAGE, META LINK, NOTE, GOAL, MESSAGE, SCENARIO, DELETE, CANCEL, DISCARD, REMOVE, EXPECT, SCENARIOS, BEHAVIOUR, BEHAVIOURS, AVOID, AVOIDANCE, GOALS, CONTEXT) is used.
+    // If omitted, a default set (PERSONA, KNOWLEDGE, STYLE, RULE, RULES, WRITING SAMPLE, WRITING RULES, SAMPLE, EXAMPLE, FORMAT, MODEL, ACTION, META IMAGE, META LINK, NOTE, GOAL, MESSAGE, SCENARIO, DELETE, CANCEL, DISCARD, REMOVE, EXPECT, SCENARIOS, BEHAVIOUR, BEHAVIOURS, AVOID, AVOIDANCE, GOALS, CONTEXT) is used.
     commitmentTypes?: string[];
 }
 ```

package/src/_packages/types.index.ts

@@ -65,8 +65,10 @@ import type { CitationLabelResolver } from '../book-components/Chat/types/Citati
 import type { ParsedCitation } from '../book-components/Chat/utils/parseCitationsFromContent';
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import type { MarkdownInlineReference } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceIcon } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuStatus } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuOption } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuAction } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenu } from '../book-components/Chat/utils/renderMarkdown';
 import type { TeamToolResult } from '../book-components/Chat/utils/toolCallParsing/TeamToolResult';
 import type { QrCodeOptions } from '../book-components/Qr/useQrCode';
@@ -516,8 +518,10 @@ export type { CitationLabelResolver };
 export type { ParsedCitation };
 export type { MessageButton };
 export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceIcon };
 export type { MarkdownInlineReferenceMenuStatus };
 export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenuAction };
 export type { MarkdownInlineReferenceMenu };
 export type { TeamToolResult };
 export type { QrCodeOptions };

package/src/avatars/renderAvatarVisualTerminalText.ts

@@ -0,0 +1,249 @@
+import type { string_color } from '../types/string_person_fullname';
+import type { AsciiArtColorDepth } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import { DEFAULT_ALPHA_THRESHOLD } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import type { AnsiRgbColor } from '../utils/ascii-art/createAnsiColorCode';
+import { ANSI_RESET, createAnsiForegroundColorCode } from '../utils/ascii-art/createAnsiColorCode';
+import { Color } from '../utils/color/Color';
+import { createIdleAvatarInteractionState } from './avatarInteractionUtils';
+import type { ResolvedAvatarRenderDefinition } from './renderAvatarVisual';
+import { resolveAvatarRenderDefinition } from './renderAvatarVisual';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type {
+    AvatarSurfaceStyle,
+    AvatarVisualId,
+    AvatarVisualTerminalTextCell,
+    AvatarVisualTerminalTextGrid,
+} from './types/AvatarVisualDefinition';
+
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
+/**
+ * Height of one terminal character cell relative to its width.
+ *
+ * Terminal fonts are roughly twice as tall as they are wide, so a square avatar needs
+ * twice as many columns as rows to keep its proportions.
+ *
+ * @private within the repository
+ */
+const TERMINAL_CHARACTER_CELL_ASPECT_RATIO = 2;
+
+/**
+ * Options shared by the terminal-text avatar renderers.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextOptions = {
+    /**
+     * 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;
+
+    /**
+     * Surface used to derive the avatar palette.
+     *
+     * @default 'framed'
+     */
+    readonly surface?: AvatarSurfaceStyle;
+
+    /**
+     * Output width in terminal character cells.
+     */
+    readonly columns: number;
+
+    /**
+     * Output height in terminal character cells.
+     */
+    readonly rows: number;
+
+    /**
+     * Animation timestamp for animated visuals.
+     */
+    readonly timeMs: number;
+
+    /**
+     * Optional stable render data reused across frames.
+     */
+    readonly resolvedAvatarRenderDefinition?: ResolvedAvatarRenderDefinition;
+};
+
+/**
+ * Options for `renderAvatarVisualTerminalTextLines`.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextLinesOptions = RenderAvatarVisualTerminalTextOptions & {
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     *
+     * @default 'TRUE_COLOR'
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+};
+
+/**
+ * Renders one frame of a character-based avatar visual straight into terminal character cells.
+ *
+ * Visuals which are themselves made of characters, for example `AsciiOctopus`, lose their identity
+ * when they are rasterized onto a canvas and converted back into half-block ASCII art - every glyph
+ * is averaged away into a colored blob. Such visuals expose `renderTerminalText`, which paints the
+ * terminal grid directly and is used instead of the raster pipeline.
+ *
+ * The square avatar is centered inside the requested grid the same way `renderAvatarVisualAsciiArt`
+ * centers the avatar canvas inside a wider terminal frame.
+ *
+ * @param options Avatar identity, visual selection, and output grid size.
+ * @returns Grid of `rows` rows of `columns` cells, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export function renderAvatarVisualTerminalTextGrid(
+    options: RenderAvatarVisualTerminalTextOptions,
+): AvatarVisualTerminalTextGrid | null {
+    const resolvedRenderDefinition =
+        options.resolvedAvatarRenderDefinition ||
+        resolveAvatarRenderDefinition({
+            avatarDefinition: options.avatarDefinition,
+            visualId: options.visualId,
+            surface: options.surface,
+        });
+    const { renderTerminalText } = resolvedRenderDefinition.avatarVisual;
+
+    if (renderTerminalText === undefined) {
+        return null;
+    }
+
+    const avatarColumnCount = Math.min(options.columns, options.rows * TERMINAL_CHARACTER_CELL_ASPECT_RATIO);
+    const avatarRowCount = Math.min(options.rows, Math.round(options.columns / TERMINAL_CHARACTER_CELL_ASPECT_RATIO));
+
+    if (avatarColumnCount <= 0 || avatarRowCount <= 0) {
+        return null;
+    }
+
+    const avatarGrid = renderTerminalText({
+        columns: avatarColumnCount,
+        rows: avatarRowCount,
+        timeMs: options.timeMs,
+        avatarDefinition: resolvedRenderDefinition.avatarDefinition,
+        palette: resolvedRenderDefinition.palette,
+        createRandom: resolvedRenderDefinition.createRandom,
+        interaction: createIdleAvatarInteractionState(),
+    });
+
+    return centerAvatarVisualTerminalTextGrid(avatarGrid, options.columns, options.rows);
+}
+
+/**
+ * Renders one frame of a character-based avatar visual into ANSI-colored terminal lines.
+ *
+ * @param options Avatar identity, visual selection, output grid size, and ANSI color depth.
+ * @returns One ANSI-colored string per output row, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export function renderAvatarVisualTerminalTextLines(
+    options: RenderAvatarVisualTerminalTextLinesOptions,
+): ReadonlyArray<string> | null {
+    const terminalTextGrid = renderAvatarVisualTerminalTextGrid(options);
+
+    if (terminalTextGrid === null) {
+        return null;
+    }
+
+    return terminalTextGrid.map((terminalTextRow) =>
+        buildAvatarVisualTerminalTextLine(terminalTextRow, options.colorDepth || 'TRUE_COLOR'),
+    );
+}
+
+/**
+ * Converts one avatar cell color into the opaque terminal color it is painted with.
+ *
+ * Terminal cells cannot be blended, so the cell alpha is composited onto the dark terminal
+ * background and fully transparent cells keep the terminal background instead.
+ *
+ * @param color Cell color as a CSS color string, optionally with an alpha channel.
+ * @returns Opaque terminal color or `null` when the cell should stay empty.
+ *
+ * @private helper of `renderAvatarVisualTerminalTextLines`
+ */
+function resolveAvatarVisualTerminalTextColor(color: string_color): AnsiRgbColor | null {
+    const parsedColor = Color.fromSafe(color);
+
+    if (parsedColor.alpha < DEFAULT_ALPHA_THRESHOLD) {
+        return null;
+    }
+
+    const opacity = parsedColor.alpha / 255;
+
+    return {
+        red: Math.round(parsedColor.red * opacity),
+        green: Math.round(parsedColor.green * opacity),
+        blue: Math.round(parsedColor.blue * opacity),
+    };
+}
+
+/**
+ * Places the square avatar grid into the center of the requested terminal grid.
+ *
+ * @private helper of `renderAvatarVisualTerminalTextGrid`
+ */
+function centerAvatarVisualTerminalTextGrid(
+    avatarGrid: AvatarVisualTerminalTextGrid,
+    columns: number,
+    rows: number,
+): AvatarVisualTerminalTextGrid {
+    const avatarRowCount = avatarGrid.length;
+    const avatarColumnCount = avatarGrid[0]?.length || 0;
+    const leftCellCount = Math.floor((columns - avatarColumnCount) / 2);
+    const topRowCount = Math.floor((rows - avatarRowCount) / 2);
+
+    return Array.from({ length: rows }, (_, rowIndex) => {
+        const avatarRow = avatarGrid[rowIndex - topRowCount];
+
+        return Array.from({ length: columns }, (__, columnIndex) => avatarRow?.[columnIndex - leftCellCount] || null);
+    });
+}
+
+/**
+ * Builds one ANSI-colored terminal line from resolved character cells.
+ *
+ * @private helper of `renderAvatarVisualTerminalTextLines`
+ */
+function buildAvatarVisualTerminalTextLine(
+    terminalTextRow: ReadonlyArray<AvatarVisualTerminalTextCell | null>,
+    colorDepth: AsciiArtColorDepth,
+): string {
+    let line = '';
+    let currentForegroundCode: string | undefined = undefined;
+
+    for (const terminalTextCell of terminalTextRow) {
+        const cellColor =
+            terminalTextCell === null ? null : resolveAvatarVisualTerminalTextColor(terminalTextCell.color);
+        const nextForegroundCode =
+            cellColor === null ? undefined : createAnsiForegroundColorCode(cellColor, colorDepth);
+
+        if (nextForegroundCode !== currentForegroundCode) {
+            // Note: A reset is required whenever a previously set color must be cleared,
+            //       otherwise a stale color would bleed into the following empty cells.
+            if (nextForegroundCode === undefined) {
+                line += ANSI_RESET;
+            } else {
+                line += nextForegroundCode;
+            }
+
+            currentForegroundCode = nextForegroundCode;
+        }
+
+        line += cellColor === null || terminalTextCell === null ? ' ' : terminalTextCell.character;
+    }
+
+    if (currentForegroundCode !== undefined) {
+        line += ANSI_RESET;
+    }
+
+    return line;
+}

package/src/avatars/types/AvatarVisualDefinition.ts

@@ -93,6 +93,57 @@ export type AvatarVisualRenderContext = {
  */
 export type AvatarVisual = (context: AvatarVisualRenderContext) => void;
 
+/**
+ * One painted character cell of a terminal-text avatar frame.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextCell = {
+    /**
+     * Single character painted in the cell.
+     */
+    readonly character: string;
+
+    /**
+     * Color of the character as a CSS color string, optionally with an alpha channel.
+     */
+    readonly color: string_color;
+};
+
+/**
+ * One rendered terminal-text avatar frame as a grid of character cells.
+ *
+ * Rows are ordered top to bottom, cells left to right, and `null` leaves the terminal background visible.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextGrid = ReadonlyArray<ReadonlyArray<AvatarVisualTerminalTextCell | null>>;
+
+/**
+ * Rendering context forwarded to a terminal-text avatar visual.
+ *
+ * Unlike `AvatarVisualRenderContext` this carries no canvas, because the visual paints
+ * character cells of a fixed terminal grid instead of pixels.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextRenderContext = {
+    readonly columns: number;
+    readonly rows: number;
+    readonly timeMs: number;
+    readonly avatarDefinition: AvatarDefinition;
+    readonly palette: AvatarPalette;
+    readonly createRandom: (salt: string) => () => number;
+    readonly interaction: AvatarInteractionState;
+};
+
+/**
+ * Signature of one terminal-text avatar visual renderer.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalText = (context: AvatarVisualTerminalTextRenderContext) => AvatarVisualTerminalTextGrid;
+
 /**
  * Metadata and renderer for one built-in avatar visual.
  *
@@ -105,6 +156,15 @@ export type AvatarVisualDefinition = {
     readonly isAnimated: boolean;
     readonly supportsPointerTracking?: boolean;
     readonly render: AvatarVisual;
+
+    /**
+     * Optional native terminal renderer of visuals which are themselves made of characters.
+     *
+     * Character-based visuals lose their identity when they are rasterized onto a canvas and
+     * converted back into half-block ASCII art, so they paint the terminal character grid directly.
+     * Visuals without this renderer are rasterized through `renderAvatarVisualAsciiArt` instead.
+     */
+    readonly renderTerminalText?: AvatarVisualTerminalText;
 };
 
 /**