@promptbook/browser 0.112.0-73 → 0.112.0-79

package/umd/index.umd.js

@@ -27,7 +27,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-73';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-79';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -277,6 +277,111 @@
         }
     }
 
+    /**
+     * Shared immutable channel storage and serialization helpers for `Color`.
+     *
+     * @private base class of Color
+     */
+    class ColorValue {
+        constructor(red, green, blue, alpha = 255) {
+            this.red = red;
+            this.green = green;
+            this.blue = blue;
+            this.alpha = alpha;
+            checkChannelValue('Red', red);
+            checkChannelValue('Green', green);
+            checkChannelValue('Blue', blue);
+            checkChannelValue('Alpha', alpha);
+        }
+        /**
+         * Shortcut for `red` property
+         * Number from 0 to 255
+         * @alias red
+         */
+        get r() {
+            return this.red;
+        }
+        /**
+         * Shortcut for `green` property
+         * Number from 0 to 255
+         * @alias green
+         */
+        get g() {
+            return this.green;
+        }
+        /**
+         * Shortcut for `blue` property
+         * Number from 0 to 255
+         * @alias blue
+         */
+        get b() {
+            return this.blue;
+        }
+        /**
+         * Shortcut for `alpha` property
+         * Number from 0 (transparent) to 255 (opaque)
+         * @alias alpha
+         */
+        get a() {
+            return this.alpha;
+        }
+        /**
+         * Shortcut for `alpha` property
+         * Number from 0 (transparent) to 255 (opaque)
+         * @alias alpha
+         */
+        get opacity() {
+            return this.alpha;
+        }
+        /**
+         * Shortcut for 1-`alpha` property
+         */
+        get transparency() {
+            return 255 - this.alpha;
+        }
+        clone() {
+            return take(this.createColor(this.red, this.green, this.blue, this.alpha));
+        }
+        toString() {
+            return this.toHex();
+        }
+        toHex() {
+            if (this.alpha === 255) {
+                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}`;
+            }
+            else {
+                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
+            }
+        }
+        toRgb() {
+            if (this.alpha === 255) {
+                return `rgb(${this.red}, ${this.green}, ${this.blue})`;
+            }
+            else {
+                return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
+            }
+        }
+        toHsl() {
+            throw new Error(`Getting HSL is not implemented`);
+        }
+    }
+
+    /**
+     * Checks if the given value is a valid hex color string
+     *
+     * @param value - value to check
+     * @returns true if the value is a valid hex color string (e.g., `#009edd`, `#fff`, etc.)
+     *
+     * @private function of Color
+     */
+    function isHexColorString(value) {
+        return (typeof value === 'string' && /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(value));
+    }
+
     /**
      * Constant for short hex lengths.
      */
@@ -488,16 +593,53 @@
 
     /**
      * Pattern matching hsl regex.
+     *
+     * @private function of Color
      */
     const HSL_REGEX_PATTERN = /^hsl\(\s*([0-9.]+)\s*,\s*([0-9.]+)%\s*,\s*([0-9.]+)%\s*\)$/;
     /**
      * Pattern matching RGB regex.
+     *
+     * @private function of Color
      */
     const RGB_REGEX_PATTERN = /^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
     /**
      * Pattern matching rgba regex.
+     *
+     * @private function of Color
      */
     const RGBA_REGEX_PATTERN = /^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+    /**
+     * Parses a supported color string into RGBA channels.
+     *
+     * @param color as a string for example `#009edd`, `rgb(0,158,221)`, `rgb(0%,62%,86.7%)`, `hsl(197.1,100%,43.3%)`, `red`, `darkgrey`,...
+     * @returns RGBA channel values.
+     *
+     * @private function of Color
+     */
+    function parseColorString(color) {
+        const trimmed = color.trim();
+        const cssColor = CSS_COLORS[trimmed];
+        if (cssColor) {
+            return parseColorString(cssColor);
+        }
+        else if (isHexColorString(trimmed)) {
+            return parseHexColor(trimmed);
+        }
+        if (HSL_REGEX_PATTERN.test(trimmed)) {
+            return parseHslColor(trimmed);
+        }
+        else if (RGB_REGEX_PATTERN.test(trimmed)) {
+            return parseRgbColor(trimmed);
+        }
+        else if (RGBA_REGEX_PATTERN.test(trimmed)) {
+            return parseRgbaColor(trimmed);
+        }
+        else {
+            throw new Error(`Can not create a new Color instance from string "${trimmed}".`);
+        }
+    }
+
     /**
      * Color object represents an RGB color with alpha channel
      *
@@ -505,7 +647,7 @@
      *
      * @public exported from `@promptbook/color`
      */
-    class Color {
+    class Color extends ColorValue {
         /**
          * Creates a new Color instance from miscellaneous formats
          * - It can receive Color instance and just return the same instance
@@ -578,25 +720,7 @@
          * @returns Color object
          */
         static fromString(color) {
-            const trimmed = color.trim();
-            if (CSS_COLORS[trimmed]) {
-                return Color.fromString(CSS_COLORS[trimmed]);
-            }
-            else if (Color.isHexColorString(trimmed)) {
-                return Color.fromHex(trimmed);
-            }
-            if (HSL_REGEX_PATTERN.test(trimmed)) {
-                return Color.fromHsl(trimmed);
-            }
-            else if (RGB_REGEX_PATTERN.test(trimmed)) {
-                return Color.fromRgbString(trimmed);
-            }
-            else if (RGBA_REGEX_PATTERN.test(trimmed)) {
-                return Color.fromRgbaString(trimmed);
-            }
-            else {
-                throw new Error(`Can not create a new Color instance from string "${trimmed}".`);
-            }
+            return Color.fromColorChannels(parseColorString(color));
         }
         /**
          * Gets common color
@@ -626,8 +750,7 @@
          * @returns Color object
          */
         static fromHex(hex) {
-            const { red, green, blue, alpha } = parseHexColor(hex);
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels(parseHexColor(hex));
         }
         /**
          * Creates a new Color instance from color in hsl format
@@ -636,8 +759,7 @@
          * @returns Color object
          */
         static fromHsl(hsl) {
-            const { red, green, blue, alpha } = parseHslColor(hsl);
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels(parseHslColor(hsl));
         }
         /**
          * Creates a new Color instance from color in rgb format
@@ -646,8 +768,7 @@
          * @returns Color object
          */
         static fromRgbString(rgb) {
-            const { red, green, blue, alpha } = parseRgbColor(rgb);
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels(parseRgbColor(rgb));
         }
         /**
          * Creates a new Color instance from color in rbga format
@@ -656,8 +777,7 @@
          * @returns Color object
          */
         static fromRgbaString(rgba) {
-            const { red, green, blue, alpha } = parseRgbaColor(rgba);
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels(parseRgbaColor(rgba));
         }
         /**
          * Creates a new Color for color channels values
@@ -669,7 +789,7 @@
          * @returns Color object
          */
         static fromValues(red, green, blue, alpha = 255) {
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels({ red, green, blue, alpha });
         }
         /**
          * Checks if the given value is a valid Color object.
@@ -702,8 +822,7 @@
          * @returns true if the value is a valid hex color string (e.g., `#009edd`, `#fff`, etc.)
          */
         static isHexColorString(value) {
-            return (typeof value === 'string' &&
-                /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(value));
+            return isHexColorString(value);
         }
         /**
          * Creates new Color object
@@ -716,89 +835,13 @@
          * @param alpha number from 0 (transparent) to 255 (opaque)
          */
         constructor(red, green, blue, alpha = 255) {
-            this.red = red;
-            this.green = green;
-            this.blue = blue;
-            this.alpha = alpha;
-            checkChannelValue('Red', red);
-            checkChannelValue('Green', green);
-            checkChannelValue('Blue', blue);
-            checkChannelValue('Alpha', alpha);
+            super(red, green, blue, alpha);
         }
-        /**
-         * Shortcut for `red` property
-         * Number from 0 to 255
-         * @alias red
-         */
-        get r() {
-            return this.red;
-        }
-        /**
-         * Shortcut for `green` property
-         * Number from 0 to 255
-         * @alias green
-         */
-        get g() {
-            return this.green;
-        }
-        /**
-         * Shortcut for `blue` property
-         * Number from 0 to 255
-         * @alias blue
-         */
-        get b() {
-            return this.blue;
-        }
-        /**
-         * Shortcut for `alpha` property
-         * Number from 0 (transparent) to 255 (opaque)
-         * @alias alpha
-         */
-        get a() {
-            return this.alpha;
+        createColor(red, green, blue, alpha) {
+            return new Color(red, green, blue, alpha);
         }
-        /**
-         * Shortcut for `alpha` property
-         * Number from 0 (transparent) to 255 (opaque)
-         * @alias alpha
-         */
-        get opacity() {
-            return this.alpha;
-        }
-        /**
-         * Shortcut for 1-`alpha` property
-         */
-        get transparency() {
-            return 255 - this.alpha;
-        }
-        clone() {
-            return take(new Color(this.red, this.green, this.blue, this.alpha));
-        }
-        toString() {
-            return this.toHex();
-        }
-        toHex() {
-            if (this.alpha === 255) {
-                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}`;
-            }
-            else {
-                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
-            }
-        }
-        toRgb() {
-            if (this.alpha === 255) {
-                return `rgb(${this.red}, ${this.green}, ${this.blue})`;
-            }
-            else {
-                return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
-            }
-        }
-        toHsl() {
-            throw new Error(`Getting HSL is not implemented`);
+        static fromColorChannels({ red, green, blue, alpha }) {
+            return take(new Color(red, green, blue, alpha));
         }
     }
 
@@ -6592,7 +6635,7 @@
      *
      * @private helper of `minecraft2AvatarVisual`
      */
-    const LIGHT_DIRECTION$1 = normalizeVector3({
+    const LIGHT_DIRECTION$2 = normalizeVector3({
         x: 0.4,
         y: -0.65,
         z: 0.92,
@@ -6804,7 +6847,7 @@
                 corners: projectedCorners,
                 texture: faceDefinition.texture,
                 averageDepth: transformedCorners.reduce((depthSum, corner) => depthSum + corner.z, 0) / transformedCorners.length,
-                lightIntensity: clampNumber$1(dotProduct3D(faceNormal, LIGHT_DIRECTION$1), -1, 1),
+                lightIntensity: clampNumber$1(dotProduct3D(faceNormal, LIGHT_DIRECTION$2), -1, 1),
                 outlineColor: cuboid.outlineColor,
             };
         });
@@ -7864,13 +7907,138 @@
         context.restore();
     }
 
+    /* eslint-disable no-magic-numbers */
+    /**
+     * Draws one projected eye on a rotated octopus surface.
+     *
+     * @private helper of the 3D octopus avatar visuals
+     */
+    function drawProjectedOrganicEye(context, localCenter, radiusX, radiusY, center, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, timeMs, phase, interaction, eyeStyle) {
+        const centerScenePoint = transformScenePoint(localCenter, center, rotationX, rotationY);
+        if (centerScenePoint.z <= center.z) {
+            return;
+        }
+        const horizontalScenePoint = transformScenePoint({ x: localCenter.x + radiusX, y: localCenter.y, z: localCenter.z }, center, rotationX, rotationY);
+        const verticalScenePoint = transformScenePoint({ x: localCenter.x, y: localCenter.y + radiusY, z: localCenter.z }, center, rotationX, rotationY);
+        const projectedCenterPoint = projectScenePoint(centerScenePoint, size, sceneCenterX, sceneCenterY);
+        const projectedHorizontalPoint = projectScenePoint(horizontalScenePoint, size, sceneCenterX, sceneCenterY);
+        const projectedVerticalPoint = projectScenePoint(verticalScenePoint, size, sceneCenterX, sceneCenterY);
+        const projectedRadiusX = Math.hypot(projectedHorizontalPoint.x - projectedCenterPoint.x, projectedHorizontalPoint.y - projectedCenterPoint.y);
+        const projectedRadiusY = Math.hypot(projectedVerticalPoint.x - projectedCenterPoint.x, projectedVerticalPoint.y - projectedCenterPoint.y);
+        if (projectedRadiusX < size * 0.008 || projectedRadiusY < size * 0.008) {
+            return;
+        }
+        const { pupilOffsetX, pupilOffsetY } = resolveOrganicEyeMotion({
+            radiusX: projectedRadiusX,
+            radiusY: projectedRadiusY,
+            timeMs,
+            phase,
+            interaction,
+        });
+        const rotation = Math.atan2(projectedHorizontalPoint.y - projectedCenterPoint.y, projectedHorizontalPoint.x - projectedCenterPoint.x);
+        context.save();
+        context.translate(projectedCenterPoint.x, projectedCenterPoint.y);
+        context.rotate(rotation);
+        context.beginPath();
+        context.ellipse(0, 0, projectedRadiusX, projectedRadiusY, 0, 0, Math.PI * 2);
+        context.fillStyle = '#f8fbff';
+        context.fill();
+        context.clip();
+        const irisGradient = context.createRadialGradient(-projectedRadiusX * 0.2, -projectedRadiusY * 0.26, projectedRadiusX * 0.05, 0, 0, projectedRadiusX * 0.92);
+        irisGradient.addColorStop(0, palette.highlight);
+        irisGradient.addColorStop(0.56, palette.secondary);
+        irisGradient.addColorStop(1, palette.shadow);
+        context.beginPath();
+        context.ellipse(pupilOffsetX, pupilOffsetY, projectedRadiusX * 0.62 * eyeStyle.irisScale, projectedRadiusY * 0.72 * eyeStyle.irisScale, 0, 0, Math.PI * 2);
+        context.fillStyle = irisGradient;
+        context.fill();
+        context.beginPath();
+        context.ellipse(pupilOffsetX, pupilOffsetY, projectedRadiusX * 0.15 * eyeStyle.pupilWidthScale, projectedRadiusY * 0.48 * eyeStyle.pupilHeightScale, 0, 0, Math.PI * 2);
+        context.fillStyle = palette.ink;
+        context.fill();
+        context.beginPath();
+        context.ellipse(pupilOffsetX - projectedRadiusX * 0.22, pupilOffsetY - projectedRadiusY * 0.24, projectedRadiusX * 0.12, projectedRadiusY * 0.14, 0, 0, Math.PI * 2);
+        context.fillStyle = '#ffffff';
+        context.fill();
+        context.restore();
+        context.save();
+        context.translate(projectedCenterPoint.x, projectedCenterPoint.y);
+        context.rotate(rotation);
+        context.beginPath();
+        context.ellipse(0, 0, projectedRadiusX, projectedRadiusY, 0, 0, Math.PI * 2);
+        context.strokeStyle = `${palette.shadow}cc`;
+        context.lineWidth = projectedRadiusX * 0.16;
+        context.stroke();
+        context.beginPath();
+        context.moveTo(-projectedRadiusX * 0.88, -projectedRadiusY * eyeStyle.upperLidInsetRatio);
+        context.quadraticCurveTo(0, -projectedRadiusY * (eyeStyle.upperLidArchRatio - interaction.gazeY * 0.16 + interaction.intensity * 0.08), projectedRadiusX * 0.88, -projectedRadiusY * eyeStyle.upperLidInsetRatio);
+        context.strokeStyle = `${palette.shadow}73`;
+        context.lineWidth = projectedRadiusX * 0.14;
+        context.lineCap = 'round';
+        context.stroke();
+        if (eyeStyle.lowerLidOpacity > 0) {
+            context.beginPath();
+            context.moveTo(-projectedRadiusX * 0.74, projectedRadiusY * 0.2);
+            context.quadraticCurveTo(0, projectedRadiusY * 0.38, projectedRadiusX * 0.74, projectedRadiusY * 0.2);
+            context.strokeStyle = `${palette.highlight}${formatAlphaHex(eyeStyle.lowerLidOpacity)}`;
+            context.lineWidth = projectedRadiusX * 0.08;
+            context.lineCap = 'round';
+            context.stroke();
+        }
+        context.restore();
+    }
+    /**
+     * Draws a subtle projected mouth arc across the front of a rotated octopus surface.
+     *
+     * @private helper of the 3D octopus avatar visuals
+     */
+    function drawProjectedOrganicMouth(context, localPoints, center, rotationX, rotationY, sceneCenterX, sceneCenterY, palette, size) {
+        const scenePoints = localPoints.map((localPoint) => transformScenePoint(localPoint, center, rotationX, rotationY));
+        if (scenePoints.some((scenePoint) => scenePoint.z <= center.z)) {
+            return;
+        }
+        const projectedPoints = scenePoints.map((scenePoint) => projectScenePoint(scenePoint, size, sceneCenterX, sceneCenterY));
+        context.beginPath();
+        context.moveTo(projectedPoints[0].x, projectedPoints[0].y);
+        context.quadraticCurveTo(projectedPoints[1].x, projectedPoints[1].y, projectedPoints[2].x, projectedPoints[2].y);
+        context.strokeStyle = `${palette.ink}b8`;
+        context.lineWidth = Math.max(1.1, size * 0.009);
+        context.lineCap = 'round';
+        context.stroke();
+    }
+    /**
+     * Draws one filled projected quad.
+     *
+     * @private helper of the 3D octopus avatar visuals
+     */
+    function drawProjectedQuad(context, corners, fillStyle) {
+        context.beginPath();
+        context.moveTo(corners[0].x, corners[0].y);
+        context.lineTo(corners[1].x, corners[1].y);
+        context.lineTo(corners[2].x, corners[2].y);
+        context.lineTo(corners[3].x, corners[3].y);
+        context.closePath();
+        context.fillStyle = fillStyle;
+        context.fill();
+    }
+    /**
+     * Converts an opacity ratio into a two-digit hexadecimal alpha suffix.
+     *
+     * @private helper of the 3D octopus avatar visuals
+     */
+    function formatAlphaHex(opacity) {
+        return Math.round(clampNumber$1(opacity, 0, 1) * 255)
+            .toString(16)
+            .padStart(2, '0');
+    }
+
     /* eslint-disable no-magic-numbers */
     /**
      * Light direction used by the organic 3D octopus shading.
      *
      * @private helper of `octopus3dAvatarVisual`
      */
-    const LIGHT_DIRECTION = normalizeVector3({
+    const LIGHT_DIRECTION$1 = normalizeVector3({
         x: 0.48,
         y: -0.62,
         z: 0.94,
@@ -7983,17 +8151,17 @@
             for (const tentacleStroke of tentacleStrokes.filter((candidateTentacleStroke) => candidateTentacleStroke.isFrontFacing)) {
                 drawTentacleStroke(context, tentacleStroke, palette);
             }
-            drawProjectedEye(context, {
+            drawProjectedOrganicEye(context, {
                 x: -faceEyeSpacing,
                 y: faceEyeYOffset,
                 z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, -faceEyeSpacing, faceEyeYOffset),
             }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + eyeRandom() * 0.6, interaction, morphologyProfile.face.eyeStyle);
-            drawProjectedEye(context, {
+            drawProjectedOrganicEye(context, {
                 x: faceEyeSpacing,
                 y: faceEyeYOffset,
                 z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, faceEyeSpacing, faceEyeYOffset),
             }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + 0.7 + eyeRandom() * 0.6, interaction, morphologyProfile.face.eyeStyle);
-            drawProjectedMouth(context, [
+            drawProjectedOrganicMouth(context, [
                 {
                     x: -mouthHalfWidth,
                     y: mouthY,
@@ -8080,7 +8248,7 @@
                     corners: projectedCorners,
                     averageDepth: transformedCorners.reduce((depthSum, transformedCorner) => depthSum + transformedCorner.z, 0) /
                         transformedCorners.length,
-                    lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION), -1, 1),
+                    lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION$1), -1, 1),
                     fillStyle: resolveSurfacePatchFillStyle(palette, verticalProgress + verticalColorBias),
                     outlineColor,
                 });
@@ -8262,128 +8430,260 @@
         const remainingDepthRatio = Math.max(0, 1 - normalizedX * normalizedX - normalizedY * normalizedY);
         return Math.sqrt(remainingDepthRatio) * radiusZ;
     }
+
+    /* eslint-disable no-magic-numbers */
     /**
-     * Draws one projected eye on the turned octopus mantle.
+     * Light direction used by the single-mesh octopus shading.
      *
-     * @private helper of `octopus3dAvatarVisual`
+     * @private helper of `octopus3d2AvatarVisual`
      */
-    function drawProjectedEye(context, localCenter, radiusX, radiusY, center, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, timeMs, phase, interaction, eyeStyle) {
-        const centerScenePoint = transformScenePoint(localCenter, center, rotationX, rotationY);
-        if (centerScenePoint.z <= center.z) {
-            return;
-        }
-        const horizontalScenePoint = transformScenePoint({ x: localCenter.x + radiusX, y: localCenter.y, z: localCenter.z }, center, rotationX, rotationY);
-        const verticalScenePoint = transformScenePoint({ x: localCenter.x, y: localCenter.y + radiusY, z: localCenter.z }, center, rotationX, rotationY);
-        const projectedCenterPoint = projectScenePoint(centerScenePoint, size, sceneCenterX, sceneCenterY);
-        const projectedHorizontalPoint = projectScenePoint(horizontalScenePoint, size, sceneCenterX, sceneCenterY);
-        const projectedVerticalPoint = projectScenePoint(verticalScenePoint, size, sceneCenterX, sceneCenterY);
-        const projectedRadiusX = Math.hypot(projectedHorizontalPoint.x - projectedCenterPoint.x, projectedHorizontalPoint.y - projectedCenterPoint.y);
-        const projectedRadiusY = Math.hypot(projectedVerticalPoint.x - projectedCenterPoint.x, projectedVerticalPoint.y - projectedCenterPoint.y);
-        if (projectedRadiusX < size * 0.008 || projectedRadiusY < size * 0.008) {
-            return;
-        }
-        const { pupilOffsetX, pupilOffsetY } = resolveOrganicEyeMotion({
-            radiusX: projectedRadiusX,
-            radiusY: projectedRadiusY,
-            timeMs,
-            phase,
-            interaction,
-        });
-        const rotation = Math.atan2(projectedHorizontalPoint.y - projectedCenterPoint.y, projectedHorizontalPoint.x - projectedCenterPoint.x);
+    const LIGHT_DIRECTION = normalizeVector3({
+        x: 0.38,
+        y: -0.6,
+        z: 0.98,
+    });
+    /**
+     * Octopus 3D 2 avatar visual.
+     *
+     * @private built-in avatar visual
+     */
+    const octopus3d2AvatarVisual = {
+        id: 'octopus3d2',
+        title: 'Octopus 3D 2',
+        description: 'Continuous blobby 3D octopus portrait with one soft mesh, turning silhouette, and cursor-aware eyes.',
+        isAnimated: true,
+        supportsPointerTracking: true,
+        render({ context, size, palette, createRandom, timeMs, interaction }) {
+            const morphologyProfile = createOctopus3MorphologyProfile(createRandom);
+            const animationRandom = createRandom('octopus3d2-animation-profile');
+            const eyeRandom = createRandom('octopus3d2-eye-profile');
+            const animationPhase = animationRandom() * Math.PI * 2;
+            const sceneCenterX = size * 0.5;
+            const sceneCenterY = size * 0.575;
+            const bob = Math.sin(timeMs / 940 + animationPhase) * size * 0.013;
+            const meshCenter = {
+                x: interaction.bodyOffsetX * size * 0.044 + size * morphologyProfile.body.centerXJitterRatio * 0.5,
+                y: -size * 0.03 + interaction.bodyOffsetY * size * 0.026 + bob,
+                z: interaction.intensity * size * 0.018,
+            };
+            const rotationY = -0.14 +
+                Math.sin(timeMs / 2600 + animationPhase) * 0.04 +
+                interaction.bodyOffsetX * 0.2 +
+                interaction.gazeX * 0.78;
+            const rotationX = -0.06 +
+                Math.cos(timeMs / 3000 + animationPhase * 0.7) * 0.02 -
+                interaction.bodyOffsetY * 0.08 -
+                interaction.gazeY * 0.34;
+            const surfaceOptions = {
+                radiusX: size * morphologyProfile.body.bodyRadiusRatio * morphologyProfile.body.horizontalStretch * 1.02,
+                radiusY: size * morphologyProfile.body.bodyRadiusRatio * morphologyProfile.body.verticalStretch * 1.22,
+                radiusZ: size *
+                    morphologyProfile.body.bodyRadiusRatio *
+                    (0.98 + (morphologyProfile.body.horizontalStretch - 1) * 0.2),
+                morphologyProfile,
+                timeMs,
+                animationPhase,
+            };
+            const surfacePatches = resolveVisibleBlobbyOctopusPatches({
+                ...surfaceOptions,
+                center: meshCenter,
+                rotationX,
+                rotationY,
+                sceneCenterX,
+                sceneCenterY,
+                size,
+                palette,
+            });
+            const eyeLatitude = clampNumber$1(morphologyProfile.face.eyeCenterYOffsetRatio * 4.4, -0.16, 0.11);
+            const eyeLongitude = clampNumber$1(morphologyProfile.face.eyeSpacingRatio * 3.25, 0.2, 0.34);
+            const mouthLatitude = clampNumber$1(eyeLatitude + 0.19 + morphologyProfile.face.mouthYOffsetRatio * 1.08, 0.08, 0.34);
+            const mouthCenterLongitude = clampNumber$1(morphologyProfile.face.mouthCenterOffsetRatio * 5.8, -0.08, 0.08);
+            const mouthHalfLongitude = clampNumber$1(eyeLongitude * 0.82, 0.16, 0.29);
+            const mouthCurveLatitude = clampNumber$1(mouthLatitude + morphologyProfile.face.mouthCurveDepthRatio * 0.85, mouthLatitude + 0.03, 0.42);
+            drawAvatarFrame(context, size, palette);
+            drawBlobbyOctopusAtmosphere(context, size, palette, sceneCenterX, sceneCenterY, interaction, timeMs);
+            drawBlobbyOctopusShadow(context, size, palette, interaction, timeMs, morphologyProfile);
+            for (const surfacePatch of surfacePatches.sort((firstSurfacePatch, secondSurfacePatch) => firstSurfacePatch.averageDepth - secondSurfacePatch.averageDepth)) {
+                drawBlobbySurfacePatch(context, surfacePatch);
+            }
+            const leftEyeLocalCenter = sampleBlobbyOctopusSurfacePoint(surfaceOptions, eyeLatitude, -eyeLongitude);
+            const rightEyeLocalCenter = sampleBlobbyOctopusSurfacePoint(surfaceOptions, eyeLatitude, eyeLongitude);
+            const eyeRadiusX = size * morphologyProfile.face.eyeRadiusXRatio * 0.78;
+            const eyeRadiusY = eyeRadiusX * morphologyProfile.face.eyeHeightRatio * 0.92;
+            drawProjectedOrganicEye(context, leftEyeLocalCenter, eyeRadiusX, eyeRadiusY, meshCenter, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + eyeRandom() * 0.7, interaction, morphologyProfile.face.eyeStyle);
+            drawProjectedOrganicEye(context, rightEyeLocalCenter, eyeRadiusX, eyeRadiusY, meshCenter, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + 0.9 + eyeRandom() * 0.7, interaction, morphologyProfile.face.eyeStyle);
+            drawProjectedOrganicMouth(context, [
+                sampleBlobbyOctopusSurfacePoint(surfaceOptions, mouthLatitude, mouthCenterLongitude - mouthHalfLongitude),
+                sampleBlobbyOctopusSurfacePoint(surfaceOptions, mouthCurveLatitude, mouthCenterLongitude),
+                sampleBlobbyOctopusSurfacePoint(surfaceOptions, mouthLatitude, mouthCenterLongitude + mouthHalfLongitude),
+            ], meshCenter, rotationX, rotationY, sceneCenterX, sceneCenterY, palette, size);
+        },
+    };
+    /**
+     * Draws the deep-water glow behind the continuous octopus mesh.
+     *
+     * @private helper of `octopus3d2AvatarVisual`
+     */
+    function drawBlobbyOctopusAtmosphere(context, size, palette, sceneCenterX, sceneCenterY, interaction, timeMs) {
+        const glowGradient = context.createRadialGradient(sceneCenterX + interaction.gazeX * size * 0.11, sceneCenterY - size * 0.17 + interaction.gazeY * size * 0.05, size * 0.05, sceneCenterX, sceneCenterY - size * 0.03, size * 0.66);
+        glowGradient.addColorStop(0, `${palette.highlight}5e`);
+        glowGradient.addColorStop(0.38, `${palette.accent}26`);
+        glowGradient.addColorStop(1, `${palette.highlight}00`);
+        context.fillStyle = glowGradient;
+        context.fillRect(0, 0, size, size);
+        const lowerGradient = context.createRadialGradient(sceneCenterX + Math.sin(timeMs / 1650) * size * 0.045, sceneCenterY + size * 0.28, size * 0.06, sceneCenterX, sceneCenterY + size * 0.28, size * 0.52);
+        lowerGradient.addColorStop(0, `${palette.secondary}22`);
+        lowerGradient.addColorStop(1, `${palette.secondary}00`);
+        context.fillStyle = lowerGradient;
+        context.fillRect(0, 0, size, size);
+    }
+    /**
+     * Draws the soft floor shadow that anchors the single mesh in the frame.
+     *
+     * @private helper of `octopus3d2AvatarVisual`
+     */
+    function drawBlobbyOctopusShadow(context, size, palette, interaction, timeMs, morphologyProfile) {
         context.save();
-        context.translate(projectedCenterPoint.x, projectedCenterPoint.y);
-        context.rotate(rotation);
-        context.beginPath();
-        context.ellipse(0, 0, projectedRadiusX, projectedRadiusY, 0, 0, Math.PI * 2);
-        context.fillStyle = '#f8fbff';
-        context.fill();
-        context.clip();
-        const irisGradient = context.createRadialGradient(-projectedRadiusX * 0.2, -projectedRadiusY * 0.26, projectedRadiusX * 0.05, 0, 0, projectedRadiusX * 0.92);
-        irisGradient.addColorStop(0, palette.highlight);
-        irisGradient.addColorStop(0.56, palette.secondary);
-        irisGradient.addColorStop(1, palette.shadow);
-        context.beginPath();
-        context.ellipse(pupilOffsetX, pupilOffsetY, projectedRadiusX * 0.62 * eyeStyle.irisScale, projectedRadiusY * 0.72 * eyeStyle.irisScale, 0, 0, Math.PI * 2);
-        context.fillStyle = irisGradient;
-        context.fill();
-        context.beginPath();
-        context.ellipse(pupilOffsetX, pupilOffsetY, projectedRadiusX * 0.15 * eyeStyle.pupilWidthScale, projectedRadiusY * 0.48 * eyeStyle.pupilHeightScale, 0, 0, Math.PI * 2);
-        context.fillStyle = palette.ink;
-        context.fill();
+        context.fillStyle = `${palette.shadow}66`;
+        context.filter = `blur(${size * 0.024}px)`;
         context.beginPath();
-        context.ellipse(pupilOffsetX - projectedRadiusX * 0.22, pupilOffsetY - projectedRadiusY * 0.24, projectedRadiusX * 0.12, projectedRadiusY * 0.14, 0, 0, Math.PI * 2);
-        context.fillStyle = '#ffffff';
+        context.ellipse(size * 0.5 + interaction.gazeX * size * 0.045, size * 0.88 + Math.sin(timeMs / 940) * size * 0.008, size * (0.18 + (morphologyProfile.body.horizontalStretch - 1) * 0.04 + interaction.intensity * 0.018), size * 0.062, 0, 0, Math.PI * 2);
         context.fill();
         context.restore();
-        context.save();
-        context.translate(projectedCenterPoint.x, projectedCenterPoint.y);
-        context.rotate(rotation);
-        context.beginPath();
-        context.ellipse(0, 0, projectedRadiusX, projectedRadiusY, 0, 0, Math.PI * 2);
-        context.strokeStyle = `${palette.shadow}cc`;
-        context.lineWidth = projectedRadiusX * 0.16;
-        context.stroke();
-        context.beginPath();
-        context.moveTo(-projectedRadiusX * 0.88, -projectedRadiusY * eyeStyle.upperLidInsetRatio);
-        context.quadraticCurveTo(0, -projectedRadiusY * (eyeStyle.upperLidArchRatio - interaction.gazeY * 0.16 + interaction.intensity * 0.08), projectedRadiusX * 0.88, -projectedRadiusY * eyeStyle.upperLidInsetRatio);
-        context.strokeStyle = `${palette.shadow}73`;
-        context.lineWidth = projectedRadiusX * 0.14;
-        context.lineCap = 'round';
-        context.stroke();
-        if (eyeStyle.lowerLidOpacity > 0) {
-            context.beginPath();
-            context.moveTo(-projectedRadiusX * 0.74, projectedRadiusY * 0.2);
-            context.quadraticCurveTo(0, projectedRadiusY * 0.38, projectedRadiusX * 0.74, projectedRadiusY * 0.2);
-            context.strokeStyle = `${palette.highlight}${formatAlphaHex(eyeStyle.lowerLidOpacity)}`;
-            context.lineWidth = projectedRadiusX * 0.08;
-            context.lineCap = 'round';
-            context.stroke();
+    }
+    /**
+     * Resolves all visible projected patches for the single blobby octopus mesh.
+     *
+     * @private helper of `octopus3d2AvatarVisual`
+     */
+    function resolveVisibleBlobbyOctopusPatches(options) {
+        const { center, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, morphologyProfile, animationPhase, timeMs, } = options;
+        const latitudePatchCount = 12;
+        const longitudePatchCount = 24;
+        const surfacePatches = [];
+        for (let latitudeIndex = 0; latitudeIndex < latitudePatchCount; latitudeIndex++) {
+            const startLatitude = -Math.PI / 2 + (latitudeIndex / latitudePatchCount) * Math.PI;
+            const endLatitude = -Math.PI / 2 + ((latitudeIndex + 1) / latitudePatchCount) * Math.PI;
+            const centerLatitude = (startLatitude + endLatitude) / 2;
+            const verticalProgress = (Math.sin(centerLatitude) + 1) / 2;
+            for (let longitudeIndex = 0; longitudeIndex < longitudePatchCount; longitudeIndex++) {
+                const startLongitude = -Math.PI + (longitudeIndex / longitudePatchCount) * Math.PI * 2;
+                const endLongitude = -Math.PI + ((longitudeIndex + 1) / longitudePatchCount) * Math.PI * 2;
+                const centerLongitude = (startLongitude + endLongitude) / 2;
+                const localCorners = [
+                    sampleBlobbyOctopusSurfacePoint(options, startLatitude, startLongitude),
+                    sampleBlobbyOctopusSurfacePoint(options, startLatitude, endLongitude),
+                    sampleBlobbyOctopusSurfacePoint(options, endLatitude, endLongitude),
+                    sampleBlobbyOctopusSurfacePoint(options, endLatitude, startLongitude),
+                ];
+                const transformedCorners = localCorners.map((localCorner) => transformScenePoint(localCorner, center, rotationX, rotationY));
+                const surfaceNormal = normalizeVector3(crossProduct3D(subtractPoint3D(transformedCorners[1], transformedCorners[0]), subtractPoint3D(transformedCorners[2], transformedCorners[0])));
+                if (surfaceNormal.z <= 0.01) {
+                    continue;
+                }
+                const projectedCorners = transformedCorners.map((transformedCorner) => projectScenePoint(transformedCorner, size, sceneCenterX, sceneCenterY));
+                surfacePatches.push({
+                    corners: projectedCorners,
+                    averageDepth: transformedCorners.reduce((depthSum, transformedCorner) => depthSum + transformedCorner.z, 0) /
+                        transformedCorners.length,
+                    lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION), -1, 1),
+                    fillStyle: resolveBlobbySurfacePatchFillStyle(palette, verticalProgress, Math.max(0, Math.cos(centerLongitude)), resolveLowerLobeWave(centerLongitude, morphologyProfile, animationPhase, timeMs)),
+                    outlineColor: verticalProgress < 0.58 ? `${palette.highlight}73` : `${palette.shadow}8a`,
+                });
+            }
         }
-        context.restore();
+        return surfacePatches;
+    }
+    /**
+     * Samples one point on the continuous Octopus 3D 2 surface.
+     *
+     * The lower hemisphere widens and falls into soft lobe waves so the octopus stays one connected mesh
+     * instead of switching to separately rendered tentacles.
+     *
+     * @private helper of `octopus3d2AvatarVisual`
+     */
+    function sampleBlobbyOctopusSurfacePoint(options, latitude, longitude) {
+        const { radiusX, radiusY, radiusZ, morphologyProfile, timeMs, animationPhase } = options;
+        const cosineLatitude = Math.max(0, Math.cos(latitude));
+        const verticalProgress = (Math.sin(latitude) + 1) / 2;
+        const upperBlend = Math.pow(1 - verticalProgress, 1.2);
+        const lowerBlend = Math.pow(verticalProgress, 1.42);
+        const lowerLobeWave = resolveLowerLobeWave(longitude, morphologyProfile, animationPhase, timeMs);
+        const skirtEnvelope = Math.pow(cosineLatitude, 0.5) * lowerBlend;
+        const horizontalScale = 1.02 +
+            skirtEnvelope * (0.34 + (morphologyProfile.tentacles.rootSpreadScale - 1) * 0.22 + lowerLobeWave * 0.22) -
+            upperBlend * 0.08;
+        const depthScale = 1.04 +
+            upperBlend * 0.16 +
+            Math.max(0, Math.cos(longitude)) * 0.1 +
+            skirtEnvelope * (0.08 + lowerLobeWave * 0.06) -
+            Math.max(0, -Math.cos(longitude)) * 0.04;
+        const lowerDrop = skirtEnvelope *
+            radiusY *
+            (0.28 + lowerLobeWave * 0.14 + (morphologyProfile.tentacles.flowLengthScale - 1) * 0.12);
+        const swayX = Math.sin(timeMs / 1250 + longitude * 1.8 + animationPhase) * skirtEnvelope * radiusX * 0.05;
+        const swayZ = Math.cos(timeMs / 1480 + longitude * 1.2 - animationPhase * 0.7) * skirtEnvelope * radiusZ * 0.03;
+        return {
+            x: Math.sin(longitude) * cosineLatitude * radiusX * horizontalScale + swayX,
+            y: Math.sin(latitude) * radiusY * (1 + upperBlend * 0.14) -
+                upperBlend * radiusY * 0.1 +
+                lowerDrop +
+                Math.sin(timeMs / 1780 + animationPhase + latitude * 1.4) * skirtEnvelope * radiusY * 0.02,
+            z: Math.cos(longitude) * cosineLatitude * radiusZ * depthScale + swayZ,
+        };
     }
     /**
-     * Draws a subtle projected mouth arc across the front of the mantle.
+     * Resolves the soft lower-lobe wave that makes the silhouette read more like a real octopus.
      *
-     * @private helper of `octopus3dAvatarVisual`
+     * @private helper of `octopus3d2AvatarVisual`
      */
-    function drawProjectedMouth(context, localPoints, center, rotationX, rotationY, sceneCenterX, sceneCenterY, palette, size) {
-        const scenePoints = localPoints.map((localPoint) => transformScenePoint(localPoint, center, rotationX, rotationY));
-        if (scenePoints.some((scenePoint) => scenePoint.z <= center.z)) {
-            return;
-        }
-        const projectedPoints = scenePoints.map((scenePoint) => projectScenePoint(scenePoint, size, sceneCenterX, sceneCenterY));
-        context.beginPath();
-        context.moveTo(projectedPoints[0].x, projectedPoints[0].y);
-        context.quadraticCurveTo(projectedPoints[1].x, projectedPoints[1].y, projectedPoints[2].x, projectedPoints[2].y);
-        context.strokeStyle = `${palette.ink}b8`;
-        context.lineWidth = Math.max(1.1, size * 0.009);
-        context.lineCap = 'round';
-        context.stroke();
+    function resolveLowerLobeWave(longitude, morphologyProfile, animationPhase, timeMs) {
+        const lobeCount = Math.max(4, Math.round((morphologyProfile.body.lobeCount + morphologyProfile.tentacles.count) / 2));
+        return (Math.cos(longitude * lobeCount + animationPhase + timeMs / 1040) + 1) / 2;
     }
     /**
-     * Draws one filled projected quad.
+     * Resolves one base fill tone for a surface patch on the single octopus mesh.
      *
-     * @private helper of `octopus3dAvatarVisual`
+     * @private helper of `octopus3d2AvatarVisual`
      */
-    function drawProjectedQuad(context, corners, fillStyle) {
-        context.beginPath();
-        context.moveTo(corners[0].x, corners[0].y);
-        context.lineTo(corners[1].x, corners[1].y);
-        context.lineTo(corners[2].x, corners[2].y);
-        context.lineTo(corners[3].x, corners[3].y);
-        context.closePath();
-        context.fillStyle = fillStyle;
-        context.fill();
+    function resolveBlobbySurfacePatchFillStyle(palette, verticalProgress, forwardness, lowerLobeWave) {
+        const tonalProgress = clampNumber$1(verticalProgress + lowerLobeWave * 0.12 - forwardness * 0.07, 0, 1);
+        if (tonalProgress < 0.16) {
+            return palette.highlight;
+        }
+        if (tonalProgress < 0.34) {
+            return palette.secondary;
+        }
+        if (tonalProgress < 0.72) {
+            return forwardness > 0.58 ? palette.secondary : palette.primary;
+        }
+        return `${palette.shadow}f2`;
     }
     /**
-     * Converts an opacity ratio into a two-digit hexadecimal alpha suffix.
+     * Draws one projected patch with soft octopus shading.
      *
-     * @private helper of `octopus3dAvatarVisual`
+     * @private helper of `octopus3d2AvatarVisual`
      */
-    function formatAlphaHex(opacity) {
-        return Math.round(clampNumber$1(opacity, 0, 1) * 255)
-            .toString(16)
-            .padStart(2, '0');
+    function drawBlobbySurfacePatch(context, surfacePatch) {
+        drawProjectedQuad(context, surfacePatch.corners, surfacePatch.fillStyle);
+        if (surfacePatch.lightIntensity > 0) {
+            drawProjectedQuad(context, surfacePatch.corners, `rgba(255, 255, 255, ${0.16 * surfacePatch.lightIntensity})`);
+        }
+        else if (surfacePatch.lightIntensity < 0) {
+            drawProjectedQuad(context, surfacePatch.corners, `rgba(0, 0, 0, ${0.24 * Math.abs(surfacePatch.lightIntensity)})`);
+        }
+        context.save();
+        context.beginPath();
+        context.moveTo(surfacePatch.corners[0].x, surfacePatch.corners[0].y);
+        for (let cornerIndex = 1; cornerIndex < surfacePatch.corners.length; cornerIndex++) {
+            context.lineTo(surfacePatch.corners[cornerIndex].x, surfacePatch.corners[cornerIndex].y);
+        }
+        context.closePath();
+        context.strokeStyle = surfacePatch.outlineColor;
+        context.lineWidth = Math.max(1, getProjectedQuadPerimeter(surfacePatch.corners) * 0.0042);
+        context.lineJoin = 'round';
+        context.stroke();
+        context.restore();
     }
 
     /* eslint-disable no-magic-numbers */
@@ -9155,6 +9455,7 @@
         octopus2AvatarVisual,
         octopus3AvatarVisual,
         octopus3dAvatarVisual,
+        octopus3d2AvatarVisual,
         asciiOctopusAvatarVisual,
         minecraftAvatarVisual,
         minecraft2AvatarVisual,
@@ -14819,11 +15120,11 @@
         });
     }
     /**
-     * Best-effort decoder for uploaded or remote file bytes whose extension or encoding may be unknown.
+     * Prepares one attachment for best-effort text decoding.
      *
-     * @private internal utility for shared text decoding
+     * @private function of decodeAttachmentAsText
      */
-    function decodeAttachmentAsText(input, options = {}) {
+    function createDecodeAttachmentPreparation(input, options) {
         var _a;
         const maxBytes = Math.max(1, Math.floor((_a = options.maxBytes) !== null && _a !== void 0 ? _a : DEFAULT_ATTACHMENT_TEXT_DECODE_BYTES));
         const forceText = options.forceText === true;
@@ -14837,54 +15138,102 @@
         const inspection = inspectBytes(truncatedBytes);
         const trustedTextMime = isTrustedTextMimeType(mimeType);
         const trustedBinaryMime = isTrustedBinaryMimeType(mimeType);
+        const shouldTreatAsBinary = (trustedBinaryMime || inspection.looksBinary) && !trustedTextMime;
         if (isTruncated) {
             warnings.push(`Decoded only the first ${maxBytes} bytes of \`${input.filename}\` because the attachment exceeded the text preview limit.`);
         }
-        const shouldTreatAsBinary = (trustedBinaryMime || inspection.looksBinary) && !trustedTextMime;
-        if (shouldTreatAsBinary && !forceText) {
-            warnings.push('File content looks binary, so text decoding was skipped.');
-            return {
-                text: '',
-                encodingUsed: 'binary',
-                confidence: 1,
-                warnings,
-                wasBinary: true,
-                isTruncated,
-            };
+        return {
+            warnings,
+            charset,
+            bom,
+            inspection,
+            truncatedBytes,
+            isTruncated,
+            forceText,
+            shouldTreatAsBinary,
+        };
+    }
+    /**
+     * Returns an early result when the attachment should stay classified as binary.
+     *
+     * @private function of decodeAttachmentAsText
+     */
+    function createBinaryDecodeResult(preparation) {
+        if (!preparation.shouldTreatAsBinary) {
+            return null;
         }
-        if (shouldTreatAsBinary && forceText) {
-            warnings.push('File content looks binary, but text decoding was forced with `forceText`.');
+        if (preparation.forceText) {
+            preparation.warnings.push('File content looks binary, but text decoding was forced with `forceText`.');
+            return null;
         }
-        if (charset && !isSupportedEncoding(charset)) {
-            warnings.push(`Ignored unsupported declared charset \`${charset}\` and used best-effort detection instead.`);
+        preparation.warnings.push('File content looks binary, so text decoding was skipped.');
+        return {
+            text: '',
+            encodingUsed: 'binary',
+            confidence: 1,
+            warnings: preparation.warnings,
+            wasBinary: true,
+            isTruncated: preparation.isTruncated,
+        };
+    }
+    /**
+     * Warns when the declared charset cannot be used by the runtime decoder.
+     *
+     * @private function of decodeAttachmentAsText
+     */
+    function addUnsupportedCharsetWarning(preparation) {
+        if (preparation.charset && !isSupportedEncoding(preparation.charset)) {
+            preparation.warnings.push(`Ignored unsupported declared charset \`${preparation.charset}\` and used best-effort detection instead.`);
         }
-        const bytesToDecode = bom ? truncatedBytes.subarray(bom.offset) : truncatedBytes;
-        const candidates = buildCandidateEncodings({
-            mimeType,
-            charset: charset && isSupportedEncoding(charset) ? charset : null,
-            bom,
-            inspection,
-        });
-        const decodedCandidates = candidates
+    }
+    /**
+     * Returns the byte slice that should actually be decoded as text.
+     *
+     * @private function of decodeAttachmentAsText
+     */
+    function getBytesToDecode(preparation) {
+        return preparation.bom ? preparation.truncatedBytes.subarray(preparation.bom.offset) : preparation.truncatedBytes;
+    }
+    /**
+     * Decodes all candidate encodings and sorts the successful results by score.
+     *
+     * @private function of decodeAttachmentAsText
+     */
+    function decodeAttachmentCandidates(preparation) {
+        return buildCandidateEncodings({
+            charset: preparation.charset && isSupportedEncoding(preparation.charset) ? preparation.charset : null,
+            bom: preparation.bom,
+            inspection: preparation.inspection,
+        })
             .map(({ encoding, source }) => {
-            const decoded = decodeWithEncoding(bytesToDecode, encoding);
+            const decoded = decodeWithEncoding(getBytesToDecode(preparation), encoding);
             return decoded ? { ...decoded, source } : null;
         })
             .filter((candidate) => candidate !== null)
             .sort((left, right) => left.score - right.score);
-        const bestCandidate = decodedCandidates[0];
-        if (!bestCandidate) {
-            warnings.push('No supported text decoder was available.');
-            return {
-                text: '',
-                encodingUsed: 'binary',
-                confidence: 0,
-                warnings,
-                wasBinary: true,
-                isTruncated,
-            };
-        }
-        const secondBestCandidate = decodedCandidates[1];
+    }
+    /**
+     * Returns the fallback result used when no text decoder could be applied.
+     *
+     * @private function of decodeAttachmentAsText
+     */
+    function createNoDecoderAvailableResult(preparation) {
+        preparation.warnings.push('No supported text decoder was available.');
+        return {
+            text: '',
+            encodingUsed: 'binary',
+            confidence: 0,
+            warnings: preparation.warnings,
+            wasBinary: true,
+            isTruncated: preparation.isTruncated,
+        };
+    }
+    /**
+     * Estimates confidence for the winning decoded text candidate.
+     *
+     * @private function of decodeAttachmentAsText
+     */
+    function computeDecodeConfidence(bestCandidate, secondBestCandidate, preparation) {
         const baseConfidence = bestCandidate.source === 'bom'
             ? 1
             : bestCandidate.source === 'charset'
@@ -14897,27 +15246,62 @@
                         ? 0.82
                         : 0.62;
         const scoreMargin = secondBestCandidate ? Math.max(0, secondBestCandidate.score - bestCandidate.score) : 0.2;
-        const confidence = Math.max(0.2, Math.min(shouldTreatAsBinary && forceText ? 0.45 : 1, baseConfidence + Math.min(0.18, scoreMargin / 2)));
+        return Math.max(0.2, Math.min(preparation.shouldTreatAsBinary && preparation.forceText ? 0.45 : 1, baseConfidence + Math.min(0.18, scoreMargin / 2)));
+    }
+    /**
+     * Appends user-facing warnings derived from the chosen decoded text candidate.
+     *
+     * @private function of decodeAttachmentAsText
+     */
+    function addDecodeWarnings(bestCandidate, confidence, preparation) {
         if (bestCandidate.source === 'heuristic' && bestCandidate.encoding !== 'utf-8') {
-            warnings.push(`Encoding was guessed as \`${bestCandidate.encoding}\`.`);
+            preparation.warnings.push(`Encoding was guessed as \`${bestCandidate.encoding}\`.`);
         }
         if (bestCandidate.source === 'heuristic' &&
             bestCandidate.encoding === 'utf-8' &&
             bestCandidate.replacementCount > 0) {
-            warnings.push('UTF-8 decoding produced replacement characters, so the extracted text may contain errors.');
+            preparation.warnings.push('UTF-8 decoding produced replacement characters, so the extracted text may contain errors.');
         }
         if (confidence < 0.6) {
-            warnings.push('Decoding confidence is low, so the extracted text may contain errors.');
+            preparation.warnings.push('Decoding confidence is low, so the extracted text may contain errors.');
         }
+    }
+    /**
+     * Creates the final decoded-text result from the chosen candidate and accumulated metadata.
+     *
+     * @private function of decodeAttachmentAsText
+     */
+    function createDecodedTextResult(bestCandidate, confidence, preparation) {
         return {
-            text: isTruncated ? appendTruncatedMarker(bestCandidate.text) : bestCandidate.text,
+            text: preparation.isTruncated ? appendTruncatedMarker(bestCandidate.text) : bestCandidate.text,
             encodingUsed: bestCandidate.encoding,
             confidence,
-            warnings,
+            warnings: preparation.warnings,
             wasBinary: false,
-            isTruncated,
+            isTruncated: preparation.isTruncated,
         };
     }
+    /**
+     * Best-effort decoder for uploaded or remote file bytes whose extension or encoding may be unknown.
+     *
+     * @private internal utility for shared text decoding
+     */
+    function decodeAttachmentAsText(input, options = {}) {
+        const preparation = createDecodeAttachmentPreparation(input, options);
+        const binaryResult = createBinaryDecodeResult(preparation);
+        if (binaryResult) {
+            return binaryResult;
+        }
+        addUnsupportedCharsetWarning(preparation);
+        const decodedCandidates = decodeAttachmentCandidates(preparation);
+        const bestCandidate = decodedCandidates[0];
+        if (!bestCandidate) {
+            return createNoDecoderAvailableResult(preparation);
+        }
+        const confidence = computeDecodeConfidence(bestCandidate, decodedCandidates[1], preparation);
+        addDecodeWarnings(bestCandidate, confidence, preparation);
+        return createDecodedTextResult(bestCandidate, confidence, preparation);
+    }
 
     /**
      * Convert file extension to mime type
@@ -19285,120 +19669,183 @@
      * @public exported from `@promptbook/utils`
      */
     function checkSerializableAsJson(options) {
-        const { value, name, message } = options;
+        checkSerializableValue(options);
+    }
+    // TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
+    // TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
+    // Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
+    /**
+     * Checks one value and dispatches to the appropriate specialized validator.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableValue(options) {
+        const { value } = options;
+        if (isSerializablePrimitive(value)) {
+            return;
+        }
         if (value === undefined) {
-            throw new UnexpectedError(`${name} is undefined`);
+            throw new UnexpectedError(`${options.name} is undefined`);
         }
-        else if (value === null) {
-            return;
+        if (typeof value === 'symbol') {
+            throw new UnexpectedError(`${options.name} is symbol`);
         }
-        else if (typeof value === 'boolean') {
-            return;
+        if (typeof value === 'function') {
+            throw new UnexpectedError(`${options.name} is function`);
         }
-        else if (typeof value === 'number' && !isNaN(value)) {
+        if (Array.isArray(value)) {
+            checkSerializableArray(options, value);
             return;
         }
-        else if (typeof value === 'string') {
+        if (value !== null && typeof value === 'object') {
+            checkSerializableObject(options, value);
             return;
         }
-        else if (typeof value === 'symbol') {
-            throw new UnexpectedError(`${name} is symbol`);
-        }
-        else if (typeof value === 'function') {
-            throw new UnexpectedError(`${name} is function`);
-        }
-        else if (typeof value === 'object' && Array.isArray(value)) {
-            for (let i = 0; i < value.length; i++) {
-                checkSerializableAsJson({ name: `${name}[${i}]`, value: value[i], message });
-            }
+        throwUnknownTypeError(options);
+    }
+    /**
+     * Checks the primitive values that are directly JSON serializable.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function isSerializablePrimitive(value) {
+        return (value === null ||
+            typeof value === 'boolean' ||
+            (typeof value === 'number' && !isNaN(value)) ||
+            typeof value === 'string');
+    }
+    /**
+     * Recursively checks JSON array items.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableArray(context, arrayValue) {
+        for (let index = 0; index < arrayValue.length; index++) {
+            checkSerializableAsJson({
+                ...context,
+                name: `${context.name}[${index}]`,
+                value: arrayValue[index],
+            });
         }
-        else if (typeof value === 'object') {
-            if (value instanceof Date) {
-                throw new UnexpectedError(spacetrim.spaceTrim((block) => `
-                        \`${name}\` is Date
+    }
+    /**
+     * Checks object-like values and dispatches special unsupported built-ins.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableObject(context, objectValue) {
+        checkUnsupportedObjectType(context, objectValue);
+        checkSerializableObjectEntries(context, objectValue);
+        assertJsonStringificationSucceeds(context, objectValue);
+    }
+    /**
+     * Rejects built-in objects that must be converted before JSON serialization.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkUnsupportedObjectType(context, objectValue) {
+        if (objectValue instanceof Date) {
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                    \`${context.name}\` is Date
 
-                        Use \`string_date_iso8601\` instead
+                    Use \`string_date_iso8601\` instead
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
-                    `));
-            }
-            else if (value instanceof Map) {
-                throw new UnexpectedError(`${name} is Map`);
-            }
-            else if (value instanceof Set) {
-                throw new UnexpectedError(`${name} is Set`);
-            }
-            else if (value instanceof RegExp) {
-                throw new UnexpectedError(`${name} is RegExp`);
-            }
-            else if (value instanceof Error) {
-                throw new UnexpectedError(spacetrim.spaceTrim((block) => `
-                        \`${name}\` is unserialized Error
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
+                `));
+        }
+        if (objectValue instanceof Map) {
+            throw new UnexpectedError(`${context.name} is Map`);
+        }
+        if (objectValue instanceof Set) {
+            throw new UnexpectedError(`${context.name} is Set`);
+        }
+        if (objectValue instanceof RegExp) {
+            throw new UnexpectedError(`${context.name} is RegExp`);
+        }
+        if (objectValue instanceof Error) {
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                    \`${context.name}\` is unserialized Error
 
-                        Use function \`serializeError\`
+                    Use function \`serializeError\`
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
 
-                    `));
+                `));
+        }
+    }
+    /**
+     * Recursively checks object properties while preserving omitted `undefined` keys.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableObjectEntries(context, objectValue) {
+        for (const [subName, subValue] of Object.entries(objectValue)) {
+            if (subValue === undefined) {
+                // Note: undefined in object is serializable - it is just omitted
+                continue;
             }
-            else {
-                for (const [subName, subValue] of Object.entries(value)) {
-                    if (subValue === undefined) {
-                        // Note: undefined in object is serializable - it is just omitted
-                        continue;
-                    }
-                    checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
-                }
-                try {
-                    JSON.stringify(value); // <- TODO: [0]
-                }
-                catch (error) {
-                    assertsError(error);
-                    throw new UnexpectedError(spacetrim.spaceTrim((block) => `
-                            \`${name}\` is not serializable
+            checkSerializableAsJson({
+                ...context,
+                name: `${context.name}.${subName}`,
+                value: subValue,
+            });
+        }
+    }
+    /**
+     * Uses `JSON.stringify` as the final guard for cases like circular references.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function assertJsonStringificationSucceeds(context, objectValue) {
+        try {
+            JSON.stringify(objectValue); // <- TODO: [0]
+        }
+        catch (error) {
+            assertsError(error);
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                    \`${context.name}\` is not serializable
 
-                            ${block(error.stack || error.message)}
+                    ${block(error.stack || error.message)}
 
-                            Additional message for \`${name}\`:
-                            ${block(message || '(nothing)')}
-                        `));
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
+                `));
+        }
+        /*
+        TODO: [0] Is there some more elegant way to check circular references?
+        const seen = new Set();
+        const stack = [{ value }];
+        while (stack.length > 0) {
+            const { value } = stack.pop()!;
+            if (typeof value === 'object' && value !== null) {
+                if (seen.has(value)) {
+                    throw new UnexpectedError(`${name} has circular reference`);
                 }
-                /*
-                TODO: [0] Is there some more elegant way to check circular references?
-                const seen = new Set();
-                const stack = [{ value }];
-                while (stack.length > 0) {
-                    const { value } = stack.pop()!;
-                    if (typeof value === 'object' && value !== null) {
-                        if (seen.has(value)) {
-                            throw new UnexpectedError(`${name} has circular reference`);
-                        }
-                        seen.add(value);
-                        if (Array.isArray(value)) {
-                            stack.push(...value.map((value) => ({ value })));
-                        } else {
-                            stack.push(...Object.values(value).map((value) => ({ value })));
-                        }
-                    }
+                seen.add(value);
+                if (Array.isArray(value)) {
+                    stack.push(...value.map((value) => ({ value })));
+                } else {
+                    stack.push(...Object.values(value).map((value) => ({ value })));
                 }
-                */
-                return;
             }
         }
-        else {
-            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
-                    \`${name}\` is unknown type
+        */
+    }
+    /**
+     * Throws the fallback error for unsupported value types like `bigint` and `NaN`.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function throwUnknownTypeError(context) {
+        throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                \`${context.name}\` is unknown type
 
-                    Additional message for \`${name}\`:
-                    ${block(message || '(nothing)')}
-                `));
-        }
+                Additional message for \`${context.name}\`:
+                ${block(context.message || '(nothing)')}
+            `));
     }
-    // TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
-    // TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
-    // Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
 
     /**
      * Creates a deep clone of the given object
@@ -22351,7 +22798,7 @@
      */
     function createPostprocessingCommands(task) {
         var _a;
-        return ((_a = task.postprocessingFunctionNames) === null || _a === void 0 ? void 0 : _a.map((postprocessingFunctionName) => `POSTPROCESSING \`${postprocessingFunctionName}\``)) || [];
+        return (((_a = task.postprocessingFunctionNames) === null || _a === void 0 ? void 0 : _a.map((postprocessingFunctionName) => `POSTPROCESSING \`${postprocessingFunctionName}\``)) || []);
     }
     /**
      * Collects expectation commands.
@@ -22894,8 +23341,7 @@
      * @private internal utility of `validatePipeline`
      */
     function validateTaskSupportsJokers(task, pipelineIdentification) {
-        if (task.format ||
-            task.expectations /* <- TODO: Require at least 1 -> min <- expectation to use jokers */) {
+        if (task.format || task.expectations /* <- TODO: Require at least 1 -> min <- expectation to use jokers */) {
             return;
         }
         throw new PipelineLogicError(spacetrim.spaceTrim((block) => `
@@ -26260,9 +26706,7 @@
                     ${block(quoteMultilineText(((_b = failure.error) === null || _b === void 0 ? void 0 : _b.message) || ''))}
 
                     Result:
-                    ${block(failure.result === null
-            ? 'null'
-            : quoteMultilineText(spacetrim.spaceTrim(failure.result)))}
+                    ${block(failure.result === null ? 'null' : quoteMultilineText(spacetrim.spaceTrim(failure.result)))}
                 `;
         }))
             .join('\n\n---\n\n');
@@ -30102,7 +30546,10 @@
                             Cannot find model in ${this.options.getTitle()} models with name "${defaultModelName}" which should be used as default.
 
                             Available models:
-                            ${block(this.options.getHardcodedModels().map(({ modelName }) => `- "${modelName}"`).join('\n'))}
+                            ${block(this.options
+                .getHardcodedModels()
+                .map(({ modelName }) => `- "${modelName}"`)
+                .join('\n'))}
 
                             Model "${defaultModelName}" is probably not available anymore, not installed, inaccessible or misconfigured.
 
@@ -30456,7 +30903,8 @@
             };
             let rawPromptContent = templateParameters(content, { ...parameters, modelName });
             if ('attachments' in prompt && Array.isArray(prompt.attachments) && prompt.attachments.length > 0) {
-                rawPromptContent += '\n\n' + prompt.attachments.map((attachment) => `Image attachment: ${attachment.url}`).join('\n');
+                rawPromptContent +=
+                    '\n\n' + prompt.attachments.map((attachment) => `Image attachment: ${attachment.url}`).join('\n');
             }
             const rawRequest = {
                 ...modelSettings,
@@ -30561,7 +31009,9 @@
          * Schedules one request through the shared limiter and retry policy.
          */
         async executeRateLimitedRequest(requestFn) {
-            return this.limiter.schedule(() => this.makeRequestWithNetworkRetry(requestFn)).catch((error) => {
+            return this.limiter
+                .schedule(() => this.makeRequestWithNetworkRetry(requestFn))
+                .catch((error) => {
                 assertsError(error);
                 if (this.options.isVerbose) {
                     console.info(colors__default["default"].bgRed('error'), error);
@@ -31768,7 +32218,9 @@
                 pollingState.lastProgressAtMs = nowMs;
                 pollingState.lastProgressKey = progressKey;
             }
-            if (this.options.isVerbose && (statusCountsKey !== pollingState.lastCountsKey || nowMs - pollingState.lastLogAtMs >= progressLogIntervalMs)) {
+            if (this.options.isVerbose &&
+                (statusCountsKey !== pollingState.lastCountsKey ||
+                    nowMs - pollingState.lastLogAtMs >= progressLogIntervalMs)) {
                 console.info('[🤰]', 'Vector store file batch status', {
                     vectorStoreId,
                     batchId,