@promptbook/google/esm/src/avatars/types/AvatarVisualDefinition.d.ts

Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action

import type { CSSProperties } from 'react';
import type { string_css_class } from '../../types/string_markdown';
import type { string_color } from '../../types/string_person_fullname';
import type { AvatarDefinition } from './AvatarDefinition';
/**
 * Supported built-in avatar visual identifiers.
 *
 * @private shared contract for the avatar rendering system
 */
export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'octopus3' | 'octopus3d' | 'octopus3d2' | 'octopus3d3' | 'octopus3d4' | 'ascii-octopus' | 'minecraft' | 'minecraft2' | 'fractal' | 'orb';
/**
 * Derived color palette used by avatar visuals.
 *
 * @private shared contract for the avatar rendering system
 */
export type AvatarPalette = {
    readonly background: string_color;
    readonly backgroundSecondary: string_color;
    readonly primary: string_color;
    readonly secondary: string_color;
    readonly accent: string_color;
    readonly highlight: string_color;
    readonly shadow: string_color;
    readonly ink: string_color;
};
/**
 * Surface style used when placing the avatar into different UI shells.
 *
 * @private shared contract for the avatar rendering system
 */
export type AvatarSurfaceStyle = 'framed' | 'transparent';
/**
 * Pointer source currently driving avatar interaction.
 *
 * @private shared contract for the avatar rendering system
 */
export type AvatarPointerType = 'idle' | 'mouse' | 'touch' | 'pen';
/**
 * Smoothed interaction state forwarded to animated avatar visuals.
 *
 * @private shared contract for the avatar rendering system
 */
export type AvatarInteractionState = {
    readonly gazeX: number;
    readonly gazeY: number;
    readonly bodyOffsetX: number;
    readonly bodyOffsetY: number;
    readonly intensity: number;
    readonly isPointerActive: boolean;
    readonly pointerType: AvatarPointerType;
};
/**
 * Rendering context forwarded to a single avatar visual.
 *
 * @private shared contract for the avatar rendering system
 */
export type AvatarVisualRenderContext = {
    readonly canvas: HTMLCanvasElement;
    readonly context: CanvasRenderingContext2D;
    readonly size: number;
    readonly devicePixelRatio: number;
    readonly timeMs: number;
    readonly avatarDefinition: AvatarDefinition;
    readonly palette: AvatarPalette;
    readonly createRandom: (salt: string) => () => number;
    readonly surface: AvatarSurfaceStyle;
    readonly interaction: AvatarInteractionState;
};
/**
 * Signature of one canvas-based avatar visual renderer.
 *
 * @private shared contract for the avatar rendering system
 */
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.
 *
 * @private shared contract for the avatar rendering system
 */
export type AvatarVisualDefinition = {
    readonly id: AvatarVisualId;
    readonly title: string;
    readonly description: string;
    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;
};
/**
 * Props of the shared `<Avatar/>` component.
 *
 * @private shared contract for the avatar rendering system
 */
export type AvatarProps = {
    /**
     * Stable visual identity for the rendered avatar.
     */
    readonly avatarDefinition: AvatarDefinition;
    /**
     * Selected visual style.
     */
    readonly visualId: AvatarVisualId;
    /**
     * Surface used to composite the avatar in its parent UI.
     */
    readonly surface?: AvatarSurfaceStyle;
    /**
     * Output size in CSS pixels.
     */
    readonly size?: number;
    /**
     * Optional canvas title.
     */
    readonly title?: string;
    /**
     * Optional CSS class name applied to the canvas.
     */
    readonly className?: string_css_class;
    /**
     * Optional inline style applied to the canvas.
     */
    readonly style?: CSSProperties;
};
/**
 * Low-level rendering options for a single canvas frame.
 *
 * @private shared contract for the avatar rendering system
 */
export type RenderAvatarVisualOptions = {
    readonly canvas: HTMLCanvasElement;
    readonly avatarDefinition: AvatarDefinition;
    readonly visualId: AvatarVisualId;
    readonly surface?: AvatarSurfaceStyle;
    readonly size: number;
    readonly timeMs: number;
    readonly devicePixelRatio?: number;
    readonly interaction?: AvatarInteractionState;
};