@promptbook/components 0.112.0-47 → 0.112.0-48

package/umd/index.umd.js

@@ -30,7 +30,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-47';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-48';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1392,11 +1392,12 @@
      * Creates the shared derived palette used by every avatar visual.
      *
      * @param avatarDefinition Stable avatar definition.
+     * @param surface Surface style used by the parent UI.
      * @returns Derived palette.
      *
      * @private utility of the avatar rendering system
      */
-    function createAvatarPalette(avatarDefinition) {
+    function createAvatarPalette(avatarDefinition, surface = 'framed') {
         const normalizedAvatarDefinition = normalizeAvatarDefinition(avatarDefinition);
         const primaryColor = Color.fromSafe(normalizedAvatarDefinition.colors[0] || PROMPTBOOK_COLOR);
         const secondaryColor = Color.fromSafe(normalizedAvatarDefinition.colors[1] || primaryColor.then(lighten(0.12)).then(saturate(0.16)));
@@ -1406,8 +1407,8 @@
         const highlightColor = Color.fromSafe(accentColor.then(lighten(0.22)).then(saturate(0.08)));
         const shadowColor = Color.fromSafe(primaryColor.then(darken(0.46)).then(saturate(0.14)));
         return {
-            background: backgroundColor.toHex(),
-            backgroundSecondary: backgroundSecondaryColor.toHex(),
+            background: surface === 'transparent' ? 'transparent' : backgroundColor.toHex(),
+            backgroundSecondary: surface === 'transparent' ? 'transparent' : backgroundSecondaryColor.toHex(),
             primary: primaryColor.toHex(),
             secondary: secondaryColor.toHex(),
             accent: accentColor.toHex(),
@@ -1426,6 +1427,9 @@
      * @private utility of the avatar rendering system
      */
     function drawAvatarFrame(context, size, palette) {
+        if (palette.background === 'transparent' && palette.backgroundSecondary === 'transparent') {
+            return;
+        }
         const gradient = context.createLinearGradient(0, 0, size, size);
         gradient.addColorStop(0, palette.background);
         gradient.addColorStop(1, palette.backgroundSecondary);
@@ -1577,7 +1581,7 @@
      *
      * @private shared avatar contract
      */
-    const DEFAULT_AGENT_AVATAR_VISUAL_ID = 'octopus2';
+    const DEFAULT_AGENT_AVATAR_VISUAL_ID = 'octopus3';
     /**
      * Resolve a base URL for relative images, preferring the provided base or browser location.
      *
@@ -11722,6 +11726,7 @@
      * Supported USE types:
      * - USE BROWSER: Enables the agent to use a web browser tool
      * - USE SEARCH ENGINE (future): Enables search engine access
+     * - USE DEEPSEARCH: Enables deeper research-oriented search access
      * - USE FILE SYSTEM (future): Enables file system operations
      * - USE MCP (future): Enables MCP server connections
      *
@@ -11744,7 +11749,7 @@
          * Short one-line description of USE commitments.
          */
         get description() {
-            return 'Enable the agent to use specific tools or capabilities (BROWSER, SEARCH ENGINE, etc.).';
+            return 'Enable the agent to use specific tools or capabilities (BROWSER, SEARCH ENGINE, DEEPSEARCH, etc.).';
         }
         /**
          * Icon for this commitment.
@@ -11765,6 +11770,7 @@
 
             - **USE BROWSER** - Enables the agent to use a web browser tool to access and retrieve information from the internet
             - **USE SEARCH ENGINE** (future) - Enables search engine access
+            - **USE DEEPSEARCH** - Enables deeper research-oriented search access
             - **USE FILE SYSTEM** (future) - Enables file system operations
             - **USE MCP** (future) - Enables MCP server connections
 
@@ -11819,7 +11825,7 @@
          * Checks if this is a known USE type
          */
         isKnownUseType(useType) {
-            const knownTypes = ['BROWSER', 'SEARCH ENGINE', 'FILE SYSTEM', 'MCP'];
+            const knownTypes = ['BROWSER', 'SEARCH ENGINE', 'DEEPSEARCH', 'FILE SYSTEM', 'MCP'];
             return knownTypes.includes(useType.toUpperCase());
         }
     }
@@ -11832,6 +11838,7 @@
      */
     const AGGREGATED_USE_COMMITMENT_TYPES = [
         'USE BROWSER',
+        'USE DEEPSEARCH',
         'USE SEARCH ENGINE',
         'USE TIME',
     ];
@@ -11911,6 +11918,15 @@
                     - Do not tell the user you cannot search for information, YOU CAN.
                     ${block(formatOptionalInstructionBlock('Search instructions', combinedAdditionalInstructions))}
                 `);
+            case 'USE DEEPSEARCH':
+                return spacetrim.spaceTrim((block) => `
+                    Tool:
+                    - You have access to DeepSearch via the tool "deep_search".
+                    - Use it for broader research tasks that need multi-step investigation, comparison, or synthesis across multiple sources.
+                    - Prefer it over quick search when the user asks for a well-grounded brief, report, or deeper investigation.
+                    - Do not pretend you cannot research current information when this tool is available.
+                    ${block(formatOptionalInstructionBlock('DeepSearch instructions', combinedAdditionalInstructions))}
+                `);
         }
     }
     /**
@@ -13460,6 +13476,207 @@
     }
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
+    /**
+     * A search engine implementation that uses the SerpApi to fetch Google search results.
+     *
+     * @private <- TODO: !!!! Export via some package
+     */
+    class SerpSearchEngine {
+        get title() {
+            return 'SerpApi Search Engine';
+        }
+        get description() {
+            return 'Search engine that uses SerpApi to fetch Google search results';
+        }
+        checkConfiguration() {
+            if (!process.env.SERP_API_KEY) {
+                throw new Error('SERP_API_KEY is not configured');
+            }
+        }
+        async search(query, options = {}) {
+            const apiKey = process.env.SERP_API_KEY;
+            if (!apiKey) {
+                throw new Error('SERP_API_KEY is not configured');
+            }
+            const url = new URL('https://serpapi.com/search');
+            url.searchParams.set('api_key', apiKey);
+            url.searchParams.set('engine', 'google');
+            url.searchParams.set('q', query);
+            for (const [key, value] of Object.entries(options)) {
+                url.searchParams.set(key, String(value));
+            }
+            const response = await fetch(url.toString());
+            if (!response.ok) {
+                const body = await response.text();
+                throw new Error(`SerpApi failed with status ${response.status}: ${response.statusText}\n${body}`);
+            }
+            const data = (await response.json());
+            return (data.organic_results || []).map((item) => ({
+                title: item.title,
+                url: item.link,
+                snippet: item.snippet || '',
+            }));
+        }
+    }
+
+    /**
+     * Creates one SERP-backed tool function used as a local fallback for search-like commitments.
+     *
+     * @param toolName - Technical tool name used for validation messages.
+     * @param resultLabel - Human-readable label used in formatted results.
+     * @returns Async tool function compatible with commitment tool registration.
+     *
+     * @private internal helper for search-like commitments
+     */
+    function createSerpSearchToolFunction(toolName, resultLabel) {
+        return async (rawArgs) => {
+            const { query, ...searchOptions } = rawArgs;
+            if (typeof query !== 'string' || !query.trim()) {
+                throw new Error(`${toolName} query is required`);
+            }
+            const searchEngine = new SerpSearchEngine();
+            const results = await searchEngine.search(query, searchOptions);
+            return spacetrim.spaceTrim((block) => `
+                ${resultLabel} results for "${query}"${Object.keys(searchOptions).length === 0
+            ? ''
+            : ` with options ${JSON.stringify(searchOptions)}`}:
+
+                ${block(results
+            .map((result) => spacetrim.spaceTrim(`
+                                - **${result.title}**
+                                  ${result.url}
+                                  ${result.snippet}
+                            `))
+            .join('\n\n'))}
+            `);
+        };
+    }
+
+    /**
+     * USE DEEPSEARCH commitment definition
+     *
+     * The `USE DEEPSEARCH` commitment indicates that the agent should use a deeper research-oriented
+     * search workflow instead of lightweight web search when it needs fresh information from the internet.
+     *
+     * The content following `USE DEEPSEARCH` is an arbitrary text that the agent should know
+     * (e.g. search scope or research instructions).
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * USE DEEPSEARCH
+     * USE DEEPSEARCH Compare official vendor documentation with independent benchmarks.
+     * ```
+     *
+     * @private [🪔] Maybe export the commitments through some package
+     */
+    class UseDeepSearchCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('USE DEEPSEARCH');
+        }
+        get requiresContent() {
+            return false;
+        }
+        /**
+         * Short one-line description of USE DEEPSEARCH.
+         */
+        get description() {
+            return 'Enable the agent to use DeepSearch for more thorough internet research.';
+        }
+        /**
+         * Icon for this commitment.
+         */
+        get icon() {
+            return '🔬';
+        }
+        /**
+         * Markdown documentation for USE DEEPSEARCH commitment.
+         */
+        get documentation() {
+            return spacetrim.spaceTrim(`
+            # USE DEEPSEARCH
+
+            Enables the agent to use DeepSearch for broader, more thorough internet research than lightweight web search.
+
+            ## Key aspects
+
+            - The content following \`USE DEEPSEARCH\` is arbitrary guidance for the research workflow.
+            - In Agents Server, the OpenAI Agents SDK runtime uses a nested deep-research agent for this tool.
+            - Use this for investigations, comparisons, market scans, or other tasks that benefit from deeper synthesis.
+            - Prefer regular \`USE SEARCH ENGINE\` when a quick factual lookup is enough.
+
+            ## Examples
+
+            \`\`\`book
+            Due Diligence Researcher
+
+            GOAL Investigate vendors thoroughly before making recommendations.
+            USE DEEPSEARCH Compare official sources with credible third-party analysis.
+            RULE Cite the strongest supporting sources in the final answer.
+            \`\`\`
+
+            \`\`\`book
+            Market Analyst
+
+            GOAL Build concise but well-grounded research briefs.
+            USE DEEPSEARCH Focus on recent public information and competing viewpoints.
+            CLOSED
+            \`\`\`
+        `);
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            const existingTools = requirements.tools || [];
+            const updatedTools = existingTools.some((tool) => tool.name === 'deep_search')
+                ? existingTools
+                : [
+                    ...existingTools,
+                    {
+                        name: 'deep_search',
+                        description: spacetrim.spaceTrim(`
+                          Research the internet deeply and synthesize a grounded answer.
+                          Use this tool for broader investigations, comparisons, and requests that need more than a quick search.
+                      `),
+                        parameters: {
+                            type: 'object',
+                            properties: {
+                                query: {
+                                    type: 'string',
+                                    description: 'The research question or investigation request.',
+                                },
+                            },
+                            required: ['query'],
+                            additionalProperties: false,
+                        },
+                    },
+                ];
+            return appendAggregatedUseCommitmentPlaceholder({
+                ...requirements,
+                tools: updatedTools,
+                _metadata: {
+                    ...requirements._metadata,
+                    useDeepSearch: content || true,
+                },
+            }, this.type);
+        }
+        /**
+         * Gets human-readable titles for tool functions provided by this commitment.
+         */
+        getToolTitles() {
+            return {
+                deep_search: 'DeepSearch',
+            };
+        }
+        /**
+         * Gets the local fallback implementation for the `deep_search` tool.
+         */
+        getToolFunctions() {
+            return {
+                deep_search: createSerpSearchToolFunction('deep_search', 'DeepSearch'),
+            };
+        }
+    }
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+
     /**
      * Lightweight email token matcher used for `USE EMAIL` first-line parsing.
      *
@@ -15691,49 +15908,6 @@
     }
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
-    /**
-     * A search engine implementation that uses the SerpApi to fetch Google search results.
-     *
-     * @private <- TODO: !!!! Export via some package
-     */
-    class SerpSearchEngine {
-        get title() {
-            return 'SerpApi Search Engine';
-        }
-        get description() {
-            return 'Search engine that uses SerpApi to fetch Google search results';
-        }
-        checkConfiguration() {
-            if (!process.env.SERP_API_KEY) {
-                throw new Error('SERP_API_KEY is not configured');
-            }
-        }
-        async search(query, options = {}) {
-            const apiKey = process.env.SERP_API_KEY;
-            if (!apiKey) {
-                throw new Error('SERP_API_KEY is not configured');
-            }
-            const url = new URL('https://serpapi.com/search');
-            url.searchParams.set('api_key', apiKey);
-            url.searchParams.set('engine', 'google');
-            url.searchParams.set('q', query);
-            for (const [key, value] of Object.entries(options)) {
-                url.searchParams.set(key, String(value));
-            }
-            const response = await fetch(url.toString());
-            if (!response.ok) {
-                const body = await response.text();
-                throw new Error(`SerpApi failed with status ${response.status}: ${response.statusText}\n${body}`);
-            }
-            const data = (await response.json());
-            return (data.organic_results || []).map((item) => ({
-                title: item.title,
-                url: item.link,
-                snippet: item.snippet || '',
-            }));
-        }
-    }
-
     /**
      * USE SEARCH ENGINE commitment definition
      *
@@ -15877,26 +16051,7 @@
          */
         getToolFunctions() {
             return {
-                async web_search(args) {
-                    console.log('!!!! [Tool] web_search called', { args });
-                    const { query, ...options } = args;
-                    if (!query) {
-                        throw new Error('Search query is required');
-                    }
-                    const searchEngine = new SerpSearchEngine();
-                    const results = await searchEngine.search(query, options);
-                    return spacetrim.spaceTrim((block) => `
-                        Search results for "${query}"${Object.keys(options).length === 0 ? '' : ` with options ${JSON.stringify(options)}`}:
-
-                        ${block(results
-                    .map((result) => spacetrim.spaceTrim(`
-                                            - **${result.title}**
-                                              ${result.url}
-                                              ${result.snippet}
-                                        `))
-                    .join('\n\n'))}
-                    `);
-                },
+                web_search: createSerpSearchToolFunction('web_search', 'Search'),
             };
         }
     }
@@ -17542,6 +17697,7 @@
         new ClosedCommitmentDefinition(),
         new TeamCommitmentDefinition(),
         new UseBrowserCommitmentDefinition(),
+        new UseDeepSearchCommitmentDefinition(),
         new UseSearchEngineCommitmentDefinition(),
         new UseSpawnCommitmentDefinition(),
         new UseTimeoutCommitmentDefinition(),
@@ -17853,6 +18009,11 @@
             label: 'Internet',
             iconName: 'Search',
         },
+        'USE DEEPSEARCH': {
+            type: 'search-engine',
+            label: 'DeepSearch',
+            iconName: 'Search',
+        },
         'USE TIME': {
             type: 'time',
             label: 'Time',
@@ -25728,6 +25889,320 @@
                             }), children: jsxRuntime.jsx(SendIcon, { size: 25 }) })] }), speechRecognition && (jsxRuntime.jsx(ChatInputAreaDictationPanel, { bubbleText: speechRecognitionUiDescriptor.bubbleText, bubbleTone: speechRecognitionUiDescriptor.bubbleTone, shouldShowPanel: shouldShowDictationPanel, isExpanded: isDictationPanelExpanded, interimText: dictationInterimText, error: dictationError, lastFinalChunk: dictationLastFinalChunk, editableChunk: dictationEditableChunk, canBacktrack: canBacktrack, dictationSettings: dictationSettings, isBrowserSpeechFallbackSupported: isBrowserSpeechFallbackSupported, canOpenBrowserSettings: canOpenBrowserSettings, onToggleExpanded: toggleDictationPanel, onExpand: expandDictationPanel, onEditableChunkChange: setDictationEditableChunk, onRetryPermissionRequest: handleRetryPermissionRequest, onOpenBrowserSettings: handleOpenBrowserSettings, onApplyCorrection: handleApplyCorrection, onBacktrackLastChunk: handleBacktrackLastChunk, onDictationSettingChange: handleDictationSettingChange })), isUploading && (jsxRuntime.jsxs("div", { className: styles$5.uploadProgress, children: [jsxRuntime.jsx("div", { className: styles$5.uploadProgressBar, children: jsxRuntime.jsx("div", { className: styles$5.uploadProgressFill }) }), jsxRuntime.jsx("span", { children: "Uploading files..." })] })), isDragOver && onFileUpload && (jsxRuntime.jsx("div", { className: styles$5.dragOverlay, children: jsxRuntime.jsxs("div", { className: styles$5.dragOverlayContent, children: [jsxRuntime.jsx(AttachmentIcon, { size: 48 }), jsxRuntime.jsx("span", { children: "Drop files here to upload" })] }) }))] }));
     }
 
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+    /**
+     * Maximum normalized eye travel used when the viewer moves across the viewport.
+     *
+     * @private utility of the avatar rendering system
+     */
+    const MAX_GAZE_OFFSET = 0.78;
+    /**
+     * Maximum normalized body lean used for subtle mantle response.
+     *
+     * @private utility of the avatar rendering system
+     */
+    const MAX_BODY_OFFSET = 0.28;
+    /**
+     * Smoothing window used while a live pointer or touch target is active.
+     *
+     * @private utility of the avatar rendering system
+     */
+    const ACTIVE_INTERACTION_SMOOTHING_MS = 90;
+    /**
+     * Slower smoothing window used when easing the avatar back to its idle state.
+     *
+     * @private utility of the avatar rendering system
+     */
+    const IDLE_INTERACTION_SMOOTHING_MS = 230;
+    /**
+     * Maximum frame delta allowed when smoothing interaction after tab stalls.
+     *
+     * @private utility of the avatar rendering system
+     */
+    const MAX_INTERACTION_FRAME_DELTA_MS = 64;
+    /**
+     * Extra damping used for the slower body lean compared with the quicker eye motion.
+     *
+     * @private utility of the avatar rendering system
+     */
+    const BODY_INTERACTION_SMOOTHING_MULTIPLIER = 1.2;
+    /**
+     * Stable zeroed interaction state used by non-interactive render paths.
+     *
+     * @private utility of the avatar rendering system
+     */
+    const IDLE_AVATAR_INTERACTION_STATE = {
+        gazeX: 0,
+        gazeY: 0,
+        bodyOffsetX: 0,
+        bodyOffsetY: 0,
+        intensity: 0,
+        isPointerActive: false,
+        pointerType: 'idle',
+    };
+    /**
+     * Creates one stable cache key from the meaningful avatar-definition fields.
+     *
+     * @param avatarDefinition Normalized or raw avatar definition.
+     * @returns Stable cache key that ignores object identity churn.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function createAvatarDefinitionKey(avatarDefinition) {
+        const normalizedAvatarDefinition = normalizeAvatarDefinition(avatarDefinition);
+        return [
+            normalizedAvatarDefinition.agentName,
+            normalizedAvatarDefinition.agentHash,
+            normalizedAvatarDefinition.colors.join('|'),
+        ].join('::');
+    }
+    /**
+     * Returns the neutral interaction state used by static/server-side renders.
+     *
+     * @returns Zeroed interaction state.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function createIdleAvatarInteractionState() {
+        return IDLE_AVATAR_INTERACTION_STATE;
+    }
+    /**
+     * Creates a fresh runtime state for the interactive animation loop.
+     *
+     * @returns Runtime interaction state with neutral values.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function createAvatarInteractionRuntimeState() {
+        return {
+            ...IDLE_AVATAR_INTERACTION_STATE,
+            lastFrameMs: null,
+        };
+    }
+    /**
+     * Converts the shared viewport pointer state into one avatar-local gaze target.
+     *
+     * @param avatarBounds Canvas bounds in viewport coordinates.
+     * @param pointerSnapshot Latest shared pointer sample.
+     * @returns Local target used to steer eyes and subtle body lean.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function resolveAvatarPointerTarget(avatarBounds, pointerSnapshot) {
+        if (!pointerSnapshot || !pointerSnapshot.isPointerActive) {
+            return {
+                ...IDLE_AVATAR_INTERACTION_STATE,
+            };
+        }
+        const centerX = avatarBounds.left + avatarBounds.width / 2;
+        const centerY = avatarBounds.top + avatarBounds.height / 2;
+        const normalizedX = (pointerSnapshot.clientX - centerX) / Math.max(avatarBounds.width / 2, 1);
+        const normalizedY = (pointerSnapshot.clientY - centerY) / Math.max(avatarBounds.height / 2, 1);
+        const normalizedLength = Math.hypot(normalizedX, normalizedY) || 1;
+        const clampedLength = Math.min(1, normalizedLength);
+        const targetX = (normalizedX / normalizedLength) * clampedLength;
+        const targetY = (normalizedY / normalizedLength) * clampedLength;
+        const intensity = clamp01$1(clampedLength);
+        return {
+            gazeX: targetX * MAX_GAZE_OFFSET,
+            gazeY: targetY * MAX_GAZE_OFFSET,
+            bodyOffsetX: targetX * MAX_BODY_OFFSET,
+            bodyOffsetY: targetY * MAX_BODY_OFFSET,
+            intensity,
+            isPointerActive: true,
+            pointerType: pointerSnapshot.pointerType,
+        };
+    }
+    /**
+     * Advances the smoothed interaction state toward the latest pointer target.
+     *
+     * @param runtimeState Previous animation-frame state.
+     * @param pointerTarget Latest local pointer target.
+     * @param nowMs Current animation-frame timestamp.
+     * @returns Next runtime state to keep in the animation loop.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function stepAvatarInteractionRuntimeState(runtimeState, pointerTarget, nowMs) {
+        const deltaMs = runtimeState.lastFrameMs === null
+            ? 16
+            : Math.min(MAX_INTERACTION_FRAME_DELTA_MS, Math.max(8, nowMs - runtimeState.lastFrameMs));
+        const smoothingWindowMs = pointerTarget.isPointerActive
+            ? ACTIVE_INTERACTION_SMOOTHING_MS
+            : IDLE_INTERACTION_SMOOTHING_MS;
+        // This exponential interpolation keeps the gaze response smooth regardless of fluctuating frame rates.
+        return {
+            gazeX: interpolateExponentially(runtimeState.gazeX, pointerTarget.gazeX, deltaMs, smoothingWindowMs),
+            gazeY: interpolateExponentially(runtimeState.gazeY, pointerTarget.gazeY, deltaMs, smoothingWindowMs),
+            bodyOffsetX: interpolateExponentially(runtimeState.bodyOffsetX, pointerTarget.bodyOffsetX, deltaMs, smoothingWindowMs * BODY_INTERACTION_SMOOTHING_MULTIPLIER),
+            bodyOffsetY: interpolateExponentially(runtimeState.bodyOffsetY, pointerTarget.bodyOffsetY, deltaMs, smoothingWindowMs * BODY_INTERACTION_SMOOTHING_MULTIPLIER),
+            intensity: interpolateExponentially(runtimeState.intensity, pointerTarget.intensity, deltaMs, smoothingWindowMs),
+            isPointerActive: pointerTarget.isPointerActive,
+            pointerType: pointerTarget.pointerType,
+            lastFrameMs: nowMs,
+        };
+    }
+    /**
+     * Clamps a scalar into the inclusive `[0, 1]` range.
+     *
+     * @param value Arbitrary scalar.
+     * @returns Clamped scalar.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function clamp01$1(value) {
+        return Math.min(1, Math.max(0, value));
+    }
+    /**
+     * Interpolates between two values using frame-rate-independent exponential easing.
+     *
+     * @param currentValue Current smoothed value.
+     * @param targetValue Target value.
+     * @param deltaMs Elapsed milliseconds since the previous frame.
+     * @param smoothingWindowMs Time constant controlling responsiveness.
+     * @returns Smoothed next value.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function interpolateExponentially(currentValue, targetValue, deltaMs, smoothingWindowMs) {
+        const blend = 1 - Math.exp(-deltaMs / Math.max(1, smoothingWindowMs));
+        return currentValue + (targetValue - currentValue) * blend;
+    }
+
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+    /**
+     * Active avatar instances currently consuming the shared pointer tracker.
+     *
+     * @private utility of the avatar rendering system
+     */
+    let avatarPointerTrackingConsumerCount = 0;
+    /**
+     * Latest shared viewport pointer sample.
+     *
+     * @private utility of the avatar rendering system
+     */
+    let currentAvatarPointerSnapshot = null;
+    /**
+     * Cleanup function for the lazily attached global listeners.
+     *
+     * @private utility of the avatar rendering system
+     */
+    let releaseAvatarPointerTrackingListeners = null;
+    /**
+     * Starts the shared pointer tracker and returns a disposer for the caller.
+     *
+     * @returns Cleanup function that releases one consumer.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function retainAvatarPointerTracking() {
+        avatarPointerTrackingConsumerCount++;
+        if (avatarPointerTrackingConsumerCount === 1) {
+            releaseAvatarPointerTrackingListeners = attachAvatarPointerTrackingListeners();
+        }
+        return () => {
+            avatarPointerTrackingConsumerCount = Math.max(0, avatarPointerTrackingConsumerCount - 1);
+            if (avatarPointerTrackingConsumerCount === 0) {
+                currentAvatarPointerSnapshot = null;
+                releaseAvatarPointerTrackingListeners === null || releaseAvatarPointerTrackingListeners === void 0 ? void 0 : releaseAvatarPointerTrackingListeners();
+                releaseAvatarPointerTrackingListeners = null;
+            }
+        };
+    }
+    /**
+     * Returns the latest shared viewport pointer sample when available.
+     *
+     * @returns Shared pointer snapshot or `null`.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function getAvatarPointerSnapshot() {
+        return currentAvatarPointerSnapshot;
+    }
+    /**
+     * Attaches the global pointer/touch listeners used by all live avatar canvases.
+     *
+     * @returns Cleanup function for the attached listeners.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function attachAvatarPointerTrackingListeners() {
+        if (typeof window === 'undefined') {
+            return () => undefined;
+        }
+        const clearPointerSnapshot = () => {
+            currentAvatarPointerSnapshot = null;
+        };
+        const updatePointerSnapshot = (clientX, clientY, pointerType) => {
+            currentAvatarPointerSnapshot = {
+                clientX,
+                clientY,
+                isPointerActive: true,
+                pointerType,
+            };
+        };
+        const handlePointerMove = (event) => {
+            updatePointerSnapshot(event.clientX, event.clientY, normalizeAvatarPointerType(event.pointerType));
+        };
+        const handlePointerDown = (event) => {
+            updatePointerSnapshot(event.clientX, event.clientY, normalizeAvatarPointerType(event.pointerType));
+        };
+        const handlePointerUp = (event) => {
+            if (normalizeAvatarPointerType(event.pointerType) !== 'mouse') {
+                clearPointerSnapshot();
+            }
+        };
+        const handleMouseOut = (event) => {
+            if (!event.relatedTarget) {
+                clearPointerSnapshot();
+            }
+        };
+        const handleTouchEvent = (event) => {
+            const touch = event.touches[0] || event.changedTouches[0];
+            if (!touch) {
+                clearPointerSnapshot();
+                return;
+            }
+            updatePointerSnapshot(touch.clientX, touch.clientY, 'touch');
+        };
+        window.addEventListener('pointermove', handlePointerMove, { passive: true });
+        window.addEventListener('pointerdown', handlePointerDown, { passive: true });
+        window.addEventListener('pointerup', handlePointerUp, { passive: true });
+        window.addEventListener('pointercancel', clearPointerSnapshot, { passive: true });
+        window.addEventListener('mouseout', handleMouseOut, { passive: true });
+        window.addEventListener('blur', clearPointerSnapshot);
+        window.addEventListener('touchstart', handleTouchEvent, { passive: true });
+        window.addEventListener('touchmove', handleTouchEvent, { passive: true });
+        window.addEventListener('touchend', clearPointerSnapshot, { passive: true });
+        window.addEventListener('touchcancel', clearPointerSnapshot, { passive: true });
+        return () => {
+            window.removeEventListener('pointermove', handlePointerMove);
+            window.removeEventListener('pointerdown', handlePointerDown);
+            window.removeEventListener('pointerup', handlePointerUp);
+            window.removeEventListener('pointercancel', clearPointerSnapshot);
+            window.removeEventListener('mouseout', handleMouseOut);
+            window.removeEventListener('blur', clearPointerSnapshot);
+            window.removeEventListener('touchstart', handleTouchEvent);
+            window.removeEventListener('touchmove', handleTouchEvent);
+            window.removeEventListener('touchend', clearPointerSnapshot);
+            window.removeEventListener('touchcancel', clearPointerSnapshot);
+        };
+    }
+    /**
+     * Normalizes browser pointer-type strings into the shared avatar contract.
+     *
+     * @param pointerType Raw browser pointer type.
+     * @returns Shared pointer type.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function normalizeAvatarPointerType(pointerType) {
+        if (pointerType === 'touch' || pointerType === 'pen') {
+            return pointerType;
+        }
+        return 'mouse';
+    }
+
     /* eslint-disable no-magic-numbers */
     /**
      * Builds a smoothly morphing octopus-like silhouette from deterministic parameters.
@@ -25804,8 +26279,9 @@
      * @private shared geometry helper of `octopus3AvatarVisual` and `asciiOctopusAvatarVisual`
      */
     function createOrganicOctopusTentacleShapes(options) {
-        const { size, centerX, centerY, bodyRadius, horizontalStretch, tentacleCount, shapePhase, createRandom, timeMs, saltPrefix, } = options;
+        const { size, centerX, centerY, bodyRadius, horizontalStretch, tentacleCount, shapePhase, createRandom, timeMs, saltPrefix, bodyPoints } = options;
         const baseY = centerY + bodyRadius * 0.74;
+        const lowerBodyAnchorPoints = bodyPoints ? resolveTentacleBodyAnchorPoints(bodyPoints, centerY + bodyRadius * 0.04) : null;
         return Array.from({ length: tentacleCount }, (_, tentacleIndex) => {
             const tentacleRandom = createRandom(`${saltPrefix}-tentacle-${tentacleIndex}`);
             const spreadProgress = tentacleCount === 1 ? 0.5 : tentacleIndex / (tentacleCount - 1);
@@ -25817,10 +26293,21 @@
             const curlDirection = centeredProgress === 0 ? (tentacleRandom() < 0.5 ? -1 : 1) : Math.sign(centeredProgress);
             const lateralReach = centeredProgress * size * (0.1 + tentacleRandom() * 0.1) + temporalSway;
             const tipReach = curlDirection * size * (0.025 + tentacleRandom() * 0.07);
-            const startPoint = {
-                x: centerX + centeredProgress * bodyRadius * horizontalStretch * 1.52,
-                y: baseY + Math.abs(centeredProgress) * size * 0.012 + tentacleRandom() * size * 0.01,
-            };
+            const startYOffset = Math.abs(centeredProgress) * size * 0.012 + tentacleRandom() * size * 0.01;
+            const startPoint = lowerBodyAnchorPoints && lowerBodyAnchorPoints.length >= 2
+                ? createInsetTentacleStartPoint({
+                    bodyPoints: lowerBodyAnchorPoints,
+                    anchorProgress: spreadProgress,
+                    centerX,
+                    centerY,
+                    bodyRadius,
+                    centeredProgress,
+                    startYOffset,
+                })
+                : {
+                    x: centerX + centeredProgress * bodyRadius * horizontalStretch * 1.52,
+                    y: baseY + startYOffset,
+                };
             const controlPointOne = {
                 x: startPoint.x + centeredProgress * size * 0.045 + temporalSway * 0.4,
                 y: startPoint.y + flowLength * (0.21 + tentacleRandom() * 0.08),
@@ -25850,6 +26337,67 @@
             };
         });
     }
+    /**
+     * Narrows the body contour to lower anchor points that can safely host tentacle roots.
+     *
+     * @param bodyPoints Generated closed-loop body points.
+     * @param lowerBodyThresholdY Minimum Y coordinate considered part of the lower mantle.
+     * @returns Body points sorted from left to right across the lower silhouette.
+     *
+     * @private shared geometry helper of `octopus3AvatarVisual`
+     */
+    function resolveTentacleBodyAnchorPoints(bodyPoints, lowerBodyThresholdY) {
+        const lowerBodyPoints = bodyPoints.filter((bodyPoint) => bodyPoint.y >= lowerBodyThresholdY).sort((leftPoint, rightPoint) => leftPoint.x - rightPoint.x);
+        if (lowerBodyPoints.length >= 2) {
+            return lowerBodyPoints;
+        }
+        return [...bodyPoints].sort((leftPoint, rightPoint) => leftPoint.x - rightPoint.x);
+    }
+    /**
+     * Resolves one tentacle root from the provided lower body contour and nudges it inside the mantle.
+     *
+     * @param options Tentacle anchor options.
+     * @returns Tentacle start point safely embedded inside the body silhouette.
+     *
+     * @private shared geometry helper of `octopus3AvatarVisual`
+     */
+    function createInsetTentacleStartPoint(options) {
+        const { bodyPoints, anchorProgress, centerX, centerY, bodyRadius, centeredProgress, startYOffset } = options;
+        const clampedAnchorProgress = Math.min(0.94, Math.max(0.06, anchorProgress));
+        const bodyAnchorPoint = interpolatePointAlongTentacleAnchors(bodyPoints, clampedAnchorProgress);
+        const inwardX = centerX - bodyAnchorPoint.x;
+        const inwardY = centerY + bodyRadius * 0.08 - bodyAnchorPoint.y;
+        const inwardLength = Math.hypot(inwardX, inwardY) || 1;
+        const insetDistance = bodyRadius * (0.12 + Math.abs(centeredProgress) * 0.05) + startYOffset * 0.32;
+        return {
+            x: bodyAnchorPoint.x + (inwardX / inwardLength) * insetDistance,
+            y: bodyAnchorPoint.y + (inwardY / inwardLength) * insetDistance,
+        };
+    }
+    /**
+     * Interpolates one left-to-right anchor point along the prepared lower body contour.
+     *
+     * @param bodyPoints Lower body contour points sorted from left to right.
+     * @param progress Interpolation progress in the range `[0, 1]`.
+     * @returns Interpolated anchor point.
+     *
+     * @private shared geometry helper of `octopus3AvatarVisual`
+     */
+    function interpolatePointAlongTentacleAnchors(bodyPoints, progress) {
+        if (bodyPoints.length === 1) {
+            return bodyPoints[0];
+        }
+        const anchorIndex = progress * (bodyPoints.length - 1);
+        const startIndex = Math.floor(anchorIndex);
+        const endIndex = Math.min(bodyPoints.length - 1, startIndex + 1);
+        const blend = anchorIndex - startIndex;
+        const startPoint = bodyPoints[startIndex];
+        const endPoint = bodyPoints[endIndex];
+        return {
+            x: startPoint.x + (endPoint.x - startPoint.x) * blend,
+            y: startPoint.y + (endPoint.y - startPoint.y) * blend,
+        };
+    }
     /**
      * Samples the cubic tentacle centerline and offsets normals to build a filled ribbon.
      *
@@ -25879,6 +26427,26 @@
             };
         });
     }
+    /**
+     * Resolves smooth pupil offsets that blend autonomous idle drift with live viewer tracking.
+     *
+     * @param options Eye motion options.
+     * @returns Resolved pupil offsets.
+     *
+     * @private shared geometry helper of octopus avatar visuals
+     */
+    function resolveOrganicEyeMotion(options) {
+        const { radiusX, radiusY, timeMs, phase, interaction, autonomousDriftRatioX = 0.12, autonomousDriftRatioY = 0.08, } = options;
+        const autonomousOffsetX = Math.sin(timeMs / 1280 + phase) * radiusX * autonomousDriftRatioX;
+        const autonomousOffsetY = Math.cos(timeMs / 940 + phase) * radiusY * autonomousDriftRatioY;
+        const interactionBlend = Math.min(1, interaction.intensity * 0.9);
+        return {
+            pupilOffsetX: autonomousOffsetX * (1 - interactionBlend) +
+                interaction.gazeX * radiusX * (0.18 + interactionBlend * 0.18),
+            pupilOffsetY: autonomousOffsetY * (1 - interactionBlend) +
+                interaction.gazeY * radiusY * (0.16 + interactionBlend * 0.16),
+        };
+    }
     /**
      * Samples one point on a cubic Bezier curve.
      *
@@ -25932,13 +26500,14 @@
     const asciiOctopusAvatarVisual = {
         id: 'ascii-octopus',
         title: 'AsciiOctopus',
-        description: 'Morphing alien octopus translated into animated ASCII glyphs with deterministic blob and tentacle geometry.',
+        description: 'Morphing alien octopus translated into animated ASCII glyphs with responsive eyes and seeded geometry.',
         isAnimated: true,
-        render({ context, size, palette, createRandom, timeMs }) {
+        supportsPointerTracking: true,
+        render({ context, size, palette, createRandom, timeMs, interaction }) {
             const gridRandom = createRandom('ascii-octopus-grid');
             const staticRandom = createRandom('ascii-octopus-static');
             const gridMetrics = createAsciiGridMetrics(size, gridRandom);
-            const layout = createAsciiOctopusLayout(size, timeMs, createRandom, staticRandom);
+            const layout = createAsciiOctopusLayout(size, timeMs, createRandom, staticRandom, interaction);
             drawAvatarFrame(context, size, palette);
             drawAsciiBackdrop(context, size, palette, layout, timeMs);
             context.save();
@@ -26012,7 +26581,8 @@
      */
     function resolveAsciiGlyph(options) {
         const { point, layout, palette, cellWidth, cellHeight, noise, timeMs } = options;
-        const eyeGlyphDescriptor = resolveEyeGlyph(point, layout.leftEye, palette, timeMs) || resolveEyeGlyph(point, layout.rightEye, palette, timeMs);
+        const eyeGlyphDescriptor = resolveEyeGlyph(point, layout.leftEye, layout.interaction, palette, timeMs) ||
+            resolveEyeGlyph(point, layout.rightEye, layout.interaction, palette, timeMs);
         if (eyeGlyphDescriptor) {
             return eyeGlyphDescriptor;
         }
@@ -26057,9 +26627,14 @@
      *
      * @private helper of `asciiOctopusAvatarVisual`
      */
-    function resolveEyeGlyph(point, eyeFeature, palette, timeMs) {
-        const pupilOffsetX = Math.sin(timeMs / 1280 + eyeFeature.phase) * eyeFeature.radiusX * 0.12;
-        const pupilOffsetY = Math.cos(timeMs / 940 + eyeFeature.phase) * eyeFeature.radiusY * 0.08;
+    function resolveEyeGlyph(point, eyeFeature, interaction, palette, timeMs) {
+        const { pupilOffsetX, pupilOffsetY } = resolveOrganicEyeMotion({
+            radiusX: eyeFeature.radiusX,
+            radiusY: eyeFeature.radiusY,
+            timeMs,
+            phase: eyeFeature.phase,
+            interaction,
+        });
         const scleraDistance = measureRotatedEllipseDistance(point, eyeFeature.centerX, eyeFeature.centerY, eyeFeature.radiusX, eyeFeature.radiusY, eyeFeature.rotation);
         if (scleraDistance > 1.08) {
             return null;
@@ -26233,9 +26808,9 @@
      *
      * @private helper of `asciiOctopusAvatarVisual`
      */
-    function createAsciiOctopusLayout(size, timeMs, createRandom, staticRandom) {
-        const centerX = size * (0.5 + (staticRandom() - 0.5) * 0.02);
-        const centerY = size * (0.41 + staticRandom() * 0.05);
+    function createAsciiOctopusLayout(size, timeMs, createRandom, staticRandom, interaction) {
+        const centerX = size * (0.5 + (staticRandom() - 0.5) * 0.02) + interaction.bodyOffsetX * size * 0.05;
+        const centerY = size * (0.41 + staticRandom() * 0.05) + interaction.bodyOffsetY * size * 0.035;
         const bodyRadius = size * (0.195 + staticRandom() * 0.05);
         const horizontalStretch = 1.08 + staticRandom() * 0.22;
         const verticalStretch = 0.88 + staticRandom() * 0.14;
@@ -26275,6 +26850,7 @@
             createRandom,
             timeMs,
             saltPrefix: 'ascii-octopus',
+            bodyPoints,
         });
         const sampledTentacles = tentacleShapes.map(sampleOrganicTentacleRibbonPoints);
         const leftEye = {
@@ -26295,7 +26871,7 @@
         };
         const mouthPoints = sampleQuadraticBezierPoints({ x: centerX - size * 0.074, y: centerY + size * 0.092 }, {
             x: centerX,
-            y: centerY + size * (0.142 + Math.sin(timeMs / 620 + shapePhase) * 0.016),
+            y: centerY + size * (0.142 + Math.sin(timeMs / 620 + shapePhase) * 0.016) + interaction.gazeY * size * 0.012,
         }, { x: centerX + size * 0.074, y: centerY + size * 0.092 }, 12);
         let leftBound = Number.POSITIVE_INFINITY;
         let rightBound = Number.NEGATIVE_INFINITY;
@@ -26321,6 +26897,7 @@
             bodyRadius,
             horizontalStretch,
             shapePhase,
+            interaction,
             bodyPoints,
             sampledTentacles,
             leftEye,
@@ -27041,15 +27618,16 @@
     const octopusAvatarVisual = {
         id: 'octopus',
         title: 'Octopus',
-        description: 'Playful underwater mascot with animated tentacles, bubbles, and seed-based markings.',
+        description: 'Playful underwater mascot with cursor-following eyes, animated tentacles, bubbles, and seeded markings.',
         isAnimated: true,
-        render({ context, size, palette, createRandom, timeMs }) {
+        supportsPointerTracking: true,
+        render({ context, size, palette, createRandom, timeMs, interaction }) {
             const staticRandom = createRandom('octopus-static');
             const bubbleRandom = createRandom('octopus-bubbles');
             const bubbleCount = 8;
             const bubbleRadiusBase = size * 0.02;
-            const centerX = size * 0.5;
-            const centerY = size * 0.42;
+            const centerX = size * 0.5 + interaction.bodyOffsetX * size * 0.035;
+            const centerY = size * 0.42 + interaction.bodyOffsetY * size * 0.024;
             const headRadius = size * (0.19 + staticRandom() * 0.03);
             const mantleHeight = headRadius * 1.18;
             const tentacleLength = size * (0.18 + staticRandom() * 0.06);
@@ -27129,11 +27707,9 @@
             }
             const eyeOffsetX = headRadius * 0.42;
             const eyeY = centerY + headRadius * 0.04;
-            const pupilDriftX = Math.sin(timeMs / 850) * headRadius * 0.05;
-            const pupilDriftY = Math.cos(timeMs / 930) * headRadius * 0.03;
             const eyeRadius = headRadius * 0.22;
-            drawEye(context, centerX - eyeOffsetX, eyeY, eyeRadius, palette, pupilDriftX, pupilDriftY);
-            drawEye(context, centerX + eyeOffsetX, eyeY, eyeRadius, palette, pupilDriftX, pupilDriftY);
+            drawEye(context, centerX - eyeOffsetX, eyeY, eyeRadius, palette, timeMs, interaction, 0);
+            drawEye(context, centerX + eyeOffsetX, eyeY, eyeRadius, palette, timeMs, interaction, Math.PI / 5);
             context.beginPath();
             context.arc(centerX - headRadius * 0.28, centerY + headRadius * 0.3, headRadius * 0.12, 0, Math.PI * 2);
             context.arc(centerX + headRadius * 0.28, centerY + headRadius * 0.3, headRadius * 0.12, 0, Math.PI * 2);
@@ -27156,22 +27732,32 @@
      * @param centerY Eye center Y coordinate.
      * @param radius Eye radius.
      * @param palette Derived avatar palette.
-     * @param pupilDriftX Horizontal pupil drift.
-     * @param pupilDriftY Vertical pupil drift.
+     * @param timeMs Current animation time in milliseconds.
+     * @param interaction Smoothed avatar interaction state.
+     * @param phase Seed-based phase offset.
      *
      * @private helper of `octopusAvatarVisual`
      */
-    function drawEye(context, centerX, centerY, radius, palette, pupilDriftX, pupilDriftY) {
+    function drawEye(context, centerX, centerY, radius, palette, timeMs, interaction, phase) {
+        const { pupilOffsetX, pupilOffsetY } = resolveOrganicEyeMotion({
+            radiusX: radius,
+            radiusY: radius,
+            timeMs,
+            phase,
+            interaction,
+            autonomousDriftRatioX: 0.05,
+            autonomousDriftRatioY: 0.03,
+        });
         context.beginPath();
         context.arc(centerX, centerY, radius, 0, Math.PI * 2);
         context.fillStyle = '#ffffff';
         context.fill();
         context.beginPath();
-        context.arc(centerX + pupilDriftX, centerY + pupilDriftY, radius * 0.45, 0, Math.PI * 2);
+        context.arc(centerX + pupilOffsetX, centerY + pupilOffsetY, radius * 0.45, 0, Math.PI * 2);
         context.fillStyle = palette.ink;
         context.fill();
         context.beginPath();
-        context.arc(centerX + pupilDriftX - radius * 0.12, centerY + pupilDriftY - radius * 0.12, radius * 0.15, 0, Math.PI * 2);
+        context.arc(centerX + pupilOffsetX - radius * 0.12, centerY + pupilOffsetY - radius * 0.12, radius * 0.15, 0, Math.PI * 2);
         context.fillStyle = '#ffffff';
         context.fill();
         context.beginPath();
@@ -27190,12 +27776,13 @@
     const octopus2AvatarVisual = {
         id: 'octopus2',
         title: 'Octopus2',
-        description: 'Organic alien octopus rendered as one continuously morphing blob with luminous eyes and soft inner motion.',
+        description: 'Organic alien octopus rendered as one continuously morphing blob with responsive luminous eyes.',
         isAnimated: true,
-        render({ context, size, palette, createRandom, timeMs }) {
+        supportsPointerTracking: true,
+        render({ context, size, palette, createRandom, timeMs, interaction }) {
             const staticRandom = createRandom('octopus2-static');
-            const centerX = size * 0.5;
-            const centerY = size * (0.48 + staticRandom() * 0.03);
+            const centerX = size * 0.5 + interaction.bodyOffsetX * size * 0.042;
+            const centerY = size * (0.48 + staticRandom() * 0.03) + interaction.bodyOffsetY * size * 0.028;
             const bodyRadius = size * (0.25 + staticRandom() * 0.035);
             const horizontalStretch = 1.04 + staticRandom() * 0.16;
             const verticalStretch = 0.94 + staticRandom() * 0.12;
@@ -27266,11 +27853,11 @@
             const eyeCenterY = centerY - size * 0.02;
             const eyeRadiusX = size * 0.072;
             const eyeRadiusY = size * 0.086;
-            drawAlienEye(context, centerX - eyeOffsetX, eyeCenterY, eyeRadiusX, eyeRadiusY, palette, timeMs, shapePhase);
-            drawAlienEye(context, centerX + eyeOffsetX, eyeCenterY, eyeRadiusX, eyeRadiusY, palette, timeMs, shapePhase + Math.PI / 5);
+            drawAlienEye(context, centerX - eyeOffsetX, eyeCenterY, eyeRadiusX, eyeRadiusY, palette, timeMs, shapePhase, interaction);
+            drawAlienEye(context, centerX + eyeOffsetX, eyeCenterY, eyeRadiusX, eyeRadiusY, palette, timeMs, shapePhase + Math.PI / 5, interaction);
             context.beginPath();
             context.moveTo(centerX - size * 0.08, centerY + size * 0.12);
-            context.quadraticCurveTo(centerX, centerY + size * (0.175 + Math.sin(timeMs / 520 + shapePhase) * 0.012), centerX + size * 0.08, centerY + size * 0.12);
+            context.quadraticCurveTo(centerX, centerY + size * (0.175 + Math.sin(timeMs / 520 + shapePhase) * 0.012) + interaction.gazeY * size * 0.01, centerX + size * 0.08, centerY + size * 0.12);
             context.strokeStyle = `${palette.ink}b3`;
             context.lineWidth = size * 0.013;
             context.lineCap = 'round';
@@ -27348,12 +27935,19 @@
      * @param palette Derived avatar palette.
      * @param timeMs Current animation time in milliseconds.
      * @param phase Seed-based animation phase.
+     * @param interaction Smoothed avatar interaction state.
      *
      * @private helper of `octopus2AvatarVisual`
      */
-    function drawAlienEye(context, centerX, centerY, radiusX, radiusY, palette, timeMs, phase) {
-        const pupilOffsetX = Math.sin(timeMs / 1300 + phase) * radiusX * 0.12;
-        const pupilOffsetY = Math.cos(timeMs / 970 + phase) * radiusY * 0.1;
+    function drawAlienEye(context, centerX, centerY, radiusX, radiusY, palette, timeMs, phase, interaction) {
+        const { pupilOffsetX, pupilOffsetY } = resolveOrganicEyeMotion({
+            radiusX,
+            radiusY,
+            timeMs,
+            phase,
+            interaction,
+            autonomousDriftRatioY: 0.1,
+        });
         context.save();
         context.beginPath();
         context.ellipse(centerX, centerY, radiusX, radiusY, 0, 0, Math.PI * 2);
@@ -27393,12 +27987,13 @@
     const octopus3AvatarVisual = {
         id: 'octopus3',
         title: 'Octopus3',
-        description: 'Gelatinous alien octopus with a morphing mantle, visible ribbon tentacles, and seeded facial features.',
+        description: 'Gelatinous alien octopus with a morphing mantle, responsive eyes, and visible ribbon tentacles.',
         isAnimated: true,
-        render({ context, size, palette, createRandom, timeMs }) {
+        supportsPointerTracking: true,
+        render({ context, size, palette, createRandom, timeMs, interaction }) {
             const staticRandom = createRandom('octopus3-static');
-            const centerX = size * (0.5 + (staticRandom() - 0.5) * 0.02);
-            const centerY = size * (0.41 + staticRandom() * 0.05);
+            const centerX = size * (0.5 + (staticRandom() - 0.5) * 0.02) + interaction.bodyOffsetX * size * 0.05;
+            const centerY = size * (0.41 + staticRandom() * 0.05) + interaction.bodyOffsetY * size * 0.035;
             const bodyRadius = size * (0.2 + staticRandom() * 0.045);
             const horizontalStretch = 1.08 + staticRandom() * 0.22;
             const verticalStretch = 0.9 + staticRandom() * 0.12;
@@ -27438,6 +28033,7 @@
                 createRandom,
                 timeMs,
                 saltPrefix: 'octopus3',
+                bodyPoints,
             });
             drawAvatarFrame(context, size, palette);
             drawOctopus3Atmosphere(context, size, palette, centerX, centerY, timeMs, shapePhase);
@@ -27483,11 +28079,11 @@
             context.ellipse(centerX, centerY - size * 0.14, size * 0.18, size * 0.062, 0, Math.PI, Math.PI * 2);
             context.fillStyle = `${palette.highlight}3d`;
             context.fill();
-            drawSeededEye(context, centerX - eyeSpacing, centerY - size * 0.01, eyeRadiusX, eyeRadiusY, (staticRandom() - 0.5) * 0.28, palette, timeMs, shapePhase);
-            drawSeededEye(context, centerX + eyeSpacing, centerY - size * 0.01, eyeRadiusX, eyeRadiusY, (staticRandom() - 0.5) * 0.28, palette, timeMs, shapePhase + Math.PI / 4);
+            drawSeededEye(context, centerX - eyeSpacing, centerY - size * 0.01, eyeRadiusX, eyeRadiusY, (staticRandom() - 0.5) * 0.28, palette, timeMs, shapePhase, interaction);
+            drawSeededEye(context, centerX + eyeSpacing, centerY - size * 0.01, eyeRadiusX, eyeRadiusY, (staticRandom() - 0.5) * 0.28, palette, timeMs, shapePhase + Math.PI / 4, interaction);
             context.beginPath();
             context.moveTo(centerX - size * 0.07, centerY + size * 0.09);
-            context.quadraticCurveTo(centerX, centerY + size * (0.14 + Math.sin(timeMs / 620 + shapePhase) * 0.016), centerX + size * 0.07, centerY + size * 0.09);
+            context.quadraticCurveTo(centerX, centerY + size * (0.14 + Math.sin(timeMs / 620 + shapePhase) * 0.016) + interaction.gazeY * size * 0.012, centerX + size * 0.07, centerY + size * 0.09);
             context.strokeStyle = `${palette.ink}b3`;
             context.lineWidth = size * 0.012;
             context.lineCap = 'round';
@@ -27675,12 +28271,18 @@
      * @param palette Derived avatar palette.
      * @param timeMs Current animation time in milliseconds.
      * @param phase Seed-based animation phase.
+     * @param interaction Smoothed avatar interaction state.
      *
      * @private helper of `octopus3AvatarVisual`
      */
-    function drawSeededEye(context, centerX, centerY, radiusX, radiusY, rotation, palette, timeMs, phase) {
-        const pupilOffsetX = Math.sin(timeMs / 1280 + phase) * radiusX * 0.12;
-        const pupilOffsetY = Math.cos(timeMs / 940 + phase) * radiusY * 0.08;
+    function drawSeededEye(context, centerX, centerY, radiusX, radiusY, rotation, palette, timeMs, phase, interaction) {
+        const { pupilOffsetX, pupilOffsetY } = resolveOrganicEyeMotion({
+            radiusX,
+            radiusY,
+            timeMs,
+            phase,
+            interaction,
+        });
         context.save();
         context.translate(centerX, centerY);
         context.rotate(rotation);
@@ -27716,7 +28318,7 @@
         context.stroke();
         context.beginPath();
         context.moveTo(-radiusX * 0.88, -radiusY * 0.08);
-        context.quadraticCurveTo(0, -radiusY * 0.9, radiusX * 0.88, -radiusY * 0.08);
+        context.quadraticCurveTo(0, -radiusY * (0.9 - interaction.gazeY * 0.16 + interaction.intensity * 0.08), radiusX * 0.88, -radiusY * 0.08);
         context.strokeStyle = `${palette.shadow}73`;
         context.lineWidth = radiusX * 0.16;
         context.lineCap = 'round';
@@ -27864,6 +28466,7 @@
     function renderAvatarVisual(options) {
         const normalizedAvatarDefinition = normalizeAvatarDefinition(options.avatarDefinition);
         const avatarVisual = getAvatarVisualById(options.visualId);
+        const surface = options.surface || 'framed';
         const context = options.canvas.getContext('2d');
         if (!context) {
             throw new Error('2D canvas rendering context is unavailable.');
@@ -27876,8 +28479,10 @@
             devicePixelRatio: options.devicePixelRatio || 1,
             timeMs: options.timeMs,
             avatarDefinition: normalizedAvatarDefinition,
-            palette: createAvatarPalette(normalizedAvatarDefinition),
+            palette: createAvatarPalette(normalizedAvatarDefinition, surface),
             createRandom: createAvatarRandomFactory(normalizedAvatarDefinition),
+            surface,
+            interaction: options.interaction || createIdleAvatarInteractionState(),
         });
     }
 
@@ -27893,42 +28498,74 @@
      * @private shared component for in-repository avatar previews
      */
     function Avatar(props) {
-        const { avatarDefinition, visualId, size = DEFAULT_AVATAR_SIZE, title, className, style } = props;
+        const { avatarDefinition, visualId, surface = 'framed', size = DEFAULT_AVATAR_SIZE, title, className, style } = props;
         const canvasRef = react.useRef(null);
-        const normalizedAvatarDefinition = react.useMemo(() => normalizeAvatarDefinition(avatarDefinition), [avatarDefinition]);
+        const animationStartRef = react.useRef(null);
+        const interactionRuntimeStateRef = react.useRef(createAvatarInteractionRuntimeState());
+        const avatarColorsKey = avatarDefinition.colors.join('|');
+        const normalizedAvatarDefinition = react.useMemo(() => normalizeAvatarDefinition(avatarDefinition), [avatarDefinition.agentHash, avatarDefinition.agentName, avatarColorsKey]);
+        const avatarDefinitionKey = react.useMemo(() => createAvatarDefinitionKey(normalizedAvatarDefinition), [normalizedAvatarDefinition.agentHash, normalizedAvatarDefinition.agentName, normalizedAvatarDefinition.colors.join('|')]);
         const avatarVisual = react.useMemo(() => getAvatarVisualById(visualId), [visualId]);
+        react.useEffect(() => {
+            interactionRuntimeStateRef.current = createAvatarInteractionRuntimeState();
+        }, [avatarDefinitionKey, visualId]);
         react.useEffect(() => {
             const canvas = canvasRef.current;
             if (!canvas) {
                 throw new Error('Avatar canvas is not mounted.');
             }
+            const isDynamicAvatar = avatarVisual.isAnimated || avatarVisual.supportsPointerTracking === true;
+            const releasePointerTracking = avatarVisual.supportsPointerTracking ? retainAvatarPointerTracking() : null;
             let animationFrameId = null;
-            const animationStart = performance.now();
+            if (animationStartRef.current === null) {
+                animationStartRef.current = performance.now();
+            }
             const renderFrame = (now) => {
+                const pointerSnapshot = avatarVisual.supportsPointerTracking ? getAvatarPointerSnapshot() : null;
+                let interactionState = createIdleAvatarInteractionState();
+                if (avatarVisual.supportsPointerTracking && pointerSnapshot) {
+                    interactionRuntimeStateRef.current = stepAvatarInteractionRuntimeState(interactionRuntimeStateRef.current, resolveAvatarPointerTarget(canvas.getBoundingClientRect(), pointerSnapshot), now);
+                    interactionState = interactionRuntimeStateRef.current;
+                }
+                else if (avatarVisual.supportsPointerTracking) {
+                    interactionRuntimeStateRef.current = stepAvatarInteractionRuntimeState(interactionRuntimeStateRef.current, createIdleAvatarInteractionState(), now);
+                    interactionState = interactionRuntimeStateRef.current;
+                }
                 renderAvatarVisual({
                     canvas,
                     avatarDefinition: normalizedAvatarDefinition,
                     visualId,
+                    surface,
                     size,
-                    timeMs: now - animationStart,
+                    timeMs: now - animationStartRef.current,
                     devicePixelRatio: window.devicePixelRatio || 1,
+                    interaction: interactionState,
                 });
-                if (avatarVisual.isAnimated) {
+                if (isDynamicAvatar) {
                     animationFrameId = window.requestAnimationFrame(renderFrame);
                 }
             };
-            renderFrame(animationStart);
+            renderFrame(performance.now());
             return () => {
                 if (animationFrameId !== null) {
                     window.cancelAnimationFrame(animationFrameId);
                 }
+                releasePointerTracking === null || releasePointerTracking === void 0 ? void 0 : releasePointerTracking();
             };
-        }, [avatarVisual.isAnimated, normalizedAvatarDefinition, size, visualId]);
+        }, [
+            avatarDefinitionKey,
+            avatarVisual.isAnimated,
+            avatarVisual.supportsPointerTracking,
+            normalizedAvatarDefinition,
+            size,
+            surface,
+            visualId,
+        ]);
         return (jsxRuntime.jsx("canvas", { ref: canvasRef, title: title || `${normalizedAvatarDefinition.agentName} avatar`, className: className, style: {
                 width: size,
                 height: size,
                 display: 'block',
-                borderRadius: size * AVATAR_CANVAS_RADIUS_RATIO,
+                borderRadius: surface === 'transparent' ? 0 : size * AVATAR_CANVAS_RADIUS_RATIO,
                 ...style,
             } }));
     }
@@ -27939,9 +28576,9 @@
      * @private shared component for avatar media rendering
      */
     function AvatarOrImage(props) {
-        const { imageUrl, avatarDefinition, visualId, size, alt, className, style } = props;
+        const { imageUrl, avatarDefinition, visualId, surface, size, alt, className, style } = props;
         if (avatarDefinition && visualId) {
-            return (jsxRuntime.jsx(Avatar, { avatarDefinition: avatarDefinition, visualId: visualId, size: size, title: alt, className: className, style: style }));
+            return (jsxRuntime.jsx(Avatar, { avatarDefinition: avatarDefinition, visualId: visualId, surface: surface, size: size, title: alt, className: className, style: style }));
         }
         if (!imageUrl) {
             return null;
@@ -38549,6 +39186,14 @@
      * Constant for default agent kit model name.
      */
     const DEFAULT_AGENT_KIT_MODEL_NAME = 'gpt-5.4-mini';
+    /**
+     * Default model used for nested DeepSearch tool invocations.
+     */
+    const DEFAULT_DEEP_SEARCH_MODEL_NAME = 'o4-mini-deep-research';
+    /**
+     * Tool name used by the Book commitment-backed DeepSearch capability.
+     */
+    const DEEP_SEARCH_TOOL_NAME = 'deep_search';
     /**
      * Creates one structured log entry for streamed tool-call updates.
      *
@@ -38591,6 +39236,98 @@
         }
         return 'COMPLETE';
     }
+    /**
+     * Returns true when one tool definition represents the dedicated DeepSearch capability.
+     *
+     * @param toolDefinition - Tool definition from compiled model requirements.
+     * @returns `true` when the tool should be backed by a nested deep-research agent.
+     *
+     * @private helper of `OpenAiAgentKitExecutionTools`
+     */
+    function isDeepSearchToolDefinition(toolDefinition) {
+        return toolDefinition.name === DEEP_SEARCH_TOOL_NAME;
+    }
+    /**
+     * Normalizes Promptbook JSON-schema tool parameters for AgentKit function tools.
+     *
+     * @param parameters - Promptbook tool parameters.
+     * @returns AgentKit-compatible JSON schema or `undefined`.
+     *
+     * @private helper of `OpenAiAgentKitExecutionTools`
+     */
+    function normalizeAgentKitToolParameters(parameters) {
+        var _a, _b;
+        if (!parameters) {
+            return undefined;
+        }
+        return {
+            ...parameters,
+            additionalProperties: (_a = parameters.additionalProperties) !== null && _a !== void 0 ? _a : false,
+            required: (_b = parameters.required) !== null && _b !== void 0 ? _b : [],
+        };
+    }
+    /**
+     * Creates instructions for the nested DeepSearch specialist agent.
+     *
+     * @param toolDescription - Model-facing description from the original tool definition.
+     * @returns System instructions for the nested deep-research agent.
+     *
+     * @private helper of `OpenAiAgentKitExecutionTools`
+     */
+    function createDeepSearchAgentInstructions(toolDescription) {
+        const normalizedDescription = toolDescription.trim();
+        return spacetrim.spaceTrim((block) => `
+            You are a DeepSearch specialist working as a tool for another agent.
+            Perform thorough, source-grounded public-web research based on the provided request.
+            Use web search to gather current information, compare relevant viewpoints, and synthesize a concise research brief.
+            Do not ask follow-up questions. If the request is not specific enough, state the assumptions you had to make.
+            Include citations in the research brief whenever sources were used.
+            ${block(normalizedDescription ? `Tool guidance:\n${normalizedDescription}` : '')}
+        `);
+    }
+    /**
+     * Builds the nested DeepSearch prompt from structured tool arguments.
+     *
+     * @param rawInput - Parsed function-tool arguments provided by the outer agent.
+     * @returns Prompt text passed to the nested deep-research agent.
+     *
+     * @private helper of `OpenAiAgentKitExecutionTools`
+     */
+    function buildDeepSearchToolInput(rawInput) {
+        const input = rawInput && typeof rawInput === 'object' ? rawInput : {};
+        const query = typeof input.query === 'string' ? input.query.trim() : '';
+        const additionalHints = Object.entries(input)
+            .filter(([key, value]) => key !== 'query' && value !== undefined && value !== null && String(value).trim() !== '')
+            .map(([key, value]) => `- ${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`);
+        return spacetrim.spaceTrim((block) => `
+            Research request:
+            ${query || JSON.stringify(input)}
+            ${block(additionalHints.length > 0 ? `Execution hints:\n${additionalHints.join('\n')}` : '')}
+        `);
+    }
+    /**
+     * Creates the native Agent SDK tool used for `USE DEEPSEARCH`.
+     *
+     * @param toolDefinition - Promptbook tool definition for `deep_search`.
+     * @returns AgentKit tool backed by a nested deep-research agent.
+     *
+     * @private helper of `OpenAiAgentKitExecutionTools`
+     */
+    function createDeepSearchAgentKitTool(toolDefinition) {
+        const deepSearchAgent = new agents.Agent({
+            name: 'DeepSearch',
+            model: DEFAULT_DEEP_SEARCH_MODEL_NAME,
+            instructions: createDeepSearchAgentInstructions(toolDefinition.description),
+            tools: [agents.webSearchTool({ searchContextSize: 'high' })],
+        });
+        return deepSearchAgent.asTool({
+            toolName: toolDefinition.name,
+            toolDescription: toolDefinition.description,
+            parameters: normalizeAgentKitToolParameters(toolDefinition.parameters),
+            inputBuilder: ({ params }) => buildDeepSearchToolInput(params),
+            customOutputExtractor: (result) => { var _a; return typeof result.finalOutput === 'string' ? result.finalOutput : JSON.stringify((_a = result.finalOutput) !== null && _a !== void 0 ? _a : ''); },
+        });
+    }
     /**
      * Constant for default JSON schema name.
      */
@@ -38931,25 +39668,23 @@
          * Builds the tool list for AgentKit, including hosted file search when applicable.
          */
         buildAgentKitTools(options) {
-            var _a;
             const { tools, vectorStoreId } = options;
             const agentKitTools = [];
             if (vectorStoreId) {
                 agentKitTools.push(agents.fileSearchTool(vectorStoreId));
             }
             if (tools && tools.length > 0) {
-                const scriptTools = this.resolveScriptTools();
+                let scriptTools = null;
                 for (const toolDefinition of tools) {
+                    if (isDeepSearchToolDefinition(toolDefinition)) {
+                        agentKitTools.push(createDeepSearchAgentKitTool(toolDefinition));
+                        continue;
+                    }
+                    scriptTools !== null && scriptTools !== void 0 ? scriptTools : (scriptTools = this.resolveScriptTools());
                     agentKitTools.push(agents.tool({
                         name: toolDefinition.name,
                         description: toolDefinition.description,
-                        parameters: toolDefinition.parameters
-                            ? {
-                                ...toolDefinition.parameters,
-                                additionalProperties: false,
-                                required: (_a = toolDefinition.parameters.required) !== null && _a !== void 0 ? _a : [],
-                            }
-                            : undefined,
+                        parameters: normalizeAgentKitToolParameters(toolDefinition.parameters),
                         strict: false,
                         execute: async (input, runContext, details) => {
                             var _a, _b, _c, _d;
@@ -45136,6 +45871,7 @@
         delete_wallet_record: { title: 'Deleting wallet', emoji: '👛' },
         request_wallet_record: { title: 'Requesting wallet', emoji: '👛' },
         web_search: { title: 'Searching the web', emoji: '🔎' },
+        deep_search: { title: 'Deep research', emoji: '🔬' },
         useSearchEngine: { title: 'Searching the web', emoji: '🔎' },
         search: { title: 'Searching the web', emoji: '🔎' },
         useBrowser: { title: 'Browsing the web', emoji: '🌐' },
@@ -48097,7 +48833,7 @@
      * @private function of ChatToolCallModal
      */
     function isSearchToolCallName(toolName) {
-        return toolName === 'web_search' || toolName === 'useSearchEngine' || toolName === 'search';
+        return toolName === 'web_search' || toolName === 'deep_search' || toolName === 'useSearchEngine' || toolName === 'search';
     }
     /**
      * Checks whether a tool name should use the time renderer.
@@ -48797,6 +49533,12 @@
                 });
             }
         }
+        const staticConversationDelayConfig = {
+            ...FAST_FLOW,
+            beforeFirstMessage: 0,
+            // Show the full internal exchange immediately so the modal never opens as a blank panel.
+            showIntermediateMessages: messages.length,
+        };
         const agentName = ((_c = (_b = teamResult.conversation) === null || _b === void 0 ? void 0 : _b.find((entry) => entry.sender === 'AGENT' || entry.role === 'AGENT')) === null || _c === void 0 ? void 0 : _c.name) || 'Agent';
         const teammateConversationName = ((_e = (_d = teamResult.conversation) === null || _d === void 0 ? void 0 : _d.find((entry) => entry.sender === 'TEAMMATE' || entry.role === 'TEAMMATE')) === null || _e === void 0 ? void 0 : _e.name) || '';
         const teammateProfile = teammateUrl ? teamProfiles[teammateUrl] : undefined;
@@ -48833,7 +49575,7 @@
                 avatarSrc: resolvedTeammateAvatar || undefined,
             },
         ];
-        return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx("div", { className: classNames(styles$5.searchModalHeader, styles$5.teamModalHeader), children: jsxRuntime.jsxs("div", { className: styles$5.teamHeaderParticipants, children: [jsxRuntime.jsx(TeamHeaderProfile, { label: resolvedAgentLabel, avatarSrc: resolvedAgentAvatar, avatarDefinition: resolvedAgentAvatarDefinition, avatarVisualId: resolvedAgentAvatarVisualId, fallbackColor: resolvedAgentHeaderColor }), jsxRuntime.jsx("span", { className: styles$5.teamHeaderDivider, children: "talking with" }), jsxRuntime.jsx(TeamHeaderProfile, { label: resolvedTeammateLabel, avatarSrc: resolvedTeammateAvatar, fallbackColor: "#0ea5e9", href: teammateLink })] }) }), jsxRuntime.jsxs("div", { className: styles$5.searchModalContent, children: [messages.length > 0 ? (jsxRuntime.jsx("div", { className: styles$5.teamChatContainer, children: jsxRuntime.jsx(MockedChat, { title: `Chat between ${resolvedAgentLabel} and ${resolvedTeammateLabel}`, messages: messages, participants: participants, isResettable: false, isPausable: false, isSaveButtonEnabled: false, isCopyButtonEnabled: false, visual: "STANDALONE", delayConfig: FAST_FLOW }) })) : (jsxRuntime.jsx("div", { className: styles$5.noResults, children: "No teammate conversation available." })), (hasTeamToolCalls || hasTeamCitations) && (jsxRuntime.jsxs("div", { className: styles$5.teamToolCallSection, children: [hasTeamToolCalls && (jsxRuntime.jsxs("div", { className: styles$5.teamToolCallGroup, children: [jsxRuntime.jsx("div", { className: styles$5.teamToolCallHeading, children: "Actions" }), jsxRuntime.jsx("div", { className: styles$5.teamToolCallChips, children: teamToolCalls.map((toolCallEntry, index) => {
+        return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx("div", { className: classNames(styles$5.searchModalHeader, styles$5.teamModalHeader), children: jsxRuntime.jsxs("div", { className: styles$5.teamHeaderParticipants, children: [jsxRuntime.jsx(TeamHeaderProfile, { label: resolvedAgentLabel, avatarSrc: resolvedAgentAvatar, avatarDefinition: resolvedAgentAvatarDefinition, avatarVisualId: resolvedAgentAvatarVisualId, fallbackColor: resolvedAgentHeaderColor }), jsxRuntime.jsx("span", { className: styles$5.teamHeaderDivider, children: "talking with" }), jsxRuntime.jsx(TeamHeaderProfile, { label: resolvedTeammateLabel, avatarSrc: resolvedTeammateAvatar, fallbackColor: "#0ea5e9", href: teammateLink })] }) }), jsxRuntime.jsxs("div", { className: styles$5.searchModalContent, children: [messages.length > 0 ? (jsxRuntime.jsx("div", { className: styles$5.teamChatContainer, children: jsxRuntime.jsx(MockedChat, { title: `Chat between ${resolvedAgentLabel} and ${resolvedTeammateLabel}`, messages: messages, participants: participants, isResettable: false, isPausable: false, isSaveButtonEnabled: false, isCopyButtonEnabled: false, visual: "STANDALONE", delayConfig: staticConversationDelayConfig }) })) : (jsxRuntime.jsx("div", { className: styles$5.noResults, children: "No teammate conversation available." })), (hasTeamToolCalls || hasTeamCitations) && (jsxRuntime.jsxs("div", { className: styles$5.teamToolCallSection, children: [hasTeamToolCalls && (jsxRuntime.jsxs("div", { className: styles$5.teamToolCallGroup, children: [jsxRuntime.jsx("div", { className: styles$5.teamToolCallHeading, children: "Actions" }), jsxRuntime.jsx("div", { className: styles$5.teamToolCallChips, children: teamToolCalls.map((toolCallEntry, index) => {
                                                 const chipletInfo = getToolCallChipletInfo(toolCallEntry.toolCall, undefined, toolTitles);
                                                 const chipletText = buildToolCallChipText(chipletInfo);
                                                 return (jsxRuntime.jsxs("button", { className: styles$5.completedToolCall, onClick: () => {