@promptbook/browser 0.112.0-73 → 0.112.0-79

package/esm/index.es.js

@@ -29,7 +29,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @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
@@ -279,6 +279,111 @@ function checkChannelValue(channelName, value) {
     }
 }
 
+/**
+ * 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.
  */
@@ -490,16 +595,53 @@ function parseAlphaValue(value) {
 
 /**
  * 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
  *
@@ -507,7 +649,7 @@ const RGBA_REGEX_PATTERN = /^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.
  *
  * @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
@@ -580,25 +722,7 @@ class Color {
      * @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
@@ -628,8 +752,7 @@ class Color {
      * @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
@@ -638,8 +761,7 @@ class Color {
      * @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
@@ -648,8 +770,7 @@ class Color {
      * @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
@@ -658,8 +779,7 @@ class Color {
      * @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
@@ -671,7 +791,7 @@ class Color {
      * @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.
@@ -704,8 +824,7 @@ class Color {
      * @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
@@ -718,89 +837,13 @@ class Color {
      * @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));
     }
 }
 
@@ -6594,7 +6637,7 @@ function fillTextureRect(texture, x, y, width, height, color) {
  *
  * @private helper of `minecraft2AvatarVisual`
  */
-const LIGHT_DIRECTION$1 = normalizeVector3({
+const LIGHT_DIRECTION$2 = normalizeVector3({
     x: 0.4,
     y: -0.65,
     z: 0.92,
@@ -6806,7 +6849,7 @@ function resolveVisibleCuboidFaces(cuboid, size, sceneCenterX, sceneCenterY) {
             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,
         };
     });
@@ -7866,13 +7909,138 @@ function drawSeededEye(context, centerX, centerY, radiusX, radiusY, rotation, pa
     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,
@@ -7985,17 +8153,17 @@ const octopus3dAvatarVisual = {
         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,
@@ -8082,7 +8250,7 @@ function resolveVisibleEllipsoidPatches(options) {
                 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,
             });
@@ -8264,128 +8432,260 @@ function resolveEllipsoidSurfaceDepth(radiusX, radiusY, radiusZ, x, y) {
     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 */
@@ -9157,6 +9457,7 @@ const AVATAR_VISUALS = [
     octopus2AvatarVisual,
     octopus3AvatarVisual,
     octopus3dAvatarVisual,
+    octopus3d2AvatarVisual,
     asciiOctopusAvatarVisual,
     minecraftAvatarVisual,
     minecraft2AvatarVisual,
@@ -14821,11 +15122,11 @@ function buildCandidateEncodings(options) {
     });
 }
 /**
- * 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;
@@ -14839,54 +15140,102 @@ function decodeAttachmentAsText(input, options = {}) {
     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'
@@ -14899,27 +15248,62 @@ function decodeAttachmentAsText(input, options = {}) {
                     ? 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
@@ -19287,120 +19671,183 @@ function orderJson(options) {
  * @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$1((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$1((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$1((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$1((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$1((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$1((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$1((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$1((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
@@ -22353,7 +22800,7 @@ function createJokerCommands(task) {
  */
 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.
@@ -22896,8 +23343,7 @@ function hasTaskJokers(task) {
  * @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$1((block) => `
@@ -26262,9 +26708,7 @@ function createFailuresSummary($failedResults) {
                     ${block(quoteMultilineText(((_b = failure.error) === null || _b === void 0 ? void 0 : _b.message) || ''))}
 
                     Result:
-                    ${block(failure.result === null
-            ? 'null'
-            : quoteMultilineText(spaceTrim$1(failure.result)))}
+                    ${block(failure.result === null ? 'null' : quoteMultilineText(spaceTrim$1(failure.result)))}
                 `;
     }))
         .join('\n\n---\n\n');
@@ -30104,7 +30548,10 @@ class OpenAiCompatibleModelCatalog {
                             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.
 
@@ -30458,7 +30905,8 @@ class OpenAiCompatibleNonChatPromptCaller {
         };
         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,
@@ -30563,7 +31011,9 @@ class OpenAiCompatibleRequestManager {
      * 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.bgRed('error'), error);
@@ -31770,7 +32220,9 @@ class OpenAiVectorStoreFileBatchPoller {
             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,