@promptbook/cli 0.113.0-1 → 0.113.0-10

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.113.0-1",
+    "version": "0.113.0-10",
     "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/avatarAnimationScheduler.ts

@@ -133,7 +133,8 @@ function ensureAvatarAnimationLoop(): void {
         // Run the most stale listeners first so each avatar keeps its target FPS even when
         // total work exceeds the per-frame budget.
         dueListenerEntries.sort(
-            (firstListenerEntry, secondListenerEntry) => firstListenerEntry.lastRunAtMs - secondListenerEntry.lastRunAtMs,
+            (firstListenerEntry, secondListenerEntry) =>
+                firstListenerEntry.lastRunAtMs - secondListenerEntry.lastRunAtMs,
         );
 
         const listenersToRunCount = Math.min(dueListenerEntries.length, MAX_AVATAR_LISTENERS_PER_FRAME);

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

@@ -0,0 +1,257 @@
+import { spaceTrim } from 'spacetrim';
+import { EnvironmentMismatchError } from '../errors/EnvironmentMismatchError';
+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 { AvatarSurfaceStyle, AvatarVisualId } from './types/AvatarVisualDefinition';
+
+/**
+ * Default output width of the ASCII avatar in terminal character cells.
+ *
+ * @private within the repository
+ */
+export const DEFAULT_AVATAR_ASCII_ART_COLUMNS = 32;
+
+/**
+ * Stable animation timestamp used when rasterizing animated avatar visuals into a static ASCII frame.
+ *
+ * @private within the repository
+ */
+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.
+ *
+ * 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;
+
+    /**
+     * Surface used to composite the avatar before ASCII conversion.
+     *
+     * @default 'framed'
+     */
+    readonly surface?: AvatarSurfaceStyle;
+
+    /**
+     * 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;
+
+    /**
+     * 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.
+     */
+    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 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;
+
+    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'];
+    }
+
+    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) {
+        throw new EnvironmentMismatchError(
+            spaceTrim(`
+                2D canvas rendering context is unavailable while converting the avatar visual to ASCII art.
+
+                Provide a \`createCanvas\` factory whose canvases support \`getContext('2d')\`,
+                for example \`createCanvas\` of \`@napi-rs/canvas\` in Node.js.
+            `),
+        );
+    }
+
+    return context;
+}
+
+/**
+ * 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';

package/src/avatars/visuals/octopus2AvatarVisual.ts

@@ -2,11 +2,7 @@
 
 import { drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
-import {
-    createOrganicOctopusBodyPoints,
-    resolveOrganicEyeMotion,
-    traceSmoothClosedPath,
-} from './octopusAvatarVisualShared';
+import { createOrganicOctopusBodyPoints, resolveOrganicEyeMotion, traceSmoothClosedPath } from './octopusAvatarVisualShared';
 
 /**
  * Octopus2 avatar visual.

package/src/avatars/visuals/octopus3AvatarVisual.ts

@@ -3,14 +3,7 @@
 import { drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
 import type { OrganicTentacleShape } from './octopusAvatarVisualShared';
-import {
-    createOrganicOctopusBodyPoints,
-    createOrganicOctopusTentacleShapes,
-    getCubicBezierPoint,
-    resolveOrganicEyeMotion,
-    sampleOrganicTentacleRibbonPoints,
-    traceSmoothClosedPath,
-} from './octopusAvatarVisualShared';
+import { createOrganicOctopusBodyPoints, createOrganicOctopusTentacleShapes, getCubicBezierPoint, resolveOrganicEyeMotion, sampleOrganicTentacleRibbonPoints, traceSmoothClosedPath } from './octopusAvatarVisualShared';
 
 /**
  * Deterministic morphology knobs that keep `Octopus3` recognizable while widening seeded body, face, and tentacle variety.

package/src/avatars/visuals/octopus3d2AvatarVisual.ts

@@ -2,20 +2,11 @@
 
 import { drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
-import {
-    clampNumber,
-    crossProduct3D,
-    dotProduct3D,
-    getProjectedQuadPerimeter,
-    normalizeVector3,
-    projectScenePoint,
-    subtractPoint3D,
-    transformScenePoint,
-    type Point3D,
-    type ProjectedPoint,
-} from './avatar3dProjectionShared';
+import type { Point3D, ProjectedPoint } from './avatar3dProjectionShared';
+import { clampNumber, crossProduct3D, dotProduct3D, getProjectedQuadPerimeter, normalizeVector3, projectScenePoint, subtractPoint3D, transformScenePoint } from './avatar3dProjectionShared';
+import type { Octopus3MorphologyProfile } from './octopus3AvatarVisual';
+import { createOctopus3MorphologyProfile } from './octopus3AvatarVisual';
 import { drawProjectedOrganicEye, drawProjectedOrganicMouth, drawProjectedQuad } from './octopus3dAvatarVisualShared';
-import { createOctopus3MorphologyProfile, type Octopus3MorphologyProfile } from './octopus3AvatarVisual';
 
 /**
  * One visible projected patch on the continuous Octopus 3D 2 mesh.

package/src/avatars/visuals/octopus3d3AvatarVisual.ts

@@ -2,20 +2,11 @@
 
 import { drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
-import {
-    clampNumber,
-    crossProduct3D,
-    dotProduct3D,
-    getProjectedQuadPerimeter,
-    normalizeVector3,
-    projectScenePoint,
-    subtractPoint3D,
-    transformScenePoint,
-    type Point3D,
-    type ProjectedPoint,
-} from './avatar3dProjectionShared';
+import type { Point3D, ProjectedPoint } from './avatar3dProjectionShared';
+import { clampNumber, crossProduct3D, dotProduct3D, getProjectedQuadPerimeter, normalizeVector3, projectScenePoint, subtractPoint3D, transformScenePoint } from './avatar3dProjectionShared';
+import type { Octopus3MorphologyProfile } from './octopus3AvatarVisual';
+import { createOctopus3MorphologyProfile } from './octopus3AvatarVisual';
 import { drawProjectedOrganicEye, drawProjectedOrganicMouth, drawProjectedQuad } from './octopus3dAvatarVisualShared';
-import { createOctopus3MorphologyProfile, type Octopus3MorphologyProfile } from './octopus3AvatarVisual';
 
 /**
  * One visible projected patch on the continuous Octopus 3D 3 mesh.
@@ -502,12 +493,16 @@ function resolveVisibleContinuousOctopusPatches(
     }
 
     for (let longitudeIndex = 0; longitudeIndex < longitudePatchCount; longitudeIndex++) {
-        const patchCenterLongitude = (longitudeBoundaries[longitudeIndex]! + longitudeBoundaries[longitudeIndex + 1]!) / 2;
+        const patchCenterLongitude =
+            (longitudeBoundaries[longitudeIndex]! + longitudeBoundaries[longitudeIndex + 1]!) / 2;
         cachedTentacleInfluencesByPatchCenterLongitude[longitudeIndex] = resolveContinuousTentacleInfluence(
             options,
             patchCenterLongitude,
         );
-        cachedLobeWavesByPatchCenterLongitude[longitudeIndex] = resolveContinuousLobeWave(options, patchCenterLongitude);
+        cachedLobeWavesByPatchCenterLongitude[longitudeIndex] = resolveContinuousLobeWave(
+            options,
+            patchCenterLongitude,
+        );
         cachedCosByPatchCenterLongitude[longitudeIndex] = Math.max(0, Math.cos(patchCenterLongitude));
     }
 

package/src/avatars/visuals/octopus3d4AvatarVisual.ts

@@ -2,20 +2,11 @@
 
 import { drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
-import {
-    clampNumber,
-    crossProduct3D,
-    dotProduct3D,
-    getProjectedQuadPerimeter,
-    normalizeVector3,
-    projectScenePoint,
-    subtractPoint3D,
-    transformScenePoint,
-    type Point3D,
-    type ProjectedPoint,
-} from './avatar3dProjectionShared';
+import type { Point3D, ProjectedPoint } from './avatar3dProjectionShared';
+import { clampNumber, crossProduct3D, dotProduct3D, getProjectedQuadPerimeter, normalizeVector3, projectScenePoint, subtractPoint3D, transformScenePoint } from './avatar3dProjectionShared';
+import type { Octopus3MorphologyProfile } from './octopus3AvatarVisual';
+import { createOctopus3MorphologyProfile } from './octopus3AvatarVisual';
 import { drawProjectedOrganicEye, drawProjectedOrganicMouth, drawProjectedQuad } from './octopus3dAvatarVisualShared';
-import { createOctopus3MorphologyProfile, type Octopus3MorphologyProfile } from './octopus3AvatarVisual';
 
 /**
  * One visible projected patch on the continuous Octopus 3D 4 mesh.
@@ -193,8 +184,14 @@ export const octopus3d4AvatarVisual: AvatarVisualDefinition = {
     isAnimated: true,
     supportsPointerTracking: true,
     render({ context, size, palette, createRandom, timeMs, interaction }) {
-        const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset, tentacleProfiles, skinSpots } =
-            getOctopus3d4StableState(createRandom);
+        const {
+            morphologyProfile,
+            animationPhase,
+            leftEyePhaseOffset,
+            rightEyePhaseOffset,
+            tentacleProfiles,
+            skinSpots,
+        } = getOctopus3d4StableState(createRandom);
         const sceneCenterX = size * 0.5;
         const sceneCenterY = size * 0.535;
         const bob = Math.sin(timeMs / 980 + animationPhase) * size * 0.013;
@@ -568,7 +565,8 @@ function resolveVisibleBlobbyContinuousPatches(
     }
 
     for (let longitudeIndex = 0; longitudeIndex < longitudePatchCount; longitudeIndex++) {
-        const patchCenterLongitude = (longitudeBoundaries[longitudeIndex]! + longitudeBoundaries[longitudeIndex + 1]!) / 2;
+        const patchCenterLongitude =
+            (longitudeBoundaries[longitudeIndex]! + longitudeBoundaries[longitudeIndex + 1]!) / 2;
         cachedTentacleInfluencesByPatchCenterLongitude[longitudeIndex] = resolveBlobbyTentacleInfluence(
             options,
             patchCenterLongitude,
@@ -702,8 +700,7 @@ function sampleBlobbyContinuousSurfacePointWithLongitudeCache(
     const lowerBlend = smoothStep(0.34, 1, verticalProgress);
     const tipBlend = smoothStep(0.66, 1, verticalProgress);
     const centerPull = resolveSignedAngularDistance(longitude, tentacleInfluence.centerLongitude);
-    const effectiveLongitude =
-        longitude + centerPull * lowerBlend * tentacleInfluence.core * (0.26 + tipBlend * 0.22);
+    const effectiveLongitude = longitude + centerPull * lowerBlend * tentacleInfluence.core * (0.26 + tipBlend * 0.22);
     const mantleRipple =
         Math.sin(
             longitude * morphologyProfile.body.lobeCount +
@@ -742,10 +739,7 @@ function sampleBlobbyContinuousSurfacePointWithLongitudeCache(
         lowerBlend * tentacleInfluence.core * (0.12 + tentacleInfluence.depthScale * 0.07) -
         Math.max(0, -Math.cos(effectiveLongitude)) * 0.05;
     const tentacleTubeRadius =
-        lowerBlend *
-        tentacleInfluence.core *
-        (0.12 + tipBlend * 0.07 + tentacleInfluence.widthScale * 0.028) *
-        radiusX;
+        lowerBlend * tentacleInfluence.core * (0.12 + tipBlend * 0.07 + tentacleInfluence.widthScale * 0.028) * radiusX;
     const planarRadiusX = cosineLatitude * radiusX * horizontalScale + tentacleTubeRadius;
     const planarRadiusZ = cosineLatitude * radiusZ * depthScale + tentacleTubeRadius * 0.74;
     const lowerDrop =
@@ -759,10 +753,7 @@ function sampleBlobbyContinuousSurfacePointWithLongitudeCache(
     const combinedTentacleSway = (primaryTentacleWave + secondaryTentacleWave) * radiusX * (0.06 + tipBlend * 0.06);
 
     return {
-        x:
-            Math.sin(effectiveLongitude) * planarRadiusX +
-            combinedTentacleSway +
-            tentacleCurl * radiusX * 0.18,
+        x: Math.sin(effectiveLongitude) * planarRadiusX + combinedTentacleSway + tentacleCurl * radiusX * 0.18,
         y:
             Math.sin(latitude) * radiusY * (1 + upperBlend * 0.14) -
             upperBlend * radiusY * 0.12 +
@@ -911,11 +902,7 @@ function drawBlobbyContinuousSurfacePatch(
     drawProjectedQuad(context, surfacePatch.corners, surfacePatch.fillStyle);
 
     if (surfacePatch.lightIntensity > 0) {
-        drawProjectedQuad(
-            context,
-            surfacePatch.corners,
-            `rgba(255, 255, 255, ${0.2 * surfacePatch.lightIntensity})`,
-        );
+        drawProjectedQuad(context, surfacePatch.corners, `rgba(255, 255, 255, ${0.2 * surfacePatch.lightIntensity})`);
     } else if (surfacePatch.lightIntensity < 0) {
         drawProjectedQuad(
             context,

package/src/avatars/visuals/octopus3dAvatarVisual.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,11 +12,10 @@ import {
     projectScenePoint,
     subtractPoint3D,
     transformScenePoint,
-    type Point3D,
-    type ProjectedPoint,
 } from './avatar3dProjectionShared';
+import type { Octopus3MorphologyProfile } from './octopus3AvatarVisual';
+import { createOctopus3MorphologyProfile } from './octopus3AvatarVisual';
 import { drawProjectedOrganicEye, drawProjectedOrganicMouth, drawProjectedQuad } from './octopus3dAvatarVisualShared';
-import { createOctopus3MorphologyProfile, type Octopus3MorphologyProfile } from './octopus3AvatarVisual';
 
 /**
  * One visible projected surface patch on the octopus mesh.

package/src/avatars/visuals/octopus3dAvatarVisualShared.ts

@@ -1,13 +1,8 @@
 /* eslint-disable no-magic-numbers */
 
 import type { AvatarPalette } from '../types/AvatarVisualDefinition';
-import {
-    clampNumber,
-    projectScenePoint,
-    transformScenePoint,
-    type Point3D,
-    type ProjectedPoint,
-} from './avatar3dProjectionShared';
+import type { Point3D, ProjectedPoint } from './avatar3dProjectionShared';
+import { clampNumber, projectScenePoint, transformScenePoint } from './avatar3dProjectionShared';
 import { resolveOrganicEyeMotion } from './octopusAvatarVisualShared';
 
 // Note: [💞] Ignore a discrepancy between file name and entity name

package/src/book-2.0/agent-source/parseAgentSource/applyMetaCommitment.ts

@@ -16,6 +16,7 @@ type MetaCommitmentApplier = (state: ParseAgentSourceState, content: string) =>
  */
 const META_COMMITMENT_APPLIERS: Readonly<Record<string, MetaCommitmentApplier | undefined>> = {
     'META AVATAR': applyMetaAvatarContent,
+    'META VISUAL': applyMetaAvatarContent,
     'META LINK': applyMetaLinkContent,
     'META DOMAIN': applyMetaDomainContent,
     'META IMAGE': applyMetaImageContent,
@@ -72,7 +73,7 @@ function applyGenericMetaCommitment(state: ParseAgentSourceState, content: strin
 }
 
 /**
- * Applies META AVATAR content into the canonical `meta.avatar` field.
+ * Applies META AVATAR / META VISUAL content into the canonical `meta.avatar` field.
  */
 function applyMetaAvatarContent(state: ParseAgentSourceState, content: string): void {
     const avatarVisualId = resolveAvatarVisualId(content);

package/src/book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown.ts

@@ -1,9 +1,6 @@
 import { spaceTrim } from 'spacetrim';
 import { NotYetImplementedCommitmentDefinition } from '../../commitments/_base/NotYetImplementedCommitmentDefinition';
-import {
-    formatCommitmentReplacementText,
-    getCommitmentNoticeMetadata,
-} from '../../commitments/_common/getCommitmentNoticeMetadata';
+import { formatCommitmentReplacementText, getCommitmentNoticeMetadata } from '../../commitments/_common/getCommitmentNoticeMetadata';
 import { getGroupedCommitmentDefinitions } from '../../commitments/_common/getGroupedCommitmentDefinitions';
 import type { string_markdown } from '../../types/string_markdown';
 import { BOOK_LANGUAGE_VERSION } from '../../version';
@@ -55,6 +52,7 @@ const PROFILE_COMMITMENT_TYPES = new Set([
     'PERSONAE',
     'META',
     'META AVATAR',
+    'META VISUAL',
     'META IMAGE',
     'META LINK',
     'META DOMAIN',
@@ -333,7 +331,7 @@ export function createStandaloneBookLanguageMarkdown(): string_markdown {
             4. **Add capabilities**
             Add only necessary \`USE*\` and/or \`MEMORY\` commitments.
             5. **Set profile metadata**
-            Add \`META DESCRIPTION\`, \`META AVATAR\` or \`META IMAGE\`, \`META INPUT PLACEHOLDER\`, and disclaimers if needed.
+            Add \`META DESCRIPTION\`, \`META AVATAR\` / \`META VISUAL\` or \`META IMAGE\`, \`META INPUT PLACEHOLDER\`, and disclaimers if needed.
             6. **Add first interaction**
             Add \`INITIAL MESSAGE\` and optionally sample \`USER MESSAGE\` / \`AGENT MESSAGE\` pairs.
             7. **Close for deterministic behavior (optional)**