@promptbook/remote-server 0.112.0-54 → 0.112.0-56

package/esm/index.es.js

@@ -40,7 +40,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-54';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-56';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -11227,6 +11227,24 @@ class BaseCommitmentDefinition {
     get requiresContent() {
         return true;
     }
+    /**
+     * Whether this commitment should be prioritized in menus, documentation, and intellisense.
+     */
+    get isImportant() {
+        return false;
+    }
+    /**
+     * Whether this commitment is unfinished and not ready to use.
+     */
+    get isUnfinished() {
+        return false;
+    }
+    /**
+     * Whether this commitment is low-level and should be surfaced with caution.
+     */
+    get isLowLevel() {
+        return false;
+    }
     /**
      * Optional UI/docs-only deprecation metadata.
      */
@@ -11343,8 +11361,8 @@ class BaseCommitmentDefinition {
 /**
  * ACTION commitment definition
  *
- * The ACTION commitment defines specific actions or capabilities that the agent can perform.
- * This helps define what the agent is capable of doing and how it should approach tasks.
+ * Deprecated legacy commitment for broad capability notes.
+ * New books should prefer the appropriate `USE*` commitment instead.
  *
  * Example usage in agent source:
  *
@@ -11363,7 +11381,15 @@ class ActionCommitmentDefinition extends BaseCommitmentDefinition {
      * Short one-line description of ACTION.
      */
     get description() {
-        return 'Define agent capabilities and actions it can perform.';
+        return 'Deprecated legacy capability commitment. Prefer concrete `USE*` commitments.';
+    }
+    /**
+     * Optional UI/docs-only deprecation metadata.
+     */
+    get deprecation() {
+        return {
+            message: 'Use a concrete `USE*` commitment instead.',
+        };
     }
     /**
      * Icon for this commitment.
@@ -11378,33 +11404,43 @@ class ActionCommitmentDefinition extends BaseCommitmentDefinition {
         return spaceTrim$1(`
             # ${this.type}
 
-            Defines specific actions or capabilities that the agent can perform.
+            Deprecated legacy commitment for broad capability notes.
 
-            ## Key aspects
+            ## Migration
 
-            - Both terms work identically and can be used interchangeably.
-            - Each action adds to the agent's capability list.
-            - Actions help users understand what the agent can do.
+            - Existing \`${this.type}\` and \`ACTIONS\` books still parse and compile.
+            - New books should prefer the appropriate \`USE*\` commitment instead.
+            - Keep \`${this.type}\` only when maintaining older books that already rely on it.
 
-            ## Examples
+            ## Preferred replacement
 
             \`\`\`book
-            Code Assistant
+            Research Assistant
 
-            PERSONA You are a programming assistant
-            ACTION Can generate code snippets and explain programming concepts
-            ACTION Able to debug existing code and suggest improvements
-            ACTION Can create unit tests for functions
+            PERSONA You are a helpful research assistant
+            USE SEARCH ENGINE
+            RULE Always cite your sources when providing information from the web
+            \`\`\`
+
+            ## Legacy compatibility example
+
+            \`\`\`book
+            Research Assistant
+
+            PERSONA You are a helpful research assistant
+            ACTION Can search for current information and summarize findings
+            RULE Always cite your sources when providing information from the web
             \`\`\`
 
+            ## Legacy compatibility example with additional tools
+
             \`\`\`book
-            Data Scientist
+            Code Assistant
 
-            PERSONA You are a data analysis expert
-            ACTION Able to analyze data and provide insights
-            ACTION Can create visualizations and charts
-            ACTION Capable of statistical analysis and modeling
-            KNOWLEDGE Data analysis best practices and statistical methods
+            PERSONA You are a programming assistant
+            USE BROWSER
+            USE SEARCH ENGINE
+            RULE Prefer the narrowest useful capability for the task.
             \`\`\`
         `);
     }
@@ -11413,7 +11449,7 @@ class ActionCommitmentDefinition extends BaseCommitmentDefinition {
         if (!trimmedContent) {
             return requirements;
         }
-        // Add action capability to the system message
+        // Keep the legacy capability note for backward compatibility.
         const actionSection = `Capability: ${trimmedContent}`;
         return this.appendToSystemMessage(requirements, actionSection, '\n\n');
     }
@@ -11548,9 +11584,9 @@ class ComponentCommitmentDefinition extends BaseCommitmentDefinition {
 /**
  * DELETE commitment definition
  *
- * The DELETE commitment (and its aliases CANCEL, DISCARD, REMOVE) is used to
- * remove or disregard certain information or context. This can be useful for
- * overriding previous commitments or removing unwanted behaviors.
+ * The DELETE commitment (and its aliases CANCEL, DISCARD, REMOVE) is a low-level
+ * unfinished commitment used to remove or disregard certain information or context.
+ * It is intentionally surfaced with caution because it is not ready for broad use yet.
  *
  * Example usage in agent source:
  *
@@ -11571,7 +11607,13 @@ class DeleteCommitmentDefinition extends BaseCommitmentDefinition {
      * Short one-line description of DELETE/CANCEL/DISCARD/REMOVE.
      */
     get description() {
-        return 'Remove or **disregard** certain information, context, or previous commitments.';
+        return 'Unfinished low-level commitment for removing or disregarding information. Use carefully.';
+    }
+    /**
+     * Marks DELETE as unfinished and not ready to use.
+     */
+    get isUnfinished() {
+        return true;
     }
     /**
      * Icon for this commitment.
@@ -11586,7 +11628,13 @@ class DeleteCommitmentDefinition extends BaseCommitmentDefinition {
         return spaceTrim$1(`
             # DELETE (CANCEL, DISCARD, REMOVE)
 
-            A commitment to remove or disregard certain information or context. This can be useful for overriding previous commitments or removing unwanted behaviors.
+            A low-level unfinished commitment to remove or disregard certain information or context. It is not ready to use broadly yet, so use it carefully.
+
+            ## Status
+
+            - This commitment is unfinished and not ready to use yet.
+            - Treat it as a low-level prompt-surgery tool rather than a general-purpose commitment.
+            - Prefer higher-level commitments when a clearer dedicated commitment exists.
 
             ## Aliases
 
@@ -11601,6 +11649,7 @@ class DeleteCommitmentDefinition extends BaseCommitmentDefinition {
             - Useful for overriding previous commitments in the same agent definition.
             - Can be used to remove inherited behaviors from base personas.
             - Helps fine-tune agent behavior by explicitly removing unwanted elements.
+            - Because this commitment is unfinished, keep an eye on future changes before relying on it in production books.
 
             ## Use cases
 
@@ -11608,6 +11657,7 @@ class DeleteCommitmentDefinition extends BaseCommitmentDefinition {
             - Removing conflicting or outdated instructions
             - Disabling specific response patterns
             - Canceling previous formatting or style requirements
+            - Experimenting with low-level prompt rewrites when you know exactly what needs to be removed
 
             ## Examples
 
@@ -11774,11 +11824,10 @@ class DictionaryCommitmentDefinition extends BaseCommitmentDefinition {
 /**
  * FORMAT commitment definition
  *
- * The FORMAT commitment defines the specific output structure and formatting
- * that the agent should use in its responses. This includes data formats,
- * response templates, and structural requirements.
+ * Deprecated legacy commitment for output formatting and response structure.
+ * New books should prefer `WRITING SAMPLE` and `WRITING RULES`.
  *
- * Example usage in agent source:
+ * Legacy example usage in agent source:
  *
  * ```book
  * FORMAT Always respond in JSON format with 'status' and 'data' fields
@@ -11795,7 +11844,16 @@ class FormatCommitmentDefinition extends BaseCommitmentDefinition {
      * Short one-line description of FORMAT.
      */
     get description() {
-        return 'Specify output structure or formatting requirements.';
+        return 'Deprecated legacy formatting commitment. Prefer `WRITING SAMPLE` and `WRITING RULES` for new books.';
+    }
+    /**
+     * Optional UI/docs-only deprecation metadata.
+     */
+    get deprecation() {
+        return {
+            message: 'Use `WRITING SAMPLE` and `WRITING RULES` instead.',
+            replacedBy: ['WRITING SAMPLE', 'WRITING RULES'],
+        };
     }
     /**
      * Icon for this commitment.
@@ -11810,31 +11868,39 @@ class FormatCommitmentDefinition extends BaseCommitmentDefinition {
         return spaceTrim$1(`
             # ${this.type}
 
-            Defines the specific output structure and formatting for responses (data formats, templates, structure).
+            Deprecated legacy commitment for output formatting and response structure.
 
-            ## Key aspects
+            ## Migration
 
-            - Both terms work identically and can be used interchangeably.
-            - If they are in conflict, the last one takes precedence.
-            - You can specify both data formats and presentation styles.
+            - Existing \`${this.type}\` and \`FORMATS\` books still parse and compile.
+            - New books should use \`WRITING RULES\` for formatting or structure constraints and \`WRITING SAMPLE\` when a concrete example communicates the target shape better.
+            - Runtime behavior is intentionally unchanged for backward compatibility.
 
-            ## Examples
+            ## Preferred replacement
 
             \`\`\`book
-            Customer Support Bot
+            Data Analyst
 
-            PERSONA You are a helpful customer support agent
-            FORMAT Always respond in JSON format with 'status' and 'data' fields
-            FORMAT Use markdown formatting for all code blocks
+            GOAL Present results in a clean, readable structure.
+            WRITING RULES Use markdown headings for sections and bullet points for lists.
+            WRITING RULES Keep tables narrow and readable.
+            WRITING SAMPLE
+            Summary
+            - ...
+            Details
+            - ...
+            Next steps
+            - ...
             \`\`\`
 
+            ## Legacy compatibility example
+
             \`\`\`book
             Data Analyst
 
-            PERSONA You are a data analysis expert
+            GOAL Present results in a clean structure.
             FORMAT Present results in structured tables
             FORMAT Include confidence scores for all predictions
-            WRITING RULES Be concise and precise in explanations
             \`\`\`
         `);
     }
@@ -12185,6 +12251,12 @@ class GoalCommitmentDefinition extends BaseCommitmentDefinition {
     get description() {
         return 'Define the effective agent **goal**; when multiple goals exist, only the last one stays effective.';
     }
+    /**
+     * Marks GOAL as one of the priority commitments surfaced first in catalogues.
+     */
+    get isImportant() {
+        return true;
+    }
     /**
      * Icon for this commitment.
      */
@@ -12596,6 +12668,12 @@ class KnowledgeCommitmentDefinition extends BaseCommitmentDefinition {
     get description() {
         return 'Add domain **knowledge** via direct text or external sources (RAG).';
     }
+    /**
+     * Marks KNOWLEDGE as one of the priority commitments surfaced first in catalogues.
+     */
+    get isImportant() {
+        return true;
+    }
     /**
      * Icon for this commitment.
      */
@@ -13883,6 +13961,7 @@ class MessageSuffixCommitmentDefinition extends BaseCommitmentDefinition {
  * META commitment definition
  *
  * The META commitment handles all meta-information about the agent such as:
+ * - META AVATAR: Sets the agent's built-in default avatar visual
  * - META IMAGE: Sets the agent's avatar/profile image URL
  * - META LINK: Provides profile/source links for the person the agent models
  * - META DOMAIN: Sets the canonical custom domain/host of the agent
@@ -13897,6 +13976,7 @@ class MessageSuffixCommitmentDefinition extends BaseCommitmentDefinition {
  * Example usage in agent source:
  *
  * ```book
+ * META AVATAR pixel-art
  * META IMAGE https://example.com/avatar.jpg
  * META LINK https://twitter.com/username
  * META DOMAIN my-agent.com
@@ -13936,6 +14016,7 @@ class MetaCommitmentDefinition extends BaseCommitmentDefinition {
 
             ## Supported META types
 
+            - **META AVATAR** - Sets the agent's built-in default avatar visual
             - **META IMAGE** - Sets the agent's avatar/profile image URL
             - **META LINK** - Provides profile/source links for the person the agent models
             - **META DOMAIN** - Sets the canonical custom domain/host of the agent
@@ -13959,6 +14040,7 @@ class MetaCommitmentDefinition extends BaseCommitmentDefinition {
             \`\`\`book
             Professional Assistant
 
+            META AVATAR octopus3
             META IMAGE https://example.com/professional-avatar.jpg
             META TITLE Senior Business Consultant
             META DESCRIPTION Specialized in strategic planning and project management
@@ -14020,12 +14102,3236 @@ class MetaCommitmentDefinition extends BaseCommitmentDefinition {
      * Checks if this is a known meta type
      */
     isKnownMetaType(metaType) {
-        const knownTypes = ['IMAGE', 'LINK', 'TITLE', 'DESCRIPTION', 'AUTHOR', 'VERSION', 'LICENSE'];
+        const knownTypes = ['AVATAR', 'IMAGE', 'LINK', 'TITLE', 'DESCRIPTION', 'AUTHOR', 'VERSION', 'LICENSE'];
         return knownTypes.includes(metaType.toUpperCase());
     }
 }
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * Makes color transformer which darker the given color
+ *
+ * @param amount from 0 to 1
+ *
+ * @public exported from `@promptbook/color`
+ */
+function darken(amount) {
+    return lighten(-amount);
+}
+
+/* eslint-disable no-magic-numbers */
+/**
+ * Corner radius ratio used for the common rounded card frame.
+ *
+ * @private utility of the avatar rendering system
+ */
+const FRAME_RADIUS_RATIO = 0.18;
+/**
+ * Draws the common rounded background frame used by most visuals.
+ *
+ * @param context Canvas 2D context.
+ * @param size Canvas size in CSS pixels.
+ * @param palette Derived avatar palette.
+ *
+ * @private utility of the avatar rendering system
+ */
+function drawAvatarFrame(context, size, palette) {
+    if (palette.background === 'transparent' && palette.backgroundSecondary === 'transparent') {
+        return;
+    }
+    const gradient = context.createLinearGradient(0, 0, size, size);
+    gradient.addColorStop(0, palette.background);
+    gradient.addColorStop(1, palette.backgroundSecondary);
+    context.save();
+    createRoundedRectPath(context, 0, 0, size, size, size * FRAME_RADIUS_RATIO);
+    context.fillStyle = gradient;
+    context.fill();
+    context.restore();
+    context.save();
+    context.strokeStyle = 'rgba(255,255,255,0.12)';
+    context.lineWidth = Math.max(1.5, size * 0.012);
+    createRoundedRectPath(context, size * 0.02, size * 0.02, size * 0.96, size * 0.96, size * 0.15);
+    context.stroke();
+    context.restore();
+}
+/**
+ * Creates a rounded rectangle path on the current canvas context.
+ *
+ * @param context Canvas 2D context.
+ * @param x Left coordinate.
+ * @param y Top coordinate.
+ * @param width Rectangle width.
+ * @param height Rectangle height.
+ * @param radius Corner radius.
+ *
+ * @private utility of the avatar rendering system
+ */
+function createRoundedRectPath(context, x, y, width, height, radius) {
+    const normalizedRadius = Math.min(radius, width / 2, height / 2);
+    context.beginPath();
+    context.moveTo(x + normalizedRadius, y);
+    context.arcTo(x + width, y, x + width, y + height, normalizedRadius);
+    context.arcTo(x + width, y + height, x, y + height, normalizedRadius);
+    context.arcTo(x, y + height, x, y, normalizedRadius);
+    context.arcTo(x, y, x + width, y, normalizedRadius);
+    context.closePath();
+}
+/**
+ * Picks one deterministic element from a non-empty collection.
+ *
+ * @param items Candidate items.
+ * @param random Seeded random generator.
+ * @returns Picked item.
+ *
+ * @private utility of the avatar rendering system
+ */
+function pickRandomItem(items, random) {
+    return items[Math.floor(random() * items.length)];
+}
+
+/* eslint-disable no-magic-numbers */
+/**
+ * Builds a smoothly morphing octopus-like silhouette from deterministic parameters.
+ *
+ * @param options Shape construction options.
+ * @returns Closed-loop body points.
+ *
+ * @private shared geometry helper of `octopus2AvatarVisual` and `octopus3AvatarVisual`
+ */
+function createOrganicOctopusBodyPoints(options) {
+    const { centerX, centerY, bodyRadius, horizontalStretch, verticalStretch, mantleLift, lowerDrop, tentacleDepth, wobbleAmplitude, lobeCount, shapePhase, timeMs, pointCount = 36, } = options;
+    return Array.from({ length: pointCount }, (_, pointIndex) => {
+        const progress = pointIndex / pointCount;
+        const angle = -Math.PI / 2 + progress * Math.PI * 2;
+        const cosine = Math.cos(angle);
+        const sine = Math.sin(angle);
+        const upperFactor = Math.max(0, -sine);
+        const lowerFactor = Math.max(0, sine);
+        const lobeEnvelope = Math.pow(lowerFactor, 1.35);
+        const tentacleWave = Math.max(0, Math.cos(angle * lobeCount + shapePhase + timeMs / 780)) * tentacleDepth * lobeEnvelope;
+        const surfaceWave = Math.sin(angle * 3 + shapePhase + timeMs / 1200) * 0.62 +
+            Math.sin(angle * 5 - shapePhase * 0.7 - timeMs / 910) * 0.38;
+        const breathingWave = Math.sin(timeMs / 960 + shapePhase + angle * 0.45) * wobbleAmplitude;
+        const radius = bodyRadius * (1 + upperFactor * 0.12 + lowerFactor * 0.08 + surfaceWave * 0.05) +
+            tentacleWave +
+            breathingWave;
+        return {
+            x: centerX +
+                cosine * radius * horizontalStretch +
+                Math.sin(angle * 2 + shapePhase) * lobeEnvelope * wobbleAmplitude * 0.7,
+            y: centerY +
+                sine * radius * verticalStretch -
+                upperFactor * mantleLift +
+                lowerFactor * lowerDrop +
+                tentacleWave * 0.28,
+        };
+    });
+}
+/**
+ * Traces a smooth closed path through the provided points.
+ *
+ * @param context Canvas 2D context.
+ * @param points Closed-loop points.
+ *
+ * @private shared geometry helper of `octopus2AvatarVisual` and `octopus3AvatarVisual`
+ */
+function traceSmoothClosedPath(context, points) {
+    const lastPoint = points[points.length - 1];
+    const firstPoint = points[0];
+    const initialMidpoint = {
+        x: (lastPoint.x + firstPoint.x) / 2,
+        y: (lastPoint.y + firstPoint.y) / 2,
+    };
+    context.beginPath();
+    context.moveTo(initialMidpoint.x, initialMidpoint.y);
+    for (let pointIndex = 0; pointIndex < points.length; pointIndex++) {
+        const point = points[pointIndex];
+        const nextPoint = points[(pointIndex + 1) % points.length];
+        const midpoint = {
+            x: (point.x + nextPoint.x) / 2,
+            y: (point.y + nextPoint.y) / 2,
+        };
+        context.quadraticCurveTo(point.x, point.y, midpoint.x, midpoint.y);
+    }
+    context.closePath();
+}
+/**
+ * Creates deterministic ribbon tentacles for the organic octopus visuals.
+ *
+ * @param options Tentacle construction options.
+ * @returns Tentacle descriptors.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual` and `asciiOctopusAvatarVisual`
+ */
+function createOrganicOctopusTentacleShapes(options) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const { size, centerX, centerY, bodyRadius, horizontalStretch, tentacleCount, shapePhase, createRandom, timeMs, saltPrefix, bodyPoints, variation, } = options;
+    const baseY = centerY + bodyRadius * 0.74;
+    const lowerBodyAnchorPoints = bodyPoints
+        ? resolveTentacleBodyAnchorPoints(bodyPoints, centerY + bodyRadius * 0.04)
+        : null;
+    const flowLengthScale = (_a = variation === null || variation === void 0 ? void 0 : variation.flowLengthScale) !== null && _a !== void 0 ? _a : 1;
+    const lateralReachScale = (_b = variation === null || variation === void 0 ? void 0 : variation.lateralReachScale) !== null && _b !== void 0 ? _b : 1;
+    const tipReachScale = (_c = variation === null || variation === void 0 ? void 0 : variation.tipReachScale) !== null && _c !== void 0 ? _c : 1;
+    const baseWidthScale = (_d = variation === null || variation === void 0 ? void 0 : variation.baseWidthScale) !== null && _d !== void 0 ? _d : 1;
+    const tipWidthScale = (_e = variation === null || variation === void 0 ? void 0 : variation.tipWidthScale) !== null && _e !== void 0 ? _e : 1;
+    const rootSpreadScale = (_f = variation === null || variation === void 0 ? void 0 : variation.rootSpreadScale) !== null && _f !== void 0 ? _f : 1;
+    const startYOffsetScale = (_g = variation === null || variation === void 0 ? void 0 : variation.startYOffsetScale) !== null && _g !== void 0 ? _g : 1;
+    const swayScale = (_h = variation === null || variation === void 0 ? void 0 : variation.swayScale) !== null && _h !== void 0 ? _h : 1;
+    return Array.from({ length: tentacleCount }, (_, tentacleIndex) => {
+        const tentacleRandom = createRandom(`${saltPrefix}-tentacle-${tentacleIndex}`);
+        const spreadProgress = tentacleCount === 1 ? 0.5 : tentacleIndex / (tentacleCount - 1);
+        const centeredProgress = spreadProgress - 0.5;
+        const spreadCenteredProgress = centeredProgress * rootSpreadScale;
+        const spreadAnchorProgress = Math.min(1, Math.max(0, 0.5 + spreadCenteredProgress));
+        const temporalSway = Math.sin(timeMs / (720 + tentacleIndex * 34) + shapePhase + tentacleRandom() * Math.PI * 2) *
+            size *
+            (0.014 + tentacleRandom() * 0.015) *
+            swayScale;
+        const flowLength = size * (0.24 + tentacleRandom() * 0.18) * flowLengthScale;
+        const curlDirection = spreadCenteredProgress === 0 ? (tentacleRandom() < 0.5 ? -1 : 1) : Math.sign(spreadCenteredProgress);
+        const lateralReach = spreadCenteredProgress * size * (0.1 + tentacleRandom() * 0.1) * lateralReachScale + temporalSway;
+        const tipReach = curlDirection * size * (0.025 + tentacleRandom() * 0.07) * tipReachScale;
+        const startYOffset = (Math.abs(spreadCenteredProgress) * size * 0.012 + tentacleRandom() * size * 0.01) * startYOffsetScale;
+        const startPoint = lowerBodyAnchorPoints && lowerBodyAnchorPoints.length >= 2
+            ? createInsetTentacleStartPoint({
+                bodyPoints: lowerBodyAnchorPoints,
+                anchorProgress: spreadAnchorProgress,
+                centerX,
+                centerY,
+                bodyRadius,
+                centeredProgress: spreadCenteredProgress,
+                startYOffset,
+            })
+            : {
+                x: centerX + spreadCenteredProgress * bodyRadius * horizontalStretch * 1.52,
+                y: baseY + startYOffset,
+            };
+        const controlPointOne = {
+            x: startPoint.x + spreadCenteredProgress * size * 0.045 * lateralReachScale + temporalSway * 0.4,
+            y: startPoint.y + flowLength * (0.21 + tentacleRandom() * 0.08),
+        };
+        const controlPointTwo = {
+            x: startPoint.x + lateralReach + tipReach,
+            y: startPoint.y + flowLength * (0.62 + tentacleRandom() * 0.12),
+        };
+        const endPoint = {
+            x: startPoint.x + lateralReach + tipReach * 1.2,
+            y: startPoint.y +
+                flowLength * (0.9 + tentacleRandom() * 0.12) +
+                Math.cos(timeMs / (840 + tentacleIndex * 41) + shapePhase) * size * (0.008 + tentacleRandom() * 0.01),
+        };
+        const baseWidth = size * (0.038 + tentacleRandom() * 0.02) * (1 - Math.abs(spreadCenteredProgress) * 0.18) * baseWidthScale;
+        const tipWidth = baseWidth * Math.min(0.52, (0.18 + tentacleRandom() * 0.2) * tipWidthScale);
+        return {
+            startPoint,
+            controlPointOne,
+            controlPointTwo,
+            endPoint,
+            baseWidth,
+            tipWidth,
+            colorBias: tentacleRandom(),
+            highlightBias: tentacleRandom(),
+            sampleCount: 14 + Math.floor(tentacleRandom() * 6),
+        };
+    });
+}
+/**
+ * Narrows the body contour to lower anchor points that can safely host tentacle roots.
+ *
+ * @param bodyPoints Generated closed-loop body points.
+ * @param lowerBodyThresholdY Minimum Y coordinate considered part of the lower mantle.
+ * @returns Body points sorted from left to right across the lower silhouette.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual`
+ */
+function resolveTentacleBodyAnchorPoints(bodyPoints, lowerBodyThresholdY) {
+    const lowerBodyPoints = bodyPoints
+        .filter((bodyPoint) => bodyPoint.y >= lowerBodyThresholdY)
+        .sort((leftPoint, rightPoint) => leftPoint.x - rightPoint.x);
+    if (lowerBodyPoints.length >= 2) {
+        return lowerBodyPoints;
+    }
+    return [...bodyPoints].sort((leftPoint, rightPoint) => leftPoint.x - rightPoint.x);
+}
+/**
+ * Resolves one tentacle root from the provided lower body contour and nudges it inside the mantle.
+ *
+ * @param options Tentacle anchor options.
+ * @returns Tentacle start point safely embedded inside the body silhouette.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual`
+ */
+function createInsetTentacleStartPoint(options) {
+    const { bodyPoints, anchorProgress, centerX, centerY, bodyRadius, centeredProgress, startYOffset } = options;
+    const clampedAnchorProgress = Math.min(0.94, Math.max(0.06, anchorProgress));
+    const bodyAnchorPoint = interpolatePointAlongTentacleAnchors(bodyPoints, clampedAnchorProgress);
+    const inwardX = centerX - bodyAnchorPoint.x;
+    const inwardY = centerY + bodyRadius * 0.08 - bodyAnchorPoint.y;
+    const inwardLength = Math.hypot(inwardX, inwardY) || 1;
+    const insetDistance = bodyRadius * (0.12 + Math.abs(centeredProgress) * 0.05) + startYOffset * 0.32;
+    return {
+        x: bodyAnchorPoint.x + (inwardX / inwardLength) * insetDistance,
+        y: bodyAnchorPoint.y + (inwardY / inwardLength) * insetDistance,
+    };
+}
+/**
+ * Interpolates one left-to-right anchor point along the prepared lower body contour.
+ *
+ * @param bodyPoints Lower body contour points sorted from left to right.
+ * @param progress Interpolation progress in the range `[0, 1]`.
+ * @returns Interpolated anchor point.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual`
+ */
+function interpolatePointAlongTentacleAnchors(bodyPoints, progress) {
+    if (bodyPoints.length === 1) {
+        return bodyPoints[0];
+    }
+    const anchorIndex = progress * (bodyPoints.length - 1);
+    const startIndex = Math.floor(anchorIndex);
+    const endIndex = Math.min(bodyPoints.length - 1, startIndex + 1);
+    const blend = anchorIndex - startIndex;
+    const startPoint = bodyPoints[startIndex];
+    const endPoint = bodyPoints[endIndex];
+    return {
+        x: startPoint.x + (endPoint.x - startPoint.x) * blend,
+        y: startPoint.y + (endPoint.y - startPoint.y) * blend,
+    };
+}
+/**
+ * Samples the cubic tentacle centerline and offsets normals to build a filled ribbon.
+ *
+ * @param tentacleShape Deterministic tentacle descriptor.
+ * @returns Sampled ribbon points.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual` and `asciiOctopusAvatarVisual`
+ */
+function sampleOrganicTentacleRibbonPoints(tentacleShape) {
+    return Array.from({ length: tentacleShape.sampleCount + 1 }, (_, sampleIndex) => {
+        const progress = sampleIndex / tentacleShape.sampleCount;
+        const point = getCubicBezierPoint(tentacleShape.startPoint, tentacleShape.controlPointOne, tentacleShape.controlPointTwo, tentacleShape.endPoint, progress);
+        const previousPoint = getCubicBezierPoint(tentacleShape.startPoint, tentacleShape.controlPointOne, tentacleShape.controlPointTwo, tentacleShape.endPoint, Math.max(0, progress - 0.04));
+        const nextPoint = getCubicBezierPoint(tentacleShape.startPoint, tentacleShape.controlPointOne, tentacleShape.controlPointTwo, tentacleShape.endPoint, Math.min(1, progress + 0.04));
+        const tangentX = nextPoint.x - previousPoint.x;
+        const tangentY = nextPoint.y - previousPoint.y;
+        const tangentLength = Math.hypot(tangentX, tangentY) || 1;
+        const width = tentacleShape.baseWidth + (tentacleShape.tipWidth - tentacleShape.baseWidth) * Math.pow(progress, 1.1);
+        return {
+            x: point.x,
+            y: point.y,
+            normalX: -tangentY / tangentLength,
+            normalY: tangentX / tangentLength,
+            width,
+            progress,
+        };
+    });
+}
+/**
+ * Resolves smooth pupil offsets that blend autonomous idle drift with live viewer tracking.
+ *
+ * @param options Eye motion options.
+ * @returns Resolved pupil offsets.
+ *
+ * @private shared geometry helper of octopus avatar visuals
+ */
+function resolveOrganicEyeMotion(options) {
+    const { radiusX, radiusY, timeMs, phase, interaction, autonomousDriftRatioX = 0.12, autonomousDriftRatioY = 0.08, } = options;
+    const autonomousOffsetX = Math.sin(timeMs / 1280 + phase) * radiusX * autonomousDriftRatioX;
+    const autonomousOffsetY = Math.cos(timeMs / 940 + phase) * radiusY * autonomousDriftRatioY;
+    const interactionBlend = Math.min(1, interaction.intensity * 0.9);
+    return {
+        pupilOffsetX: autonomousOffsetX * (1 - interactionBlend) + interaction.gazeX * radiusX * (0.18 + interactionBlend * 0.18),
+        pupilOffsetY: autonomousOffsetY * (1 - interactionBlend) + interaction.gazeY * radiusY * (0.16 + interactionBlend * 0.16),
+    };
+}
+/**
+ * Samples one point on a cubic Bezier curve.
+ *
+ * @param startPoint Curve start point.
+ * @param controlPointOne First control point.
+ * @param controlPointTwo Second control point.
+ * @param endPoint Curve end point.
+ * @param progress Sampling progress in the range `[0, 1]`.
+ * @returns Sampled point.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual`
+ */
+function getCubicBezierPoint(startPoint, controlPointOne, controlPointTwo, endPoint, progress) {
+    const inverseProgress = 1 - progress;
+    return {
+        x: inverseProgress * inverseProgress * inverseProgress * startPoint.x +
+            3 * inverseProgress * inverseProgress * progress * controlPointOne.x +
+            3 * inverseProgress * progress * progress * controlPointTwo.x +
+            progress * progress * progress * endPoint.x,
+        y: inverseProgress * inverseProgress * inverseProgress * startPoint.y +
+            3 * inverseProgress * inverseProgress * progress * controlPointOne.y +
+            3 * inverseProgress * progress * progress * controlPointTwo.y +
+            progress * progress * progress * endPoint.y,
+    };
+}
+
+/* eslint-disable no-magic-numbers */
+/**
+ * Glyph ramp used for the main octopus body fill.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+const BODY_GLYPHS = ['.', ':', '-', '=', '+', '*', '#', '%', '@'];
+/**
+ * Glyph ramp used on silhouette edges so the ASCII blob stays legible.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+const OUTLINE_GLYPHS = ['#', '%', '@'];
+/**
+ * Glyph ramp used in the surrounding atmosphere.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+const ATMOSPHERE_GLYPHS = ['.', ':', "'", '`'];
+/**
+ * AsciiOctopus avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+const asciiOctopusAvatarVisual = {
+    id: 'ascii-octopus',
+    title: 'AsciiOctopus',
+    description: 'Morphing alien octopus translated into animated ASCII glyphs with responsive eyes and seeded geometry.',
+    isAnimated: true,
+    supportsPointerTracking: true,
+    render({ context, size, palette, createRandom, timeMs, interaction }) {
+        const gridRandom = createRandom('ascii-octopus-grid');
+        const staticRandom = createRandom('ascii-octopus-static');
+        const gridMetrics = createAsciiGridMetrics(size, gridRandom);
+        const layout = createAsciiOctopusLayout(size, timeMs, createRandom, staticRandom, interaction);
+        drawAvatarFrame(context, size, palette);
+        drawAsciiBackdrop(context, size, palette, layout, timeMs);
+        context.save();
+        context.font = `600 ${gridMetrics.fontSize}px monospace`;
+        context.textAlign = 'center';
+        context.textBaseline = 'middle';
+        // The ASCII renderer samples the morphing octopus field on a low-resolution grid so the shape stays organic
+        // while the glyph layout remains deterministic for the same avatar input.
+        const cellRandom = createRandom('ascii-octopus-cells');
+        for (let rowIndex = 0; rowIndex < gridMetrics.rowCount; rowIndex++) {
+            for (let columnIndex = 0; columnIndex < gridMetrics.columnCount; columnIndex++) {
+                const point = {
+                    x: gridMetrics.offsetX + columnIndex * gridMetrics.cellWidth,
+                    y: gridMetrics.offsetY + rowIndex * gridMetrics.cellHeight,
+                };
+                const noise = cellRandom();
+                const glyphDescriptor = resolveAsciiGlyph({
+                    point,
+                    layout,
+                    palette,
+                    cellWidth: gridMetrics.cellWidth,
+                    cellHeight: gridMetrics.cellHeight,
+                    noise,
+                    timeMs,
+                });
+                if (!glyphDescriptor) {
+                    continue;
+                }
+                context.fillStyle = glyphDescriptor.color;
+                context.fillText(glyphDescriptor.character, point.x, point.y);
+            }
+        }
+        context.restore();
+    },
+};
+/**
+ * Draws the dark terminal-like glow behind the ASCII octopus.
+ *
+ * @param context Canvas 2D context.
+ * @param size Canvas size in CSS pixels.
+ * @param palette Derived avatar palette.
+ * @param layout Prepared octopus layout.
+ * @param timeMs Current animation time in milliseconds.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function drawAsciiBackdrop(context, size, palette, layout, timeMs) {
+    const haloGradient = context.createRadialGradient(layout.centerX, layout.centerY - size * 0.12, size * 0.06, layout.centerX, layout.centerY, size * 0.62);
+    haloGradient.addColorStop(0, `${palette.highlight}26`);
+    haloGradient.addColorStop(0.42, `${palette.accent}16`);
+    haloGradient.addColorStop(1, `${palette.highlight}00`);
+    context.fillStyle = haloGradient;
+    context.fillRect(0, 0, size, size);
+    const lowerGlowGradient = context.createRadialGradient(layout.centerX + Math.sin(timeMs / 1100 + layout.shapePhase) * size * 0.03, layout.centerY + size * 0.2, size * 0.05, layout.centerX, layout.centerY + size * 0.24, size * 0.46);
+    lowerGlowGradient.addColorStop(0, `${palette.secondary}1f`);
+    lowerGlowGradient.addColorStop(1, `${palette.secondary}00`);
+    context.fillStyle = lowerGlowGradient;
+    context.fillRect(0, 0, size, size);
+    context.beginPath();
+    context.ellipse(layout.centerX, layout.centerY + size * 0.29, size * 0.23, size * 0.065, 0, 0, Math.PI * 2);
+    context.fillStyle = `${palette.shadow}33`;
+    context.fill();
+}
+/**
+ * Resolves the ASCII character that should be drawn for one sampled cell.
+ *
+ * @param options Cell evaluation options.
+ * @returns Character descriptor or `null` when the cell should stay empty.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function resolveAsciiGlyph(options) {
+    const { point, layout, palette, cellWidth, cellHeight, noise, timeMs } = options;
+    const eyeGlyphDescriptor = resolveEyeGlyph(point, layout.leftEye, layout.interaction, palette, timeMs) ||
+        resolveEyeGlyph(point, layout.rightEye, layout.interaction, palette, timeMs);
+    if (eyeGlyphDescriptor) {
+        return eyeGlyphDescriptor;
+    }
+    const mouthGlyphDescriptor = resolveMouthGlyph(point, layout, palette, cellHeight);
+    if (mouthGlyphDescriptor) {
+        return mouthGlyphDescriptor;
+    }
+    const isWithinOctopusBounds = point.x >= layout.leftBound &&
+        point.x <= layout.rightBound &&
+        point.y >= layout.topBound &&
+        point.y <= layout.bottomBound;
+    if (!isWithinOctopusBounds) {
+        return resolveAtmosphereGlyph(point, layout, palette, noise, timeMs);
+    }
+    const isInsideBody = isPointInsidePolygon(point, layout.bodyPoints);
+    const bodyEdgeDistance = isInsideBody
+        ? getDistanceToPolyline(point, layout.bodyPoints, true)
+        : Number.POSITIVE_INFINITY;
+    const tentacleCoverage = measureTentacleCoverage(point, layout.sampledTentacles, cellWidth);
+    if (isInsideBody || tentacleCoverage) {
+        return resolveOctopusSurfaceGlyph({
+            point,
+            layout,
+            palette,
+            isInsideBody,
+            bodyEdgeDistance,
+            tentacleCoverage,
+            cellWidth,
+            cellHeight,
+            noise,
+            timeMs,
+        });
+    }
+    return resolveAtmosphereGlyph(point, layout, palette, noise, timeMs);
+}
+/**
+ * Resolves the ASCII character for one eye cell.
+ *
+ * @param point Sampled cell point.
+ * @param eyeFeature Eye geometry.
+ * @param palette Derived avatar palette.
+ * @param timeMs Current animation time in milliseconds.
+ * @returns Eye glyph descriptor or `null`.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function resolveEyeGlyph(point, eyeFeature, interaction, palette, timeMs) {
+    const { pupilOffsetX, pupilOffsetY } = resolveOrganicEyeMotion({
+        radiusX: eyeFeature.radiusX,
+        radiusY: eyeFeature.radiusY,
+        timeMs,
+        phase: eyeFeature.phase,
+        interaction,
+    });
+    const scleraDistance = measureRotatedEllipseDistance(point, eyeFeature.centerX, eyeFeature.centerY, eyeFeature.radiusX, eyeFeature.radiusY, eyeFeature.rotation);
+    if (scleraDistance > 1.08) {
+        return null;
+    }
+    const highlightDistance = measureRotatedEllipseDistance(point, eyeFeature.centerX + pupilOffsetX - eyeFeature.radiusX * 0.24, eyeFeature.centerY + pupilOffsetY - eyeFeature.radiusY * 0.26, eyeFeature.radiusX * 0.18, eyeFeature.radiusY * 0.14, eyeFeature.rotation);
+    if (highlightDistance <= 1) {
+        return { character: '*', color: '#ffffff' };
+    }
+    const pupilDistance = measureRotatedEllipseDistance(point, eyeFeature.centerX + pupilOffsetX, eyeFeature.centerY + pupilOffsetY, eyeFeature.radiusX * 0.2, eyeFeature.radiusY * 0.48, eyeFeature.rotation);
+    if (pupilDistance <= 1) {
+        return { character: '@', color: palette.ink };
+    }
+    const irisDistance = measureRotatedEllipseDistance(point, eyeFeature.centerX + pupilOffsetX, eyeFeature.centerY + pupilOffsetY, eyeFeature.radiusX * 0.64, eyeFeature.radiusY * 0.72, eyeFeature.rotation);
+    if (irisDistance <= 1) {
+        return {
+            character: irisDistance < 0.46 ? '0' : 'o',
+            color: irisDistance < 0.62 ? palette.secondary : `${palette.highlight}d9`,
+        };
+    }
+    return {
+        character: scleraDistance > 0.82 ? 'o' : '0',
+        color: '#f8fbff',
+    };
+}
+/**
+ * Resolves the ASCII character for the octopus mouth.
+ *
+ * @param point Sampled cell point.
+ * @param layout Prepared octopus layout.
+ * @param palette Derived avatar palette.
+ * @param cellHeight Character cell height.
+ * @returns Mouth glyph descriptor or `null`.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function resolveMouthGlyph(point, layout, palette, cellHeight) {
+    const mouthDistance = getDistanceToPolyline(point, layout.mouthPoints, false);
+    if (mouthDistance > cellHeight * 0.38) {
+        return null;
+    }
+    const horizontalProgress = clamp01((point.x - layout.mouthPoints[0].x) /
+        (layout.mouthPoints[layout.mouthPoints.length - 1].x - layout.mouthPoints[0].x));
+    let character = '-';
+    if (horizontalProgress < 0.28) {
+        character = '\\';
+    }
+    else if (horizontalProgress > 0.72) {
+        character = '/';
+    }
+    else if (horizontalProgress > 0.42 && horizontalProgress < 0.58) {
+        character = '_';
+    }
+    return {
+        character,
+        color: `${palette.ink}bf`,
+    };
+}
+/**
+ * Resolves the ASCII character for body and tentacle cells.
+ *
+ * @param options Surface evaluation options.
+ * @returns Surface glyph descriptor.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function resolveOctopusSurfaceGlyph(options) {
+    const { point, layout, palette, isInsideBody, bodyEdgeDistance, tentacleCoverage, cellHeight, noise, timeMs } = options;
+    const isTentacleDominant = tentacleCoverage !== null && (!isInsideBody || point.y > layout.centerY + layout.bodyRadius * 0.08);
+    if (isTentacleDominant && tentacleCoverage) {
+        const isSuckerBand = tentacleCoverage.progress > 0.24 && tentacleCoverage.progress < 0.82 && noise > 0.78;
+        if (isSuckerBand && tentacleCoverage.normalizedDistance > 0.42) {
+            return {
+                character: noise > 0.9 ? '0' : 'o',
+                color: `${palette.highlight}d0`,
+            };
+        }
+        return {
+            character: pickTentacleCharacter(tentacleCoverage, noise),
+            color: tentacleCoverage.progress < 0.24
+                ? `${palette.secondary}c7`
+                : tentacleCoverage.progress > 0.72
+                    ? `${palette.accent}bf`
+                    : tentacleCoverage.normalizedDistance > 0.7
+                        ? `${palette.highlight}bf`
+                        : `${palette.primary}c9`,
+        };
+    }
+    const highlightBias = clamp01((layout.centerY - point.y + layout.bodyRadius * 0.44) / (layout.bodyRadius * 1.14));
+    const bodyDepth = clamp01(1 - bodyEdgeDistance / (layout.bodyRadius * 0.9));
+    const shimmer = Math.sin(timeMs / 720 + point.x * 0.085 + point.y * 0.06 + layout.shapePhase) * 0.05;
+    const bodyIntensity = clamp01(0.22 + bodyDepth * 0.58 + highlightBias * 0.2 + shimmer + (noise - 0.5) * 0.18);
+    const isOutline = isInsideBody && bodyEdgeDistance < cellHeight * 0.54;
+    const character = isOutline
+        ? pickRampCharacter(OUTLINE_GLYPHS, clamp01(0.58 + bodyIntensity * 0.42))
+        : pickRampCharacter(BODY_GLYPHS, bodyIntensity);
+    let color = `${palette.primary}bf`;
+    if (highlightBias > 0.76) {
+        color = `${palette.highlight}d9`;
+    }
+    else if (bodyDepth > 0.7) {
+        color = `${palette.secondary}cb`;
+    }
+    else if ((point.x < layout.centerX && noise > 0.58) || (point.x >= layout.centerX && noise < 0.42)) {
+        color = `${palette.accent}ba`;
+    }
+    return {
+        character,
+        color: isOutline ? `${palette.highlight}c9` : color,
+    };
+}
+/**
+ * Resolves faint atmosphere glyphs around the ASCII octopus.
+ *
+ * @param point Sampled cell point.
+ * @param layout Prepared octopus layout.
+ * @param palette Derived avatar palette.
+ * @param noise Stable per-cell noise.
+ * @param timeMs Current animation time in milliseconds.
+ * @returns Atmosphere glyph descriptor or `null`.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function resolveAtmosphereGlyph(point, layout, palette, noise, timeMs) {
+    const horizontalDistance = Math.abs(point.x - layout.centerX) / (layout.bodyRadius * layout.horizontalStretch * 2.2);
+    const verticalDistance = Math.abs(point.y - (layout.centerY + layout.bodyRadius * 0.04)) / (layout.bodyRadius * 2.1);
+    const haloDistance = Math.hypot(horizontalDistance, verticalDistance);
+    const shimmer = Math.sin(timeMs / 1450 + point.x * 0.03 + point.y * 0.04 + layout.shapePhase) * 0.06;
+    const density = clamp01(1.16 - haloDistance + shimmer + (noise - 0.5) * 0.14);
+    if (density < 0.18 || noise > density * 0.84 + 0.34) {
+        return null;
+    }
+    return {
+        character: pickRampCharacter(ATMOSPHERE_GLYPHS, density),
+        color: point.y < layout.centerY ? `${palette.highlight}63` : `${palette.accent}47`,
+    };
+}
+/**
+ * Builds the grid used by the ASCII renderer.
+ *
+ * @param size Canvas size in CSS pixels.
+ * @param staticRandom Stable random generator for this avatar.
+ * @returns Grid metrics.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function createAsciiGridMetrics(size, staticRandom) {
+    const fontSize = Math.max(9, Math.round(size * (0.048 + staticRandom() * 0.006)));
+    const cellWidth = fontSize * (0.58 + staticRandom() * 0.04);
+    const cellHeight = fontSize * 0.82;
+    const columnCount = Math.max(12, Math.floor(size / cellWidth) - 1);
+    const rowCount = Math.max(12, Math.floor(size / cellHeight) - 1);
+    const offsetX = (size - (columnCount - 1) * cellWidth) / 2;
+    const offsetY = (size - (rowCount - 1) * cellHeight) / 2;
+    return {
+        fontSize,
+        cellWidth,
+        cellHeight,
+        columnCount,
+        rowCount,
+        offsetX,
+        offsetY,
+    };
+}
+/**
+ * Builds the deterministic octopus geometry that will later be sampled into ASCII cells.
+ *
+ * @param size Canvas size in CSS pixels.
+ * @param timeMs Current animation time in milliseconds.
+ * @param createRandom Seeded random factory scoped to the avatar.
+ * @param staticRandom Stable random generator for this avatar.
+ * @returns Prepared octopus layout.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function createAsciiOctopusLayout(size, timeMs, createRandom, staticRandom, interaction) {
+    const centerX = size * (0.5 + (staticRandom() - 0.5) * 0.02) + interaction.bodyOffsetX * size * 0.05;
+    const centerY = size * (0.41 + staticRandom() * 0.05) + interaction.bodyOffsetY * size * 0.035;
+    const bodyRadius = size * (0.195 + staticRandom() * 0.05);
+    const horizontalStretch = 1.08 + staticRandom() * 0.22;
+    const verticalStretch = 0.88 + staticRandom() * 0.14;
+    const mantleLift = size * (0.1 + staticRandom() * 0.03);
+    const lowerDrop = size * (0.03 + staticRandom() * 0.024);
+    const tentacleDepth = size * (0.026 + staticRandom() * 0.022);
+    const wobbleAmplitude = size * (0.008 + staticRandom() * 0.01);
+    const lobeCount = 5 + Math.floor(staticRandom() * 4);
+    const shapePhase = staticRandom() * Math.PI * 2;
+    const tentacleCount = 8 + Math.floor(staticRandom() * 5);
+    const eyeSpacing = size * (0.108 + staticRandom() * 0.042);
+    const eyeRadiusX = size * (0.05 + staticRandom() * 0.015);
+    const eyeRadiusY = eyeRadiusX * (1.16 + staticRandom() * 0.2);
+    const bodyPoints = createOrganicOctopusBodyPoints({
+        centerX,
+        centerY,
+        bodyRadius,
+        horizontalStretch,
+        verticalStretch,
+        mantleLift,
+        lowerDrop,
+        tentacleDepth,
+        wobbleAmplitude,
+        lobeCount,
+        shapePhase,
+        timeMs,
+        pointCount: 40,
+    });
+    const tentacleShapes = createOrganicOctopusTentacleShapes({
+        size,
+        centerX,
+        centerY,
+        bodyRadius,
+        horizontalStretch,
+        tentacleCount,
+        shapePhase,
+        createRandom,
+        timeMs,
+        saltPrefix: 'ascii-octopus',
+        bodyPoints,
+    });
+    const sampledTentacles = tentacleShapes.map(sampleOrganicTentacleRibbonPoints);
+    const leftEye = {
+        centerX: centerX - eyeSpacing,
+        centerY: centerY - size * 0.01,
+        radiusX: eyeRadiusX,
+        radiusY: eyeRadiusY,
+        rotation: (staticRandom() - 0.5) * 0.24,
+        phase: shapePhase,
+    };
+    const rightEye = {
+        centerX: centerX + eyeSpacing,
+        centerY: centerY - size * 0.01,
+        radiusX: eyeRadiusX,
+        radiusY: eyeRadiusY,
+        rotation: (staticRandom() - 0.5) * 0.24,
+        phase: shapePhase + Math.PI / 4,
+    };
+    const mouthPoints = sampleQuadraticBezierPoints({ x: centerX - size * 0.074, y: centerY + size * 0.092 }, {
+        x: centerX,
+        y: centerY +
+            size * (0.142 + Math.sin(timeMs / 620 + shapePhase) * 0.016) +
+            interaction.gazeY * size * 0.012,
+    }, { x: centerX + size * 0.074, y: centerY + size * 0.092 }, 12);
+    let leftBound = Number.POSITIVE_INFINITY;
+    let rightBound = Number.NEGATIVE_INFINITY;
+    let topBound = Number.POSITIVE_INFINITY;
+    let bottomBound = Number.NEGATIVE_INFINITY;
+    for (const bodyPoint of bodyPoints) {
+        leftBound = Math.min(leftBound, bodyPoint.x);
+        rightBound = Math.max(rightBound, bodyPoint.x);
+        topBound = Math.min(topBound, bodyPoint.y);
+        bottomBound = Math.max(bottomBound, bodyPoint.y);
+    }
+    for (const sampledTentacle of sampledTentacles) {
+        for (const ribbonPoint of sampledTentacle) {
+            leftBound = Math.min(leftBound, ribbonPoint.x - ribbonPoint.width);
+            rightBound = Math.max(rightBound, ribbonPoint.x + ribbonPoint.width);
+            topBound = Math.min(topBound, ribbonPoint.y - ribbonPoint.width);
+            bottomBound = Math.max(bottomBound, ribbonPoint.y + ribbonPoint.width);
+        }
+    }
+    return {
+        centerX,
+        centerY,
+        bodyRadius,
+        horizontalStretch,
+        shapePhase,
+        interaction,
+        bodyPoints,
+        sampledTentacles,
+        leftEye,
+        rightEye,
+        mouthPoints,
+        leftBound: leftBound - size * 0.08,
+        rightBound: rightBound + size * 0.08,
+        topBound: topBound - size * 0.08,
+        bottomBound: bottomBound + size * 0.08,
+    };
+}
+/**
+ * Samples points along a quadratic Bezier curve.
+ *
+ * @param startPoint Curve start point.
+ * @param controlPoint Curve control point.
+ * @param endPoint Curve end point.
+ * @param pointCount Number of intervals to sample.
+ * @returns Sampled curve points.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function sampleQuadraticBezierPoints(startPoint, controlPoint, endPoint, pointCount) {
+    return Array.from({ length: pointCount + 1 }, (_, pointIndex) => {
+        const progress = pointIndex / pointCount;
+        const inverseProgress = 1 - progress;
+        return {
+            x: inverseProgress * inverseProgress * startPoint.x +
+                2 * inverseProgress * progress * controlPoint.x +
+                progress * progress * endPoint.x,
+            y: inverseProgress * inverseProgress * startPoint.y +
+                2 * inverseProgress * progress * controlPoint.y +
+                progress * progress * endPoint.y,
+        };
+    });
+}
+/**
+ * Measures how strongly the sampled cell intersects with the generated tentacles.
+ *
+ * @param point Sampled cell point.
+ * @param sampledTentacles Pre-sampled tentacle ribbons.
+ * @param cellWidth Character cell width.
+ * @returns Nearest tentacle coverage or `null`.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function measureTentacleCoverage(point, sampledTentacles, cellWidth) {
+    let bestTentacleCoverage = null;
+    let bestNormalizedDistance = 0;
+    for (const sampledTentacle of sampledTentacles) {
+        for (const ribbonPoint of sampledTentacle) {
+            const deltaX = point.x - ribbonPoint.x;
+            const deltaY = point.y - ribbonPoint.y;
+            const distance = Math.hypot(deltaX, deltaY);
+            const coverageRadius = ribbonPoint.width + cellWidth * 0.22;
+            const normalizedDistance = 1 - distance / coverageRadius;
+            if (normalizedDistance <= bestNormalizedDistance || normalizedDistance <= 0) {
+                continue;
+            }
+            bestNormalizedDistance = normalizedDistance;
+            bestTentacleCoverage = {
+                tangentAngle: Math.atan2(-ribbonPoint.normalX, ribbonPoint.normalY),
+                progress: ribbonPoint.progress,
+                normalizedDistance,
+            };
+        }
+    }
+    return bestTentacleCoverage;
+}
+/**
+ * Picks one ASCII character that matches the nearest tentacle direction.
+ *
+ * @param tentacleCoverage Nearest tentacle coverage.
+ * @param noise Stable per-cell noise.
+ * @returns Tentacle ASCII character.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function pickTentacleCharacter(tentacleCoverage, noise) {
+    const isSuckerBand = tentacleCoverage.progress > 0.24 && tentacleCoverage.progress < 0.82 && noise > 0.82;
+    if (isSuckerBand && tentacleCoverage.normalizedDistance > 0.34) {
+        return noise > 0.91 ? '0' : 'o';
+    }
+    const horizontalWeight = Math.abs(Math.cos(tentacleCoverage.tangentAngle));
+    const verticalWeight = Math.abs(Math.sin(tentacleCoverage.tangentAngle));
+    if (horizontalWeight > 0.84) {
+        return noise > 0.52 ? '=' : '-';
+    }
+    if (verticalWeight > 0.82) {
+        return noise > 0.56 ? '|' : '!';
+    }
+    return Math.sin(tentacleCoverage.tangentAngle) * Math.cos(tentacleCoverage.tangentAngle) > 0 ? '\\' : '/';
+}
+/**
+ * Picks one character from an ordered ramp.
+ *
+ * @param glyphRamp Ordered glyph ramp.
+ * @param intensity Normalized intensity in the range `[0, 1]`.
+ * @returns Selected glyph.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function pickRampCharacter(glyphRamp, intensity) {
+    const characterIndex = Math.min(glyphRamp.length - 1, Math.floor(clamp01(intensity) * glyphRamp.length));
+    return glyphRamp[characterIndex];
+}
+/**
+ * Measures the normalized distance from a point to a rotated ellipse.
+ *
+ * @param point Sampled cell point.
+ * @param centerX Ellipse center X coordinate.
+ * @param centerY Ellipse center Y coordinate.
+ * @param radiusX Horizontal ellipse radius.
+ * @param radiusY Vertical ellipse radius.
+ * @param rotation Ellipse rotation in radians.
+ * @returns Normalized ellipse distance where values below `1` are inside.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function measureRotatedEllipseDistance(point, centerX, centerY, radiusX, radiusY, rotation) {
+    const cosine = Math.cos(rotation);
+    const sine = Math.sin(rotation);
+    const translatedX = point.x - centerX;
+    const translatedY = point.y - centerY;
+    const localX = translatedX * cosine + translatedY * sine;
+    const localY = -translatedX * sine + translatedY * cosine;
+    return Math.sqrt((localX * localX) / (radiusX * radiusX) + (localY * localY) / (radiusY * radiusY));
+}
+/**
+ * Checks whether a point lies inside the given closed polygon.
+ *
+ * @param point Sampled cell point.
+ * @param polygonPoints Polygon points in order.
+ * @returns `true` when the point lies inside the polygon.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function isPointInsidePolygon(point, polygonPoints) {
+    let isInside = false;
+    for (let currentPointIndex = 0, previousPointIndex = polygonPoints.length - 1; currentPointIndex < polygonPoints.length; previousPointIndex = currentPointIndex++) {
+        const currentPoint = polygonPoints[currentPointIndex];
+        const previousPoint = polygonPoints[previousPointIndex];
+        const isIntersecting = currentPoint.y > point.y !== previousPoint.y > point.y &&
+            point.x <
+                ((previousPoint.x - currentPoint.x) * (point.y - currentPoint.y)) / (previousPoint.y - currentPoint.y) +
+                    currentPoint.x;
+        if (isIntersecting) {
+            isInside = !isInside;
+        }
+    }
+    return isInside;
+}
+/**
+ * Measures the shortest distance from a point to a polyline.
+ *
+ * @param point Sampled cell point.
+ * @param polylinePoints Polyline points in order.
+ * @param isClosed Whether the final point should connect back to the first point.
+ * @returns Shortest distance to the polyline.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function getDistanceToPolyline(point, polylinePoints, isClosed) {
+    let shortestDistance = Number.POSITIVE_INFINITY;
+    const segmentCount = isClosed ? polylinePoints.length : polylinePoints.length - 1;
+    for (let segmentIndex = 0; segmentIndex < segmentCount; segmentIndex++) {
+        const startPoint = polylinePoints[segmentIndex];
+        const endPoint = polylinePoints[(segmentIndex + 1) % polylinePoints.length];
+        shortestDistance = Math.min(shortestDistance, getDistanceToLineSegment(point, startPoint, endPoint));
+    }
+    return shortestDistance;
+}
+/**
+ * Measures the shortest distance from a point to one line segment.
+ *
+ * @param point Sampled cell point.
+ * @param startPoint Segment start point.
+ * @param endPoint Segment end point.
+ * @returns Shortest distance to the segment.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function getDistanceToLineSegment(point, startPoint, endPoint) {
+    const deltaX = endPoint.x - startPoint.x;
+    const deltaY = endPoint.y - startPoint.y;
+    const segmentLengthSquared = deltaX * deltaX + deltaY * deltaY;
+    if (segmentLengthSquared === 0) {
+        return Math.hypot(point.x - startPoint.x, point.y - startPoint.y);
+    }
+    const progress = clamp01(((point.x - startPoint.x) * deltaX + (point.y - startPoint.y) * deltaY) / segmentLengthSquared);
+    const projectionX = startPoint.x + deltaX * progress;
+    const projectionY = startPoint.y + deltaY * progress;
+    return Math.hypot(point.x - projectionX, point.y - projectionY);
+}
+/**
+ * Clamps a number into the inclusive range `[0, 1]`.
+ *
+ * @param value Arbitrary numeric value.
+ * @returns Clamped value.
+ *
+ * @private helper of `asciiOctopusAvatarVisual`
+ */
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+
+/* eslint-disable no-magic-numbers */
+/**
+ * Fractal avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+const fractalAvatarVisual = {
+    id: 'fractal',
+    title: 'Fractal',
+    description: 'Layered dragon-curve ribbons with deterministic glows, bends, and seeded color interplay.',
+    isAnimated: true,
+    render({ context, size, palette, createRandom, timeMs }) {
+        const staticRandom = createRandom('fractal-static');
+        const centerX = size * 0.5;
+        const centerY = size * 0.5;
+        const layerCount = 2 + Math.floor(staticRandom() * 3);
+        const haloRotation = staticRandom() * Math.PI * 2;
+        const colorSequence = [palette.primary, palette.secondary, palette.accent, palette.highlight];
+        drawAvatarFrame(context, size, palette);
+        drawFractalBackground(context, size, palette, timeMs, haloRotation);
+        for (let layerIndex = 0; layerIndex < layerCount; layerIndex++) {
+            const layerRandom = createRandom(`fractal-layer-${layerIndex}`);
+            const order = 8 + Math.floor(layerRandom() * 4);
+            const turnSequence = createDragonCurveTurns(order);
+            const basePoints = createDragonCurvePoints(turnSequence);
+            const transformedPoints = transformDragonCurvePoints(basePoints, {
+                size,
+                centerX: centerX + (layerRandom() - 0.5) * size * 0.08,
+                centerY: centerY + (layerRandom() - 0.5) * size * 0.08,
+                rotation: layerRandom() * Math.PI * 2 + Math.sin(timeMs / (1700 + layerIndex * 280) + layerIndex) * 0.14,
+                scale: size * (0.19 + layerIndex * 0.055 + layerRandom() * 0.045),
+                horizontalStretch: 0.74 + layerRandom() * 0.9,
+                verticalStretch: 0.74 + layerRandom() * 0.9,
+                warpAmplitude: size * (0.008 + layerRandom() * 0.012),
+                warpPhase: layerRandom() * Math.PI * 2,
+                mirrorX: layerRandom() < 0.5 ? -1 : 1,
+                mirrorY: layerRandom() < 0.38 ? -1 : 1,
+                timeMs,
+            });
+            const primaryColor = colorSequence[layerIndex % colorSequence.length];
+            const secondaryColor = colorSequence[(layerIndex + 1) % colorSequence.length];
+            const tertiaryColor = colorSequence[(layerIndex + 2) % colorSequence.length];
+            const strokeWidth = size * (0.026 - layerIndex * 0.0035);
+            drawDragonCurveLayer(context, transformedPoints, {
+                size,
+                primaryColor,
+                secondaryColor,
+                tertiaryColor,
+                shadowColor: palette.shadow,
+                strokeWidth,
+                timeMs,
+                layerIndex,
+            });
+        }
+        drawFractalCore(context, size, palette, timeMs, staticRandom());
+    },
+};
+/**
+ * Draws the shared luminous atmosphere behind the curve layers.
+ *
+ * @param context Canvas 2D context.
+ * @param size Canvas size in CSS pixels.
+ * @param palette Derived avatar palette.
+ * @param timeMs Current animation time in milliseconds.
+ * @param haloRotation Seed-based phase offset.
+ *
+ * @private helper of `fractalAvatarVisual`
+ */
+function drawFractalBackground(context, size, palette, timeMs, haloRotation) {
+    const centerX = size * 0.5;
+    const centerY = size * 0.5;
+    const radialGlow = context.createRadialGradient(centerX, centerY, size * 0.06, centerX, centerY, size * 0.72);
+    radialGlow.addColorStop(0, `${palette.highlight}55`);
+    radialGlow.addColorStop(0.4, `${palette.secondary}1f`);
+    radialGlow.addColorStop(1, `${palette.highlight}00`);
+    context.fillStyle = radialGlow;
+    context.fillRect(0, 0, size, size);
+    for (let haloIndex = 0; haloIndex < 3; haloIndex++) {
+        const radius = size * (0.17 + haloIndex * 0.09);
+        const rotation = haloRotation + haloIndex * 0.85 + timeMs / (4400 + haloIndex * 700);
+        context.beginPath();
+        context.ellipse(centerX, centerY, radius, radius * (0.62 + haloIndex * 0.06), rotation, 0, Math.PI * 2);
+        context.strokeStyle = haloIndex % 2 === 0 ? `${palette.secondary}24` : `${palette.accent}20`;
+        context.lineWidth = size * 0.006;
+        context.stroke();
+    }
+}
+/**
+ * Generates the left-right turn sequence for a dragon curve.
+ *
+ * @param order Number of folding iterations.
+ * @returns Turn sequence where `1` means right and `-1` means left.
+ *
+ * @private helper of `fractalAvatarVisual`
+ */
+function createDragonCurveTurns(order) {
+    let turns = [];
+    for (let iteration = 0; iteration < order; iteration++) {
+        turns = [
+            ...turns,
+            1,
+            ...turns
+                .slice()
+                .reverse()
+                .map((turn) => (turn === 1 ? -1 : 1)),
+        ];
+    }
+    return turns;
+}
+/**
+ * Converts a dragon-curve turn sequence into a raw grid polyline.
+ *
+ * @param turnSequence Ordered turn sequence.
+ * @returns Unscaled polyline points.
+ *
+ * @private helper of `fractalAvatarVisual`
+ */
+function createDragonCurvePoints(turnSequence) {
+    const points = [{ x: 0, y: 0 }];
+    const directions = [
+        { x: 1, y: 0 },
+        { x: 0, y: 1 },
+        { x: -1, y: 0 },
+        { x: 0, y: -1 },
+    ];
+    let directionIndex = 0;
+    for (let segmentIndex = 0; segmentIndex <= turnSequence.length; segmentIndex++) {
+        const currentPoint = points[points.length - 1];
+        const direction = directions[directionIndex];
+        points.push({
+            x: currentPoint.x + direction.x,
+            y: currentPoint.y + direction.y,
+        });
+        if (segmentIndex < turnSequence.length) {
+            directionIndex = (directionIndex + turnSequence[segmentIndex] + directions.length) % directions.length;
+        }
+    }
+    return points;
+}
+/**
+ * Normalizes and decorates the dragon-curve polyline for avatar rendering.
+ *
+ * @param points Raw grid polyline points.
+ * @param options Transformation parameters.
+ * @returns Transformed canvas points.
+ *
+ * @private helper of `fractalAvatarVisual`
+ */
+function transformDragonCurvePoints(points, options) {
+    const { size, centerX, centerY, rotation, scale, horizontalStretch, verticalStretch, warpAmplitude, warpPhase, mirrorX, mirrorY, timeMs, } = options;
+    const bounds = getPointBounds(points);
+    const width = Math.max(1, bounds.maxX - bounds.minX);
+    const height = Math.max(1, bounds.maxY - bounds.minY);
+    const normalizationScale = scale / Math.max(width, height);
+    const cosine = Math.cos(rotation);
+    const sine = Math.sin(rotation);
+    return points.map((point, pointIndex) => {
+        const normalizedX = (point.x - (bounds.minX + width / 2)) * normalizationScale * horizontalStretch * mirrorX;
+        const normalizedY = (point.y - (bounds.minY + height / 2)) * normalizationScale * verticalStretch * mirrorY;
+        const progress = pointIndex / Math.max(1, points.length - 1);
+        const localWarp = Math.sin(progress * Math.PI * 4 + warpPhase + timeMs / 1400) * warpAmplitude +
+            Math.cos(progress * Math.PI * 7 - warpPhase + timeMs / 1800) * warpAmplitude * 0.45;
+        const rotatedX = normalizedX * cosine - normalizedY * sine;
+        const rotatedY = normalizedX * sine + normalizedY * cosine;
+        return {
+            x: centerX + rotatedX + Math.sin(progress * Math.PI * 2 + warpPhase) * localWarp,
+            y: centerY +
+                rotatedY +
+                Math.cos(progress * Math.PI * 3 + warpPhase * 0.6) * localWarp +
+                (progress - 0.5) * size * 0.02,
+        };
+    });
+}
+/**
+ * Returns the bounding box of a point cloud.
+ *
+ * @param points Point cloud to inspect.
+ * @returns Bounding box.
+ *
+ * @private helper of `fractalAvatarVisual`
+ */
+function getPointBounds(points) {
+    return points.reduce((bounds, point) => ({
+        minX: Math.min(bounds.minX, point.x),
+        maxX: Math.max(bounds.maxX, point.x),
+        minY: Math.min(bounds.minY, point.y),
+        maxY: Math.max(bounds.maxY, point.y),
+    }), {
+        minX: Number.POSITIVE_INFINITY,
+        maxX: Number.NEGATIVE_INFINITY,
+        minY: Number.POSITIVE_INFINITY,
+        maxY: Number.NEGATIVE_INFINITY,
+    });
+}
+/**
+ * Draws one stylized dragon-curve ribbon with glow and spark nodes.
+ *
+ * @param context Canvas 2D context.
+ * @param points Transformed polyline points.
+ * @param options Layer styling options.
+ *
+ * @private helper of `fractalAvatarVisual`
+ */
+function drawDragonCurveLayer(context, points, options) {
+    const { size, primaryColor, secondaryColor, tertiaryColor, shadowColor, strokeWidth, timeMs, layerIndex } = options;
+    const firstPoint = points[0];
+    const lastPoint = points[points.length - 1];
+    const ribbonGradient = context.createLinearGradient(firstPoint.x, firstPoint.y, lastPoint.x, lastPoint.y);
+    ribbonGradient.addColorStop(0, `${primaryColor}f2`);
+    ribbonGradient.addColorStop(0.5, `${secondaryColor}e6`);
+    ribbonGradient.addColorStop(1, `${tertiaryColor}f2`);
+    context.save();
+    context.beginPath();
+    tracePolyline(context, points);
+    context.strokeStyle = `${shadowColor}82`;
+    context.lineWidth = strokeWidth * 1.8;
+    context.lineJoin = 'round';
+    context.lineCap = 'round';
+    context.filter = `blur(${size * 0.022}px)`;
+    context.stroke();
+    context.restore();
+    context.beginPath();
+    tracePolyline(context, points);
+    context.strokeStyle = ribbonGradient;
+    context.lineWidth = strokeWidth;
+    context.lineJoin = 'round';
+    context.lineCap = 'round';
+    context.stroke();
+    context.beginPath();
+    tracePolyline(context, points);
+    context.strokeStyle = 'rgba(255,255,255,0.22)';
+    context.lineWidth = Math.max(1.2, strokeWidth * 0.28);
+    context.lineJoin = 'round';
+    context.lineCap = 'round';
+    context.stroke();
+    const sparkStride = Math.max(24, Math.floor(points.length / 18));
+    for (let pointIndex = sparkStride; pointIndex < points.length; pointIndex += sparkStride) {
+        const point = points[pointIndex];
+        const pulse = 0.7 + 0.3 * Math.sin(timeMs / 700 + pointIndex * 0.12 + layerIndex);
+        const radius = strokeWidth * (0.24 + pulse * 0.22);
+        context.beginPath();
+        context.arc(point.x, point.y, radius * 1.8, 0, Math.PI * 2);
+        context.fillStyle = `${secondaryColor}20`;
+        context.fill();
+        context.beginPath();
+        context.arc(point.x, point.y, radius, 0, Math.PI * 2);
+        context.fillStyle = tertiaryColor;
+        context.fill();
+    }
+}
+/**
+ * Traces a polyline through the provided points.
+ *
+ * @param context Canvas 2D context.
+ * @param points Polyline points.
+ *
+ * @private helper of `fractalAvatarVisual`
+ */
+function tracePolyline(context, points) {
+    const firstPoint = points[0];
+    context.moveTo(firstPoint.x, firstPoint.y);
+    for (let pointIndex = 1; pointIndex < points.length; pointIndex++) {
+        const point = points[pointIndex];
+        context.lineTo(point.x, point.y);
+    }
+}
+/**
+ * Draws the central crystalline accent tying the dragon-curve layers together.
+ *
+ * @param context Canvas 2D context.
+ * @param size Canvas size in CSS pixels.
+ * @param palette Derived avatar palette.
+ * @param timeMs Current animation time in milliseconds.
+ * @param corePhase Seed-based phase offset.
+ *
+ * @private helper of `fractalAvatarVisual`
+ */
+function drawFractalCore(context, size, palette, timeMs, corePhase) {
+    const centerX = size * 0.5;
+    const centerY = size * 0.5;
+    const radius = size * 0.082;
+    const rotation = corePhase * Math.PI * 2 + timeMs / 2200;
+    const innerRotation = -rotation * 1.35;
+    context.save();
+    context.translate(centerX, centerY);
+    context.rotate(rotation);
+    context.beginPath();
+    for (let pointIndex = 0; pointIndex < 4; pointIndex++) {
+        const angle = (pointIndex / 4) * Math.PI * 2;
+        const x = Math.cos(angle) * radius;
+        const y = Math.sin(angle) * radius;
+        if (pointIndex === 0) {
+            context.moveTo(x, y);
+        }
+        else {
+            context.lineTo(x, y);
+        }
+    }
+    context.closePath();
+    context.fillStyle = `${palette.highlight}88`;
+    context.shadowColor = `${palette.highlight}77`;
+    context.shadowBlur = size * 0.05;
+    context.fill();
+    context.restore();
+    context.save();
+    context.translate(centerX, centerY);
+    context.rotate(innerRotation);
+    context.beginPath();
+    for (let pointIndex = 0; pointIndex < 4; pointIndex++) {
+        const angle = Math.PI / 4 + (pointIndex / 4) * Math.PI * 2;
+        const x = Math.cos(angle) * radius * 0.55;
+        const y = Math.sin(angle) * radius * 0.55;
+        if (pointIndex === 0) {
+            context.moveTo(x, y);
+        }
+        else {
+            context.lineTo(x, y);
+        }
+    }
+    context.closePath();
+    context.fillStyle = `${palette.ink}cc`;
+    context.fill();
+    context.restore();
+}
+
+/* eslint-disable no-magic-numbers */
+/**
+ * Minecraft-style 3D avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+const minecraftAvatarVisual = {
+    id: 'minecraft',
+    title: 'Minecraft 3D',
+    description: 'Blocky 3D portrait with deterministic pixel textures, shoulders, and hovering depth.',
+    isAnimated: true,
+    render({ context, size, palette, createRandom, timeMs }) {
+        const random = createRandom('minecraft');
+        const bob = Math.sin(timeMs / 880) * size * 0.015;
+        const headSize = size * 0.34;
+        const depth = headSize * 0.22;
+        const headX = size * 0.31;
+        const headY = size * 0.18 + bob;
+        const bodyWidth = headSize * 0.86;
+        const bodyHeight = headSize * 0.82;
+        const bodyDepth = depth * 0.8;
+        const bodyX = size * 0.33;
+        const bodyY = headY + headSize * 0.96;
+        const hasHeadband = random() < 0.5;
+        const faceTexture = createMinecraftFaceTexture(createRandom('minecraft-face'), palette, hasHeadband);
+        const shirtTexture = createMinecraftShirtTexture(createRandom('minecraft-shirt'), palette);
+        drawAvatarFrame(context, size, palette);
+        const spotlight = context.createRadialGradient(size * 0.5, size * 0.18, size * 0.05, size * 0.5, size * 0.18, size * 0.5);
+        spotlight.addColorStop(0, `${palette.highlight}66`);
+        spotlight.addColorStop(1, `${palette.highlight}00`);
+        context.fillStyle = spotlight;
+        context.fillRect(0, 0, size, size);
+        context.save();
+        context.fillStyle = 'rgba(0, 0, 0, 0.22)';
+        context.filter = `blur(${size * 0.018}px)`;
+        context.beginPath();
+        context.ellipse(size * 0.5, size * 0.86, size * 0.2, size * 0.06, 0, 0, Math.PI * 2);
+        context.fill();
+        context.restore();
+        drawVoxelCuboid(context, {
+            x: bodyX,
+            y: bodyY,
+            width: bodyWidth,
+            height: bodyHeight,
+            depth: bodyDepth,
+            frontTexture: shirtTexture,
+            topColor: `${palette.highlight}cc`,
+            sideColor: `${palette.secondary}dd`,
+            outlineColor: `${palette.shadow}aa`,
+        });
+        drawVoxelCuboid(context, {
+            x: headX,
+            y: headY,
+            width: headSize,
+            height: headSize,
+            depth,
+            frontTexture: faceTexture,
+            topColor: `${palette.highlight}ee`,
+            sideColor: `${palette.secondary}ee`,
+            outlineColor: `${palette.shadow}cc`,
+        });
+    },
+};
+/**
+ * Draws a stylized voxel cuboid with a front pixel texture.
+ *
+ * @param context Canvas 2D context.
+ * @param cuboid Cuboid settings.
+ *
+ * @private helper of `minecraftAvatarVisual`
+ */
+function drawVoxelCuboid(context, cuboid) {
+    var _a;
+    const { x, y, width, height, depth, frontTexture, topColor, sideColor, outlineColor } = cuboid;
+    const lift = depth * 0.6;
+    context.save();
+    context.beginPath();
+    context.moveTo(x, y);
+    context.lineTo(x + depth, y - lift);
+    context.lineTo(x + width + depth, y - lift);
+    context.lineTo(x + width, y);
+    context.closePath();
+    context.fillStyle = topColor;
+    context.fill();
+    context.restore();
+    context.save();
+    context.beginPath();
+    context.moveTo(x + width, y);
+    context.lineTo(x + width + depth, y - lift);
+    context.lineTo(x + width + depth, y + height - lift);
+    context.lineTo(x + width, y + height);
+    context.closePath();
+    context.fillStyle = sideColor;
+    context.fill();
+    context.restore();
+    const rows = frontTexture.length;
+    const columns = ((_a = frontTexture[0]) === null || _a === void 0 ? void 0 : _a.length) || 0;
+    const pixelWidth = width / Math.max(columns, 1);
+    const pixelHeight = height / Math.max(rows, 1);
+    context.save();
+    createRoundedRectPath(context, x, y, width, height, width * 0.03);
+    context.clip();
+    for (let rowIndex = 0; rowIndex < rows; rowIndex++) {
+        for (let columnIndex = 0; columnIndex < columns; columnIndex++) {
+            context.fillStyle = frontTexture[rowIndex][columnIndex];
+            context.fillRect(x + columnIndex * pixelWidth, y + rowIndex * pixelHeight, pixelWidth, pixelHeight);
+        }
+    }
+    context.restore();
+    context.strokeStyle = outlineColor;
+    context.lineWidth = Math.max(1.2, width * 0.025);
+    context.beginPath();
+    context.moveTo(x, y);
+    context.lineTo(x + depth, y - lift);
+    context.lineTo(x + width + depth, y - lift);
+    context.lineTo(x + width + depth, y + height - lift);
+    context.lineTo(x + width, y + height);
+    context.lineTo(x, y + height);
+    context.closePath();
+    context.stroke();
+}
+/**
+ * Creates the front-face pixel texture for the cube head.
+ *
+ * @param random Seeded random generator.
+ * @param palette Derived avatar palette.
+ * @param hasHeadband Whether the avatar should render a headband row.
+ * @returns 8x8 pixel texture.
+ *
+ * @private helper of `minecraftAvatarVisual`
+ */
+function createMinecraftFaceTexture(random, palette, hasHeadband) {
+    const texture = Array.from({ length: 8 }, () => Array.from({ length: 8 }, () => palette.highlight));
+    const hairlineColor = random() < 0.5 ? palette.primary : palette.secondary;
+    const cheekColor = random() < 0.5 ? `${palette.accent}bb` : `${palette.secondary}bb`;
+    for (let rowIndex = 0; rowIndex < 2; rowIndex++) {
+        for (let columnIndex = 0; columnIndex < 8; columnIndex++) {
+            texture[rowIndex][columnIndex] = hairlineColor;
+        }
+    }
+    texture[2][0] = hairlineColor;
+    texture[2][7] = hairlineColor;
+    texture[3][0] = hairlineColor;
+    texture[3][7] = hairlineColor;
+    if (hasHeadband) {
+        for (let columnIndex = 0; columnIndex < 8; columnIndex++) {
+            texture[2][columnIndex] = palette.accent;
+        }
+    }
+    texture[3][2] = palette.ink;
+    texture[3][5] = palette.ink;
+    texture[4][2] = '#ffffff';
+    texture[4][5] = '#ffffff';
+    texture[5][1] = cheekColor;
+    texture[5][6] = cheekColor;
+    texture[5][3] = palette.shadow;
+    texture[5][4] = palette.shadow;
+    texture[6][3] = palette.shadow;
+    texture[6][4] = palette.shadow;
+    return texture;
+}
+/**
+ * Creates the front-face pixel texture for the torso.
+ *
+ * @param random Seeded random generator.
+ * @param palette Derived avatar palette.
+ * @returns 8x8 torso texture.
+ *
+ * @private helper of `minecraftAvatarVisual`
+ */
+function createMinecraftShirtTexture(random, palette) {
+    const texture = Array.from({ length: 8 }, () => Array.from({ length: 8 }, () => palette.primary));
+    const stripeColor = random() < 0.5 ? palette.secondary : palette.highlight;
+    for (let rowIndex = 0; rowIndex < 2; rowIndex++) {
+        for (let columnIndex = 0; columnIndex < 8; columnIndex++) {
+            texture[rowIndex][columnIndex] = palette.shadow;
+        }
+    }
+    for (let rowIndex = 2; rowIndex < 8; rowIndex++) {
+        texture[rowIndex][3] = stripeColor;
+        texture[rowIndex][4] = stripeColor;
+    }
+    texture[4][1] = palette.accent;
+    texture[4][6] = palette.accent;
+    texture[5][2] = palette.highlight;
+    texture[5][5] = palette.highlight;
+    return texture;
+}
+
+/* eslint-disable no-magic-numbers */
+/**
+ * Octopus avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+const octopusAvatarVisual = {
+    id: 'octopus',
+    title: 'Octopus',
+    description: 'Playful underwater mascot with cursor-following eyes, animated tentacles, bubbles, and seeded markings.',
+    isAnimated: true,
+    supportsPointerTracking: true,
+    render({ context, size, palette, createRandom, timeMs, interaction }) {
+        const staticRandom = createRandom('octopus-static');
+        const bubbleRandom = createRandom('octopus-bubbles');
+        const bubbleCount = 8;
+        const bubbleRadiusBase = size * 0.02;
+        const centerX = size * 0.5 + interaction.bodyOffsetX * size * 0.035;
+        const centerY = size * 0.42 + interaction.bodyOffsetY * size * 0.024;
+        const headRadius = size * (0.19 + staticRandom() * 0.03);
+        const mantleHeight = headRadius * 1.18;
+        const tentacleLength = size * (0.18 + staticRandom() * 0.06);
+        const tentaclePhases = Array.from({ length: 8 }, () => staticRandom() * Math.PI * 2);
+        const spotCount = 3 + Math.floor(staticRandom() * 4);
+        const spotColors = [palette.secondary, palette.accent, palette.highlight];
+        drawAvatarFrame(context, size, palette);
+        const waterGlow = context.createRadialGradient(centerX, size * 0.22, size * 0.06, centerX, size * 0.22, size * 0.58);
+        waterGlow.addColorStop(0, `${palette.highlight}66`);
+        waterGlow.addColorStop(1, `${palette.highlight}00`);
+        context.fillStyle = waterGlow;
+        context.fillRect(0, 0, size, size);
+        for (let bubbleIndex = 0; bubbleIndex < bubbleCount; bubbleIndex++) {
+            const x = size * (0.15 + bubbleRandom() * 0.7);
+            const y = size * (0.12 + bubbleRandom() * 0.68);
+            const radius = bubbleRadiusBase * (0.6 + bubbleRandom() * 2.3);
+            context.beginPath();
+            context.arc(x, y, radius, 0, Math.PI * 2);
+            context.fillStyle = 'rgba(255,255,255,0.08)';
+            context.fill();
+            context.beginPath();
+            context.arc(x - radius * 0.22, y - radius * 0.22, radius * 0.25, 0, Math.PI * 2);
+            context.fillStyle = 'rgba(255,255,255,0.28)';
+            context.fill();
+        }
+        for (let tentacleIndex = 0; tentacleIndex < 8; tentacleIndex++) {
+            const startX = centerX + (tentacleIndex - 3.5) * headRadius * 0.19;
+            const startY = centerY + headRadius * 0.62;
+            const animationPhase = tentaclePhases[tentacleIndex];
+            const sway = Math.sin(timeMs / 520 + animationPhase) * size * 0.03;
+            const endX = startX + (tentacleIndex - 3.5) * size * 0.025 + sway;
+            const endY = startY + tentacleLength + Math.cos(timeMs / 700 + animationPhase) * size * 0.01;
+            const controlX = (startX + endX) / 2 + sway * 0.8;
+            const controlY = startY + tentacleLength * 0.45;
+            const lineWidth = size * (0.042 - tentacleIndex * 0.0022);
+            context.beginPath();
+            context.moveTo(startX, startY);
+            context.quadraticCurveTo(controlX, controlY, endX, endY);
+            context.lineCap = 'round';
+            context.strokeStyle = palette.primary;
+            context.lineWidth = lineWidth;
+            context.stroke();
+            for (let cupIndex = 1; cupIndex <= 3; cupIndex++) {
+                const cupT = cupIndex / 4;
+                const cupX = (1 - cupT) * (1 - cupT) * startX + 2 * (1 - cupT) * cupT * controlX + cupT * cupT * endX;
+                const cupY = (1 - cupT) * (1 - cupT) * startY + 2 * (1 - cupT) * cupT * controlY + cupT * cupT * endY;
+                context.beginPath();
+                context.arc(cupX, cupY, lineWidth * 0.18, 0, Math.PI * 2);
+                context.fillStyle = `${palette.highlight}cc`;
+                context.fill();
+            }
+        }
+        context.save();
+        context.fillStyle = palette.primary;
+        context.shadowColor = `${palette.shadow}88`;
+        context.shadowBlur = size * 0.08;
+        context.beginPath();
+        context.ellipse(centerX, centerY, headRadius, mantleHeight, 0, Math.PI, 0, true);
+        context.lineTo(centerX + headRadius, centerY);
+        context.ellipse(centerX, centerY, headRadius, headRadius * 0.82, 0, 0, Math.PI);
+        context.closePath();
+        context.fill();
+        context.restore();
+        context.beginPath();
+        context.ellipse(centerX, centerY - headRadius * 0.22, headRadius * 0.74, headRadius * 0.42, 0, Math.PI, Math.PI * 2);
+        context.fillStyle = `${palette.highlight}55`;
+        context.fill();
+        for (let spotIndex = 0; spotIndex < spotCount; spotIndex++) {
+            const spotRandom = createRandom(`octopus-spot-${spotIndex}`);
+            const spotX = centerX + (spotRandom() - 0.5) * headRadius * 1.1;
+            const spotY = centerY - headRadius * 0.05 + (spotRandom() - 0.5) * headRadius * 0.9;
+            const spotRadius = headRadius * (0.07 + spotRandom() * 0.07);
+            context.beginPath();
+            context.arc(spotX, spotY, spotRadius, 0, Math.PI * 2);
+            context.fillStyle = pickRandomItem(spotColors, spotRandom);
+            context.fill();
+        }
+        const eyeOffsetX = headRadius * 0.42;
+        const eyeY = centerY + headRadius * 0.04;
+        const eyeRadius = headRadius * 0.22;
+        drawEye(context, centerX - eyeOffsetX, eyeY, eyeRadius, palette, timeMs, interaction, 0);
+        drawEye(context, centerX + eyeOffsetX, eyeY, eyeRadius, palette, timeMs, interaction, Math.PI / 5);
+        context.beginPath();
+        context.arc(centerX - headRadius * 0.28, centerY + headRadius * 0.3, headRadius * 0.12, 0, Math.PI * 2);
+        context.arc(centerX + headRadius * 0.28, centerY + headRadius * 0.3, headRadius * 0.12, 0, Math.PI * 2);
+        context.fillStyle = `${palette.accent}44`;
+        context.fill();
+        context.beginPath();
+        context.moveTo(centerX - headRadius * 0.18, centerY + headRadius * 0.24);
+        context.quadraticCurveTo(centerX, centerY + headRadius * 0.42, centerX + headRadius * 0.18, centerY + headRadius * 0.24);
+        context.strokeStyle = palette.shadow;
+        context.lineWidth = size * 0.016;
+        context.lineCap = 'round';
+        context.stroke();
+    },
+};
+/**
+ * Draws one expressive octopus eye.
+ *
+ * @param context Canvas 2D context.
+ * @param centerX Eye center X coordinate.
+ * @param centerY Eye center Y coordinate.
+ * @param radius Eye radius.
+ * @param palette Derived avatar palette.
+ * @param timeMs Current animation time in milliseconds.
+ * @param interaction Smoothed avatar interaction state.
+ * @param phase Seed-based phase offset.
+ *
+ * @private helper of `octopusAvatarVisual`
+ */
+function drawEye(context, centerX, centerY, radius, palette, timeMs, interaction, phase) {
+    const { pupilOffsetX, pupilOffsetY } = resolveOrganicEyeMotion({
+        radiusX: radius,
+        radiusY: radius,
+        timeMs,
+        phase,
+        interaction,
+        autonomousDriftRatioX: 0.05,
+        autonomousDriftRatioY: 0.03,
+    });
+    context.beginPath();
+    context.arc(centerX, centerY, radius, 0, Math.PI * 2);
+    context.fillStyle = '#ffffff';
+    context.fill();
+    context.beginPath();
+    context.arc(centerX + pupilOffsetX, centerY + pupilOffsetY, radius * 0.45, 0, Math.PI * 2);
+    context.fillStyle = palette.ink;
+    context.fill();
+    context.beginPath();
+    context.arc(centerX + pupilOffsetX - radius * 0.12, centerY + pupilOffsetY - radius * 0.12, radius * 0.15, 0, Math.PI * 2);
+    context.fillStyle = '#ffffff';
+    context.fill();
+    context.beginPath();
+    context.arc(centerX, centerY, radius, 0, Math.PI * 2);
+    context.strokeStyle = palette.shadow;
+    context.lineWidth = radius * 0.18;
+    context.stroke();
+}
+
+/* eslint-disable no-magic-numbers */
+/**
+ * Octopus2 avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+const octopus2AvatarVisual = {
+    id: 'octopus2',
+    title: 'Octopus2',
+    description: 'Organic alien octopus rendered as one continuously morphing blob with responsive luminous eyes.',
+    isAnimated: true,
+    supportsPointerTracking: true,
+    render({ context, size, palette, createRandom, timeMs, interaction }) {
+        const staticRandom = createRandom('octopus2-static');
+        const centerX = size * 0.5 + interaction.bodyOffsetX * size * 0.042;
+        const centerY = size * (0.48 + staticRandom() * 0.03) + interaction.bodyOffsetY * size * 0.028;
+        const bodyRadius = size * (0.25 + staticRandom() * 0.035);
+        const horizontalStretch = 1.04 + staticRandom() * 0.16;
+        const verticalStretch = 0.94 + staticRandom() * 0.12;
+        const mantleLift = size * (0.075 + staticRandom() * 0.025);
+        const lowerDrop = size * (0.05 + staticRandom() * 0.02);
+        const tentacleDepth = size * (0.08 + staticRandom() * 0.03);
+        const wobbleAmplitude = size * (0.014 + staticRandom() * 0.008);
+        const lobeCount = 6 + Math.floor(staticRandom() * 3);
+        const shapePhase = staticRandom() * Math.PI * 2;
+        const bodyPoints = createOrganicOctopusBodyPoints({
+            centerX,
+            centerY,
+            bodyRadius,
+            horizontalStretch,
+            verticalStretch,
+            mantleLift,
+            lowerDrop,
+            tentacleDepth,
+            wobbleAmplitude,
+            lobeCount,
+            shapePhase,
+            timeMs,
+        });
+        drawAvatarFrame(context, size, palette);
+        const hazeGradient = context.createRadialGradient(centerX, size * 0.22, size * 0.05, centerX, centerY, size * 0.6);
+        hazeGradient.addColorStop(0, `${palette.highlight}4d`);
+        hazeGradient.addColorStop(0.45, `${palette.accent}24`);
+        hazeGradient.addColorStop(1, `${palette.highlight}00`);
+        context.fillStyle = hazeGradient;
+        context.fillRect(0, 0, size, size);
+        const rimGlowGradient = context.createRadialGradient(centerX, centerY + size * 0.08, size * 0.14, centerX, centerY, size * 0.5);
+        rimGlowGradient.addColorStop(0, `${palette.secondary}26`);
+        rimGlowGradient.addColorStop(1, `${palette.secondary}00`);
+        context.fillStyle = rimGlowGradient;
+        context.fillRect(0, 0, size, size);
+        context.save();
+        traceSmoothClosedPath(context, bodyPoints);
+        const bodyGradient = context.createRadialGradient(centerX - size * 0.09, centerY - size * 0.18, size * 0.06, centerX, centerY + size * 0.14, size * 0.5);
+        bodyGradient.addColorStop(0, palette.highlight);
+        bodyGradient.addColorStop(0.25, palette.secondary);
+        bodyGradient.addColorStop(0.68, palette.primary);
+        bodyGradient.addColorStop(1, palette.shadow);
+        context.fillStyle = bodyGradient;
+        context.shadowColor = `${palette.shadow}aa`;
+        context.shadowBlur = size * 0.08;
+        context.shadowOffsetY = size * 0.018;
+        context.fill();
+        context.restore();
+        context.save();
+        traceSmoothClosedPath(context, bodyPoints);
+        context.clip();
+        const interiorGlowGradient = context.createLinearGradient(centerX, centerY - size * 0.22, centerX, centerY + size * 0.36);
+        interiorGlowGradient.addColorStop(0, `${palette.highlight}59`);
+        interiorGlowGradient.addColorStop(0.45, `${palette.accent}1a`);
+        interiorGlowGradient.addColorStop(1, `${palette.shadow}00`);
+        context.fillStyle = interiorGlowGradient;
+        context.fillRect(centerX - size * 0.36, centerY - size * 0.34, size * 0.72, size * 0.76);
+        drawInteriorFilaments(context, centerX, centerY, size, palette, timeMs, shapePhase);
+        drawLowerSuckers(context, centerX, centerY, size, palette, createRandom, timeMs);
+        context.restore();
+        context.save();
+        traceSmoothClosedPath(context, bodyPoints);
+        context.strokeStyle = `${palette.highlight}59`;
+        context.lineWidth = size * 0.014;
+        context.stroke();
+        context.restore();
+        const eyeOffsetX = size * 0.13;
+        const eyeCenterY = centerY - size * 0.02;
+        const eyeRadiusX = size * 0.072;
+        const eyeRadiusY = size * 0.086;
+        drawAlienEye(context, centerX - eyeOffsetX, eyeCenterY, eyeRadiusX, eyeRadiusY, palette, timeMs, shapePhase, interaction);
+        drawAlienEye(context, centerX + eyeOffsetX, eyeCenterY, eyeRadiusX, eyeRadiusY, palette, timeMs, shapePhase + Math.PI / 5, interaction);
+        context.beginPath();
+        context.moveTo(centerX - size * 0.08, centerY + size * 0.12);
+        context.quadraticCurveTo(centerX, centerY + size * (0.175 + Math.sin(timeMs / 520 + shapePhase) * 0.012) + interaction.gazeY * size * 0.01, centerX + size * 0.08, centerY + size * 0.12);
+        context.strokeStyle = `${palette.ink}b3`;
+        context.lineWidth = size * 0.013;
+        context.lineCap = 'round';
+        context.stroke();
+        context.beginPath();
+        context.ellipse(centerX, centerY - size * 0.13, size * 0.16, size * 0.065, 0, Math.PI, Math.PI * 2);
+        context.fillStyle = `${palette.highlight}33`;
+        context.fill();
+    },
+};
+/**
+ * Draws translucent inner filaments clipped inside the main body mesh.
+ *
+ * @param context Canvas 2D context.
+ * @param centerX Body center X coordinate.
+ * @param centerY Body center Y coordinate.
+ * @param size Canvas size in CSS pixels.
+ * @param palette Derived avatar palette.
+ * @param timeMs Current animation time in milliseconds.
+ * @param shapePhase Seed-based phase offset.
+ *
+ * @private helper of `octopus2AvatarVisual`
+ */
+function drawInteriorFilaments(context, centerX, centerY, size, palette, timeMs, shapePhase) {
+    for (let filamentIndex = 0; filamentIndex < 5; filamentIndex++) {
+        const horizontalOffset = (filamentIndex - 2) * size * 0.075;
+        const sway = Math.sin(timeMs / 720 + filamentIndex * 0.8 + shapePhase) * size * 0.028;
+        context.beginPath();
+        context.moveTo(centerX + horizontalOffset * 0.35, centerY - size * 0.11);
+        context.bezierCurveTo(centerX + horizontalOffset - sway * 0.35, centerY - size * 0.01, centerX + horizontalOffset + sway, centerY + size * 0.13, centerX + horizontalOffset * 0.85 + sway * 0.55, centerY + size * 0.3);
+        context.strokeStyle = filamentIndex % 2 === 0 ? `${palette.highlight}29` : `${palette.accent}24`;
+        context.lineWidth = size * (0.01 + filamentIndex * 0.0008);
+        context.lineCap = 'round';
+        context.stroke();
+    }
+}
+/**
+ * Draws soft sucker-like highlights in the lower body area.
+ *
+ * @param context Canvas 2D context.
+ * @param centerX Body center X coordinate.
+ * @param centerY Body center Y coordinate.
+ * @param size Canvas size in CSS pixels.
+ * @param palette Derived avatar palette.
+ * @param createRandom Seeded random factory scoped to the avatar.
+ * @param timeMs Current animation time in milliseconds.
+ *
+ * @private helper of `octopus2AvatarVisual`
+ */
+function drawLowerSuckers(context, centerX, centerY, size, palette, createRandom, timeMs) {
+    const suckerRandom = createRandom('octopus2-suckers');
+    for (let suckerIndex = 0; suckerIndex < 12; suckerIndex++) {
+        const x = centerX + (suckerRandom() - 0.5) * size * 0.36;
+        const y = centerY + size * (0.11 + suckerRandom() * 0.22);
+        const radiusX = size * (0.015 + suckerRandom() * 0.012);
+        const radiusY = radiusX * (0.72 + suckerRandom() * 0.34);
+        const rotation = suckerRandom() * Math.PI + Math.sin(timeMs / 1100 + suckerIndex) * 0.08;
+        context.beginPath();
+        context.ellipse(x, y, radiusX, radiusY, rotation, 0, Math.PI * 2);
+        context.fillStyle = `${palette.highlight}24`;
+        context.fill();
+        context.strokeStyle = `${palette.highlight}40`;
+        context.lineWidth = Math.max(1, size * 0.005);
+        context.stroke();
+    }
+}
+/**
+ * Draws one luminous alien eye on top of the organic octopus mesh.
+ *
+ * @param context Canvas 2D context.
+ * @param centerX Eye center X coordinate.
+ * @param centerY Eye center Y coordinate.
+ * @param radiusX Eye horizontal radius.
+ * @param radiusY Eye vertical radius.
+ * @param palette Derived avatar palette.
+ * @param timeMs Current animation time in milliseconds.
+ * @param phase Seed-based animation phase.
+ * @param interaction Smoothed avatar interaction state.
+ *
+ * @private helper of `octopus2AvatarVisual`
+ */
+function drawAlienEye(context, centerX, centerY, radiusX, radiusY, palette, timeMs, phase, interaction) {
+    const { pupilOffsetX, pupilOffsetY } = resolveOrganicEyeMotion({
+        radiusX,
+        radiusY,
+        timeMs,
+        phase,
+        interaction,
+        autonomousDriftRatioY: 0.1,
+    });
+    context.save();
+    context.beginPath();
+    context.ellipse(centerX, centerY, radiusX, radiusY, 0, 0, Math.PI * 2);
+    context.fillStyle = '#f8fbff';
+    context.fill();
+    context.clip();
+    const irisGradient = context.createRadialGradient(centerX - radiusX * 0.18, centerY - radiusY * 0.22, radiusX * 0.05, centerX, centerY, radiusX * 0.9);
+    irisGradient.addColorStop(0, palette.highlight);
+    irisGradient.addColorStop(0.55, palette.secondary);
+    irisGradient.addColorStop(1, palette.shadow);
+    context.beginPath();
+    context.ellipse(centerX + pupilOffsetX, centerY + pupilOffsetY, radiusX * 0.68, radiusY * 0.72, 0, 0, Math.PI * 2);
+    context.fillStyle = irisGradient;
+    context.fill();
+    context.beginPath();
+    context.ellipse(centerX + pupilOffsetX, centerY + pupilOffsetY, radiusX * 0.16, radiusY * 0.48, 0, 0, Math.PI * 2);
+    context.fillStyle = palette.ink;
+    context.fill();
+    context.beginPath();
+    context.ellipse(centerX + pupilOffsetX - radiusX * 0.18, centerY + pupilOffsetY - radiusY * 0.24, radiusX * 0.12, radiusY * 0.14, 0, 0, Math.PI * 2);
+    context.fillStyle = '#ffffff';
+    context.fill();
+    context.restore();
+    context.beginPath();
+    context.ellipse(centerX, centerY, radiusX, radiusY, 0, 0, Math.PI * 2);
+    context.strokeStyle = `${palette.shadow}cc`;
+    context.lineWidth = radiusX * 0.2;
+    context.stroke();
+}
+
+/* eslint-disable no-magic-numbers */
+/**
+ * Builds one deterministic morphology profile for `Octopus3`.
+ *
+ * @param createRandom Seeded random factory scoped to the current avatar.
+ * @returns Stable morphology profile.
+ *
+ * @private helper of `octopus3AvatarVisual`
+ */
+function createOctopus3MorphologyProfile(createRandom) {
+    const bodyRandom = createRandom('octopus3-body-profile');
+    const faceRandom = createRandom('octopus3-face-profile');
+    const detailRandom = createRandom('octopus3-detail-profile');
+    const bodyFamilyRoll = bodyRandom();
+    let bodyFamily;
+    let body;
+    let tentacles;
+    if (bodyFamilyRoll < 0.34) {
+        bodyFamily = 'lantern';
+        body = {
+            centerXJitterRatio: resolveSeededRange(bodyRandom, -0.018, 0.018),
+            centerYRatio: resolveSeededRange(bodyRandom, 0.39, 0.435),
+            bodyRadiusRatio: resolveSeededRange(bodyRandom, 0.19, 0.23),
+            horizontalStretch: resolveSeededRange(bodyRandom, 0.94, 1.08),
+            verticalStretch: resolveSeededRange(bodyRandom, 1.02, 1.18),
+            mantleLiftRatio: resolveSeededRange(bodyRandom, 0.115, 0.148),
+            lowerDropRatio: resolveSeededRange(bodyRandom, 0.042, 0.066),
+            tentacleDepthRatio: resolveSeededRange(bodyRandom, 0.018, 0.03),
+            wobbleAmplitudeRatio: resolveSeededRange(bodyRandom, 0.009, 0.017),
+            lobeCount: resolveSeededIntegerRange(bodyRandom, 4, 6),
+            pointCount: resolveSeededIntegerRange(bodyRandom, 38, 42),
+            shadowWidthRatio: resolveSeededRange(bodyRandom, 0.18, 0.23),
+            shadowHeightRatio: resolveSeededRange(bodyRandom, 0.055, 0.075),
+            crownHighlightWidthRatio: resolveSeededRange(bodyRandom, 0.14, 0.18),
+            crownHighlightHeightRatio: resolveSeededRange(bodyRandom, 0.045, 0.062),
+            crownHighlightYOffsetRatio: resolveSeededRange(bodyRandom, -0.165, -0.135),
+        };
+        tentacles = {
+            count: resolveSeededIntegerRange(bodyRandom, 7, 10),
+            flowLengthScale: resolveSeededRange(bodyRandom, 1.08, 1.34),
+            lateralReachScale: resolveSeededRange(bodyRandom, 0.72, 0.94),
+            tipReachScale: resolveSeededRange(bodyRandom, 0.82, 1.06),
+            baseWidthScale: resolveSeededRange(bodyRandom, 0.82, 0.98),
+            tipWidthScale: resolveSeededRange(bodyRandom, 0.9, 1.08),
+            rootSpreadScale: resolveSeededRange(bodyRandom, 0.76, 0.94),
+            startYOffsetScale: resolveSeededRange(bodyRandom, 0.82, 1),
+            swayScale: resolveSeededRange(bodyRandom, 0.82, 1.02),
+        };
+    }
+    else if (bodyFamilyRoll < 0.68) {
+        bodyFamily = 'drifter';
+        body = {
+            centerXJitterRatio: resolveSeededRange(bodyRandom, -0.025, 0.025),
+            centerYRatio: resolveSeededRange(bodyRandom, 0.425, 0.46),
+            bodyRadiusRatio: resolveSeededRange(bodyRandom, 0.175, 0.215),
+            horizontalStretch: resolveSeededRange(bodyRandom, 1.22, 1.42),
+            verticalStretch: resolveSeededRange(bodyRandom, 0.82, 0.92),
+            mantleLiftRatio: resolveSeededRange(bodyRandom, 0.092, 0.115),
+            lowerDropRatio: resolveSeededRange(bodyRandom, 0.02, 0.036),
+            tentacleDepthRatio: resolveSeededRange(bodyRandom, 0.032, 0.052),
+            wobbleAmplitudeRatio: resolveSeededRange(bodyRandom, 0.013, 0.022),
+            lobeCount: resolveSeededIntegerRange(bodyRandom, 7, 9),
+            pointCount: resolveSeededIntegerRange(bodyRandom, 40, 46),
+            shadowWidthRatio: resolveSeededRange(bodyRandom, 0.24, 0.28),
+            shadowHeightRatio: resolveSeededRange(bodyRandom, 0.06, 0.082),
+            crownHighlightWidthRatio: resolveSeededRange(bodyRandom, 0.17, 0.22),
+            crownHighlightHeightRatio: resolveSeededRange(bodyRandom, 0.038, 0.055),
+            crownHighlightYOffsetRatio: resolveSeededRange(bodyRandom, -0.14, -0.11),
+        };
+        tentacles = {
+            count: resolveSeededIntegerRange(bodyRandom, 10, 13),
+            flowLengthScale: resolveSeededRange(bodyRandom, 0.88, 1.08),
+            lateralReachScale: resolveSeededRange(bodyRandom, 1.18, 1.42),
+            tipReachScale: resolveSeededRange(bodyRandom, 1.12, 1.42),
+            baseWidthScale: resolveSeededRange(bodyRandom, 0.9, 1.06),
+            tipWidthScale: resolveSeededRange(bodyRandom, 0.88, 1.08),
+            rootSpreadScale: resolveSeededRange(bodyRandom, 1.12, 1.32),
+            startYOffsetScale: resolveSeededRange(bodyRandom, 0.92, 1.14),
+            swayScale: resolveSeededRange(bodyRandom, 1.04, 1.22),
+        };
+    }
+    else {
+        bodyFamily = 'rounded';
+        body = {
+            centerXJitterRatio: resolveSeededRange(bodyRandom, -0.02, 0.02),
+            centerYRatio: resolveSeededRange(bodyRandom, 0.398, 0.442),
+            bodyRadiusRatio: resolveSeededRange(bodyRandom, 0.208, 0.248),
+            horizontalStretch: resolveSeededRange(bodyRandom, 1.06, 1.22),
+            verticalStretch: resolveSeededRange(bodyRandom, 0.9, 1.01),
+            mantleLiftRatio: resolveSeededRange(bodyRandom, 0.1, 0.128),
+            lowerDropRatio: resolveSeededRange(bodyRandom, 0.032, 0.052),
+            tentacleDepthRatio: resolveSeededRange(bodyRandom, 0.038, 0.06),
+            wobbleAmplitudeRatio: resolveSeededRange(bodyRandom, 0.014, 0.024),
+            lobeCount: resolveSeededIntegerRange(bodyRandom, 5, 8),
+            pointCount: resolveSeededIntegerRange(bodyRandom, 39, 44),
+            shadowWidthRatio: resolveSeededRange(bodyRandom, 0.2, 0.25),
+            shadowHeightRatio: resolveSeededRange(bodyRandom, 0.055, 0.08),
+            crownHighlightWidthRatio: resolveSeededRange(bodyRandom, 0.16, 0.2),
+            crownHighlightHeightRatio: resolveSeededRange(bodyRandom, 0.05, 0.07),
+            crownHighlightYOffsetRatio: resolveSeededRange(bodyRandom, -0.155, -0.122),
+        };
+        tentacles = {
+            count: resolveSeededIntegerRange(bodyRandom, 8, 12),
+            flowLengthScale: resolveSeededRange(bodyRandom, 0.94, 1.16),
+            lateralReachScale: resolveSeededRange(bodyRandom, 0.9, 1.14),
+            tipReachScale: resolveSeededRange(bodyRandom, 0.96, 1.22),
+            baseWidthScale: resolveSeededRange(bodyRandom, 1.02, 1.2),
+            tipWidthScale: resolveSeededRange(bodyRandom, 1.02, 1.22),
+            rootSpreadScale: resolveSeededRange(bodyRandom, 0.94, 1.08),
+            startYOffsetScale: resolveSeededRange(bodyRandom, 0.9, 1.08),
+            swayScale: resolveSeededRange(bodyRandom, 0.9, 1.1),
+        };
+    }
+    const faceFamilyRoll = faceRandom();
+    let faceFamily;
+    let face;
+    if (faceFamilyRoll < 0.34) {
+        faceFamily = 'watchful';
+        face = {
+            eyeSpacingRatio: resolveSeededRange(faceRandom, 0.118, 0.152),
+            eyeCenterYOffsetRatio: resolveSeededRange(faceRandom, -0.026, -0.002),
+            eyeRadiusXRatio: resolveSeededRange(faceRandom, 0.05, 0.062),
+            eyeHeightRatio: resolveSeededRange(faceRandom, 1.18, 1.38),
+            eyeRotationRange: resolveSeededRange(faceRandom, 0.16, 0.28),
+            eyeTiltBias: resolveSeededRange(faceRandom, 0.02, 0.06),
+            mouthWidthRatio: resolveSeededRange(faceRandom, 0.058, 0.074),
+            mouthYOffsetRatio: resolveSeededRange(faceRandom, 0.086, 0.104),
+            mouthCurveDepthRatio: resolveSeededRange(faceRandom, 0.126, 0.15),
+            mouthCenterOffsetRatio: resolveSeededRange(faceRandom, -0.006, 0.006),
+            mouthCornerTiltRatio: resolveSeededRange(faceRandom, -0.002, 0.002),
+            eyeStyle: {
+                irisScale: resolveSeededRange(faceRandom, 1, 1.1),
+                pupilWidthScale: resolveSeededRange(faceRandom, 0.86, 1.02),
+                pupilHeightScale: resolveSeededRange(faceRandom, 0.94, 1.08),
+                upperLidArchRatio: resolveSeededRange(faceRandom, 0.96, 1.12),
+                upperLidInsetRatio: resolveSeededRange(faceRandom, 0.08, 0.14),
+                lowerLidOpacity: resolveSeededRange(faceRandom, 0.12, 0.22),
+            },
+        };
+    }
+    else if (faceFamilyRoll < 0.68) {
+        faceFamily = 'sleepy';
+        face = {
+            eyeSpacingRatio: resolveSeededRange(faceRandom, 0.092, 0.124),
+            eyeCenterYOffsetRatio: resolveSeededRange(faceRandom, -0.002, 0.024),
+            eyeRadiusXRatio: resolveSeededRange(faceRandom, 0.058, 0.074),
+            eyeHeightRatio: resolveSeededRange(faceRandom, 0.96, 1.14),
+            eyeRotationRange: resolveSeededRange(faceRandom, 0.1, 0.22),
+            eyeTiltBias: resolveSeededRange(faceRandom, 0.01, 0.05),
+            mouthWidthRatio: resolveSeededRange(faceRandom, 0.066, 0.086),
+            mouthYOffsetRatio: resolveSeededRange(faceRandom, 0.094, 0.118),
+            mouthCurveDepthRatio: resolveSeededRange(faceRandom, 0.118, 0.145),
+            mouthCenterOffsetRatio: resolveSeededRange(faceRandom, -0.004, 0.004),
+            mouthCornerTiltRatio: resolveSeededRange(faceRandom, -0.004, 0.004),
+            eyeStyle: {
+                irisScale: resolveSeededRange(faceRandom, 0.9, 1),
+                pupilWidthScale: resolveSeededRange(faceRandom, 1, 1.18),
+                pupilHeightScale: resolveSeededRange(faceRandom, 0.78, 0.92),
+                upperLidArchRatio: resolveSeededRange(faceRandom, 0.7, 0.88),
+                upperLidInsetRatio: resolveSeededRange(faceRandom, -0.02, 0.06),
+                lowerLidOpacity: resolveSeededRange(faceRandom, 0.22, 0.34),
+            },
+        };
+    }
+    else {
+        faceFamily = 'mischief';
+        face = {
+            eyeSpacingRatio: resolveSeededRange(faceRandom, 0.086, 0.114),
+            eyeCenterYOffsetRatio: resolveSeededRange(faceRandom, -0.018, 0.01),
+            eyeRadiusXRatio: resolveSeededRange(faceRandom, 0.046, 0.06),
+            eyeHeightRatio: resolveSeededRange(faceRandom, 1.08, 1.28),
+            eyeRotationRange: resolveSeededRange(faceRandom, 0.28, 0.44),
+            eyeTiltBias: resolveSeededRange(faceRandom, 0.12, 0.22),
+            mouthWidthRatio: resolveSeededRange(faceRandom, 0.052, 0.074),
+            mouthYOffsetRatio: resolveSeededRange(faceRandom, 0.082, 0.1),
+            mouthCurveDepthRatio: resolveSeededRange(faceRandom, 0.116, 0.15),
+            mouthCenterOffsetRatio: resolveSeededRange(faceRandom, -0.018, 0.018),
+            mouthCornerTiltRatio: resolveSeededRange(faceRandom, -0.01, 0.01),
+            eyeStyle: {
+                irisScale: resolveSeededRange(faceRandom, 1.04, 1.12),
+                pupilWidthScale: resolveSeededRange(faceRandom, 0.72, 0.9),
+                pupilHeightScale: resolveSeededRange(faceRandom, 0.96, 1.14),
+                upperLidArchRatio: resolveSeededRange(faceRandom, 0.88, 1.02),
+                upperLidInsetRatio: resolveSeededRange(faceRandom, 0.04, 0.12),
+                lowerLidOpacity: resolveSeededRange(faceRandom, 0.08, 0.18),
+            },
+        };
+    }
+    return {
+        bodyFamily,
+        faceFamily,
+        body,
+        tentacles,
+        face,
+        details: {
+            mantleCurrentCount: resolveSeededIntegerRange(detailRandom, 4, 8),
+            mantleNodeCount: resolveSeededIntegerRange(detailRandom, 3, 7),
+        },
+    };
+}
+/**
+ * Resolves one seeded floating-point number inside the provided range.
+ *
+ * @param random Seeded random generator.
+ * @param minimumValue Inclusive lower bound.
+ * @param maximumValue Inclusive upper bound.
+ * @returns Seeded number within the range.
+ *
+ * @private helper of `octopus3AvatarVisual`
+ */
+function resolveSeededRange(random, minimumValue, maximumValue) {
+    return minimumValue + random() * (maximumValue - minimumValue);
+}
+/**
+ * Resolves one seeded integer inside the provided inclusive range.
+ *
+ * @param random Seeded random generator.
+ * @param minimumValue Inclusive lower bound.
+ * @param maximumValue Inclusive upper bound.
+ * @returns Seeded integer within the range.
+ *
+ * @private helper of `octopus3AvatarVisual`
+ */
+function resolveSeededIntegerRange(random, minimumValue, maximumValue) {
+    return minimumValue + Math.floor(random() * (maximumValue - minimumValue + 1));
+}
+/**
+ * Converts an opacity ratio into a two-digit hexadecimal alpha suffix.
+ *
+ * @param opacity Opacity ratio in the range `[0, 1]`.
+ * @returns Two-digit hexadecimal alpha string.
+ *
+ * @private helper of `octopus3AvatarVisual`
+ */
+function formatAlphaHex(opacity) {
+    return Math.round(Math.min(1, Math.max(0, opacity)) * 255)
+        .toString(16)
+        .padStart(2, '0');
+}
+/**
+ * Octopus3 avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+const octopus3AvatarVisual = {
+    id: 'octopus3',
+    title: 'Octopus3',
+    description: 'Gelatinous alien octopus with a morphing mantle, responsive eyes, and visible ribbon tentacles.',
+    isAnimated: true,
+    supportsPointerTracking: true,
+    render({ context, size, palette, createRandom, timeMs, interaction }) {
+        const morphologyProfile = createOctopus3MorphologyProfile(createRandom);
+        const animationRandom = createRandom('octopus3-animation-profile');
+        const eyeRandom = createRandom('octopus3-eye-profile');
+        const centerX = size * (0.5 + morphologyProfile.body.centerXJitterRatio) + interaction.bodyOffsetX * size * 0.05;
+        const centerY = size * morphologyProfile.body.centerYRatio + interaction.bodyOffsetY * size * 0.035;
+        const bodyRadius = size * morphologyProfile.body.bodyRadiusRatio;
+        const horizontalStretch = morphologyProfile.body.horizontalStretch;
+        const verticalStretch = morphologyProfile.body.verticalStretch;
+        const mantleLift = size * morphologyProfile.body.mantleLiftRatio;
+        const lowerDrop = size * morphologyProfile.body.lowerDropRatio;
+        const tentacleDepth = size * morphologyProfile.body.tentacleDepthRatio;
+        const wobbleAmplitude = size * morphologyProfile.body.wobbleAmplitudeRatio;
+        const lobeCount = morphologyProfile.body.lobeCount;
+        const shapePhase = animationRandom() * Math.PI * 2;
+        const eyeSpacing = size * morphologyProfile.face.eyeSpacingRatio;
+        const eyeCenterY = centerY + size * morphologyProfile.face.eyeCenterYOffsetRatio;
+        const eyeRadiusX = size * morphologyProfile.face.eyeRadiusXRatio;
+        const eyeRadiusY = eyeRadiusX * morphologyProfile.face.eyeHeightRatio;
+        const bodyPoints = createOrganicOctopusBodyPoints({
+            centerX,
+            centerY,
+            bodyRadius,
+            horizontalStretch,
+            verticalStretch,
+            mantleLift,
+            lowerDrop,
+            tentacleDepth,
+            wobbleAmplitude,
+            lobeCount,
+            shapePhase,
+            timeMs,
+            pointCount: morphologyProfile.body.pointCount,
+        });
+        const tentacleShapes = createOrganicOctopusTentacleShapes({
+            size,
+            centerX,
+            centerY,
+            bodyRadius,
+            horizontalStretch,
+            tentacleCount: morphologyProfile.tentacles.count,
+            shapePhase,
+            createRandom,
+            timeMs,
+            saltPrefix: 'octopus3',
+            bodyPoints,
+            variation: {
+                flowLengthScale: morphologyProfile.tentacles.flowLengthScale,
+                lateralReachScale: morphologyProfile.tentacles.lateralReachScale,
+                tipReachScale: morphologyProfile.tentacles.tipReachScale,
+                baseWidthScale: morphologyProfile.tentacles.baseWidthScale,
+                tipWidthScale: morphologyProfile.tentacles.tipWidthScale,
+                rootSpreadScale: morphologyProfile.tentacles.rootSpreadScale,
+                startYOffsetScale: morphologyProfile.tentacles.startYOffsetScale,
+                swayScale: morphologyProfile.tentacles.swayScale,
+            },
+        });
+        drawAvatarFrame(context, size, palette);
+        drawOctopus3Atmosphere(context, size, palette, centerX, centerY, timeMs, shapePhase, morphologyProfile);
+        context.beginPath();
+        context.ellipse(centerX, centerY + size * 0.25, size * morphologyProfile.body.shadowWidthRatio, size * morphologyProfile.body.shadowHeightRatio, 0, 0, Math.PI * 2);
+        context.fillStyle = `${palette.shadow}33`;
+        context.fill();
+        for (const tentacleShape of tentacleShapes) {
+            drawTentacleRibbon(context, tentacleShape, palette);
+        }
+        context.save();
+        traceSmoothClosedPath(context, bodyPoints);
+        const bodyGradient = context.createRadialGradient(centerX - size * 0.1, centerY - size * 0.18, size * 0.04, centerX, centerY + size * 0.16, size * 0.54);
+        bodyGradient.addColorStop(0, palette.highlight);
+        bodyGradient.addColorStop(0.18, palette.secondary);
+        bodyGradient.addColorStop(0.55, palette.primary);
+        bodyGradient.addColorStop(1, palette.shadow);
+        context.fillStyle = bodyGradient;
+        context.shadowColor = `${palette.shadow}aa`;
+        context.shadowBlur = size * 0.08;
+        context.shadowOffsetY = size * 0.02;
+        context.fill();
+        context.restore();
+        context.save();
+        traceSmoothClosedPath(context, bodyPoints);
+        context.clip();
+        const innerGlowGradient = context.createLinearGradient(centerX, centerY - size * 0.24, centerX, centerY + size * 0.26);
+        innerGlowGradient.addColorStop(0, `${palette.highlight}66`);
+        innerGlowGradient.addColorStop(0.4, `${palette.secondary}26`);
+        innerGlowGradient.addColorStop(1, `${palette.shadow}00`);
+        context.fillStyle = innerGlowGradient;
+        context.fillRect(centerX - size * 0.36, centerY - size * 0.34, size * 0.72, size * 0.72);
+        drawMantleCurrents(context, centerX, centerY, size, palette, timeMs, shapePhase, morphologyProfile);
+        drawMantleNodes(context, centerX, centerY, size, palette, createRandom, morphologyProfile);
+        context.restore();
+        context.save();
+        traceSmoothClosedPath(context, bodyPoints);
+        context.strokeStyle = `${palette.highlight}73`;
+        context.lineWidth = size * 0.013;
+        context.stroke();
+        context.restore();
+        context.beginPath();
+        context.ellipse(centerX, centerY + size * morphologyProfile.body.crownHighlightYOffsetRatio, size * morphologyProfile.body.crownHighlightWidthRatio, size * morphologyProfile.body.crownHighlightHeightRatio, 0, Math.PI, Math.PI * 2);
+        context.fillStyle = `${palette.highlight}3d`;
+        context.fill();
+        drawSeededEye(context, centerX - eyeSpacing, eyeCenterY, eyeRadiusX, eyeRadiusY, -morphologyProfile.face.eyeTiltBias + (eyeRandom() - 0.5) * morphologyProfile.face.eyeRotationRange, palette, timeMs, shapePhase, interaction, morphologyProfile.face.eyeStyle);
+        drawSeededEye(context, centerX + eyeSpacing, eyeCenterY, eyeRadiusX, eyeRadiusY, morphologyProfile.face.eyeTiltBias + (eyeRandom() - 0.5) * morphologyProfile.face.eyeRotationRange, palette, timeMs, shapePhase + Math.PI / 4, interaction, morphologyProfile.face.eyeStyle);
+        const mouthHalfWidth = size * morphologyProfile.face.mouthWidthRatio;
+        const mouthY = centerY + size * morphologyProfile.face.mouthYOffsetRatio;
+        const mouthCornerTilt = size * morphologyProfile.face.mouthCornerTiltRatio;
+        context.beginPath();
+        context.moveTo(centerX - mouthHalfWidth, mouthY - mouthCornerTilt);
+        context.quadraticCurveTo(centerX + size * morphologyProfile.face.mouthCenterOffsetRatio, centerY +
+            size * (morphologyProfile.face.mouthCurveDepthRatio + Math.sin(timeMs / 620 + shapePhase) * 0.016) +
+            interaction.gazeY * size * 0.012, centerX + mouthHalfWidth, mouthY + mouthCornerTilt);
+        context.strokeStyle = `${palette.ink}b3`;
+        context.lineWidth = size * 0.012;
+        context.lineCap = 'round';
+        context.stroke();
+    },
+};
+/**
+ * Draws the deep-sea glow around the Octopus3 silhouette.
+ *
+ * @param context Canvas 2D context.
+ * @param size Canvas size in CSS pixels.
+ * @param palette Derived avatar palette.
+ * @param centerX Body center X coordinate.
+ * @param centerY Body center Y coordinate.
+ * @param timeMs Current animation time in milliseconds.
+ * @param shapePhase Seed-based phase offset.
+ * @param morphologyProfile Seeded morphology profile.
+ *
+ * @private helper of `octopus3AvatarVisual`
+ */
+function drawOctopus3Atmosphere(context, size, palette, centerX, centerY, timeMs, shapePhase, morphologyProfile) {
+    const haloGradient = context.createRadialGradient(centerX, centerY - size * (0.07 + (morphologyProfile.body.verticalStretch - 0.9) * 0.05), size * 0.06, centerX, centerY, size * (0.56 + morphologyProfile.body.bodyRadiusRatio * 0.45));
+    haloGradient.addColorStop(0, `${palette.highlight}5c`);
+    haloGradient.addColorStop(0.35, `${palette.accent}26`);
+    haloGradient.addColorStop(1, `${palette.highlight}00`);
+    context.fillStyle = haloGradient;
+    context.fillRect(0, 0, size, size);
+    const lowerGlowGradient = context.createRadialGradient(centerX + Math.sin(timeMs / 1600 + shapePhase) * size * 0.04, centerY + size * (0.18 + morphologyProfile.tentacles.flowLengthScale * 0.025), size * 0.04, centerX, centerY + size * (0.18 + morphologyProfile.tentacles.flowLengthScale * 0.025), size * (0.42 + morphologyProfile.tentacles.lateralReachScale * 0.06));
+    lowerGlowGradient.addColorStop(0, `${palette.secondary}1f`);
+    lowerGlowGradient.addColorStop(1, `${palette.secondary}00`);
+    context.fillStyle = lowerGlowGradient;
+    context.fillRect(0, 0, size, size);
+}
+/**
+ * Draws one ribbon tentacle with a filled organic profile and visible sucker highlights.
+ *
+ * @param context Canvas 2D context.
+ * @param tentacleShape Deterministic tentacle descriptor.
+ * @param palette Derived avatar palette.
+ *
+ * @private helper of `octopus3AvatarVisual`
+ */
+function drawTentacleRibbon(context, tentacleShape, palette) {
+    const ribbonPoints = sampleOrganicTentacleRibbonPoints(tentacleShape);
+    const gradient = context.createLinearGradient(tentacleShape.startPoint.x, tentacleShape.startPoint.y, tentacleShape.endPoint.x, tentacleShape.endPoint.y);
+    gradient.addColorStop(0, tentacleShape.colorBias < 0.35 ? palette.secondary : palette.primary);
+    gradient.addColorStop(0.58, palette.primary);
+    gradient.addColorStop(1, tentacleShape.colorBias > 0.65 ? palette.highlight : palette.accent);
+    context.save();
+    traceTentacleRibbonPath(context, ribbonPoints);
+    context.fillStyle = gradient;
+    context.shadowColor = `${palette.shadow}80`;
+    context.shadowBlur = tentacleShape.baseWidth * 1.2;
+    context.shadowOffsetY = tentacleShape.baseWidth * 0.2;
+    context.fill();
+    context.restore();
+    context.save();
+    traceTentacleRibbonPath(context, ribbonPoints);
+    context.strokeStyle = tentacleShape.highlightBias > 0.5 ? `${palette.highlight}52` : `${palette.highlight}38`;
+    context.lineWidth = Math.max(1, tentacleShape.baseWidth * 0.12);
+    context.stroke();
+    context.restore();
+    context.beginPath();
+    context.moveTo(tentacleShape.startPoint.x, tentacleShape.startPoint.y);
+    context.bezierCurveTo(tentacleShape.controlPointOne.x, tentacleShape.controlPointOne.y, tentacleShape.controlPointTwo.x, tentacleShape.controlPointTwo.y, tentacleShape.endPoint.x, tentacleShape.endPoint.y);
+    context.strokeStyle = `${palette.highlight}2e`;
+    context.lineWidth = Math.max(1, tentacleShape.tipWidth * 0.9);
+    context.lineCap = 'round';
+    context.stroke();
+    drawTentacleSuckers(context, tentacleShape, palette);
+}
+/**
+ * Traces a closed ribbon path from sampled tentacle points.
+ *
+ * @param context Canvas 2D context.
+ * @param ribbonPoints Sampled ribbon points.
+ *
+ * @private helper of `octopus3AvatarVisual`
+ */
+function traceTentacleRibbonPath(context, ribbonPoints) {
+    const firstRibbonPoint = ribbonPoints[0];
+    context.beginPath();
+    context.moveTo(firstRibbonPoint.x + firstRibbonPoint.normalX * firstRibbonPoint.width, firstRibbonPoint.y + firstRibbonPoint.normalY * firstRibbonPoint.width);
+    for (const ribbonPoint of ribbonPoints.slice(1)) {
+        context.lineTo(ribbonPoint.x + ribbonPoint.normalX * ribbonPoint.width, ribbonPoint.y + ribbonPoint.normalY * ribbonPoint.width);
+    }
+    for (const ribbonPoint of [...ribbonPoints].reverse()) {
+        context.lineTo(ribbonPoint.x - ribbonPoint.normalX * ribbonPoint.width, ribbonPoint.y - ribbonPoint.normalY * ribbonPoint.width);
+    }
+    context.closePath();
+}
+/**
+ * Draws a row of soft sucker highlights along one side of the ribbon tentacle.
+ *
+ * @param context Canvas 2D context.
+ * @param tentacleShape Deterministic tentacle descriptor.
+ * @param palette Derived avatar palette.
+ *
+ * @private helper of `octopus3AvatarVisual`
+ */
+function drawTentacleSuckers(context, tentacleShape, palette) {
+    const undersideDirection = tentacleShape.endPoint.x >= tentacleShape.startPoint.x ? -1 : 1;
+    for (let suckerIndex = 0; suckerIndex < 4; suckerIndex++) {
+        const progress = 0.22 + suckerIndex * 0.17;
+        const point = getCubicBezierPoint(tentacleShape.startPoint, tentacleShape.controlPointOne, tentacleShape.controlPointTwo, tentacleShape.endPoint, progress);
+        const previousPoint = getCubicBezierPoint(tentacleShape.startPoint, tentacleShape.controlPointOne, tentacleShape.controlPointTwo, tentacleShape.endPoint, Math.max(0, progress - 0.03));
+        const nextPoint = getCubicBezierPoint(tentacleShape.startPoint, tentacleShape.controlPointOne, tentacleShape.controlPointTwo, tentacleShape.endPoint, Math.min(1, progress + 0.03));
+        const tangentX = nextPoint.x - previousPoint.x;
+        const tangentY = nextPoint.y - previousPoint.y;
+        const tangentLength = Math.hypot(tangentX, tangentY) || 1;
+        const normalX = (-tangentY / tangentLength) * undersideDirection;
+        const normalY = (tangentX / tangentLength) * undersideDirection;
+        const width = tentacleShape.baseWidth + (tentacleShape.tipWidth - tentacleShape.baseWidth) * Math.pow(progress, 1.1);
+        const suckerX = point.x + normalX * width * 0.52;
+        const suckerY = point.y + normalY * width * 0.52;
+        const rotation = Math.atan2(normalY, normalX);
+        context.beginPath();
+        context.ellipse(suckerX, suckerY, width * 0.22, width * 0.11, rotation, 0, Math.PI * 2);
+        context.fillStyle = `${palette.highlight}73`;
+        context.fill();
+        context.strokeStyle = `${palette.highlight}99`;
+        context.lineWidth = Math.max(1, width * 0.08);
+        context.stroke();
+    }
+}
+/**
+ * Draws slow inner currents inside the clipped Octopus3 mantle.
+ *
+ * @param context Canvas 2D context.
+ * @param centerX Body center X coordinate.
+ * @param centerY Body center Y coordinate.
+ * @param size Canvas size in CSS pixels.
+ * @param palette Derived avatar palette.
+ * @param timeMs Current animation time in milliseconds.
+ * @param shapePhase Seed-based phase offset.
+ * @param morphologyProfile Seeded morphology profile.
+ *
+ * @private helper of `octopus3AvatarVisual`
+ */
+function drawMantleCurrents(context, centerX, centerY, size, palette, timeMs, shapePhase, morphologyProfile) {
+    const centeredCurrentIndex = (morphologyProfile.details.mantleCurrentCount - 1) / 2;
+    for (let currentIndex = 0; currentIndex < morphologyProfile.details.mantleCurrentCount; currentIndex++) {
+        const horizontalOffset = (currentIndex - centeredCurrentIndex) *
+            size *
+            (0.05 + (morphologyProfile.body.horizontalStretch - 0.9) * 0.025);
+        const sway = Math.sin(timeMs / 680 + currentIndex * 0.78 + shapePhase) * size * 0.024;
+        context.beginPath();
+        context.moveTo(centerX + horizontalOffset * 0.3, centerY - size * (0.11 + morphologyProfile.body.verticalStretch * 0.02));
+        context.bezierCurveTo(centerX + horizontalOffset - sway * 0.25, centerY - size * 0.04, centerX + horizontalOffset + sway, centerY + size * 0.06, centerX + horizontalOffset * 0.7 + sway * 0.46, centerY + size * (0.16 + morphologyProfile.body.verticalStretch * 0.035));
+        context.strokeStyle = currentIndex % 2 === 0 ? `${palette.highlight}30` : `${palette.accent}26`;
+        context.lineWidth =
+            size * (0.0075 + currentIndex * 0.00065 + morphologyProfile.tentacles.baseWidthScale * 0.0005);
+        context.lineCap = 'round';
+        context.stroke();
+    }
+}
+/**
+ * Draws seeded luminous nodes inside the Octopus3 mantle.
+ *
+ * @param context Canvas 2D context.
+ * @param centerX Body center X coordinate.
+ * @param centerY Body center Y coordinate.
+ * @param size Canvas size in CSS pixels.
+ * @param palette Derived avatar palette.
+ * @param createRandom Seeded random factory scoped to the avatar.
+ * @param morphologyProfile Seeded morphology profile.
+ *
+ * @private helper of `octopus3AvatarVisual`
+ */
+function drawMantleNodes(context, centerX, centerY, size, palette, createRandom, morphologyProfile) {
+    for (let nodeIndex = 0; nodeIndex < morphologyProfile.details.mantleNodeCount; nodeIndex++) {
+        const nodeRandom = createRandom(`octopus3-node-${nodeIndex}`);
+        const nodeX = centerX + (nodeRandom() - 0.5) * size * (0.2 + (morphologyProfile.body.horizontalStretch - 0.9) * 0.16);
+        const nodeY = centerY -
+            size * 0.03 +
+            (nodeRandom() - 0.5) * size * (0.16 + (morphologyProfile.body.verticalStretch - 0.82) * 0.1);
+        const nodeRadius = size * (0.016 + nodeRandom() * 0.016);
+        context.beginPath();
+        context.arc(nodeX, nodeY, nodeRadius, 0, Math.PI * 2);
+        context.fillStyle = nodeIndex % 2 === 0 ? `${palette.highlight}40` : `${palette.accent}33`;
+        context.fill();
+    }
+}
+/**
+ * Draws one expressive seeded eye with a slit pupil and slightly tilted eyelids.
+ *
+ * @param context Canvas 2D context.
+ * @param centerX Eye center X coordinate.
+ * @param centerY Eye center Y coordinate.
+ * @param radiusX Eye horizontal radius.
+ * @param radiusY Eye vertical radius.
+ * @param rotation Eye rotation in radians.
+ * @param palette Derived avatar palette.
+ * @param timeMs Current animation time in milliseconds.
+ * @param phase Seed-based animation phase.
+ * @param interaction Smoothed avatar interaction state.
+ * @param eyeStyle Seeded eye-style traits.
+ *
+ * @private helper of `octopus3AvatarVisual`
+ */
+function drawSeededEye(context, centerX, centerY, radiusX, radiusY, rotation, palette, timeMs, phase, interaction, eyeStyle) {
+    const { pupilOffsetX, pupilOffsetY } = resolveOrganicEyeMotion({
+        radiusX,
+        radiusY,
+        timeMs,
+        phase,
+        interaction,
+    });
+    context.save();
+    context.translate(centerX, centerY);
+    context.rotate(rotation);
+    context.beginPath();
+    context.ellipse(0, 0, radiusX, radiusY, 0, 0, Math.PI * 2);
+    context.fillStyle = '#f8fbff';
+    context.fill();
+    context.clip();
+    const irisGradient = context.createRadialGradient(-radiusX * 0.18, -radiusY * 0.24, radiusX * 0.05, 0, 0, radiusX * 0.92);
+    irisGradient.addColorStop(0, palette.highlight);
+    irisGradient.addColorStop(0.58, palette.secondary);
+    irisGradient.addColorStop(1, palette.shadow);
+    context.beginPath();
+    context.ellipse(pupilOffsetX, pupilOffsetY, radiusX * 0.66 * eyeStyle.irisScale, radiusY * 0.74 * eyeStyle.irisScale, 0, 0, Math.PI * 2);
+    context.fillStyle = irisGradient;
+    context.fill();
+    context.beginPath();
+    context.ellipse(pupilOffsetX, pupilOffsetY, radiusX * 0.14 * eyeStyle.pupilWidthScale, radiusY * 0.5 * eyeStyle.pupilHeightScale, 0, 0, Math.PI * 2);
+    context.fillStyle = palette.ink;
+    context.fill();
+    context.beginPath();
+    context.ellipse(pupilOffsetX - radiusX * 0.22, pupilOffsetY - radiusY * 0.24, radiusX * 0.12, radiusY * 0.14, 0, 0, Math.PI * 2);
+    context.fillStyle = '#ffffff';
+    context.fill();
+    context.restore();
+    context.save();
+    context.translate(centerX, centerY);
+    context.rotate(rotation);
+    context.beginPath();
+    context.ellipse(0, 0, radiusX, radiusY, 0, 0, Math.PI * 2);
+    context.strokeStyle = `${palette.shadow}d9`;
+    context.lineWidth = radiusX * 0.18;
+    context.stroke();
+    context.beginPath();
+    context.moveTo(-radiusX * 0.88, -radiusY * eyeStyle.upperLidInsetRatio);
+    context.quadraticCurveTo(0, -radiusY * (eyeStyle.upperLidArchRatio - interaction.gazeY * 0.16 + interaction.intensity * 0.08), radiusX * 0.88, -radiusY * eyeStyle.upperLidInsetRatio);
+    context.strokeStyle = `${palette.shadow}73`;
+    context.lineWidth = radiusX * 0.16;
+    context.lineCap = 'round';
+    context.stroke();
+    if (eyeStyle.lowerLidOpacity > 0) {
+        context.beginPath();
+        context.moveTo(-radiusX * 0.74, radiusY * 0.2);
+        context.quadraticCurveTo(0, radiusY * 0.38, radiusX * 0.74, radiusY * 0.2);
+        context.strokeStyle = `${palette.highlight}${formatAlphaHex(eyeStyle.lowerLidOpacity)}`;
+        context.lineWidth = radiusX * 0.08;
+        context.lineCap = 'round';
+        context.stroke();
+    }
+    context.restore();
+}
+
+/* eslint-disable no-magic-numbers */
+/**
+ * Family variants used by the orb renderer.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+const ORB_FAMILIES = ['pearl', 'nebula', 'ember', 'glacier'];
+/**
+ * Built-in Orb avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+const orbAvatarVisual = {
+    id: 'orb',
+    title: 'Orb',
+    description: 'Glowing morphing circle-orb with seeded gradients, smooth deformations, and luminous layered depth.',
+    isAnimated: true,
+    render({ context, size, palette, createRandom, timeMs }) {
+        const profile = createOrbMorphologyProfile(createRandom);
+        const colorSet = resolveOrbColorSet(palette, profile.family);
+        const centerX = size * 0.5 + profile.coreShiftX * size * 0.06 + Math.sin(timeMs / 2600) * size * 0.009;
+        const centerY = size * 0.5 +
+            profile.coreShiftY * size * 0.06 +
+            Math.cos(timeMs / 3100 + profile.highlightAngle) * size * 0.01;
+        const radius = size * profile.baseRadiusRatio;
+        const silhouettePoints = createOrbSilhouettePoints({
+            centerX,
+            centerY,
+            radius,
+            profile,
+            timeMs,
+        });
+        drawAvatarFrame(context, size, palette);
+        drawOrbAtmosphere(context, size, centerX, centerY, radius, colorSet, profile, timeMs);
+        drawOrbBody(context, silhouettePoints, centerX, centerY, radius, colorSet, profile, size);
+        context.save();
+        traceSmoothClosedPath(context, silhouettePoints);
+        context.clip();
+        drawOrbInteriorRings(context, centerX, centerY, radius, colorSet, profile, size, timeMs);
+        drawOrbSparkles(context, centerX, centerY, radius, colorSet, profile, size, createRandom, timeMs);
+        drawOrbSheen(context, centerX, centerY, radius, colorSet, profile, size, timeMs);
+        drawOrbCore(context, centerX, centerY, radius, colorSet, profile, size, timeMs);
+        context.restore();
+        drawOrbRim(context, silhouettePoints, colorSet, size);
+    },
+};
+/**
+ * Builds the deterministic orb profile from the seeded avatar random factory.
+ *
+ * @param createRandom Seeded random factory.
+ * @returns Stable orb morphology profile.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+function createOrbMorphologyProfile(createRandom) {
+    const family = pickRandomItem(ORB_FAMILIES, createRandom('orb-family'));
+    const familyAdjustment = resolveOrbFamilyAdjustment(family);
+    const layoutRandom = createRandom('orb-layout');
+    const effectRandom = createRandom('orb-effects');
+    return {
+        family,
+        baseRadiusRatio: clampNumber(0.255 + layoutRandom() * 0.055 + familyAdjustment.baseRadiusRatio, 0.22, 0.335),
+        horizontalStretch: clampNumber(0.93 + layoutRandom() * 0.13 + familyAdjustment.horizontalStretch, 0.88, 1.16),
+        verticalStretch: clampNumber(0.91 + layoutRandom() * 0.13 + familyAdjustment.verticalStretch, 0.88, 1.15),
+        wobbleAmplitude: clampNumber(0.038 + effectRandom() * 0.042 + familyAdjustment.wobbleAmplitude, 0.022, 0.12),
+        wobbleFrequencyOne: clampInteger(2 + Math.floor(effectRandom() * 3) + familyAdjustment.wobbleFrequency, 2, 7),
+        wobbleFrequencyTwo: clampInteger(3 + Math.floor(layoutRandom() * 3) + familyAdjustment.wobbleFrequency, 3, 8),
+        wobbleFrequencyThree: clampInteger(5 + Math.floor(effectRandom() * 3) + familyAdjustment.wobbleFrequency, 4, 9),
+        ringCount: clampInteger(2 + Math.floor(effectRandom() * 3) + familyAdjustment.ringCount, 2, 5),
+        sparkleCount: clampInteger(6 + Math.floor(effectRandom() * 7) + familyAdjustment.sparkleCount, 4, 16),
+        haloCount: clampInteger(2 + Math.floor(layoutRandom() * 2) + familyAdjustment.haloCount, 1, 4),
+        coreShiftX: (layoutRandom() - 0.5) * 0.08,
+        coreShiftY: (effectRandom() - 0.5) * 0.08,
+        highlightAngle: layoutRandom() * Math.PI * 2,
+        bandRotation: effectRandom() * Math.PI * 2,
+        pulseSpeed: 0.82 + effectRandom() * 0.72,
+        haloBlurRatio: clampNumber(0.18 + layoutRandom() * 0.12 + familyAdjustment.haloBlurRatio, 0.16, 0.34),
+        sheenStrength: clampNumber(0.46 + effectRandom() * 0.28 + familyAdjustment.sheenStrength, 0.38, 0.88),
+    };
+}
+/**
+ * Resolves the family-specific adjustments that keep the orb surface varied while still circular.
+ *
+ * @param family Selected orb family.
+ * @returns Family-specific profile adjustments.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+function resolveOrbFamilyAdjustment(family) {
+    switch (family) {
+        case 'nebula':
+            return {
+                baseRadiusRatio: 0.006,
+                horizontalStretch: 0.05,
+                verticalStretch: -0.01,
+                wobbleAmplitude: 0.012,
+                wobbleFrequency: 1,
+                ringCount: 1,
+                sparkleCount: 2,
+                haloCount: 0,
+                haloBlurRatio: 0.02,
+                sheenStrength: 0.08,
+            };
+        case 'ember':
+            return {
+                baseRadiusRatio: -0.004,
+                horizontalStretch: -0.03,
+                verticalStretch: 0.03,
+                wobbleAmplitude: 0.02,
+                wobbleFrequency: 1,
+                ringCount: 0,
+                sparkleCount: 3,
+                haloCount: 0,
+                haloBlurRatio: 0.04,
+                sheenStrength: 0.06,
+            };
+        case 'glacier':
+            return {
+                baseRadiusRatio: 0.012,
+                horizontalStretch: 0.01,
+                verticalStretch: 0.02,
+                wobbleAmplitude: -0.006,
+                wobbleFrequency: -1,
+                ringCount: 0,
+                sparkleCount: 0,
+                haloCount: 0,
+                haloBlurRatio: -0.01,
+                sheenStrength: 0.12,
+            };
+        case 'pearl':
+        default:
+            return {
+                baseRadiusRatio: 0.02,
+                horizontalStretch: 0.025,
+                verticalStretch: 0.02,
+                wobbleAmplitude: -0.01,
+                wobbleFrequency: 0,
+                ringCount: 0,
+                sparkleCount: -1,
+                haloCount: 1,
+                haloBlurRatio: 0.02,
+                sheenStrength: 0.1,
+            };
+    }
+}
+/**
+ * Resolves the color set used by the orb renderer.
+ *
+ * @param palette Base avatar palette.
+ * @param family Selected orb family.
+ * @returns Derived orb-specific color set.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+function resolveOrbColorSet(palette, family) {
+    const primaryColor = Color.fromSafe(palette.primary);
+    const secondaryColor = Color.fromSafe(palette.secondary);
+    const accentColor = Color.fromSafe(palette.accent);
+    const highlightColor = Color.fromSafe(palette.highlight);
+    const shadowColor = Color.fromSafe(palette.shadow);
+    switch (family) {
+        case 'nebula':
+            return {
+                core: accentColor.then(lighten(0.16)).then(saturate(0.14)).toHex(),
+                mid: secondaryColor.then(lighten(0.08)).then(saturate(0.08)).toHex(),
+                outer: primaryColor.then(darken(0.03)).then(saturate(0.04)).toHex(),
+                rim: shadowColor.then(lighten(0.08)).toHex(),
+                highlight: highlightColor.then(lighten(0.14)).toHex(),
+                aura: secondaryColor.then(lighten(0.18)).toHex(),
+            };
+        case 'ember':
+            return {
+                core: accentColor.then(lighten(0.2)).then(saturate(0.16)).toHex(),
+                mid: primaryColor.then(lighten(0.1)).then(saturate(0.08)).toHex(),
+                outer: secondaryColor.then(darken(0.04)).then(saturate(0.04)).toHex(),
+                rim: shadowColor.then(lighten(0.08)).toHex(),
+                highlight: highlightColor.then(lighten(0.18)).toHex(),
+                aura: accentColor.then(lighten(0.12)).toHex(),
+            };
+        case 'glacier':
+            return {
+                core: highlightColor.then(lighten(0.18)).then(saturate(-0.04)).toHex(),
+                mid: secondaryColor.then(lighten(0.1)).then(saturate(-0.06)).toHex(),
+                outer: primaryColor.then(lighten(0.06)).toHex(),
+                rim: shadowColor.then(lighten(0.12)).toHex(),
+                highlight: highlightColor.then(lighten(0.26)).toHex(),
+                aura: primaryColor.then(lighten(0.18)).toHex(),
+            };
+        case 'pearl':
+        default:
+            return {
+                core: highlightColor.then(lighten(0.2)).then(saturate(-0.06)).toHex(),
+                mid: primaryColor.then(lighten(0.12)).then(saturate(-0.02)).toHex(),
+                outer: secondaryColor.then(lighten(0.08)).then(saturate(-0.04)).toHex(),
+                rim: shadowColor.then(lighten(0.12)).toHex(),
+                highlight: highlightColor.then(lighten(0.3)).toHex(),
+                aura: highlightColor.then(lighten(0.18)).toHex(),
+            };
+    }
+}
+/**
+ * Creates the orb silhouette points from the deterministic profile.
+ *
+ * @param options Orb geometry options.
+ * @returns Smoothly varying orb outline.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+function createOrbSilhouettePoints(options) {
+    const { centerX, centerY, radius, profile, timeMs } = options;
+    const pointCount = 48;
+    return Array.from({ length: pointCount }, (_, pointIndex) => {
+        const progress = pointIndex / pointCount;
+        const angle = -Math.PI / 2 + progress * Math.PI * 2;
+        const breathing = Math.sin(timeMs / (1450 / profile.pulseSpeed) + profile.bandRotation) * profile.wobbleAmplitude;
+        const surfaceWaveOne = Math.sin(angle * profile.wobbleFrequencyOne + profile.highlightAngle + timeMs / (980 / profile.pulseSpeed)) * profile.wobbleAmplitude;
+        const surfaceWaveTwo = Math.cos(angle * profile.wobbleFrequencyTwo - profile.bandRotation * 0.8 + timeMs / (1320 / profile.pulseSpeed)) *
+            profile.wobbleAmplitude *
+            0.62;
+        const surfaceWaveThree = Math.sin(angle * profile.wobbleFrequencyThree +
+            profile.highlightAngle * 1.4 -
+            timeMs / (1710 / profile.pulseSpeed)) *
+            profile.wobbleAmplitude *
+            0.38;
+        const surfaceTaper = Math.sin(angle * 2 + profile.highlightAngle) * profile.wobbleAmplitude * 0.2;
+        const localRadius = radius * (1 + breathing * 0.12 + surfaceWaveOne + surfaceWaveTwo + surfaceWaveThree + surfaceTaper);
+        return {
+            x: centerX +
+                Math.cos(angle) * localRadius * profile.horizontalStretch +
+                Math.sin(angle * 3 + profile.highlightAngle + timeMs / 2100) * radius * 0.012,
+            y: centerY +
+                Math.sin(angle) * localRadius * profile.verticalStretch +
+                Math.cos(angle * 2 - profile.highlightAngle + timeMs / 2400) * radius * 0.01,
+        };
+    });
+}
+/**
+ * Draws the atmospheric glow behind the orb.
+ *
+ * @param context Canvas 2D context.
+ * @param size Canvas size in CSS pixels.
+ * @param centerX Orb center X coordinate.
+ * @param centerY Orb center Y coordinate.
+ * @param radius Orb base radius.
+ * @param colorSet Derived orb color set.
+ * @param profile Deterministic orb profile.
+ * @param timeMs Current animation time in milliseconds.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+function drawOrbAtmosphere(context, size, centerX, centerY, radius, colorSet, profile, timeMs) {
+    const atmosphereGradient = context.createRadialGradient(centerX, centerY, radius * 0.08, centerX, centerY, radius * (1.9 + profile.haloBlurRatio));
+    atmosphereGradient.addColorStop(0, `${colorSet.highlight}26`);
+    atmosphereGradient.addColorStop(0.32, `${colorSet.aura}16`);
+    atmosphereGradient.addColorStop(1, `${colorSet.aura}00`);
+    context.save();
+    context.globalCompositeOperation = 'screen';
+    context.fillStyle = atmosphereGradient;
+    context.fillRect(0, 0, size, size);
+    for (let haloIndex = 0; haloIndex < profile.haloCount; haloIndex++) {
+        const haloPulse = Math.sin(timeMs / (1200 + haloIndex * 180) + profile.highlightAngle) * radius * 0.025;
+        const haloRadiusX = radius * (1.18 + haloIndex * 0.18) + haloPulse;
+        const haloRadiusY = radius * (0.98 + haloIndex * 0.16) + haloPulse * 0.82;
+        const haloGradient = context.createRadialGradient(centerX, centerY, radius * 0.12, centerX, centerY, haloRadiusX * 1.12);
+        haloGradient.addColorStop(0, `${colorSet.aura}${haloIndex === 0 ? '38' : '24'}`);
+        haloGradient.addColorStop(0.5, `${colorSet.highlight}${haloIndex === 0 ? '1f' : '12'}`);
+        haloGradient.addColorStop(1, `${colorSet.aura}00`);
+        context.beginPath();
+        context.ellipse(centerX, centerY, haloRadiusX, haloRadiusY, profile.highlightAngle * 0.12 + haloIndex * 0.2 + Math.sin(timeMs / 3800) * 0.04, 0, Math.PI * 2);
+        context.fillStyle = haloGradient;
+        context.fill();
+    }
+    context.restore();
+}
+/**
+ * Draws the main orb body using the smooth silhouette path.
+ *
+ * @param context Canvas 2D context.
+ * @param points Smooth orb outline points.
+ * @param centerX Orb center X coordinate.
+ * @param centerY Orb center Y coordinate.
+ * @param radius Orb base radius.
+ * @param colorSet Derived orb color set.
+ * @param profile Deterministic orb profile.
+ * @param size Canvas size in CSS pixels.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+function drawOrbBody(context, points, centerX, centerY, radius, colorSet, profile, size) {
+    const bodyGradient = context.createRadialGradient(centerX - radius * 0.22, centerY - radius * 0.24, radius * 0.05, centerX + radius * 0.02, centerY + radius * 0.1, radius * (1.14 + profile.haloBlurRatio * 0.3));
+    bodyGradient.addColorStop(0, `${colorSet.highlight}f8`);
+    bodyGradient.addColorStop(0.22, `${colorSet.core}f2`);
+    bodyGradient.addColorStop(0.58, `${colorSet.mid}e8`);
+    bodyGradient.addColorStop(0.86, `${colorSet.outer}dc`);
+    bodyGradient.addColorStop(1, `${colorSet.rim}ea`);
+    context.save();
+    traceSmoothClosedPath(context, points);
+    context.shadowColor = `${colorSet.rim}aa`;
+    context.shadowBlur = size * (0.06 + profile.haloBlurRatio * 0.15);
+    context.fillStyle = bodyGradient;
+    context.fill();
+    context.restore();
+    context.save();
+    traceSmoothClosedPath(context, points);
+    context.strokeStyle = `${colorSet.highlight}${profile.family === 'pearl' ? '72' : '58'}`;
+    context.lineWidth = Math.max(1.2, size * 0.012);
+    context.lineJoin = 'round';
+    context.lineCap = 'round';
+    context.stroke();
+    context.restore();
+}
+/**
+ * Draws the layered energy rings and soft internal gradients inside the orb.
+ *
+ * @param context Canvas 2D context.
+ * @param centerX Orb center X coordinate.
+ * @param centerY Orb center Y coordinate.
+ * @param radius Orb base radius.
+ * @param colorSet Derived orb color set.
+ * @param profile Deterministic orb profile.
+ * @param size Canvas size in CSS pixels.
+ * @param timeMs Current animation time in milliseconds.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+function drawOrbInteriorRings(context, centerX, centerY, radius, colorSet, profile, size, timeMs) {
+    const internalGradient = context.createRadialGradient(centerX - radius * 0.08, centerY - radius * 0.1, radius * 0.06, centerX, centerY, radius * (0.95 + profile.sheenStrength * 0.15));
+    internalGradient.addColorStop(0, `${colorSet.highlight}70`);
+    internalGradient.addColorStop(0.48, `${colorSet.core}22`);
+    internalGradient.addColorStop(1, `${colorSet.rim}00`);
+    context.fillStyle = internalGradient;
+    context.fillRect(centerX - radius, centerY - radius, radius * 2, radius * 2);
+    for (let ringIndex = 0; ringIndex < profile.ringCount; ringIndex++) {
+        const ringProgress = (ringIndex + 1) / (profile.ringCount + 1);
+        const ringRadiusX = radius * (0.34 + ringProgress * 0.44);
+        const ringRadiusY = radius * (0.28 + ringProgress * 0.38);
+        const ringRotation = profile.highlightAngle * 0.24 +
+            ringIndex * 0.4 +
+            Math.sin(timeMs / (1800 + ringIndex * 180) + profile.bandRotation) * 0.08;
+        context.beginPath();
+        context.ellipse(centerX + Math.cos(profile.highlightAngle) * radius * 0.03, centerY + Math.sin(profile.highlightAngle) * radius * 0.02, ringRadiusX, ringRadiusY, ringRotation, 0, Math.PI * 2);
+        context.strokeStyle = ringIndex % 2 === 0 ? `${colorSet.highlight}32` : `${colorSet.aura}24`;
+        context.lineWidth = Math.max(1.2, size * (0.007 - ringIndex * 0.001));
+        context.shadowColor = `${colorSet.highlight}55`;
+        context.shadowBlur = size * 0.02;
+        context.stroke();
+    }
+}
+/**
+ * Draws soft sparkles and seeded dust inside the orb.
+ *
+ * @param context Canvas 2D context.
+ * @param centerX Orb center X coordinate.
+ * @param centerY Orb center Y coordinate.
+ * @param radius Orb base radius.
+ * @param colorSet Derived orb color set.
+ * @param profile Deterministic orb profile.
+ * @param size Canvas size in CSS pixels.
+ * @param createRandom Seeded random factory.
+ * @param timeMs Current animation time in milliseconds.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+function drawOrbSparkles(context, centerX, centerY, radius, colorSet, profile, size, createRandom, timeMs) {
+    const sparkleStride = Math.max(1, Math.floor(profile.sparkleCount / 6));
+    for (let sparkleIndex = 0; sparkleIndex < profile.sparkleCount; sparkleIndex++) {
+        const sparkleRandom = createRandom(`orb-sparkle-${sparkleIndex}`);
+        const sparkleAngle = sparkleRandom() * Math.PI * 2 + profile.highlightAngle * 0.4;
+        const sparkleOrbitRadius = radius * (0.42 + sparkleRandom() * 0.55);
+        const sparkleOrbitPulse = 0.92 + Math.sin(timeMs / (700 + sparkleIndex * 70) + profile.bandRotation) * 0.08;
+        const sparkleCenterX = centerX + Math.cos(sparkleAngle + timeMs / (4600 / profile.pulseSpeed)) * sparkleOrbitRadius;
+        const sparkleCenterY = centerY + Math.sin(sparkleAngle + timeMs / (4600 / profile.pulseSpeed)) * sparkleOrbitRadius;
+        const sparkleRadius = size * (0.0028 + sparkleRandom() * 0.0058) * sparkleOrbitPulse;
+        context.beginPath();
+        context.arc(sparkleCenterX, sparkleCenterY, sparkleRadius * 2, 0, Math.PI * 2);
+        context.fillStyle = `${colorSet.highlight}14`;
+        context.fill();
+        context.beginPath();
+        context.arc(sparkleCenterX, sparkleCenterY, sparkleRadius, 0, Math.PI * 2);
+        context.fillStyle = sparkleIndex % sparkleStride === 0 ? `${colorSet.highlight}d2` : `${colorSet.aura}c8`;
+        context.shadowColor = `${colorSet.highlight}66`;
+        context.shadowBlur = size * 0.012;
+        context.fill();
+    }
+}
+/**
+ * Draws the specular sweep that makes the orb feel glossy and dimensional.
+ *
+ * @param context Canvas 2D context.
+ * @param centerX Orb center X coordinate.
+ * @param centerY Orb center Y coordinate.
+ * @param radius Orb base radius.
+ * @param colorSet Derived orb color set.
+ * @param profile Deterministic orb profile.
+ * @param size Canvas size in CSS pixels.
+ * @param timeMs Current animation time in milliseconds.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+function drawOrbSheen(context, centerX, centerY, radius, colorSet, profile, size, timeMs) {
+    const sheenAngle = profile.bandRotation + timeMs / (2400 / profile.pulseSpeed);
+    const sheenDirectionX = Math.cos(sheenAngle);
+    const sheenDirectionY = Math.sin(sheenAngle);
+    const sheenGradient = context.createLinearGradient(centerX - sheenDirectionX * radius, centerY - sheenDirectionY * radius, centerX + sheenDirectionX * radius, centerY + sheenDirectionY * radius);
+    sheenGradient.addColorStop(0, `${colorSet.highlight}00`);
+    sheenGradient.addColorStop(0.24, `${colorSet.highlight}0e`);
+    sheenGradient.addColorStop(0.43, `${colorSet.highlight}${profile.sheenStrength > 0.65 ? '66' : '48'}`);
+    sheenGradient.addColorStop(0.57, `${colorSet.core}${profile.sheenStrength > 0.65 ? '42' : '2e'}`);
+    sheenGradient.addColorStop(0.75, `${colorSet.aura}1e`);
+    sheenGradient.addColorStop(1, `${colorSet.highlight}00`);
+    context.fillStyle = sheenGradient;
+    context.fillRect(centerX - radius * 1.6, centerY - radius * 1.6, radius * 3.2, radius * 3.2);
+    context.beginPath();
+    context.ellipse(centerX - radius * 0.18, centerY - radius * 0.2, radius * 0.44, radius * 0.24, profile.highlightAngle * 0.32, 0, Math.PI * 2);
+    context.fillStyle = `${colorSet.highlight}${profile.family === 'ember' ? '26' : '2e'}`;
+    context.shadowColor = `${colorSet.highlight}55`;
+    context.shadowBlur = size * 0.02;
+    context.fill();
+}
+/**
+ * Draws the bright nucleus that gives the orb a recognisable center.
+ *
+ * @param context Canvas 2D context.
+ * @param centerX Orb center X coordinate.
+ * @param centerY Orb center Y coordinate.
+ * @param radius Orb base radius.
+ * @param colorSet Derived orb color set.
+ * @param profile Deterministic orb profile.
+ * @param size Canvas size in CSS pixels.
+ * @param timeMs Current animation time in milliseconds.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+function drawOrbCore(context, centerX, centerY, radius, colorSet, profile, size, timeMs) {
+    const coreRadiusX = radius * (0.18 + profile.sheenStrength * 0.06);
+    const coreRadiusY = radius * (0.15 + profile.sheenStrength * 0.045);
+    const corePulse = 1 + Math.sin(timeMs / (1100 / profile.pulseSpeed) + profile.bandRotation) * 0.04;
+    context.beginPath();
+    context.ellipse(centerX + profile.coreShiftX * radius * 0.18, centerY + profile.coreShiftY * radius * 0.18, coreRadiusX * corePulse, coreRadiusY * corePulse, profile.highlightAngle * 0.12, 0, Math.PI * 2);
+    context.fillStyle = `${colorSet.core}f0`;
+    context.shadowColor = `${colorSet.highlight}88`;
+    context.shadowBlur = size * 0.03;
+    context.fill();
+    context.beginPath();
+    context.arc(centerX - radius * 0.06, centerY - radius * 0.07, radius * 0.06, 0, Math.PI * 2);
+    context.fillStyle = `${colorSet.highlight}d6`;
+    context.fill();
+}
+/**
+ * Draws the final rim stroke so the orb stays crisp against busy backgrounds.
+ *
+ * @param context Canvas 2D context.
+ * @param points Smooth orb outline points.
+ * @param colorSet Derived orb color set.
+ * @param size Canvas size in CSS pixels.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+function drawOrbRim(context, points, colorSet, size) {
+    context.save();
+    traceSmoothClosedPath(context, points);
+    context.strokeStyle = `${colorSet.rim}c0`;
+    context.lineWidth = Math.max(1.25, size * 0.013);
+    context.lineJoin = 'round';
+    context.lineCap = 'round';
+    context.shadowColor = `${colorSet.highlight}4f`;
+    context.shadowBlur = size * 0.018;
+    context.stroke();
+    context.restore();
+}
+/**
+ * Clamps a number into the provided range.
+ *
+ * @param value Number to clamp.
+ * @param minimum Minimum accepted value.
+ * @param maximum Maximum accepted value.
+ * @returns Clamped number.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+function clampNumber(value, minimum, maximum) {
+    return Math.min(maximum, Math.max(minimum, value));
+}
+/**
+ * Clamps a number into the provided integer range.
+ *
+ * @param value Number to clamp.
+ * @param minimum Minimum accepted value.
+ * @param maximum Maximum accepted value.
+ * @returns Clamped integer.
+ *
+ * @private helper of `orbAvatarVisual`
+ */
+function clampInteger(value, minimum, maximum) {
+    return Math.min(maximum, Math.max(minimum, Math.round(value)));
+}
+
+/* eslint-disable no-magic-numbers */
+/**
+ * Pixel-art avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+const pixelArtAvatarVisual = {
+    id: 'pixel-art',
+    title: 'Pixel art',
+    description: 'Symmetric retro badge with a deterministic face and palette-driven pixels.',
+    isAnimated: false,
+    render({ context, size, palette, createRandom, avatarDefinition }) {
+        const random = createRandom('pixel-art');
+        const panelSize = size * 0.62;
+        const panelX = (size - panelSize) / 2;
+        const panelY = size * 0.19;
+        const pixelGridSize = 10;
+        const pixelSize = panelSize / pixelGridSize;
+        const halfColumns = Math.ceil(pixelGridSize / 2);
+        const colorStops = [palette.primary, palette.secondary, palette.accent, palette.highlight];
+        const foreheadRowCount = 2 + Math.floor(random() * 2);
+        const cheekInset = 1 + Math.floor(random() * 2);
+        const emblemHeight = 2 + Math.floor(random() * 2);
+        drawAvatarFrame(context, size, palette);
+        const glow = context.createRadialGradient(size * 0.5, size * 0.32, size * 0.05, size * 0.5, size * 0.32, size * 0.5);
+        glow.addColorStop(0, `${palette.highlight}aa`);
+        glow.addColorStop(1, `${palette.highlight}00`);
+        context.fillStyle = glow;
+        context.fillRect(0, 0, size, size);
+        context.save();
+        createRoundedRectPath(context, panelX, panelY, panelSize, panelSize, panelSize * 0.16);
+        context.fillStyle = palette.shadow;
+        context.shadowColor = `${palette.shadow}66`;
+        context.shadowBlur = size * 0.08;
+        context.fill();
+        context.restore();
+        for (let rowIndex = 0; rowIndex < pixelGridSize; rowIndex++) {
+            for (let columnIndex = 0; columnIndex < halfColumns; columnIndex++) {
+                const mirroredColumnIndex = pixelGridSize - columnIndex - 1;
+                const normalizedRowDistance = Math.abs(rowIndex - pixelGridSize / 2) / (pixelGridSize / 2);
+                const normalizedColumnDistance = columnIndex / halfColumns;
+                const fillChance = 0.85 - normalizedRowDistance * 0.32 - normalizedColumnDistance * 0.08;
+                if (random() > fillChance) {
+                    continue;
+                }
+                const color = colorStops[Math.min(colorStops.length - 1, Math.floor(random() *
+                    (rowIndex < foreheadRowCount
+                        ? 2
+                        : rowIndex > pixelGridSize - emblemHeight - 1
+                            ? colorStops.length
+                            : 3)))];
+                if (columnIndex === 0 &&
+                    rowIndex >= cheekInset &&
+                    rowIndex <= pixelGridSize - cheekInset - 1 &&
+                    random() < 0.4) {
+                    continue;
+                }
+                drawPixel(context, panelX + columnIndex * pixelSize, panelY + rowIndex * pixelSize, pixelSize, color);
+                if (mirroredColumnIndex !== columnIndex) {
+                    drawPixel(context, panelX + mirroredColumnIndex * pixelSize, panelY + rowIndex * pixelSize, pixelSize, color);
+                }
+            }
+        }
+        const eyeRowIndex = 3 + Math.floor(random() * 2);
+        const eyeColumnOffset = 2 + Math.floor(random() * 2);
+        drawPixel(context, panelX + eyeColumnOffset * pixelSize, panelY + eyeRowIndex * pixelSize, pixelSize, palette.ink);
+        drawPixel(context, panelX + (pixelGridSize - eyeColumnOffset - 1) * pixelSize, panelY + eyeRowIndex * pixelSize, pixelSize, palette.ink);
+        drawPixel(context, panelX + eyeColumnOffset * pixelSize, panelY + eyeRowIndex * pixelSize, pixelSize * 0.44, '#ffffff');
+        drawPixel(context, panelX + (pixelGridSize - eyeColumnOffset - 1) * pixelSize, panelY + eyeRowIndex * pixelSize, pixelSize * 0.44, '#ffffff');
+        const mouthRowIndex = eyeRowIndex + 3;
+        const mouthWidth = 2 + Math.floor(random() * 2);
+        for (let mouthOffset = 0; mouthOffset < mouthWidth; mouthOffset++) {
+            drawPixel(context, panelX + (4 + mouthOffset) * pixelSize, panelY + mouthRowIndex * pixelSize, pixelSize, palette.shadow);
+        }
+        context.save();
+        context.fillStyle = `${palette.highlight}44`;
+        context.font = `${Math.round(size * 0.12)}px sans-serif`;
+        context.textAlign = 'center';
+        context.fillText(avatarDefinition.agentName.charAt(0).toUpperCase(), size * 0.5, size * 0.88);
+        context.restore();
+    },
+};
+/**
+ * Draws one pixel-art block with a tiny inner highlight.
+ *
+ * @param context Canvas 2D context.
+ * @param x Left coordinate.
+ * @param y Top coordinate.
+ * @param size Pixel size.
+ * @param color Pixel fill color.
+ *
+ * @private helper of `pixelArtAvatarVisual`
+ */
+function drawPixel(context, x, y, size, color) {
+    const normalizedSize = size * 0.9;
+    const offset = (size - normalizedSize) / 2;
+    context.fillStyle = color;
+    context.fillRect(x + offset, y + offset, normalizedSize, normalizedSize);
+    context.fillStyle = 'rgba(255,255,255,0.18)';
+    context.fillRect(x + offset, y + offset, normalizedSize, normalizedSize * 0.14);
+}
+
+// Note: [💞] Ignore a discrepancy between file name and entity name
+/**
+ * Built-in avatar visuals available to the app.
+ *
+ * @private shared registry for the avatar rendering system
+ */
+const AVATAR_VISUALS = [
+    pixelArtAvatarVisual,
+    octopusAvatarVisual,
+    octopus2AvatarVisual,
+    octopus3AvatarVisual,
+    asciiOctopusAvatarVisual,
+    minecraftAvatarVisual,
+    fractalAvatarVisual,
+    orbAvatarVisual,
+];
+/**
+ * Normalizes user-facing avatar visual names so ids can be matched case-insensitively
+ * across spaces, hyphens, underscores, and future separator variants.
+ *
+ * @param value Raw avatar visual id or title.
+ * @returns Stable lookup key.
+ *
+ * @private shared registry for the avatar rendering system
+ */
+function normalizeAvatarVisualLookupKey(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '');
+}
+/**
+ * Resolves a user-facing avatar visual value to a supported built-in visual id.
+ *
+ * The lookup is derived from `AVATAR_VISUALS`, so new visuals become selectable by
+ * adding them to the registry rather than updating parser-specific option lists.
+ *
+ * @param value Raw visual id/title, for example `PIXEL_ART`, `pixel art`, or `pixel-art`.
+ * @returns Matching visual id or `null` when the value is empty/unknown.
+ *
+ * @private shared registry for the avatar rendering system
+ */
+function resolveAvatarVisualId(value) {
+    if (!value) {
+        return null;
+    }
+    const normalizedValue = normalizeAvatarVisualLookupKey(value);
+    if (!normalizedValue) {
+        return null;
+    }
+    const avatarVisual = AVATAR_VISUALS.find((candidateAvatarVisual) => normalizeAvatarVisualLookupKey(candidateAvatarVisual.id) === normalizedValue ||
+        normalizeAvatarVisualLookupKey(candidateAvatarVisual.title) === normalizedValue);
+    return (avatarVisual === null || avatarVisual === void 0 ? void 0 : avatarVisual.id) || null;
+}
+
+/**
+ * META AVATAR commitment definition
+ *
+ * The `META AVATAR` commitment sets the built-in default avatar visual used when
+ * the agent does not provide an explicit `META IMAGE`.
+ *
+ * @private [🪔] Maybe export the commitments through some package
+ */
+class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition {
+    constructor() {
+        super('META AVATAR');
+    }
+    /**
+     * Short one-line description of META AVATAR.
+     */
+    get description() {
+        return "Set the agent's built-in avatar visual.";
+    }
+    /**
+     * Icon for this commitment.
+     */
+    get icon() {
+        return '👤';
+    }
+    /**
+     * Markdown documentation for META AVATAR commitment.
+     */
+    get documentation() {
+        const supportedVisuals = AVATAR_VISUALS.map((avatarVisual) => `\`${avatarVisual.id}\``).join(', ');
+        return spaceTrim$1(`
+            # META AVATAR
+
+            Sets the built-in avatar visual used for the agent when no explicit \`META IMAGE\` is provided.
+
+            ## Key aspects
+
+            - Does not modify the agent's behavior or responses.
+            - Only one \`META AVATAR\` should be used per agent.
+            - If multiple are specified, the last one takes precedence.
+            - Values are matched case-insensitively and spaces, hyphens, and underscores are normalized.
+            - Supported visuals are derived from the shared avatar registry: ${supportedVisuals}.
+
+            ## Examples
+
+            \`\`\`book
+            Pixel Assistant
+
+            META AVATAR PIXEL_ART
+            GOAL Help users with concise answers.
+            \`\`\`
+
+            \`\`\`book
+            Orb Assistant
+
+            META AVATAR orb
+            GOAL Answer in a calm and focused way.
+            \`\`\`
+        `);
+    }
+    applyToAgentModelRequirements(requirements, content) {
+        // META AVATAR doesn't modify the system message or model requirements.
+        // It's handled separately in the parsing logic for profile avatar resolution.
+        return requirements;
+    }
+}
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
 /**
  * META COLOR commitment definition
  *
@@ -14695,7 +18001,13 @@ class ModelCommitmentDefinition extends BaseCommitmentDefinition {
      * Short one-line description of MODEL.
      */
     get description() {
-        return 'Enforce AI model requirements including name and technical parameters.';
+        return 'Low-level commitment for explicit model selection and technical parameters. Use carefully.';
+    }
+    /**
+     * Marks MODEL as a low-level commitment surfaced with caution.
+     */
+    get isLowLevel() {
+        return true;
     }
     /**
      * Icon for this commitment.
@@ -14710,11 +18022,17 @@ class ModelCommitmentDefinition extends BaseCommitmentDefinition {
         return spaceTrim$1(`
             # ${this.type}
 
-            Enforces technical parameters for the AI model, ensuring consistent behavior across different execution environments.
+            Low-level commitment for explicit AI model selection and technical parameters.
+
+            ## Status
+
+            - This commitment is low-level and not used by most of the users.
+            - Use it when you need to pin a specific model or fine-tune model parameters directly.
+            - Prefer automatic model selection when you do not need manual control.
 
             ## Key aspects
 
-            - When no \`MODEL\` commitment is specified, the best model requirement is picked automatically based on the agent \`PERSONA\`, \`KNOWLEDGE\`, \`TOOLS\` and other commitments
+            - When no \`MODEL\` commitment is specified, the best model requirement is picked automatically based on the agent \`PERSONA\`, \`KNOWLEDGE\`, \`TOOLS\` and other commitments.
             - Multiple \`MODEL\` commitments can be used to specify different parameters
             - Both \`MODEL\` and \`MODELS\` terms work identically and can be used interchangeably
             - Parameters control the randomness, creativity, and technical aspects of model responses
@@ -15243,6 +18561,12 @@ class RuleCommitmentDefinition extends BaseCommitmentDefinition {
     get description() {
         return 'Add behavioral rules the agent must follow.';
     }
+    /**
+     * Marks RULE as one of the priority commitments surfaced first in catalogues.
+     */
+    get isImportant() {
+        return true;
+    }
     /**
      * Icon for this commitment.
      */
@@ -15862,6 +19186,46 @@ function createTeammateLabel(url) {
 }
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * Header used for same-server TEAM calls that may access private teammate agents.
+ *
+ * @private internal Agents Server access wiring
+ */
+const TEAM_INTERNAL_AGENT_ACCESS_HEADER = 'x-promptbook-team-agent-access-token';
+/**
+ * Creates request headers for same-server TEAM calls.
+ *
+ * @param options - Target agent URL, local server URL, and resolved access token.
+ * @returns Header map when the target is same-origin; otherwise an empty map.
+ *
+ * @private internal Agents Server access wiring
+ */
+function createTeamInternalAgentAccessHeaders(options) {
+    if (!options.accessToken || !isSameOriginAgentUrl(options.agentUrl, options.localServerUrl)) {
+        return {};
+    }
+    return {
+        [TEAM_INTERNAL_AGENT_ACCESS_HEADER]: options.accessToken,
+    };
+}
+/**
+ * Checks whether a teammate URL points back to the current Agents Server origin.
+ *
+ * @private internal Agents Server access wiring
+ */
+function isSameOriginAgentUrl(agentUrl, localServerUrl) {
+    if (!localServerUrl) {
+        return false;
+    }
+    try {
+        return new URL(agentUrl).origin === new URL(localServerUrl).origin;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
 /**
  * Map of team tool functions.
  */
@@ -15907,11 +19271,17 @@ class TeamCommitmentDefinition extends BaseCommitmentDefinition {
     get description() {
         return 'Enable the agent to consult teammate agents via dedicated tools.';
     }
+    /**
+     * Marks TEAM as one of the priority commitments surfaced first in catalogues.
+     */
+    get isImportant() {
+        return true;
+    }
     /**
      * Icon for this commitment.
      */
     get icon() {
-        return '??';
+        return '👥';
     }
     /**
      * Markdown documentation for TEAM commitment.
@@ -16213,21 +19583,28 @@ function createPseudoVoidTeamToolResult(entry, request) {
 /**
  * Resolves a RemoteAgent for the given teammate URL, caching the connection.
  */
-async function getRemoteTeammateAgent(agentUrl) {
-    const cached = remoteAgentsByUrl.get(agentUrl);
+async function getRemoteTeammateAgent(agentUrl, runtimeContext) {
+    var _a, _b;
+    const requestHeaders = createTeamInternalAgentAccessHeaders({
+        agentUrl,
+        localServerUrl: (_a = runtimeContext.agentsServer) === null || _a === void 0 ? void 0 : _a.localServerUrl,
+        accessToken: (_b = runtimeContext.agentsServer) === null || _b === void 0 ? void 0 : _b.teamInternalAccessToken,
+    });
+    const cacheKey = `${agentUrl}|${requestHeaders[TEAM_INTERNAL_AGENT_ACCESS_HEADER] || ''}`;
+    const cached = remoteAgentsByUrl.get(cacheKey);
     if (cached) {
         return cached;
     }
     const connection = (async () => {
         const { RemoteAgent } = await Promise.resolve().then(function () { return RemoteAgent$1; });
-        return RemoteAgent.connect({ agentUrl });
+        return RemoteAgent.connect({ agentUrl, requestHeaders });
     })();
-    remoteAgentsByUrl.set(agentUrl, connection);
+    remoteAgentsByUrl.set(cacheKey, connection);
     try {
         return await connection;
     }
     catch (error) {
-        remoteAgentsByUrl.delete(agentUrl);
+        remoteAgentsByUrl.delete(cacheKey);
         throw error;
     }
 }
@@ -16257,8 +19634,9 @@ function createTeamToolFunction(entry) {
         let error = null;
         let toolCalls;
         try {
-            const remoteAgent = await getRemoteTeammateAgent(entry.teammate.url);
-            const prompt = buildTeammatePrompt(request, createTeamConversationRuntimeContext(args[TOOL_RUNTIME_CONTEXT_ARGUMENT]));
+            const runtimeContext = createTeamConversationRuntimeContext(args[TOOL_RUNTIME_CONTEXT_ARGUMENT]);
+            const remoteAgent = await getRemoteTeammateAgent(entry.teammate.url, runtimeContext);
+            const prompt = buildTeammatePrompt(request, runtimeContext);
             const teammateResult = await remoteAgent.callChatModel(prompt);
             response = teammateResult.content || '';
             toolCalls =
@@ -16297,11 +19675,10 @@ function createTeamToolFunction(entry) {
 /**
  * TEMPLATE commitment definition
  *
- * The TEMPLATE commitment enforces a specific response structure or template
- * that the agent must follow when generating responses. This helps ensure
- * consistent message formatting across all agent interactions.
+ * Deprecated legacy commitment for response templates and output structure.
+ * New books should prefer `WRITING SAMPLE` and `WRITING RULES`.
  *
- * Example usage in agent source:
+ * Legacy example usage in agent source:
  *
  * ```book
  * TEMPLATE Always structure your response with: 1) Summary, 2) Details, 3) Next steps
@@ -16321,7 +19698,16 @@ class TemplateCommitmentDefinition extends BaseCommitmentDefinition {
      * Short one-line description of TEMPLATE.
      */
     get description() {
-        return 'Enforce a specific message structure or response template.';
+        return 'Deprecated legacy template commitment. Prefer `WRITING SAMPLE` and `WRITING RULES` for new books.';
+    }
+    /**
+     * Optional UI/docs-only deprecation metadata.
+     */
+    get deprecation() {
+        return {
+            message: 'Use `WRITING SAMPLE` and `WRITING RULES` instead.',
+            replacedBy: ['WRITING SAMPLE', 'WRITING RULES'],
+        };
     }
     /**
      * Icon for this commitment.
@@ -16336,38 +19722,32 @@ class TemplateCommitmentDefinition extends BaseCommitmentDefinition {
         return spaceTrim$1(`
             # ${this.type}
 
-            Enforces a specific response structure or template that the agent must follow when generating responses.
+            Deprecated legacy commitment for response structure and templates.
 
-            ## Key aspects
+            ## Migration
 
-            - Both terms work identically and can be used interchangeably.
-            - Can be used with or without content.
-            - When used without content, enables template mode for structured responses.
-            - When used with content, defines the specific template structure to follow.
-            - Multiple templates can be combined, with later ones taking precedence.
+            - Existing \`${this.type}\` and \`TEMPLATES\` books still parse and compile.
+            - New books should use \`WRITING SAMPLE\` for concrete response exemplars and \`WRITING RULES\` for structure or formatting constraints.
+            - Runtime behavior is intentionally unchanged for backward compatibility.
 
-            ## Examples
+            ## Preferred replacement
 
             \`\`\`book
             Customer Support Agent
 
-            PERSONA You are a helpful customer support representative
-            TEMPLATE Always structure your response with: 1) Acknowledgment, 2) Solution, 3) Follow-up question
-            WRITING RULES Be professional and empathetic
+            GOAL Help the user with support questions.
+            WRITING SAMPLE
+            Thanks for reaching out. Here is the summary, details, and next step.
+            WRITING RULES Keep the response structured as: summary, details, next step.
             \`\`\`
 
-            \`\`\`book
-            Technical Documentation Assistant
-
-            PERSONA You are a technical writing expert
-            TEMPLATE Use the following format: **Topic:** [topic] | **Explanation:** [details] | **Example:** [code]
-            FORMAT Use markdown with clear headings
-            \`\`\`
+            ## Legacy compatibility example
 
             \`\`\`book
-            Simple Agent
+            Customer Support Agent
 
-            PERSONA You are a virtual assistant
+            GOAL Help the user with support questions.
+            TEMPLATE Always structure your response with: 1) Acknowledgment, 2) Solution, 3) Follow-up question
             TEMPLATE
             \`\`\`
         `);
@@ -16415,120 +19795,6 @@ class TemplateCommitmentDefinition extends BaseCommitmentDefinition {
 }
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
-/**
- * USE commitment definition
- *
- * The USE commitment indicates that the agent should utilize specific tools or capabilities
- * to access and interact with external systems when necessary.
- *
- * Supported USE types:
- * - USE BROWSER: Enables the agent to use a web browser tool
- * - USE SEARCH ENGINE (future): Enables search engine access
- * - USE DEEPSEARCH: Enables deeper research-oriented search access
- * - USE FILE SYSTEM (future): Enables file system operations
- * - USE MCP (future): Enables MCP server connections
- *
- * The content following the USE commitment is ignored (similar to NOTE).
- *
- * Example usage in agent source:
- *
- * ```book
- * USE BROWSER
- * USE SEARCH ENGINE
- * ```
- *
- * @private [🪔] Maybe export the commitments through some package
- */
-class UseCommitmentDefinition extends BaseCommitmentDefinition {
-    constructor() {
-        super('USE');
-    }
-    /**
-     * Short one-line description of USE commitments.
-     */
-    get description() {
-        return 'Enable the agent to use specific tools or capabilities (BROWSER, SEARCH ENGINE, DEEPSEARCH, etc.).';
-    }
-    /**
-     * Icon for this commitment.
-     */
-    get icon() {
-        return '🔧';
-    }
-    /**
-     * Markdown documentation for USE commitment.
-     */
-    get documentation() {
-        return spaceTrim$1(`
-            # USE
-
-            Enables the agent to use specific tools or capabilities for interacting with external systems.
-
-            ## Supported USE types
-
-            - **USE BROWSER** - Enables the agent to use a web browser tool to access and retrieve information from the internet
-            - **USE SEARCH ENGINE** (future) - Enables search engine access
-            - **USE DEEPSEARCH** - Enables deeper research-oriented search access
-            - **USE FILE SYSTEM** (future) - Enables file system operations
-            - **USE MCP** (future) - Enables MCP server connections
-
-            ## Key aspects
-
-            - The content following the USE commitment is ignored (similar to NOTE)
-            - Multiple USE commitments can be specified to enable multiple capabilities
-            - The actual tool usage is handled by the agent runtime
-
-            ## Examples
-
-            ### Basic browser usage
-
-            \`\`\`book
-            Research Assistant
-
-            PERSONA You are a helpful research assistant
-            USE BROWSER
-            KNOWLEDGE Can search the web for up-to-date information
-            \`\`\`
-
-            ### Multiple tools
-
-            \`\`\`book
-            Data Analyst
-
-            PERSONA You are a data analyst assistant
-            USE BROWSER
-            USE FILE SYSTEM
-            ACTION Can analyze data from various sources
-            \`\`\`
-        `);
-    }
-    applyToAgentModelRequirements(requirements, content) {
-        // USE commitments don't modify the system message or model requirements directly
-        // They are handled separately in the parsing logic for capability extraction
-        // This method exists for consistency with the CommitmentDefinition interface
-        return requirements;
-    }
-    /**
-     * Extracts the tool type from the USE commitment
-     * This is used by the parsing logic
-     */
-    extractToolType(content) {
-        var _a, _b;
-        const trimmedContent = content.trim();
-        // The tool type is the first word after USE (already stripped)
-        const match = trimmedContent.match(/^(\w+)/);
-        return (_b = (_a = match === null || match === void 0 ? void 0 : match[1]) === null || _a === void 0 ? void 0 : _a.toUpperCase()) !== null && _b !== void 0 ? _b : null;
-    }
-    /**
-     * Checks if this is a known USE type
-     */
-    isKnownUseType(useType) {
-        const knownTypes = ['BROWSER', 'SEARCH ENGINE', 'DEEPSEARCH', 'FILE SYSTEM', 'MCP'];
-        return knownTypes.includes(useType.toUpperCase());
-    }
-}
-// Note: [💞] Ignore a discrepancy between file name and entity name
-
 /**
  * All `USE` commitment types currently participating in final system-message aggregation.
  *
@@ -22495,10 +25761,10 @@ const COMMITMENT_REGISTRY = [
     new MemoryCommitmentDefinition('MEMORIES'),
     new StyleCommitmentDefinition('STYLE'),
     new StyleCommitmentDefinition('STYLES'),
-    new RuleCommitmentDefinition('RULES'),
     new RuleCommitmentDefinition('RULE'),
-    new LanguageCommitmentDefinition('LANGUAGES'),
+    new RuleCommitmentDefinition('RULES'),
     new LanguageCommitmentDefinition('LANGUAGE'),
+    new LanguageCommitmentDefinition('LANGUAGES'),
     new WritingSampleCommitmentDefinition(),
     new WritingRulesCommitmentDefinition(),
     new SampleCommitmentDefinition('SAMPLE'),
@@ -22515,6 +25781,7 @@ const COMMITMENT_REGISTRY = [
     new ActionCommitmentDefinition('ACTION'),
     new ActionCommitmentDefinition('ACTIONS'),
     new ComponentCommitmentDefinition(),
+    new MetaAvatarCommitmentDefinition(),
     new MetaImageCommitmentDefinition(),
     new MetaColorCommitmentDefinition(),
     new MetaFontCommitmentDefinition(),
@@ -22562,7 +25829,6 @@ const COMMITMENT_REGISTRY = [
     new UseMcpCommitmentDefinition(),
     new UsePrivacyCommitmentDefinition(),
     new UseProjectCommitmentDefinition(),
-    new UseCommitmentDefinition(),
     // Not yet implemented commitments (using placeholder)
     new NotYetImplementedCommitmentDefinition('EXPECT'),
     new NotYetImplementedCommitmentDefinition('BEHAVIOUR'),
@@ -22575,6 +25841,92 @@ const COMMITMENT_REGISTRY = [
 // TODO: [🧠] Maybe create through standardized $register
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * Priority order for the important commitments shown first in catalogues and intellisense.
+ *
+ * Canonical singular names stay ahead of their plural aliases so the most important
+ * commitments remain easy to scan.
+ *
+ * @private internal constant of commitment catalog sorting
+ */
+const IMPORTANT_COMMITMENT_TYPE_SORT_ORDER = new Map([
+    ['GOAL', 0],
+    ['GOALS', 1],
+    ['RULE', 2],
+    ['RULES', 3],
+    ['KNOWLEDGE', 4],
+    ['TEAM', 5],
+]);
+/**
+ * Sort rank used when unfinished, low-level, and deprecated commitments should be grouped last.
+ *
+ * @private internal constant of commitment catalog sorting
+ */
+const COMMITMENT_STATUS_SORT_ORDER = {
+    normal: 0,
+    deprecated: 1,
+    unfinished: 2,
+    lowLevel: 3,
+};
+/**
+ * Resolves the relative sort rank of one commitment status.
+ *
+ * @param definition - Commitment definition to rank.
+ * @param options - Sorting options.
+ * @returns Relative sort rank for the definition.
+ *
+ * @private internal helper of commitment catalog sorting
+ */
+function resolveCommitmentStatusSortRank(definition, options) {
+    let statusSortRank = COMMITMENT_STATUS_SORT_ORDER.normal;
+    if (options.isDeprecatedLast && definition.deprecation) {
+        statusSortRank = Math.max(statusSortRank, COMMITMENT_STATUS_SORT_ORDER.deprecated);
+    }
+    if (options.isUnfinishedLast && definition.isUnfinished) {
+        statusSortRank = Math.max(statusSortRank, COMMITMENT_STATUS_SORT_ORDER.unfinished);
+    }
+    if (options.isLowLevelLast && definition.isLowLevel) {
+        statusSortRank = Math.max(statusSortRank, COMMITMENT_STATUS_SORT_ORDER.lowLevel);
+    }
+    return statusSortRank;
+}
+/**
+ * Sorts commitment definitions so the important ones stay at the top.
+ *
+ * @param commitmentDefinitions - Definitions to sort.
+ * @param options - Sorting options.
+ * @returns Sorted commitment definitions.
+ *
+ * @private internal helper of commitment catalog sorting
+ */
+function sortCommitmentDefinitions(commitmentDefinitions, options = {}) {
+    return [...commitmentDefinitions]
+        .map((definition, index) => ({
+        definition,
+        index,
+    }))
+        .sort((left, right) => {
+        var _a, _b;
+        if (left.definition.isImportant !== right.definition.isImportant) {
+            return left.definition.isImportant ? -1 : 1;
+        }
+        if (left.definition.isImportant && right.definition.isImportant) {
+            const leftPriority = (_a = IMPORTANT_COMMITMENT_TYPE_SORT_ORDER.get(left.definition.type)) !== null && _a !== void 0 ? _a : Number.MAX_SAFE_INTEGER;
+            const rightPriority = (_b = IMPORTANT_COMMITMENT_TYPE_SORT_ORDER.get(right.definition.type)) !== null && _b !== void 0 ? _b : Number.MAX_SAFE_INTEGER;
+            if (leftPriority !== rightPriority) {
+                return leftPriority - rightPriority;
+            }
+        }
+        const leftStatusSortRank = resolveCommitmentStatusSortRank(left.definition, options);
+        const rightStatusSortRank = resolveCommitmentStatusSortRank(right.definition, options);
+        if (leftStatusSortRank !== rightStatusSortRank) {
+            return leftStatusSortRank - rightStatusSortRank;
+        }
+        return left.index - right.index;
+    })
+        .map(({ definition }) => definition);
+}
+
 /**
  * Gets all available commitment definitions
  *
@@ -22583,7 +25935,7 @@ const COMMITMENT_REGISTRY = [
  * @public exported from `@promptbook/core`
  */
 function getAllCommitmentDefinitions() {
-    return $deepFreeze([...COMMITMENT_REGISTRY]);
+    return $deepFreeze(sortCommitmentDefinitions(COMMITMENT_REGISTRY, { isUnfinishedLast: true, isLowLevelLast: true }));
 }
 
 /**
@@ -24923,7 +28275,7 @@ function deduplicatePreparationToolCalls(toolCalls) {
             lastPreparationIndex = index;
         }
         else {
-            // Remove earlier duplicate — keep only the last (most recent) one.
+            // Remove earlier duplicate - keep only the last (most recent) one.
             toolCalls.splice(index, 1);
         }
     }
@@ -25336,6 +28688,7 @@ const SIMPLE_CAPABILITY_BY_COMMITMENT_TYPE = {
  * @private internal utility of `parseAgentSource`
  */
 const META_COMMITMENT_APPLIERS = {
+    'META AVATAR': applyMetaAvatarContent,
     'META LINK': applyMetaLinkContent,
     'META DOMAIN': applyMetaDomainContent,
     'META IMAGE': applyMetaImageContent,
@@ -25699,9 +29052,26 @@ function applyGenericMetaCommitment(state, content) {
     if (metaTypeRaw === 'LINK') {
         state.links.push(metaValue);
     }
+    if (metaTypeRaw.toUpperCase() === 'AVATAR') {
+        applyMetaAvatarContent(state, metaValue);
+        return;
+    }
     const metaType = normalizeTo_camelCase(metaTypeRaw);
     state.meta[metaType] = metaValue;
 }
+/**
+ * Applies META AVATAR content into the canonical `meta.avatar` field.
+ *
+ * @private internal utility of `parseAgentSource`
+ */
+function applyMetaAvatarContent(state, content) {
+    const avatarVisualId = resolveAvatarVisualId(content);
+    if (avatarVisualId) {
+        state.meta.avatar = avatarVisualId;
+        return;
+    }
+    delete state.meta.avatar;
+}
 /**
  * Applies META LINK content into links and the canonical `meta.link` field.
  *
@@ -27286,7 +30656,7 @@ function humanizeAiTextEllipsis(aiText) {
 // Note: [🏂] This function is not tested by itself but together with other cleanup functions with `humanizeAiText`
 
 /**
- * Change dash-like characters to regular dashes `—` -> `-` and remove soft hyphens
+ * Change dash-like characters to regular dashes `-` -> `-` and remove soft hyphens
  *
  * Note: [🔂] This function is idempotent.
  * Tip: If you want to do the full cleanup, look for `humanizeAiText` exported `@promptbook/markdown-utils`
@@ -27294,7 +30664,7 @@ function humanizeAiTextEllipsis(aiText) {
  * @public exported from `@promptbook/markdown-utils`
  */
 function humanizeAiTextEmdashed(aiText) {
-    return aiText.replace(/\u00AD/g, '').replace(/[‐‑‒–—―−⁃﹣－]/g, '-');
+    return aiText.replace(/\u00AD/g, '').replace(/[‐‑‒–-―−⁃﹣－]/g, '-');
 }
 // Note: [🏂] This function is not tested by itself but together with other cleanup functions with `humanizeAiText`
 
@@ -34007,6 +37377,7 @@ function buildRemoteAgentSource(profile, meta) {
     const isMetaImageExplicit = profile.isMetaImageExplicit !== false;
     const metaLines = [
         formatMetaLine('FULLNAME', meta === null || meta === void 0 ? void 0 : meta.fullname),
+        formatMetaLine('AVATAR', meta === null || meta === void 0 ? void 0 : meta.avatar),
         formatMetaLine('IMAGE', isMetaImageExplicit ? meta === null || meta === void 0 ? void 0 : meta.image : undefined),
         formatMetaLine('DESCRIPTION', meta === null || meta === void 0 ? void 0 : meta.description),
         formatMetaLine('COLOR', meta === null || meta === void 0 ? void 0 : meta.color),
@@ -34047,7 +37418,7 @@ class RemoteAgent extends Agent {
         var _a, _b, _c;
         const agentProfileUrl = `${options.agentUrl}/api/profile`;
         const profileResponse = await fetch(agentProfileUrl, {
-            headers: attachClientVersionHeader(),
+            headers: attachClientVersionHeader(options.requestHeaders),
         });
         // <- TODO: [🐱‍🚀] What about closed-source agents?
         // <- TODO: [🐱‍🚀] Maybe use promptbookFetch
@@ -34127,6 +37498,7 @@ class RemoteAgent extends Agent {
         this.avatarVisualId = undefined;
         this.knowledgeSources = [];
         this.agentUrl = options.agentUrl;
+        this.requestHeaders = options.requestHeaders || {};
     }
     get agentName() {
         return this._remoteAgentName || super.agentName;
@@ -34163,7 +37535,7 @@ class RemoteAgent extends Agent {
             }
             const response = await fetch(`${this.agentUrl}/api/voice`, {
                 method: 'POST',
-                headers: attachClientVersionHeader(),
+                headers: attachClientVersionHeader(this.requestHeaders),
                 body: formData,
             });
             if (!response.ok) {
@@ -34194,6 +37566,7 @@ class RemoteAgent extends Agent {
         const bookResponse = await fetch(`${this.agentUrl}/api/chat`, {
             method: 'POST',
             headers: attachClientVersionHeader({
+                ...this.requestHeaders,
                 'Content-Type': 'application/json',
             }),
             body: JSON.stringify({