@promptbook/cli 0.113.0-8 → 0.113.0-9

package/esm/src/commitments/index.d.ts

@@ -62,4 +62,4 @@ import { NotYetImplementedCommitmentDefinition } from './_base/NotYetImplemented
  *
  * @private Use functions to access commitments instead of this array directly
  */
-export declare const COMMITMENT_REGISTRY: readonly [PersonaCommitmentDefinition, PersonaCommitmentDefinition, KnowledgeCommitmentDefinition, MemoryCommitmentDefinition, MemoryCommitmentDefinition, StyleCommitmentDefinition, StyleCommitmentDefinition, RuleCommitmentDefinition, RuleCommitmentDefinition, LanguageCommitmentDefinition, LanguageCommitmentDefinition, WritingSampleCommitmentDefinition, WritingRulesCommitmentDefinition, SampleCommitmentDefinition, SampleCommitmentDefinition, FormatCommitmentDefinition, FormatCommitmentDefinition, TemplateCommitmentDefinition, TemplateCommitmentDefinition, FromCommitmentDefinition, ImportCommitmentDefinition, ImportCommitmentDefinition, ModelCommitmentDefinition, ModelCommitmentDefinition, ActionCommitmentDefinition, ActionCommitmentDefinition, ComponentCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaImageCommitmentDefinition, MetaColorCommitmentDefinition, MetaFontCommitmentDefinition, MetaLinkCommitmentDefinition, MetaDomainCommitmentDefinition, MetaDisclaimerCommitmentDefinition, MetaInputPlaceholderCommitmentDefinition, MetaVisibilityCommitmentDefinition, MetaCommitmentDefinition, MetaVoiceCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, GoalCommitmentDefinition, GoalCommitmentDefinition, InitialMessageCommitmentDefinition, UserMessageCommitmentDefinition, InternalMessageCommitmentDefinition, AgentMessageCommitmentDefinition, MessageSuffixCommitmentDefinition, MessageCommitmentDefinition, MessageCommitmentDefinition, WalletCommitmentDefinition, WalletCommitmentDefinition, ScenarioCommitmentDefinition, ScenarioCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DictionaryCommitmentDefinition, OpenCommitmentDefinition, ClosedCommitmentDefinition, TeamCommitmentDefinition, UseBrowserCommitmentDefinition, UseDeepSearchCommitmentDefinition, UseSearchEngineCommitmentDefinition, UseSpawnCommitmentDefinition, UseTimeoutCommitmentDefinition, UseTimeCommitmentDefinition, UseUserLocationCommitmentDefinition, UseCalendarCommitmentDefinition, UseEmailCommitmentDefinition, UsePopupCommitmentDefinition, UseImageGeneratorCommitmentDefinition, UseMcpCommitmentDefinition, UsePrivacyCommitmentDefinition, UseProjectCommitmentDefinition, NotYetImplementedCommitmentDefinition<"EXPECT">, NotYetImplementedCommitmentDefinition<"BEHAVIOUR">, NotYetImplementedCommitmentDefinition<"BEHAVIOURS">, NotYetImplementedCommitmentDefinition<"AVOID">, NotYetImplementedCommitmentDefinition<"AVOIDANCE">, NotYetImplementedCommitmentDefinition<"CONTEXT">];
+export declare const COMMITMENT_REGISTRY: readonly [PersonaCommitmentDefinition, PersonaCommitmentDefinition, KnowledgeCommitmentDefinition, MemoryCommitmentDefinition, MemoryCommitmentDefinition, StyleCommitmentDefinition, StyleCommitmentDefinition, RuleCommitmentDefinition, RuleCommitmentDefinition, LanguageCommitmentDefinition, LanguageCommitmentDefinition, WritingSampleCommitmentDefinition, WritingRulesCommitmentDefinition, SampleCommitmentDefinition, SampleCommitmentDefinition, FormatCommitmentDefinition, FormatCommitmentDefinition, TemplateCommitmentDefinition, TemplateCommitmentDefinition, FromCommitmentDefinition, ImportCommitmentDefinition, ImportCommitmentDefinition, ModelCommitmentDefinition, ModelCommitmentDefinition, ActionCommitmentDefinition, ActionCommitmentDefinition, ComponentCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaImageCommitmentDefinition, MetaColorCommitmentDefinition, MetaFontCommitmentDefinition, MetaLinkCommitmentDefinition, MetaDomainCommitmentDefinition, MetaDisclaimerCommitmentDefinition, MetaInputPlaceholderCommitmentDefinition, MetaVisibilityCommitmentDefinition, MetaCommitmentDefinition, MetaVoiceCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, GoalCommitmentDefinition, GoalCommitmentDefinition, InitialMessageCommitmentDefinition, UserMessageCommitmentDefinition, InternalMessageCommitmentDefinition, AgentMessageCommitmentDefinition, MessageSuffixCommitmentDefinition, MessageCommitmentDefinition, MessageCommitmentDefinition, WalletCommitmentDefinition, WalletCommitmentDefinition, ScenarioCommitmentDefinition, ScenarioCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DictionaryCommitmentDefinition, OpenCommitmentDefinition, ClosedCommitmentDefinition, TeamCommitmentDefinition, UseBrowserCommitmentDefinition, UseDeepSearchCommitmentDefinition, UseSearchEngineCommitmentDefinition, UseSpawnCommitmentDefinition, UseTimeoutCommitmentDefinition, UseTimeCommitmentDefinition, UseUserLocationCommitmentDefinition, UseCalendarCommitmentDefinition, UseEmailCommitmentDefinition, UsePopupCommitmentDefinition, UseImageGeneratorCommitmentDefinition, UseMcpCommitmentDefinition, UsePrivacyCommitmentDefinition, UseProjectCommitmentDefinition, NotYetImplementedCommitmentDefinition<"EXPECT">, NotYetImplementedCommitmentDefinition<"BEHAVIOUR">, NotYetImplementedCommitmentDefinition<"BEHAVIOURS">, NotYetImplementedCommitmentDefinition<"AVOID">, NotYetImplementedCommitmentDefinition<"AVOIDANCE">, NotYetImplementedCommitmentDefinition<"CONTEXT">];

package/esm/src/conversion/validation/validatePipeline/createPipelineValidationContext.d.ts

@@ -0,0 +1,16 @@
+import type { PipelineJson } from '../../../pipeline/PipelineJson/PipelineJson';
+/**
+ * Shared validation context for one pipeline validation pass.
+ *
+ * @private type of `validatePipeline`
+ */
+export type PipelineValidationContext = {
+    pipeline: PipelineJson;
+    pipelineIdentification: string;
+};
+/**
+ * Creates the shared validation context for one pipeline.
+ *
+ * @private function of `validatePipeline`
+ */
+export declare function createPipelineValidationContext(pipeline: PipelineJson): PipelineValidationContext;

package/esm/src/conversion/validation/validatePipeline/validatePipelineCollectionsStructure.d.ts

@@ -0,0 +1,7 @@
+import type { PipelineValidationContext } from './createPipelineValidationContext';
+/**
+ * Validates that the expected top-level collections have array structure.
+ *
+ * @private function of `validatePipeline`
+ */
+export declare function validatePipelineCollectionsStructure({ pipeline, pipelineIdentification, }: PipelineValidationContext): void;

package/esm/src/conversion/validation/validatePipeline/validatePipelineDependencyResolution.d.ts

@@ -0,0 +1,7 @@
+import type { PipelineValidationContext } from './createPipelineValidationContext';
+/**
+ * Validates that task dependencies can be resolved without cycles or missing definitions.
+ *
+ * @private function of `validatePipeline`
+ */
+export declare function validatePipelineDependencyResolution({ pipeline, pipelineIdentification, }: PipelineValidationContext): void;

package/esm/src/conversion/validation/validatePipeline/validatePipelineMetadata.d.ts

@@ -0,0 +1,7 @@
+import type { PipelineValidationContext } from './createPipelineValidationContext';
+/**
+ * Validates pipeline-level metadata fields.
+ *
+ * @private function of `validatePipeline`
+ */
+export declare function validatePipelineMetadata({ pipeline, pipelineIdentification }: PipelineValidationContext): void;

package/esm/src/conversion/validation/validatePipeline/validatePipelineParameters.d.ts

@@ -0,0 +1,7 @@
+import type { PipelineValidationContext } from './createPipelineValidationContext';
+/**
+ * Validates all pipeline parameter declarations.
+ *
+ * @private function of `validatePipeline`
+ */
+export declare function validatePipelineParameters({ pipeline, pipelineIdentification }: PipelineValidationContext): void;

package/esm/src/conversion/validation/validatePipeline/validatePipelineTasks.d.ts

@@ -0,0 +1,7 @@
+import type { PipelineValidationContext } from './createPipelineValidationContext';
+/**
+ * Validates all pipeline tasks and their per-task invariants.
+ *
+ * @private function of `validatePipeline`
+ */
+export declare function validatePipelineTasks({ pipeline, pipelineIdentification }: PipelineValidationContext): void;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/RegisteredLlmToolsMessageContext.d.ts

@@ -0,0 +1,46 @@
+import type { string_name } from '../../../../types/string_name';
+import type { Registered } from '../../../../utils/misc/$Register';
+import type { LlmToolsMetadata } from '../LlmToolsMetadata';
+/**
+ * Environment variables available for provider resolution.
+ *
+ * @private type of `$registeredLlmToolsMessage`
+ */
+export type AvailableEnvironmentVariables = Record<string_name, string>;
+/**
+ * Mixed provider entry assembled from both provider registers.
+ *
+ * @private type of `$registeredLlmToolsMessage`
+ */
+export type RegisteredLlmToolEntry = Registered & Partial<Pick<LlmToolsMetadata, 'title' | 'envVariables'>>;
+/**
+ * Provider entry enriched with runtime availability and configuration flags.
+ *
+ * @private type of `$registeredLlmToolsMessage`
+ */
+export type RegisteredLlmToolStatus = RegisteredLlmToolEntry & {
+    readonly isMetadataAvailable: boolean;
+    readonly isInstalled: boolean;
+    readonly isFullyConfigured: boolean;
+    readonly isPartiallyConfigured: boolean;
+};
+/**
+ * Provider register snapshots used to build the summary.
+ *
+ * @private type of `$registeredLlmToolsMessage`
+ */
+export type RegisteredLlmToolRegisters = {
+    readonly registeredMetadata: ReadonlyArray<LlmToolsMetadata>;
+    readonly registeredTools: ReadonlyArray<Registered>;
+};
+/**
+ * Message-rendering context for the registered providers summary.
+ *
+ * @private type of `$registeredLlmToolsMessage`
+ */
+export type RegisteredLlmToolsMessageContext = {
+    readonly env: AvailableEnvironmentVariables;
+    readonly llmToolStatuses: ReadonlyArray<RegisteredLlmToolStatus>;
+    readonly usedEnvMessage: string;
+    readonly isRunningInNode: boolean;
+};

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/USED_ENV_FILENAME.d.ts

@@ -0,0 +1,11 @@
+import type { string_filename } from '../../../../types/string_filename';
+import type { $side_effect } from '../../../../utils/organization/$side_effect';
+/**
+ * Shared state for the `.env` file used to configure LLM tools.
+ *
+ * @private internal state of `$registeredLlmToolsMessage`
+ */
+export declare const USED_ENV_FILENAME: {
+    set(filepath: string_filename): $side_effect;
+    createMessage(): string;
+};

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/createRegisteredLlmToolConfigurationStatusMessage.d.ts

@@ -0,0 +1,7 @@
+import type { AvailableEnvironmentVariables, RegisteredLlmToolStatus } from './RegisteredLlmToolsMessageContext';
+/**
+ * Creates the configuration-status sentence for one provider.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function createRegisteredLlmToolConfigurationStatusMessage({ envVariables, isFullyConfigured, isPartiallyConfigured }: RegisteredLlmToolStatus, env: AvailableEnvironmentVariables): string;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/createRegisteredLlmToolEntryKey.d.ts

@@ -0,0 +1,7 @@
+import type { Registered } from '../../../../utils/misc/$Register';
+/**
+ * Creates a deduplication key for a provider entry.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function createRegisteredLlmToolEntryKey({ packageName, className }: Registered): string;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/createRegisteredLlmToolInstallationStatusMessage.d.ts

@@ -0,0 +1,7 @@
+import type { RegisteredLlmToolStatus } from './RegisteredLlmToolsMessageContext';
+/**
+ * Creates the installation-status sentence for one provider.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function createRegisteredLlmToolInstallationStatusMessage({ isMetadataAvailable, isInstalled, }: Pick<RegisteredLlmToolStatus, 'isMetadataAvailable' | 'isInstalled'>): string;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/createRegisteredLlmToolStatus.d.ts

@@ -0,0 +1,14 @@
+import type { Registered } from '../../../../utils/misc/$Register';
+import type { LlmToolsMetadata } from '../LlmToolsMetadata';
+import type { AvailableEnvironmentVariables, RegisteredLlmToolEntry, RegisteredLlmToolStatus } from './RegisteredLlmToolsMessageContext';
+/**
+ * Builds the runtime status for one provider entry.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function createRegisteredLlmToolStatus({ registeredLlmToolEntry, registeredMetadata, registeredTools, env, }: {
+    readonly registeredLlmToolEntry: RegisteredLlmToolEntry;
+    readonly registeredMetadata: ReadonlyArray<LlmToolsMetadata>;
+    readonly registeredTools: ReadonlyArray<Registered>;
+    readonly env: AvailableEnvironmentVariables;
+}): RegisteredLlmToolStatus;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/createRegisteredLlmToolsMessageContext.d.ts

@@ -0,0 +1,7 @@
+import type { RegisteredLlmToolsMessageContext } from './RegisteredLlmToolsMessageContext';
+/**
+ * Collects all state needed to render the provider summary.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function createRegisteredLlmToolsMessageContext(): RegisteredLlmToolsMessageContext;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/getAvailableRegisteredLlmToolsEnvironmentVariables.d.ts

@@ -0,0 +1,7 @@
+import type { AvailableEnvironmentVariables } from './RegisteredLlmToolsMessageContext';
+/**
+ * Reads environment variables relevant for provider configuration.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function getAvailableRegisteredLlmToolsEnvironmentVariables(isRunningInNode: boolean): AvailableEnvironmentVariables;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/getRegisteredLlmToolRegisters.d.ts

@@ -0,0 +1,7 @@
+import type { RegisteredLlmToolRegisters } from './RegisteredLlmToolsMessageContext';
+/**
+ * Takes stable snapshots of both LLM provider registers.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function getRegisteredLlmToolRegisters(): RegisteredLlmToolRegisters;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/hasRegisteredLlmToolEntry.d.ts

@@ -0,0 +1,7 @@
+import type { Registered } from '../../../../utils/misc/$Register';
+/**
+ * Checks whether the given provider entry already exists in the target register list.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function hasRegisteredLlmToolEntry(registeredLlmToolEntries: ReadonlyArray<Registered>, registeredLlmToolEntry: Registered): boolean;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/listRegisteredLlmToolEntries.d.ts

@@ -0,0 +1,9 @@
+import type { Registered } from '../../../../utils/misc/$Register';
+import type { LlmToolsMetadata } from '../LlmToolsMetadata';
+import type { RegisteredLlmToolEntry } from './RegisteredLlmToolsMessageContext';
+/**
+ * Merges provider entries from the metadata and constructor registers.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function listRegisteredLlmToolEntries(registeredMetadata: ReadonlyArray<LlmToolsMetadata>, registeredTools: ReadonlyArray<Registered>): Array<RegisteredLlmToolEntry>;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/listRegisteredLlmToolStatuses.d.ts

@@ -0,0 +1,7 @@
+import type { AvailableEnvironmentVariables, RegisteredLlmToolRegisters, RegisteredLlmToolStatus } from './RegisteredLlmToolsMessageContext';
+/**
+ * Lists provider entries enriched with installation and configuration state.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function listRegisteredLlmToolStatuses({ registeredMetadata, registeredTools }: RegisteredLlmToolRegisters, env: AvailableEnvironmentVariables): Array<RegisteredLlmToolStatus>;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/renderAvailableRegisteredLlmTools.d.ts

@@ -0,0 +1,7 @@
+import type { AvailableEnvironmentVariables, RegisteredLlmToolStatus } from './RegisteredLlmToolsMessageContext';
+/**
+ * Renders all provider lines in the status summary.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function renderAvailableRegisteredLlmTools(llmToolStatuses: ReadonlyArray<RegisteredLlmToolStatus>, env: AvailableEnvironmentVariables, isRunningInNode: boolean): string;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/renderNoRegisteredLlmToolsMessage.d.ts

@@ -0,0 +1,7 @@
+import type { string_markdown } from '../../../../types/string_markdown';
+/**
+ * Renders the fallback message for environments with no registered providers.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function renderNoRegisteredLlmToolsMessage(usedEnvMessage: string): string_markdown;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/renderRegisteredLlmToolsMessage.d.ts

@@ -0,0 +1,8 @@
+import type { string_markdown } from '../../../../types/string_markdown';
+import type { RegisteredLlmToolsMessageContext } from './RegisteredLlmToolsMessageContext';
+/**
+ * Renders the full provider status summary.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function renderRegisteredLlmToolsMessage({ env, llmToolStatuses, usedEnvMessage, isRunningInNode, }: RegisteredLlmToolsMessageContext): string_markdown;

package/esm/src/llm-providers/_common/register/$registeredLlmToolsMessage/renderRelevantRegisteredLlmToolsEnvironmentVariables.d.ts

@@ -0,0 +1,7 @@
+import type { AvailableEnvironmentVariables, RegisteredLlmToolStatus } from './RegisteredLlmToolsMessageContext';
+/**
+ * Renders the list of environment variables used by at least one registered provider.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+export declare function renderRelevantRegisteredLlmToolsEnvironmentVariables(env: AvailableEnvironmentVariables, llmToolStatuses: ReadonlyArray<RegisteredLlmToolStatus>): string;

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

@@ -39,7 +39,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
  */
@@ -76,7 +76,7 @@ export declare function resolveAgentAvatarVisualId(agent: ResolveAgentAvatarOpti
 export declare function resolveAgentAvatarFallbackUrl(options: ResolveAgentAvatarOptions): string_url_image | null;
 /**
  * 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/esm/src/utils/color/Color.d.ts

@@ -1,8 +1,8 @@
 import type { string_color } from '../../types/string_person_fullname';
 import type { string_url_image } from '../../types/string_url_image';
 import type { WithTake } from '../take/interfaces/ITakeChain';
-import { CSS_COLORS } from './css-colors';
 import { ColorValue } from './ColorValue';
+import { CSS_COLORS } from './css-colors';
 /**
  * Color object represents an RGB color with alpha channel
  *

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-5`).
+ * It follows semantic versioning (e.g., `0.113.0-8`).
  *
  * @generated
  */

package/package.json

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

package/src/_packages/types.index.ts

@@ -23,8 +23,8 @@ import type { AvatarProfileFromSourceProps } from '../book-components/AvatarProf
 import type { BookEditorUploadProgressCallback } from '../book-components/BookEditor/BookEditor';
 import type { BookEditorUploadOptions } from '../book-components/BookEditor/BookEditor';
 import type { BookEditorProps } from '../book-components/BookEditor/BookEditor';
-import type { UploadItem } from '../book-components/BookEditor/useBookEditorMonacoUploads';
-import type { UploadStats } from '../book-components/BookEditor/useBookEditorMonacoUploads';
+import type { UploadItem } from '../book-components/BookEditor/useBookEditorMonacoUploads/bookEditorMonacoUploadTypes';
+import type { UploadStats } from '../book-components/BookEditor/useBookEditorMonacoUploads/bookEditorMonacoUploadTypes';
 import type { AgentChatProps } from '../book-components/Chat/AgentChat/AgentChatProps';
 import type { AgentChipData } from '../book-components/Chat/AgentChip/AgentChip';
 import type { AgentChipProps } from '../book-components/Chat/AgentChip/AgentChip';

package/src/avatars/Avatar.tsx

@@ -2,19 +2,8 @@
 
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { retainAvatarAnimationListener } from './avatarAnimationScheduler';
-import {
-    createAvatarDefinitionKey,
-    createAvatarInteractionRuntimeState,
-    createIdleAvatarInteractionState,
-    resolveAvatarPointerTarget,
-    stepAvatarInteractionRuntimeState,
-} from './avatarInteractionUtils';
-import {
-    getAvatarPointerSnapshot,
-    getAvatarPointerSnapshotVersion,
-    getAvatarViewportLayoutVersion,
-    retainAvatarPointerTracking,
-} from './avatarPointerTracking';
+import { createAvatarDefinitionKey, createAvatarInteractionRuntimeState, createIdleAvatarInteractionState, resolveAvatarPointerTarget, stepAvatarInteractionRuntimeState } from './avatarInteractionUtils';
+import { getAvatarPointerSnapshot, getAvatarPointerSnapshotVersion, getAvatarViewportLayoutVersion, retainAvatarPointerTracking } from './avatarPointerTracking';
 import { DEFAULT_AVATAR_SIZE } from './avatarRenderingUtils';
 import { observeAvatarVisibility } from './avatarVisibilityTracking';
 import { renderAvatarVisual, resolveAvatarRenderDefinition } from './renderAvatarVisual';

package/src/avatars/renderAvatarVisual.ts

@@ -1,18 +1,7 @@
 import { createIdleAvatarInteractionState } from './avatarInteractionUtils';
-import {
-    createAvatarPalette,
-    createAvatarRandomFactory,
-    normalizeAvatarDefinition,
-    prepareAvatarCanvas,
-} from './avatarRenderingUtils';
+import { createAvatarPalette, createAvatarRandomFactory, normalizeAvatarDefinition, prepareAvatarCanvas } from './avatarRenderingUtils';
 import type { AvatarDefinition } from './types/AvatarDefinition';
-import type {
-    AvatarPalette,
-    AvatarSurfaceStyle,
-    AvatarVisualDefinition,
-    AvatarVisualId,
-    RenderAvatarVisualOptions,
-} from './types/AvatarVisualDefinition';
+import type { AvatarPalette, AvatarSurfaceStyle, AvatarVisualDefinition, AvatarVisualId, RenderAvatarVisualOptions } from './types/AvatarVisualDefinition';
 import { getAvatarVisualById } from './visuals/avatarVisualRegistry';
 
 /**

package/src/avatars/renderAvatarVisualAsciiArt.ts

@@ -1,11 +1,13 @@
 import { spaceTrim } from 'spacetrim';
 import { EnvironmentMismatchError } from '../errors/EnvironmentMismatchError';
-import type { AsciiArtColorDepth } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import { UnexpectedError } from '../errors/UnexpectedError';
+import type { AsciiArtColorDepth, AsciiArtImageData } from '../utils/ascii-art/convertImageDataToAsciiArt';
 import { convertImageDataToAsciiArt } from '../utils/ascii-art/convertImageDataToAsciiArt';
 import { DEFAULT_AVATAR_SIZE } from './avatarRenderingUtils';
+import type { ResolvedAvatarRenderDefinition } from './renderAvatarVisual';
 import { renderAvatarVisual } from './renderAvatarVisual';
 import type { AvatarDefinition } from './types/AvatarDefinition';
-import type { AvatarVisualId } from './types/AvatarVisualDefinition';
+import type { AvatarSurfaceStyle, AvatarVisualId } from './types/AvatarVisualDefinition';
 
 /**
  * Default output width of the ASCII avatar in terminal character cells.
@@ -21,6 +23,20 @@ export const DEFAULT_AVATAR_ASCII_ART_COLUMNS = 32;
  */
 const STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS = 840;
 
+/**
+ * Default source canvas width used before the pixels are converted to ASCII art.
+ *
+ * @private within the repository
+ */
+const DEFAULT_AVATAR_ASCII_ART_CANVAS_WIDTH = DEFAULT_AVATAR_SIZE;
+
+/**
+ * Default source canvas height used before the pixels are converted to ASCII art.
+ *
+ * @private within the repository
+ */
+const DEFAULT_AVATAR_ASCII_ART_CANVAS_HEIGHT = DEFAULT_AVATAR_SIZE;
+
 /**
  * Factory creating a drawable canvas of the requested pixel size.
  *
@@ -47,6 +63,13 @@ export type RenderAvatarVisualAsciiArtOptions = {
      */
     readonly visualId: AvatarVisualId;
 
+    /**
+     * Surface used to composite the avatar before ASCII conversion.
+     *
+     * @default 'framed'
+     */
+    readonly surface?: AvatarSurfaceStyle;
+
     /**
      * Output width in terminal character cells.
      *
@@ -75,6 +98,25 @@ export type RenderAvatarVisualAsciiArtOptions = {
      */
     readonly timeMs?: number;
 
+    /**
+     * Source canvas width in CSS pixels before ASCII conversion.
+     *
+     * @default `DEFAULT_AVATAR_SIZE`
+     */
+    readonly canvasWidth?: number;
+
+    /**
+     * Source canvas height in CSS pixels before ASCII conversion.
+     *
+     * @default `DEFAULT_AVATAR_SIZE`
+     */
+    readonly canvasHeight?: number;
+
+    /**
+     * Optional stable render data reused across frames.
+     */
+    readonly resolvedAvatarRenderDefinition?: ResolvedAvatarRenderDefinition;
+
     /**
      * Platform-specific canvas factory used to rasterize the visual.
      */
@@ -97,23 +139,88 @@ export type RenderAvatarVisualAsciiArtOptions = {
 export function renderAvatarVisualAsciiArt(options: RenderAvatarVisualAsciiArtOptions): ReadonlyArray<string> {
     const columns = options.columns ?? DEFAULT_AVATAR_ASCII_ART_COLUMNS;
     const rows = options.rows ?? Math.round(columns / 2);
+    const canvasWidth = options.canvasWidth ?? DEFAULT_AVATAR_ASCII_ART_CANVAS_WIDTH;
+    const canvasHeight = options.canvasHeight ?? DEFAULT_AVATAR_ASCII_ART_CANVAS_HEIGHT;
+    assertPositiveCanvasDimension(canvasWidth, 'canvasWidth');
+    assertPositiveCanvasDimension(canvasHeight, 'canvasHeight');
+
+    const imageData = renderAvatarVisualAsciiArtImageData(options, canvasWidth, canvasHeight);
+
+    return convertImageDataToAsciiArt({
+        imageData,
+        columns,
+        rows,
+        colorDepth: options.colorDepth,
+    });
+}
+
+/**
+ * Renders one avatar visual frame into source pixels ready for ASCII conversion.
+ *
+ * @private helper of `renderAvatarVisualAsciiArt`
+ */
+function renderAvatarVisualAsciiArtImageData(
+    options: RenderAvatarVisualAsciiArtOptions,
+    canvasWidth: number,
+    canvasHeight: number,
+): AsciiArtImageData {
+    const avatarSize = Math.min(canvasWidth, canvasHeight);
+    const avatarCanvas = createCanvasWithBrowserShape(options.createCanvas, avatarSize, avatarSize);
+
+    renderAvatarVisual(
+        {
+            canvas: avatarCanvas,
+            avatarDefinition: options.avatarDefinition,
+            visualId: options.visualId,
+            surface: options.surface,
+            size: avatarSize,
+            timeMs: options.timeMs ?? STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS,
+            devicePixelRatio: 1,
+        },
+        options.resolvedAvatarRenderDefinition,
+    );
+
+    if (canvasWidth === avatarSize && canvasHeight === avatarSize) {
+        return getCanvas2dContext(avatarCanvas).getImageData(0, 0, avatarSize, avatarSize);
+    }
+
+    const canvas = createCanvasWithBrowserShape(options.createCanvas, canvasWidth, canvasHeight);
+    const context = getCanvas2dContext(canvas);
+    const avatarLeft = (canvasWidth - avatarSize) / 2;
+    const avatarTop = (canvasHeight - avatarSize) / 2;
 
-    const canvas = options.createCanvas(DEFAULT_AVATAR_SIZE, DEFAULT_AVATAR_SIZE);
+    context.clearRect(0, 0, canvasWidth, canvasHeight);
+    context.drawImage(avatarCanvas, avatarLeft, avatarTop, avatarSize, avatarSize);
+
+    return context.getImageData(0, 0, canvasWidth, canvasHeight);
+}
+
+/**
+ * Creates a canvas and adds the small browser-shape compatibility shim expected by avatar rendering.
+ *
+ * @private helper of `renderAvatarVisualAsciiArt`
+ */
+function createCanvasWithBrowserShape(
+    createCanvas: CreateCanvasForAsciiArt,
+    width: number,
+    height: number,
+): HTMLCanvasElement {
+    const canvas = createCanvas(width, height);
 
     if (!canvas.style) {
         // Note: `renderAvatarVisual` expects a browser canvas shape; Node.js canvases only need this tiny compatibility shim.
         (canvas as { style: HTMLCanvasElement['style'] }).style = {} as HTMLCanvasElement['style'];
     }
 
-    renderAvatarVisual({
-        canvas,
-        avatarDefinition: options.avatarDefinition,
-        visualId: options.visualId,
-        size: DEFAULT_AVATAR_SIZE,
-        timeMs: options.timeMs ?? STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS,
-        devicePixelRatio: 1,
-    });
+    return canvas;
+}
 
+/**
+ * Reads a 2D rendering context or throws a branded environment error.
+ *
+ * @private helper of `renderAvatarVisualAsciiArt`
+ */
+function getCanvas2dContext(canvas: HTMLCanvasElement): CanvasRenderingContext2D {
     const context = canvas.getContext('2d');
 
     if (!context) {
@@ -127,12 +234,24 @@ export function renderAvatarVisualAsciiArt(options: RenderAvatarVisualAsciiArtOp
         );
     }
 
-    const imageData = context.getImageData(0, 0, DEFAULT_AVATAR_SIZE, DEFAULT_AVATAR_SIZE);
+    return context;
+}
 
-    return convertImageDataToAsciiArt({
-        imageData,
-        columns,
-        rows,
-        colorDepth: options.colorDepth,
-    });
+/**
+ * Validates one source canvas dimension.
+ *
+ * @private helper of `renderAvatarVisualAsciiArt`
+ */
+function assertPositiveCanvasDimension(value: number, dimensionName: 'canvasWidth' | 'canvasHeight'): void {
+    if (Number.isInteger(value) && value > 0) {
+        return;
+    }
+
+    throw new UnexpectedError(
+        spaceTrim(`
+            Avatar ASCII-art source canvas dimension is invalid.
+
+            \`${dimensionName}\` must be a positive integer but \`${value}\` was requested.
+        `),
+    );
 }

package/src/avatars/visuals/asciiOctopusAvatarVisual.ts

@@ -3,12 +3,7 @@
 import { drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
 import type { OrganicTentacleRibbonPoint } from './octopusAvatarVisualShared';
-import {
-    createOrganicOctopusBodyPoints,
-    createOrganicOctopusTentacleShapes,
-    resolveOrganicEyeMotion,
-    sampleOrganicTentacleRibbonPoints,
-} from './octopusAvatarVisualShared';
+import { createOrganicOctopusBodyPoints, createOrganicOctopusTentacleShapes, resolveOrganicEyeMotion, sampleOrganicTentacleRibbonPoints } from './octopusAvatarVisualShared';
 
 /**
  * Glyph ramp used for the main octopus body fill.

package/src/avatars/visuals/avatarVisualRegistry.ts

@@ -5,10 +5,10 @@ import { minecraft2AvatarVisual } from './minecraft2AvatarVisual';
 import { minecraftAvatarVisual } from './minecraftAvatarVisual';
 import { octopus2AvatarVisual } from './octopus2AvatarVisual';
 import { octopus3AvatarVisual } from './octopus3AvatarVisual';
-import { octopus3dAvatarVisual } from './octopus3dAvatarVisual';
 import { octopus3d2AvatarVisual } from './octopus3d2AvatarVisual';
 import { octopus3d3AvatarVisual } from './octopus3d3AvatarVisual';
 import { octopus3d4AvatarVisual } from './octopus3d4AvatarVisual';
+import { octopus3dAvatarVisual } from './octopus3dAvatarVisual';
 import { octopusAvatarVisual } from './octopusAvatarVisual';
 import { orbAvatarVisual } from './orbAvatarVisual';
 import { pixelArtAvatarVisual } from './pixelArtAvatarVisual';

package/src/avatars/visuals/minecraft2AvatarVisual.ts

@@ -2,6 +2,7 @@
 
 import { drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+import type { Point3D, ProjectedPoint } from './avatar3dProjectionShared';
 import {
     clampNumber,
     crossProduct3D,
@@ -11,8 +12,6 @@ import {
     projectScenePoint,
     subtractPoint3D,
     transformScenePoint,
-    type Point3D,
-    type ProjectedPoint,
 } from './avatar3dProjectionShared';
 import type { MinecraftCuboidTextures, MinecraftTexture } from './minecraftAvatarVisualShared';
 import { createMinecraftHeadTextures, createMinecraftTorsoTextures } from './minecraftAvatarVisualShared';