@promptbook/core 0.113.0-7 → 0.113.0-9

package/esm/index.es.js

@@ -28,7 +28,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.113.0-7';
+const PROMPTBOOK_ENGINE_VERSION = '0.113.0-9';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -280,6 +280,127 @@ function take(initialValue) {
     });
 }
 
+/**
+ * Validates that a channel value is a valid number within the range of 0 to 255.
+ * Throws an error if the value is not valid.
+ *
+ * @param channelName - The name of the channel being validated.
+ * @param value - The value of the channel to validate.
+ * @throws Will throw an error if the value is not a valid channel number.
+ *
+ * @private util of `@promptbook/color`
+ */
+function checkChannelValue(channelName, value) {
+    if (typeof value !== 'number') {
+        throw new Error(`${channelName} channel value is not number but ${typeof value}`);
+    }
+    if (isNaN(value)) {
+        throw new Error(`${channelName} channel value is NaN`);
+    }
+    if (Math.round(value) !== value) {
+        throw new Error(`${channelName} channel is not whole number, it is ${value}`);
+    }
+    if (value < 0) {
+        throw new Error(`${channelName} channel is lower than 0, it is ${value}`);
+    }
+    if (value > 255) {
+        throw new Error(`${channelName} channel is greater than 255, it is ${value}`);
+    }
+}
+
+/**
+ * Shared immutable channel storage and serialization helpers for `Color`.
+ *
+ * @private base class of Color
+ */
+class ColorValue {
+    constructor(red, green, blue, alpha = 255) {
+        this.red = red;
+        this.green = green;
+        this.blue = blue;
+        this.alpha = alpha;
+        checkChannelValue('Red', red);
+        checkChannelValue('Green', green);
+        checkChannelValue('Blue', blue);
+        checkChannelValue('Alpha', alpha);
+    }
+    /**
+     * Shortcut for `red` property
+     * Number from 0 to 255
+     * @alias red
+     */
+    get r() {
+        return this.red;
+    }
+    /**
+     * Shortcut for `green` property
+     * Number from 0 to 255
+     * @alias green
+     */
+    get g() {
+        return this.green;
+    }
+    /**
+     * Shortcut for `blue` property
+     * Number from 0 to 255
+     * @alias blue
+     */
+    get b() {
+        return this.blue;
+    }
+    /**
+     * Shortcut for `alpha` property
+     * Number from 0 (transparent) to 255 (opaque)
+     * @alias alpha
+     */
+    get a() {
+        return this.alpha;
+    }
+    /**
+     * Shortcut for `alpha` property
+     * Number from 0 (transparent) to 255 (opaque)
+     * @alias alpha
+     */
+    get opacity() {
+        return this.alpha;
+    }
+    /**
+     * Shortcut for 1-`alpha` property
+     */
+    get transparency() {
+        return 255 - this.alpha;
+    }
+    clone() {
+        return take(this.createColor(this.red, this.green, this.blue, this.alpha));
+    }
+    toString() {
+        return this.toHex();
+    }
+    toHex() {
+        if (this.alpha === 255) {
+            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}`;
+        }
+        else {
+            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
+        }
+    }
+    toRgb() {
+        if (this.alpha === 255) {
+            return `rgb(${this.red}, ${this.green}, ${this.blue})`;
+        }
+        else {
+            return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
+        }
+    }
+    toHsl() {
+        throw new Error(`Getting HSL is not implemented`);
+    }
+}
+
 /**
  * 🎨 List of all 140 color names which are supported by CSS
  *
@@ -439,127 +560,6 @@ const CSS_COLORS = {
 };
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
-/**
- * Validates that a channel value is a valid number within the range of 0 to 255.
- * Throws an error if the value is not valid.
- *
- * @param channelName - The name of the channel being validated.
- * @param value - The value of the channel to validate.
- * @throws Will throw an error if the value is not a valid channel number.
- *
- * @private util of `@promptbook/color`
- */
-function checkChannelValue(channelName, value) {
-    if (typeof value !== 'number') {
-        throw new Error(`${channelName} channel value is not number but ${typeof value}`);
-    }
-    if (isNaN(value)) {
-        throw new Error(`${channelName} channel value is NaN`);
-    }
-    if (Math.round(value) !== value) {
-        throw new Error(`${channelName} channel is not whole number, it is ${value}`);
-    }
-    if (value < 0) {
-        throw new Error(`${channelName} channel is lower than 0, it is ${value}`);
-    }
-    if (value > 255) {
-        throw new Error(`${channelName} channel is greater than 255, it is ${value}`);
-    }
-}
-
-/**
- * Shared immutable channel storage and serialization helpers for `Color`.
- *
- * @private base class of Color
- */
-class ColorValue {
-    constructor(red, green, blue, alpha = 255) {
-        this.red = red;
-        this.green = green;
-        this.blue = blue;
-        this.alpha = alpha;
-        checkChannelValue('Red', red);
-        checkChannelValue('Green', green);
-        checkChannelValue('Blue', blue);
-        checkChannelValue('Alpha', alpha);
-    }
-    /**
-     * Shortcut for `red` property
-     * Number from 0 to 255
-     * @alias red
-     */
-    get r() {
-        return this.red;
-    }
-    /**
-     * Shortcut for `green` property
-     * Number from 0 to 255
-     * @alias green
-     */
-    get g() {
-        return this.green;
-    }
-    /**
-     * Shortcut for `blue` property
-     * Number from 0 to 255
-     * @alias blue
-     */
-    get b() {
-        return this.blue;
-    }
-    /**
-     * Shortcut for `alpha` property
-     * Number from 0 (transparent) to 255 (opaque)
-     * @alias alpha
-     */
-    get a() {
-        return this.alpha;
-    }
-    /**
-     * Shortcut for `alpha` property
-     * Number from 0 (transparent) to 255 (opaque)
-     * @alias alpha
-     */
-    get opacity() {
-        return this.alpha;
-    }
-    /**
-     * Shortcut for 1-`alpha` property
-     */
-    get transparency() {
-        return 255 - this.alpha;
-    }
-    clone() {
-        return take(this.createColor(this.red, this.green, this.blue, this.alpha));
-    }
-    toString() {
-        return this.toHex();
-    }
-    toHex() {
-        if (this.alpha === 255) {
-            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}`;
-        }
-        else {
-            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
-        }
-    }
-    toRgb() {
-        if (this.alpha === 255) {
-            return `rgb(${this.red}, ${this.green}, ${this.blue})`;
-        }
-        else {
-            return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
-        }
-    }
-    toHsl() {
-        throw new Error(`Getting HSL is not implemented`);
-    }
-}
-
 /**
  * Checks if the given value is a valid hex color string
  *
@@ -2301,6 +2301,95 @@ function pipelineJsonToString(pipelineJson) {
 // TODO: [🏛] Escape all
 // TODO: [🧠] Should be in generated .book.md file GENERATOR_WARNING
 
+/**
+ * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
+ *
+ * @public exported from `@promptbook/core`
+ */
+class PipelineLogicError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PipelineLogicError';
+        Object.setPrototypeOf(this, PipelineLogicError.prototype);
+    }
+}
+
+/**
+ * Creates the shared validation context for one pipeline.
+ *
+ * @private function of `validatePipeline`
+ */
+function createPipelineValidationContext(pipeline) {
+    return {
+        pipeline,
+        pipelineIdentification: getPipelineIdentification$1(pipeline),
+    };
+}
+/**
+ * Builds a short file/url identification block for validation errors.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function getPipelineIdentification$1(pipeline) {
+    // Note: This is a 😐 implementation of [🚞]
+    const pipelineIdentificationParts = [];
+    if (pipeline.sourceFile !== undefined) {
+        pipelineIdentificationParts.push(`File: ${pipeline.sourceFile}`);
+    }
+    if (pipeline.pipelineUrl !== undefined) {
+        pipelineIdentificationParts.push(`Url: ${pipeline.pipelineUrl}`);
+    }
+    return pipelineIdentificationParts.join('\n');
+}
+
+/**
+ * Validates that the expected top-level collections have array structure.
+ *
+ * @private function of `validatePipeline`
+ */
+function validatePipelineCollectionsStructure({ pipeline, pipelineIdentification, }) {
+    validatePipelineParametersCollection(pipeline, pipelineIdentification);
+    validatePipelineTasksCollection(pipeline, pipelineIdentification);
+}
+/**
+ * Validates that `pipeline.parameters` is an array.
+ *
+ * @private internal utility of `validatePipelineCollectionsStructure`
+ */
+function validatePipelineParametersCollection(pipeline, pipelineIdentification) {
+    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
+    if (Array.isArray(pipeline.parameters)) {
+        return;
+    }
+    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
+    throw new ParseError(spaceTrim$1((block) => `
+                Pipeline is valid JSON but with wrong structure
+
+                \`PipelineJson.parameters\` expected to be an array, but got ${typeof pipeline.parameters}
+
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Validates that `pipeline.tasks` is an array.
+ *
+ * @private internal utility of `validatePipelineCollectionsStructure`
+ */
+function validatePipelineTasksCollection(pipeline, pipelineIdentification) {
+    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
+    if (Array.isArray(pipeline.tasks)) {
+        return;
+    }
+    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
+    throw new ParseError(spaceTrim$1((block) => `
+                Pipeline is valid JSON but with wrong structure
+
+                \`PipelineJson.tasks\` expected to be an array, but got ${typeof pipeline.tasks}
+
+                ${block(pipelineIdentification)}
+            `));
+}
+
 /**
  * Orders JSON object by keys
  *
@@ -2841,16 +2930,137 @@ const HTTP_STATUS_CODES = {
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
- * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
+ * Validates that task dependencies can be resolved without cycles or missing definitions.
  *
- * @public exported from `@promptbook/core`
+ * @private function of `validatePipeline`
  */
-class PipelineLogicError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'PipelineLogicError';
-        Object.setPrototypeOf(this, PipelineLogicError.prototype);
+function validatePipelineDependencyResolution({ pipeline, pipelineIdentification, }) {
+    let dependencyResolutionState = createInitialDependencyResolutionState(pipeline);
+    let loopLimit = LOOP_LIMIT;
+    while (hasUnresolvedTasks(dependencyResolutionState)) {
+        if (loopLimit-- < 0) {
+            throw createDependencyResolutionLoopLimitError(pipelineIdentification);
+        }
+        dependencyResolutionState = resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification);
+    }
+}
+/**
+ * Collects the parameter names that are already resolvable before dependency traversal starts.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function createInitialDependencyResolutionState(pipeline) {
+    return {
+        resolvedParameterNames: createInitiallyResolvedParameterNames(pipeline),
+        unresolvedTasks: [...pipeline.tasks],
+    };
+}
+/**
+ * Checks whether dependency resolution still has tasks left to process.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function hasUnresolvedTasks({ unresolvedTasks }) {
+    return unresolvedTasks.length > 0;
+}
+/**
+ * Resolves the next batch of currently satisfiable tasks.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification) {
+    const currentlyResolvedTasks = getCurrentlyResolvedTasks(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames);
+    if (currentlyResolvedTasks.length === 0) {
+        throw createUnresolvedTasksError(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames, pipelineIdentification);
     }
+    return {
+        resolvedParameterNames: appendResolvedTaskParameterNames(dependencyResolutionState.resolvedParameterNames, currentlyResolvedTasks),
+        unresolvedTasks: dependencyResolutionState.unresolvedTasks.filter((task) => !currentlyResolvedTasks.includes(task)),
+    };
+}
+/**
+ * Collects the parameter names that are already resolvable before dependency traversal starts.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function createInitiallyResolvedParameterNames(pipeline) {
+    let resolvedParameterNames = pipeline.parameters
+        .filter(({ isInput }) => isInput)
+        .map(({ name }) => name);
+    for (const reservedParameterName of RESERVED_PARAMETER_NAMES) {
+        resolvedParameterNames = [...resolvedParameterNames, reservedParameterName];
+    }
+    return resolvedParameterNames;
+}
+/**
+ * Adds newly resolved task outputs to the resolved parameter list.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function appendResolvedTaskParameterNames(resolvedParameterNames, currentlyResolvedTasks) {
+    return [
+        ...resolvedParameterNames,
+        ...currentlyResolvedTasks.map(({ resultingParameterName }) => resultingParameterName),
+    ];
+}
+/**
+ * Selects tasks whose dependencies are already resolved.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function getCurrentlyResolvedTasks(unresolvedTasks, resolvedParameterNames) {
+    return unresolvedTasks.filter((task) => task.dependentParameterNames.every((name) => resolvedParameterNames.includes(name)));
+}
+/**
+ * Creates the unexpected loop-limit error for dependency resolution.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function createDependencyResolutionLoopLimitError(pipelineIdentification) {
+    // Note: Really UnexpectedError not LimitReachedError - this should not happen and be caught below
+    return new UnexpectedError(spaceTrim$1((block) => `
+                Loop limit reached during detection of circular dependencies in \`validatePipeline\`
+
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Creates the detailed error for unresolved or circular task dependencies.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function createUnresolvedTasksError(unresolvedTasks, resolvedParameterNames, pipelineIdentification) {
+    return new PipelineLogicError(
+    // TODO: [🐎] DRY
+    spaceTrim$1((block) => `
+
+                Can not resolve some parameters:
+                Either you are using a parameter that is not defined, or there are some circular dependencies.
+
+                ${block(pipelineIdentification)}
+
+                **Can not resolve:**
+                ${block(unresolvedTasks
+        .map(({ resultingParameterName, dependentParameterNames }) => `- Parameter \`{${resultingParameterName}}\` which depends on ${dependentParameterNames
+        .map((dependentParameterName) => `\`{${dependentParameterName}}\``)
+        .join(' and ')}`)
+        .join('\n'))}
+
+                **Resolved:**
+                ${block(resolvedParameterNames
+        .filter((name) => !RESERVED_PARAMETER_NAMES.includes(name))
+        .map((name) => `- Parameter \`{${name}}\``)
+        .join('\n'))}
+
+
+                **Reserved (which are available):**
+                ${block(resolvedParameterNames
+        .filter((name) => RESERVED_PARAMETER_NAMES.includes(name))
+        .map((name) => `- Parameter \`{${name}}\``)
+        .join('\n'))}
+
+
+            `));
 }
 
 /**
@@ -2927,168 +3137,19 @@ function isValidPipelineUrl(url) {
 }
 // TODO: [🐠] Maybe more info why the URL is invalid
 
-/**
- * Validates PipelineJson if it is logically valid
- *
- * It checks:
- * -   if it has correct parameters dependency
- *
- * It does NOT check:
- * -   if it is valid json
- * -   if it is meaningful
- *
- * Note: [🔂] This function is idempotent.
- *
- * @param pipeline valid or invalid PipelineJson
- * @returns the same pipeline if it is logically valid
- * @throws {PipelineLogicError} on logical error in the pipeline
- *
- * @public exported from `@promptbook/core`
- */
-function validatePipeline(pipeline) {
-    if (IS_PIPELINE_LOGIC_VALIDATED) {
-        validatePipeline_InnerFunction(pipeline);
-    }
-    else {
-        try {
-            validatePipeline_InnerFunction(pipeline);
-        }
-        catch (error) {
-            if (!(error instanceof PipelineLogicError)) {
-                throw error;
-            }
-            console.error(spaceTrim$1((block) => `
-                        Pipeline is not valid but logic errors are temporarily disabled via \`IS_PIPELINE_LOGIC_VALIDATED\`
-
-                        ${block(error.message)}
-                    `));
-        }
-    }
-    return pipeline;
-}
-/**
- * Validates pipeline inner function.
- *
- * @private internal function for `validatePipeline`
- */
-function validatePipeline_InnerFunction(pipeline) {
-    // TODO: [🧠] Maybe test if promptbook is a promise and make specific error case for that
-    const context = createPipelineValidationContext(pipeline);
-    validatePipelineMetadata(context);
-    validatePipelineCollectionsStructure(context);
-    validatePipelineParameters(context);
-    validatePipelineTasks(context);
-    validatePipelineDependencyResolution(context);
-    // Note: Check that formfactor is corresponding to the pipeline interface
-    // TODO: !!6 Implement this
-    // pipeline.formfactorName
-}
-/**
- * Creates the shared validation context for one pipeline.
- *
- * @private internal utility of `validatePipeline`
- */
-function createPipelineValidationContext(pipeline) {
-    return {
-        pipeline,
-        pipelineIdentification: getPipelineIdentification$1(pipeline),
-    };
-}
-/**
- * Builds a short file/url identification block for validation errors.
- *
- * @private internal utility of `validatePipeline`
- */
-function getPipelineIdentification$1(pipeline) {
-    // Note: This is a 😐 implementation of [🚞]
-    const pipelineIdentificationParts = [];
-    if (pipeline.sourceFile !== undefined) {
-        pipelineIdentificationParts.push(`File: ${pipeline.sourceFile}`);
-    }
-    if (pipeline.pipelineUrl !== undefined) {
-        pipelineIdentificationParts.push(`Url: ${pipeline.pipelineUrl}`);
-    }
-    return pipelineIdentificationParts.join('\n');
-}
 /**
  * Validates pipeline-level metadata fields.
  *
- * @private internal step of `validatePipeline`
+ * @private function of `validatePipeline`
  */
 function validatePipelineMetadata({ pipeline, pipelineIdentification }) {
     validatePipelineUrl(pipeline, pipelineIdentification);
     validatePipelineBookVersion(pipeline, pipelineIdentification);
 }
-/**
- * Validates that the expected top-level collections have array structure.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineCollectionsStructure({ pipeline, pipelineIdentification }) {
-    validatePipelineParametersCollection(pipeline, pipelineIdentification);
-    validatePipelineTasksCollection(pipeline, pipelineIdentification);
-}
-/**
- * Validates all pipeline parameter declarations.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineParameters({ pipeline, pipelineIdentification }) {
-    for (const parameter of pipeline.parameters) {
-        validatePipelineParameter(parameter, pipeline, pipelineIdentification);
-    }
-}
-/**
- * Validates all pipeline tasks and their per-task invariants.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineTasks({ pipeline, pipelineIdentification }) {
-    // Note: All input parameters are defined - so that they can be used as result of some task
-    const definedParameters = createInitiallyDefinedParameters(pipeline);
-    for (const task of pipeline.tasks) {
-        validatePipelineTask(task, definedParameters, pipelineIdentification);
-    }
-}
-/**
- * Validates that task dependencies can be resolved without cycles or missing definitions.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineDependencyResolution({ pipeline, pipelineIdentification }) {
-    let dependencyResolutionState = createInitialDependencyResolutionState(pipeline);
-    let loopLimit = LOOP_LIMIT;
-    while (hasUnresolvedTasks(dependencyResolutionState)) {
-        if (loopLimit-- < 0) {
-            throw createDependencyResolutionLoopLimitError(pipelineIdentification);
-        }
-        dependencyResolutionState = resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification);
-    }
-}
-/**
- * Validates one pipeline parameter declaration.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineParameter(parameter, pipeline, pipelineIdentification) {
-    validateParameterDirection(parameter, pipelineIdentification);
-    validateParameterUsage(parameter, pipeline, pipelineIdentification);
-    validateParameterDefinition(parameter, pipeline, pipelineIdentification);
-}
-/**
- * Validates one pipeline task and its invariants.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineTask(task, definedParameters, pipelineIdentification) {
-    validateTaskResultingParameter(task, definedParameters, pipelineIdentification);
-    validateTaskJokers(task, pipelineIdentification);
-    validateTaskExpectations(task, pipelineIdentification);
-}
 /**
  * Validates the pipeline URL, when present.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineMetadata`
  */
 function validatePipelineUrl(pipeline, pipelineIdentification) {
     if (pipeline.pipelineUrl === undefined || isValidPipelineUrl(pipeline.pipelineUrl)) {
@@ -3104,7 +3165,7 @@ function validatePipelineUrl(pipeline, pipelineIdentification) {
 /**
  * Validates the Promptbook version, when present.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineMetadata`
  */
 function validatePipelineBookVersion(pipeline, pipelineIdentification) {
     if (pipeline.bookVersion === undefined || isValidPromptbookVersion(pipeline.bookVersion)) {
@@ -3117,48 +3178,31 @@ function validatePipelineBookVersion(pipeline, pipelineIdentification) {
                 ${block(pipelineIdentification)}
             `));
 }
+
 /**
- * Validates that `pipeline.parameters` is an array.
+ * Validates all pipeline parameter declarations.
  *
- * @private internal utility of `validatePipeline`
+ * @private function of `validatePipeline`
  */
-function validatePipelineParametersCollection(pipeline, pipelineIdentification) {
-    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
-    if (Array.isArray(pipeline.parameters)) {
-        return;
+function validatePipelineParameters({ pipeline, pipelineIdentification }) {
+    for (const parameter of pipeline.parameters) {
+        validatePipelineParameter(parameter, pipeline, pipelineIdentification);
     }
-    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
-    throw new ParseError(spaceTrim$1((block) => `
-                Pipeline is valid JSON but with wrong structure
-
-                \`PipelineJson.parameters\` expected to be an array, but got ${typeof pipeline.parameters}
-
-                ${block(pipelineIdentification)}
-            `));
 }
 /**
- * Validates that `pipeline.tasks` is an array.
+ * Validates one pipeline parameter declaration.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
-function validatePipelineTasksCollection(pipeline, pipelineIdentification) {
-    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
-    if (Array.isArray(pipeline.tasks)) {
-        return;
-    }
-    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
-    throw new ParseError(spaceTrim$1((block) => `
-                Pipeline is valid JSON but with wrong structure
-
-                \`PipelineJson.tasks\` expected to be an array, but got ${typeof pipeline.tasks}
-
-                ${block(pipelineIdentification)}
-            `));
+function validatePipelineParameter(parameter, pipeline, pipelineIdentification) {
+    validateParameterDirection(parameter, pipelineIdentification);
+    validateParameterUsage(parameter, pipeline, pipelineIdentification);
+    validateParameterDefinition(parameter, pipeline, pipelineIdentification);
 }
 /**
  * Validates that one parameter does not declare incompatible directions.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function validateParameterDirection(parameter, pipelineIdentification) {
     if (!parameter.isInput || !parameter.isOutput) {
@@ -3175,7 +3219,7 @@ function validateParameterDirection(parameter, pipelineIdentification) {
 /**
  * Validates that one intermediate parameter is actually consumed by at least one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function validateParameterUsage(parameter, pipeline, pipelineIdentification) {
     if (parameter.isInput || parameter.isOutput || isParameterUsedByAnyTask(parameter, pipeline.tasks)) {
@@ -3194,7 +3238,7 @@ function validateParameterUsage(parameter, pipeline, pipelineIdentification) {
 /**
  * Validates that one non-input parameter is produced by at least one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function validateParameterDefinition(parameter, pipeline, pipelineIdentification) {
     if (parameter.isInput || isParameterDefinedByAnyTask(parameter, pipeline.tasks)) {
@@ -3213,7 +3257,7 @@ function validateParameterDefinition(parameter, pipeline, pipelineIdentification
 /**
  * Checks whether one parameter is consumed by at least one task dependency list.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function isParameterUsedByAnyTask(parameter, tasks) {
     return tasks.some((task) => task.dependentParameterNames.includes(parameter.name));
@@ -3221,23 +3265,46 @@ function isParameterUsedByAnyTask(parameter, tasks) {
 /**
  * Checks whether one parameter is produced by at least one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function isParameterDefinedByAnyTask(parameter, tasks) {
     return tasks.some((task) => task.resultingParameterName === parameter.name);
 }
+
+/**
+ * Validates all pipeline tasks and their per-task invariants.
+ *
+ * @private function of `validatePipeline`
+ */
+function validatePipelineTasks({ pipeline, pipelineIdentification }) {
+    // Note: All input parameters are defined - so that they can be used as result of some task
+    const definedParameters = createInitiallyDefinedParameters(pipeline);
+    for (const task of pipeline.tasks) {
+        validatePipelineTask(task, definedParameters, pipelineIdentification);
+    }
+}
 /**
  * Collects the parameter names that are already defined before task validation starts.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function createInitiallyDefinedParameters(pipeline) {
     return new Set(pipeline.parameters.filter(({ isInput }) => isInput).map(({ name }) => name));
 }
+/**
+ * Validates one pipeline task and its invariants.
+ *
+ * @private internal utility of `validatePipelineTasks`
+ */
+function validatePipelineTask(task, definedParameters, pipelineIdentification) {
+    validateTaskResultingParameter(task, definedParameters, pipelineIdentification);
+    validateTaskJokers(task, pipelineIdentification);
+    validateTaskExpectations(task, pipelineIdentification);
+}
 /**
  * Validates one task result parameter declaration and marks it as defined.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskResultingParameter(task, definedParameters, pipelineIdentification) {
     if (definedParameters.has(task.resultingParameterName)) {
@@ -3259,7 +3326,7 @@ function validateTaskResultingParameter(task, definedParameters, pipelineIdentif
 /**
  * Validates joker parameters for one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskJokers(task, pipelineIdentification) {
     if (!hasTaskJokers(task)) {
@@ -3271,7 +3338,7 @@ function validateTaskJokers(task, pipelineIdentification) {
 /**
  * Checks whether one task declares any joker parameters.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function hasTaskJokers(task) {
     return !!task.jokerParameterNames && task.jokerParameterNames.length > 0;
@@ -3279,7 +3346,7 @@ function hasTaskJokers(task) {
 /**
  * Validates that a task has the required supporting features when using jokers.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskSupportsJokers(task, pipelineIdentification) {
     if (task.format || task.expectations /* <- TODO: Require at least 1 -> min <- expectation to use jokers */) {
@@ -3294,7 +3361,7 @@ function validateTaskSupportsJokers(task, pipelineIdentification) {
 /**
  * Validates that every joker parameter is also listed among task dependencies.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskJokerDependencies(task, pipelineIdentification) {
     for (const joker of task.jokerParameterNames) {
@@ -3311,7 +3378,7 @@ function validateTaskJokerDependencies(task, pipelineIdentification) {
 /**
  * Validates all expectation bounds configured on one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskExpectations(task, pipelineIdentification) {
     if (!task.expectations) {
@@ -3326,7 +3393,7 @@ function validateTaskExpectations(task, pipelineIdentification) {
 /**
  * Validates the minimum and maximum expectation ordering for one unit.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskExpectationRange(unit, min, max, pipelineIdentification) {
     if (min === undefined || max === undefined || min <= max) {
@@ -3341,7 +3408,7 @@ function validateTaskExpectationRange(unit, min, max, pipelineIdentification) {
 /**
  * Validates the minimum expectation bound for one unit.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskExpectationMin(unit, min, pipelineIdentification) {
     if (min === undefined || min >= 0) {
@@ -3356,7 +3423,7 @@ function validateTaskExpectationMin(unit, min, pipelineIdentification) {
 /**
  * Validates the maximum expectation bound for one unit.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskExpectationMax(unit, max, pipelineIdentification) {
     if (max === undefined || max > 0) {
@@ -3368,123 +3435,62 @@ function validateTaskExpectationMax(unit, max, pipelineIdentification) {
                 ${block(pipelineIdentification)}
             `));
 }
+
 /**
- * Collects the parameter names that are already resolvable before dependency traversal starts.
- *
- * @private internal utility of `validatePipeline`
- */
-function createInitialDependencyResolutionState(pipeline) {
-    return {
-        resolvedParameterNames: createInitiallyResolvedParameterNames(pipeline),
-        unresolvedTasks: [...pipeline.tasks],
-    };
-}
-/**
- * Checks whether dependency resolution still has tasks left to process.
- *
- * @private internal utility of `validatePipeline`
- */
-function hasUnresolvedTasks({ unresolvedTasks }) {
-    return unresolvedTasks.length > 0;
-}
-/**
- * Resolves the next batch of currently satisfiable tasks.
+ * Validates PipelineJson if it is logically valid
  *
- * @private internal utility of `validatePipeline`
- */
-function resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification) {
-    const currentlyResolvedTasks = getCurrentlyResolvedTasks(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames);
-    if (currentlyResolvedTasks.length === 0) {
-        throw createUnresolvedTasksError(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames, pipelineIdentification);
-    }
-    return {
-        resolvedParameterNames: appendResolvedTaskParameterNames(dependencyResolutionState.resolvedParameterNames, currentlyResolvedTasks),
-        unresolvedTasks: dependencyResolutionState.unresolvedTasks.filter((task) => !currentlyResolvedTasks.includes(task)),
-    };
-}
-/**
- * Collects the parameter names that are already resolvable before dependency traversal starts.
+ * It checks:
+ * -   if it has correct parameters dependency
  *
- * @private internal utility of `validatePipeline`
- */
-function createInitiallyResolvedParameterNames(pipeline) {
-    let resolvedParameterNames = pipeline.parameters
-        .filter(({ isInput }) => isInput)
-        .map(({ name }) => name);
-    for (const reservedParameterName of RESERVED_PARAMETER_NAMES) {
-        resolvedParameterNames = [...resolvedParameterNames, reservedParameterName];
-    }
-    return resolvedParameterNames;
-}
-/**
- * Adds newly resolved task outputs to the resolved parameter list.
+ * It does NOT check:
+ * -   if it is valid json
+ * -   if it is meaningful
  *
- * @private internal utility of `validatePipeline`
- */
-function appendResolvedTaskParameterNames(resolvedParameterNames, currentlyResolvedTasks) {
-    return [
-        ...resolvedParameterNames,
-        ...currentlyResolvedTasks.map(({ resultingParameterName }) => resultingParameterName),
-    ];
-}
-/**
- * Selects tasks whose dependencies are already resolved.
+ * Note: [🔂] This function is idempotent.
  *
- * @private internal utility of `validatePipeline`
- */
-function getCurrentlyResolvedTasks(unresolvedTasks, resolvedParameterNames) {
-    return unresolvedTasks.filter((task) => task.dependentParameterNames.every((name) => resolvedParameterNames.includes(name)));
-}
-/**
- * Creates the unexpected loop-limit error for dependency resolution.
+ * @param pipeline valid or invalid PipelineJson
+ * @returns the same pipeline if it is logically valid
+ * @throws {PipelineLogicError} on logical error in the pipeline
  *
- * @private internal utility of `validatePipeline`
+ * @public exported from `@promptbook/core`
  */
-function createDependencyResolutionLoopLimitError(pipelineIdentification) {
-    // Note: Really UnexpectedError not LimitReachedError - this should not happen and be caught below
-    return new UnexpectedError(spaceTrim$1((block) => `
-                Loop limit reached during detection of circular dependencies in \`validatePipeline\`
+function validatePipeline(pipeline) {
+    if (IS_PIPELINE_LOGIC_VALIDATED) {
+        validatePipeline_InnerFunction(pipeline);
+    }
+    else {
+        try {
+            validatePipeline_InnerFunction(pipeline);
+        }
+        catch (error) {
+            if (!(error instanceof PipelineLogicError)) {
+                throw error;
+            }
+            console.error(spaceTrim$1((block) => `
+                        Pipeline is not valid but logic errors are temporarily disabled via \`IS_PIPELINE_LOGIC_VALIDATED\`
 
-                ${block(pipelineIdentification)}
-            `));
+                        ${block(error.message)}
+                    `));
+        }
+    }
+    return pipeline;
 }
 /**
- * Creates the detailed error for unresolved or circular task dependencies.
+ * Validates pipeline inner function.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal function for `validatePipeline`
  */
-function createUnresolvedTasksError(unresolvedTasks, resolvedParameterNames, pipelineIdentification) {
-    return new PipelineLogicError(
-    // TODO: [🐎] DRY
-    spaceTrim$1((block) => `
-
-                Can not resolve some parameters:
-                Either you are using a parameter that is not defined, or there are some circular dependencies.
-
-                ${block(pipelineIdentification)}
-
-                **Can not resolve:**
-                ${block(unresolvedTasks
-        .map(({ resultingParameterName, dependentParameterNames }) => `- Parameter \`{${resultingParameterName}}\` which depends on ${dependentParameterNames
-        .map((dependentParameterName) => `\`{${dependentParameterName}}\``)
-        .join(' and ')}`)
-        .join('\n'))}
-
-                **Resolved:**
-                ${block(resolvedParameterNames
-        .filter((name) => !RESERVED_PARAMETER_NAMES.includes(name))
-        .map((name) => `- Parameter \`{${name}}\``)
-        .join('\n'))}
-
-
-                **Reserved (which are available):**
-                ${block(resolvedParameterNames
-        .filter((name) => RESERVED_PARAMETER_NAMES.includes(name))
-        .map((name) => `- Parameter \`{${name}}\``)
-        .join('\n'))}
-
-
-            `));
+function validatePipeline_InnerFunction(pipeline) {
+    // TODO: [🧠] Maybe test if promptbook is a promise and make specific error case for that
+    const context = createPipelineValidationContext(pipeline);
+    validatePipelineMetadata(context);
+    validatePipelineCollectionsStructure(context);
+    validatePipelineParameters(context);
+    validatePipelineTasks(context);
+    validatePipelineDependencyResolution(context);
+    // Note: Check that formfactor is corresponding to the pipeline interface
+    // TODO: !!6 Implement this
+    // pipeline.formfactorName
 }
 /**
  * TODO: [🧞‍♀️] Do not allow joker + foreach
@@ -11893,7 +11899,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 AVATAR / META VISUAL: 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
@@ -11908,7 +11914,7 @@ class MessageSuffixCommitmentDefinition extends BaseCommitmentDefinition {
  * Example usage in agent source:
  *
  * ```book
- * META AVATAR pixel-art
+ * META VISUAL pixel-art
  * META IMAGE https://example.com/avatar.jpg
  * META LINK https://twitter.com/username
  * META DOMAIN my-agent.com
@@ -11948,7 +11954,7 @@ class MetaCommitmentDefinition extends BaseCommitmentDefinition {
 
             ## Supported META types
 
-            - **META AVATAR** - Sets the agent's built-in default avatar visual
+            - **META AVATAR** / **META VISUAL** - 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
@@ -11972,7 +11978,7 @@ class MetaCommitmentDefinition extends BaseCommitmentDefinition {
             \`\`\`book
             Professional Assistant
 
-            META AVATAR octopus3
+            META VISUAL octopus3
             META IMAGE https://example.com/professional-avatar.jpg
             META TITLE Senior Business Consultant
             META DESCRIPTION Specialized in strategic planning and project management
@@ -15143,452 +15149,13 @@ function formatAlphaHex$1(opacity) {
         .padStart(2, '0');
 }
 
-/* eslint-disable no-magic-numbers */
-/**
- * Light direction used by the organic 3D octopus shading.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-const LIGHT_DIRECTION$3 = normalizeVector3({
-    x: 0.48,
-    y: -0.62,
-    z: 0.94,
-});
-/**
- * Cache keyed by the `createRandom` factory reference (stable per mounted `<Avatar/>`).
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-const octopus3dStableStateCache = new WeakMap();
-/**
- * Returns the stable per-avatar state, computing it on first access and caching for subsequent frames.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function getOctopus3dStableState(createRandom) {
-    const cached = octopus3dStableStateCache.get(createRandom);
-    if (cached !== undefined) {
-        return cached;
-    }
-    const animationRandom = createRandom('octopus3d-animation-profile');
-    const eyeRandom = createRandom('octopus3d-eye-profile');
-    const leftEyePhaseOffset = eyeRandom() * 0.6;
-    const rightEyePhaseOffset = eyeRandom() * 0.6;
-    const state = {
-        morphologyProfile: createOctopus3MorphologyProfile(createRandom),
-        animationPhase: animationRandom() * Math.PI * 2,
-        leftEyePhaseOffset,
-        rightEyePhaseOffset,
-    };
-    octopus3dStableStateCache.set(createRandom, state);
-    return state;
-}
-/**
- * Proper 3D Octopus visual built from projected organic meshes and tentacles.
- *
- * @private built-in avatar visual
- */
-const octopus3dAvatarVisual = {
-    id: 'octopus3d',
-    title: 'Octopus 3D',
-    description: 'Proper 3D octopus portrait with a turning silhouette, expressive eyes, and depth-sorted tentacles.',
-    isAnimated: true,
-    supportsPointerTracking: true,
-    render({ context, size, palette, createRandom, timeMs, interaction }) {
-        const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset } = getOctopus3dStableState(createRandom);
-        const sceneCenterX = size * 0.5;
-        const sceneCenterY = size * 0.56;
-        const bob = Math.sin(timeMs / 920 + animationPhase) * size * 0.014;
-        const mantleCenter = {
-            x: interaction.bodyOffsetX * size * 0.042 + size * morphologyProfile.body.centerXJitterRatio * 0.65,
-            y: -size * 0.09 + interaction.bodyOffsetY * size * 0.028 + bob,
-            z: interaction.intensity * size * 0.012,
-        };
-        const underbodyCenter = {
-            x: mantleCenter.x * 0.86,
-            y: mantleCenter.y + size * 0.168,
-            z: mantleCenter.z - size * 0.018,
-        };
-        const mantleRadiusX = size * morphologyProfile.body.bodyRadiusRatio * morphologyProfile.body.horizontalStretch;
-        const mantleRadiusY = size * morphologyProfile.body.bodyRadiusRatio * morphologyProfile.body.verticalStretch * 1.1;
-        const mantleRadiusZ = size *
-            morphologyProfile.body.bodyRadiusRatio *
-            (0.9 + (morphologyProfile.body.horizontalStretch - 1) * 0.3);
-        const underbodyRadiusX = mantleRadiusX * (0.9 + (morphologyProfile.tentacles.rootSpreadScale - 1) * 0.08);
-        const underbodyRadiusY = mantleRadiusY * (0.44 + morphologyProfile.body.lowerDropRatio * 3.1);
-        const underbodyRadiusZ = mantleRadiusZ * 0.78;
-        const bodyYaw = -0.18 +
-            Math.sin(timeMs / 2400 + animationPhase) * 0.05 +
-            interaction.bodyOffsetX * 0.18 +
-            interaction.gazeX * 0.22;
-        const bodyPitch = -0.08 +
-            Math.cos(timeMs / 2700 + animationPhase * 0.6) * 0.025 -
-            interaction.bodyOffsetY * 0.08 -
-            interaction.gazeY * 0.08;
-        const headYaw = bodyYaw - 0.04 + interaction.gazeX * 0.56;
-        const headPitch = bodyPitch - 0.02 - interaction.gazeY * 0.32;
-        const mantlePatches = resolveVisibleEllipsoidPatches({
-            center: mantleCenter,
-            radiusX: mantleRadiusX,
-            radiusY: mantleRadiusY,
-            radiusZ: mantleRadiusZ,
-            rotationX: headPitch,
-            rotationY: headYaw,
-            sceneCenterX,
-            sceneCenterY,
-            size,
-            palette,
-            verticalColorBias: 0,
-            outlineColor: `${palette.highlight}7a`,
-        });
-        const underbodyPatches = resolveVisibleEllipsoidPatches({
-            center: underbodyCenter,
-            radiusX: underbodyRadiusX,
-            radiusY: underbodyRadiusY,
-            radiusZ: underbodyRadiusZ,
-            rotationX: bodyPitch,
-            rotationY: bodyYaw,
-            sceneCenterX,
-            sceneCenterY,
-            size,
-            palette,
-            verticalColorBias: 0.18,
-            outlineColor: `${palette.shadow}8f`,
-        });
-        const tentacleStrokes = createOctopusTentacleStrokes({
-            createRandom,
-            morphologyProfile,
-            timeMs,
-            size,
-            center: underbodyCenter,
-            radiusX: underbodyRadiusX,
-            radiusY: underbodyRadiusY,
-            radiusZ: underbodyRadiusZ,
-            rotationX: bodyPitch,
-            rotationY: bodyYaw,
-            sceneCenterX,
-            sceneCenterY,
-            animationPhase,
-        });
-        const faceEyeSpacing = size * morphologyProfile.face.eyeSpacingRatio * 0.92;
-        const faceEyeYOffset = size * morphologyProfile.face.eyeCenterYOffsetRatio - mantleRadiusY * 0.02;
-        const faceEyeRadiusX = size * morphologyProfile.face.eyeRadiusXRatio * 0.82;
-        const faceEyeRadiusY = faceEyeRadiusX * morphologyProfile.face.eyeHeightRatio * 0.96;
-        const mouthHalfWidth = size * morphologyProfile.face.mouthWidthRatio * 0.92;
-        const mouthY = size * morphologyProfile.face.mouthYOffsetRatio + mantleRadiusY * 0.08;
-        drawAvatarFrame(context, size, palette);
-        drawOctopus3dAtmosphere(context, size, palette, sceneCenterX, sceneCenterY, interaction, timeMs);
-        drawOctopus3dShadow(context, size, palette, interaction, timeMs);
-        for (const tentacleStroke of tentacleStrokes.filter((candidateTentacleStroke) => !candidateTentacleStroke.isFrontFacing)) {
-            drawTentacleStroke(context, tentacleStroke, palette);
-        }
-        for (const surfacePatch of [...mantlePatches, ...underbodyPatches].sort((firstSurfacePatch, secondSurfacePatch) => firstSurfacePatch.averageDepth - secondSurfacePatch.averageDepth)) {
-            drawSurfacePatch(context, surfacePatch);
-        }
-        for (const tentacleStroke of tentacleStrokes.filter((candidateTentacleStroke) => candidateTentacleStroke.isFrontFacing)) {
-            drawTentacleStroke(context, tentacleStroke, palette);
-        }
-        drawProjectedOrganicEye(context, {
-            x: -faceEyeSpacing,
-            y: faceEyeYOffset,
-            z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, -faceEyeSpacing, faceEyeYOffset),
-        }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + leftEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
-        drawProjectedOrganicEye(context, {
-            x: faceEyeSpacing,
-            y: faceEyeYOffset,
-            z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, faceEyeSpacing, faceEyeYOffset),
-        }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + 0.7 + rightEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
-        drawProjectedOrganicMouth(context, [
-            {
-                x: -mouthHalfWidth,
-                y: mouthY,
-                z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, -mouthHalfWidth, mouthY),
-            },
-            {
-                x: size * morphologyProfile.face.mouthCenterOffsetRatio,
-                y: mouthY +
-                    size * morphologyProfile.face.mouthCurveDepthRatio * 0.38 +
-                    Math.sin(timeMs / 760 + animationPhase) * size * 0.01 +
-                    interaction.gazeY * size * 0.01,
-                z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, size * morphologyProfile.face.mouthCenterOffsetRatio, mouthY),
-            },
-            {
-                x: mouthHalfWidth,
-                y: mouthY,
-                z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, mouthHalfWidth, mouthY),
-            },
-        ], mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, palette, size);
-    },
-};
-/**
- * Draws the atmospheric underwater glow behind the octopus mesh.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function drawOctopus3dAtmosphere(context, size, palette, sceneCenterX, sceneCenterY, interaction, timeMs) {
-    const glowGradient = context.createRadialGradient(sceneCenterX + interaction.gazeX * size * 0.1, sceneCenterY - size * 0.2 + interaction.gazeY * size * 0.05, size * 0.04, sceneCenterX, sceneCenterY - size * 0.04, size * 0.62);
-    glowGradient.addColorStop(0, `${palette.highlight}5c`);
-    glowGradient.addColorStop(0.36, `${palette.accent}24`);
-    glowGradient.addColorStop(1, `${palette.highlight}00`);
-    context.fillStyle = glowGradient;
-    context.fillRect(0, 0, size, size);
-    const lowerGradient = context.createRadialGradient(sceneCenterX + Math.sin(timeMs / 1700) * size * 0.05, sceneCenterY + size * 0.23, size * 0.08, sceneCenterX, sceneCenterY + size * 0.28, size * 0.5);
-    lowerGradient.addColorStop(0, `${palette.secondary}1d`);
-    lowerGradient.addColorStop(1, `${palette.secondary}00`);
-    context.fillStyle = lowerGradient;
-    context.fillRect(0, 0, size, size);
-}
-/**
- * Draws the soft ground shadow below the octopus.
- *
- * Uses a scaled radial gradient instead of `context.filter = 'blur()'` to approximate the
- * blurry ellipse without triggering a costly software rasterization pass on every frame.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function drawOctopus3dShadow(context, size, palette, interaction, timeMs) {
-    const cx = size * 0.5 + interaction.gazeX * size * 0.04;
-    const cy = size * 0.87 + Math.sin(timeMs / 920) * size * 0.008;
-    const rx = size * (0.18 + interaction.intensity * 0.02);
-    const ry = size * 0.06;
-    context.save();
-    context.translate(cx, cy);
-    context.scale(1, ry / rx);
-    const blurRadius = rx * 1.4;
-    const shadowGradient = context.createRadialGradient(0, 0, 0, 0, 0, blurRadius);
-    shadowGradient.addColorStop(0, `${palette.shadow}7a`);
-    shadowGradient.addColorStop(0.45, `${palette.shadow}44`);
-    shadowGradient.addColorStop(0.8, `${palette.shadow}1a`);
-    shadowGradient.addColorStop(1, `${palette.shadow}00`);
-    context.fillStyle = shadowGradient;
-    context.beginPath();
-    context.arc(0, 0, blurRadius, 0, Math.PI * 2);
-    context.fill();
-    context.restore();
-}
-/**
- * Resolves visible projected patches for one rotated ellipsoid mesh.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function resolveVisibleEllipsoidPatches(options) {
-    const { center, radiusX, radiusY, radiusZ, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, verticalColorBias, outlineColor, } = options;
-    const latitudePatchCount = 10;
-    const longitudePatchCount = 18;
-    const surfacePatches = [];
-    for (let latitudeIndex = 0; latitudeIndex < latitudePatchCount; latitudeIndex++) {
-        const startLatitude = -Math.PI / 2 + (latitudeIndex / latitudePatchCount) * Math.PI;
-        const endLatitude = -Math.PI / 2 + ((latitudeIndex + 1) / latitudePatchCount) * Math.PI;
-        const verticalProgress = (latitudeIndex + 0.5) / latitudePatchCount;
-        for (let longitudeIndex = 0; longitudeIndex < longitudePatchCount; longitudeIndex++) {
-            const startLongitude = -Math.PI + (longitudeIndex / longitudePatchCount) * Math.PI * 2;
-            const endLongitude = -Math.PI + ((longitudeIndex + 1) / longitudePatchCount) * Math.PI * 2;
-            const localCorners = [
-                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, startLatitude, startLongitude),
-                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, startLatitude, endLongitude),
-                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, endLatitude, endLongitude),
-                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, endLatitude, startLongitude),
-            ];
-            const transformedCorners = localCorners.map((localCorner) => transformScenePoint(localCorner, center, rotationX, rotationY));
-            const surfaceNormal = normalizeVector3(crossProduct3D(subtractPoint3D(transformedCorners[1], transformedCorners[0]), subtractPoint3D(transformedCorners[2], transformedCorners[0])));
-            if (surfaceNormal.z <= 0.01) {
-                continue;
-            }
-            const projectedCorners = transformedCorners.map((transformedCorner) => projectScenePoint(transformedCorner, size, sceneCenterX, sceneCenterY));
-            surfacePatches.push({
-                corners: projectedCorners,
-                averageDepth: transformedCorners.reduce((depthSum, transformedCorner) => depthSum + transformedCorner.z, 0) /
-                    transformedCorners.length,
-                lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION$3), -1, 1),
-                fillStyle: resolveSurfacePatchFillStyle(palette, verticalProgress + verticalColorBias),
-                outlineColor,
-            });
-        }
-    }
-    return surfacePatches;
-}
-/**
- * Samples one point on an ellipsoid aligned to the local axes.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function sampleEllipsoidPoint(radiusX, radiusY, radiusZ, latitude, longitude) {
-    const cosineLatitude = Math.cos(latitude);
-    return {
-        x: Math.sin(longitude) * cosineLatitude * radiusX,
-        y: Math.sin(latitude) * radiusY,
-        z: Math.cos(longitude) * cosineLatitude * radiusZ,
-    };
-}
-/**
- * Resolves one base fill tone for a surface patch across the octopus body.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function resolveSurfacePatchFillStyle(palette, verticalProgress) {
-    const clampedVerticalProgress = clampNumber$1(verticalProgress, 0, 1);
-    if (clampedVerticalProgress < 0.2) {
-        return palette.highlight;
-    }
-    if (clampedVerticalProgress < 0.45) {
-        return palette.secondary;
-    }
-    if (clampedVerticalProgress < 0.8) {
-        return palette.primary;
-    }
-    return `${palette.shadow}f2`;
-}
-/**
- * Draws one projected mesh patch with organic shading.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function drawSurfacePatch(context, surfacePatch) {
-    drawProjectedQuad(context, surfacePatch.corners, surfacePatch.fillStyle);
-    if (surfacePatch.lightIntensity > 0) {
-        drawProjectedQuad(context, surfacePatch.corners, `rgba(255, 255, 255, ${0.15 * surfacePatch.lightIntensity})`);
-    }
-    else if (surfacePatch.lightIntensity < 0) {
-        drawProjectedQuad(context, surfacePatch.corners, `rgba(0, 0, 0, ${0.24 * Math.abs(surfacePatch.lightIntensity)})`);
-    }
-    context.save();
-    context.beginPath();
-    context.moveTo(surfacePatch.corners[0].x, surfacePatch.corners[0].y);
-    for (let cornerIndex = 1; cornerIndex < surfacePatch.corners.length; cornerIndex++) {
-        context.lineTo(surfacePatch.corners[cornerIndex].x, surfacePatch.corners[cornerIndex].y);
-    }
-    context.closePath();
-    context.strokeStyle = surfacePatch.outlineColor;
-    context.lineWidth = Math.max(1, getProjectedQuadPerimeter(surfacePatch.corners) * 0.0044);
-    context.lineJoin = 'round';
-    context.stroke();
-    context.restore();
-}
-/**
- * Creates the projected 3D tentacle strokes orbiting around the lower octopus body.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function createOctopusTentacleStrokes(options) {
-    const { createRandom, morphologyProfile, timeMs, size, center, radiusX, radiusY, radiusZ, rotationX, rotationY, sceneCenterX, sceneCenterY, animationPhase, } = options;
-    return Array.from({ length: morphologyProfile.tentacles.count }, (_, tentacleIndex) => {
-        const tentacleRandom = createRandom(`octopus3d-tentacle-${tentacleIndex}`);
-        const spreadProgress = morphologyProfile.tentacles.count === 1 ? 0.5 : tentacleIndex / (morphologyProfile.tentacles.count - 1);
-        const orbitAngle = -Math.PI * 0.92 + spreadProgress * Math.PI * 1.84 + (tentacleRandom() - 0.5) * 0.16;
-        const flowLength = size * (0.19 + morphologyProfile.tentacles.flowLengthScale * 0.075 + tentacleRandom() * 0.018);
-        const lateralReach = size *
-            (0.08 + morphologyProfile.tentacles.lateralReachScale * 0.05 + Math.abs(Math.sin(orbitAngle)) * 0.018);
-        const depthReach = size * (0.028 + morphologyProfile.tentacles.tipReachScale * 0.032);
-        const sway = Math.sin(timeMs / (760 + tentacleIndex * 36) + animationPhase + tentacleRandom() * Math.PI * 2);
-        const anchorPoint = {
-            x: Math.sin(orbitAngle) * radiusX * (0.84 + tentacleRandom() * 0.08),
-            y: radiusY * (0.22 + tentacleRandom() * 0.18),
-            z: Math.cos(orbitAngle) * radiusZ * (0.72 + tentacleRandom() * 0.12),
-        };
-        const controlPointOne = {
-            x: anchorPoint.x + Math.sin(orbitAngle) * lateralReach * 0.44,
-            y: anchorPoint.y + flowLength * 0.26,
-            z: anchorPoint.z + Math.cos(orbitAngle) * depthReach * 0.3 + sway * size * 0.012,
-        };
-        const controlPointTwo = {
-            x: anchorPoint.x +
-                Math.sin(orbitAngle) * lateralReach * (0.82 + morphologyProfile.tentacles.swayScale * 0.12),
-            y: anchorPoint.y + flowLength * 0.66,
-            z: anchorPoint.z + Math.cos(orbitAngle) * depthReach * 0.72 + sway * size * 0.02,
-        };
-        const endPoint = {
-            x: anchorPoint.x +
-                Math.sin(orbitAngle) * lateralReach * (1.02 + morphologyProfile.tentacles.tipWidthScale * 0.12) +
-                sway * size * 0.028,
-            y: anchorPoint.y + flowLength,
-            z: anchorPoint.z + Math.cos(orbitAngle) * depthReach + sway * size * 0.016,
-        };
-        const scenePoints = Array.from({ length: 12 }, (_, sampleIndex) => transformScenePoint(sampleCubicBezierPoint3D(anchorPoint, controlPointOne, controlPointTwo, endPoint, sampleIndex / 11), center, rotationX, rotationY));
-        const projectedPoints = scenePoints.map((scenePoint) => projectScenePoint(scenePoint, size, sceneCenterX, sceneCenterY));
-        const averageDepth = scenePoints.reduce((depthSum, scenePoint) => depthSum + scenePoint.z, 0) / scenePoints.length;
-        return {
-            projectedPoints,
-            averageDepth,
-            isFrontFacing: averageDepth >= center.z - size * 0.006,
-            baseWidth: size *
-                (0.019 +
-                    morphologyProfile.tentacles.baseWidthScale * 0.007 +
-                    tentacleRandom() * 0.003 +
-                    Math.abs(Math.sin(orbitAngle)) * 0.002),
-            tipWidth: size * (0.0046 + morphologyProfile.tentacles.tipWidthScale * 0.0018),
-            colorBias: tentacleRandom(),
-        };
-    });
-}
-/**
- * Samples one point on a cubic Bezier curve in 3D.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function sampleCubicBezierPoint3D(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,
-        z: inverseProgress * inverseProgress * inverseProgress * startPoint.z +
-            3 * inverseProgress * inverseProgress * progress * controlPointOne.z +
-            3 * inverseProgress * progress * progress * controlPointTwo.z +
-            progress * progress * progress * endPoint.z,
-    };
-}
-/**
- * Draws one projected tentacle stroke with a slim highlight ridge.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function drawTentacleStroke(context, tentacleStroke, palette) {
-    const projectedSegments = tentacleStroke.projectedPoints.length - 1;
-    for (let segmentIndex = 0; segmentIndex < projectedSegments; segmentIndex++) {
-        const startPoint = tentacleStroke.projectedPoints[segmentIndex];
-        const endPoint = tentacleStroke.projectedPoints[segmentIndex + 1];
-        const progress = segmentIndex / projectedSegments;
-        const width = tentacleStroke.baseWidth + (tentacleStroke.tipWidth - tentacleStroke.baseWidth) * progress;
-        context.beginPath();
-        context.moveTo(startPoint.x, startPoint.y);
-        context.lineTo(endPoint.x, endPoint.y);
-        context.strokeStyle = tentacleStroke.colorBias > 0.6 ? `${palette.secondary}f0` : `${palette.primary}f0`;
-        context.lineWidth = width;
-        context.lineCap = 'round';
-        context.stroke();
-        context.beginPath();
-        context.moveTo(startPoint.x, startPoint.y);
-        context.lineTo(endPoint.x, endPoint.y);
-        context.strokeStyle = tentacleStroke.isFrontFacing ? `${palette.highlight}80` : `${palette.highlight}40`;
-        context.lineWidth = Math.max(1, width * 0.34);
-        context.lineCap = 'round';
-        context.stroke();
-    }
-}
-/**
- * Resolves the front surface depth on an ellipsoid for one local face point.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function resolveEllipsoidSurfaceDepth(radiusX, radiusY, radiusZ, x, y) {
-    const normalizedX = x / radiusX;
-    const normalizedY = y / radiusY;
-    const remainingDepthRatio = Math.max(0, 1 - normalizedX * normalizedX - normalizedY * normalizedY);
-    return Math.sqrt(remainingDepthRatio) * radiusZ;
-}
-
 /* eslint-disable no-magic-numbers */
 /**
  * Light direction used by the single-mesh octopus shading.
  *
  * @private helper of `octopus3d2AvatarVisual`
  */
-const LIGHT_DIRECTION$2 = normalizeVector3({
+const LIGHT_DIRECTION$3 = normalizeVector3({
     x: 0.38,
     y: -0.6,
     z: 0.98,
@@ -15827,7 +15394,7 @@ function resolveVisibleBlobbyOctopusPatches(options) {
                     transformedCorners[2].z +
                     transformedCorners[3].z) /
                     4,
-                lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION$2), -1, 1),
+                lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION$3), -1, 1),
                 fillStyle: resolveBlobbySurfacePatchFillStyle$1(palette, verticalProgress, Math.max(0, Math.cos(centerLongitude)), resolveLowerLobeWave(centerLongitude, morphologyProfile, animationPhase, timeMs)),
                 outlineColor: verticalProgress < 0.58 ? `${palette.highlight}73` : `${palette.shadow}8a`,
             });
@@ -15942,7 +15509,7 @@ function drawBlobbySurfacePatch(context, surfacePatch) {
  *
  * @private helper of `octopus3d3AvatarVisual`
  */
-const LIGHT_DIRECTION$1 = normalizeVector3({
+const LIGHT_DIRECTION$2 = normalizeVector3({
     x: 0.34,
     y: -0.62,
     z: 1,
@@ -16249,7 +15816,7 @@ function resolveVisibleContinuousOctopusPatches(options) {
                     transformedCorners[2].z +
                     transformedCorners[3].z) /
                     4,
-                lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION$1), -1, 1),
+                lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION$2), -1, 1),
                 fillStyle: resolveContinuousSurfacePatchFillStyle(palette, verticalProgress, cachedCosByPatchCenterLongitude[longitudeIndex], cachedTentacleInfluencesByPatchCenterLongitude[longitudeIndex].core, cachedLobeWavesByPatchCenterLongitude[longitudeIndex]),
                 outlineColor: verticalProgress < 0.54 ? `${palette.highlight}69` : `${palette.shadow}78`,
             });
@@ -16564,7 +16131,7 @@ function smoothStep$1(edgeStart, edgeEnd, value) {
  *
  * @private helper of `octopus3d4AvatarVisual`
  */
-const LIGHT_DIRECTION = normalizeVector3({
+const LIGHT_DIRECTION$1 = normalizeVector3({
     x: 0.32,
     y: -0.66,
     z: 1,
@@ -16910,7 +16477,7 @@ function resolveVisibleBlobbyContinuousPatches(options) {
                 projectScenePoint(transformedCorners[2], size, sceneCenterX, sceneCenterY),
                 projectScenePoint(transformedCorners[3], size, sceneCenterX, sceneCenterY),
             ];
-            const lightIntensity = clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION), -1, 1);
+            const lightIntensity = clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION$1), -1, 1);
             const rimLightIntensity = Math.pow(clampNumber$1(dotProduct3D(surfaceNormal, RIM_LIGHT_DIRECTION), 0, 1), 2.6);
             surfacePatches.push({
                 corners: projectedCorners,
@@ -17309,6 +16876,445 @@ function formatAlphaHex(opacity) {
         .padStart(2, '0');
 }
 
+/* eslint-disable no-magic-numbers */
+/**
+ * Light direction used by the organic 3D octopus shading.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+const LIGHT_DIRECTION = normalizeVector3({
+    x: 0.48,
+    y: -0.62,
+    z: 0.94,
+});
+/**
+ * Cache keyed by the `createRandom` factory reference (stable per mounted `<Avatar/>`).
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+const octopus3dStableStateCache = new WeakMap();
+/**
+ * Returns the stable per-avatar state, computing it on first access and caching for subsequent frames.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function getOctopus3dStableState(createRandom) {
+    const cached = octopus3dStableStateCache.get(createRandom);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const animationRandom = createRandom('octopus3d-animation-profile');
+    const eyeRandom = createRandom('octopus3d-eye-profile');
+    const leftEyePhaseOffset = eyeRandom() * 0.6;
+    const rightEyePhaseOffset = eyeRandom() * 0.6;
+    const state = {
+        morphologyProfile: createOctopus3MorphologyProfile(createRandom),
+        animationPhase: animationRandom() * Math.PI * 2,
+        leftEyePhaseOffset,
+        rightEyePhaseOffset,
+    };
+    octopus3dStableStateCache.set(createRandom, state);
+    return state;
+}
+/**
+ * Proper 3D Octopus visual built from projected organic meshes and tentacles.
+ *
+ * @private built-in avatar visual
+ */
+const octopus3dAvatarVisual = {
+    id: 'octopus3d',
+    title: 'Octopus 3D',
+    description: 'Proper 3D octopus portrait with a turning silhouette, expressive eyes, and depth-sorted tentacles.',
+    isAnimated: true,
+    supportsPointerTracking: true,
+    render({ context, size, palette, createRandom, timeMs, interaction }) {
+        const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset } = getOctopus3dStableState(createRandom);
+        const sceneCenterX = size * 0.5;
+        const sceneCenterY = size * 0.56;
+        const bob = Math.sin(timeMs / 920 + animationPhase) * size * 0.014;
+        const mantleCenter = {
+            x: interaction.bodyOffsetX * size * 0.042 + size * morphologyProfile.body.centerXJitterRatio * 0.65,
+            y: -size * 0.09 + interaction.bodyOffsetY * size * 0.028 + bob,
+            z: interaction.intensity * size * 0.012,
+        };
+        const underbodyCenter = {
+            x: mantleCenter.x * 0.86,
+            y: mantleCenter.y + size * 0.168,
+            z: mantleCenter.z - size * 0.018,
+        };
+        const mantleRadiusX = size * morphologyProfile.body.bodyRadiusRatio * morphologyProfile.body.horizontalStretch;
+        const mantleRadiusY = size * morphologyProfile.body.bodyRadiusRatio * morphologyProfile.body.verticalStretch * 1.1;
+        const mantleRadiusZ = size *
+            morphologyProfile.body.bodyRadiusRatio *
+            (0.9 + (morphologyProfile.body.horizontalStretch - 1) * 0.3);
+        const underbodyRadiusX = mantleRadiusX * (0.9 + (morphologyProfile.tentacles.rootSpreadScale - 1) * 0.08);
+        const underbodyRadiusY = mantleRadiusY * (0.44 + morphologyProfile.body.lowerDropRatio * 3.1);
+        const underbodyRadiusZ = mantleRadiusZ * 0.78;
+        const bodyYaw = -0.18 +
+            Math.sin(timeMs / 2400 + animationPhase) * 0.05 +
+            interaction.bodyOffsetX * 0.18 +
+            interaction.gazeX * 0.22;
+        const bodyPitch = -0.08 +
+            Math.cos(timeMs / 2700 + animationPhase * 0.6) * 0.025 -
+            interaction.bodyOffsetY * 0.08 -
+            interaction.gazeY * 0.08;
+        const headYaw = bodyYaw - 0.04 + interaction.gazeX * 0.56;
+        const headPitch = bodyPitch - 0.02 - interaction.gazeY * 0.32;
+        const mantlePatches = resolveVisibleEllipsoidPatches({
+            center: mantleCenter,
+            radiusX: mantleRadiusX,
+            radiusY: mantleRadiusY,
+            radiusZ: mantleRadiusZ,
+            rotationX: headPitch,
+            rotationY: headYaw,
+            sceneCenterX,
+            sceneCenterY,
+            size,
+            palette,
+            verticalColorBias: 0,
+            outlineColor: `${palette.highlight}7a`,
+        });
+        const underbodyPatches = resolveVisibleEllipsoidPatches({
+            center: underbodyCenter,
+            radiusX: underbodyRadiusX,
+            radiusY: underbodyRadiusY,
+            radiusZ: underbodyRadiusZ,
+            rotationX: bodyPitch,
+            rotationY: bodyYaw,
+            sceneCenterX,
+            sceneCenterY,
+            size,
+            palette,
+            verticalColorBias: 0.18,
+            outlineColor: `${palette.shadow}8f`,
+        });
+        const tentacleStrokes = createOctopusTentacleStrokes({
+            createRandom,
+            morphologyProfile,
+            timeMs,
+            size,
+            center: underbodyCenter,
+            radiusX: underbodyRadiusX,
+            radiusY: underbodyRadiusY,
+            radiusZ: underbodyRadiusZ,
+            rotationX: bodyPitch,
+            rotationY: bodyYaw,
+            sceneCenterX,
+            sceneCenterY,
+            animationPhase,
+        });
+        const faceEyeSpacing = size * morphologyProfile.face.eyeSpacingRatio * 0.92;
+        const faceEyeYOffset = size * morphologyProfile.face.eyeCenterYOffsetRatio - mantleRadiusY * 0.02;
+        const faceEyeRadiusX = size * morphologyProfile.face.eyeRadiusXRatio * 0.82;
+        const faceEyeRadiusY = faceEyeRadiusX * morphologyProfile.face.eyeHeightRatio * 0.96;
+        const mouthHalfWidth = size * morphologyProfile.face.mouthWidthRatio * 0.92;
+        const mouthY = size * morphologyProfile.face.mouthYOffsetRatio + mantleRadiusY * 0.08;
+        drawAvatarFrame(context, size, palette);
+        drawOctopus3dAtmosphere(context, size, palette, sceneCenterX, sceneCenterY, interaction, timeMs);
+        drawOctopus3dShadow(context, size, palette, interaction, timeMs);
+        for (const tentacleStroke of tentacleStrokes.filter((candidateTentacleStroke) => !candidateTentacleStroke.isFrontFacing)) {
+            drawTentacleStroke(context, tentacleStroke, palette);
+        }
+        for (const surfacePatch of [...mantlePatches, ...underbodyPatches].sort((firstSurfacePatch, secondSurfacePatch) => firstSurfacePatch.averageDepth - secondSurfacePatch.averageDepth)) {
+            drawSurfacePatch(context, surfacePatch);
+        }
+        for (const tentacleStroke of tentacleStrokes.filter((candidateTentacleStroke) => candidateTentacleStroke.isFrontFacing)) {
+            drawTentacleStroke(context, tentacleStroke, palette);
+        }
+        drawProjectedOrganicEye(context, {
+            x: -faceEyeSpacing,
+            y: faceEyeYOffset,
+            z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, -faceEyeSpacing, faceEyeYOffset),
+        }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + leftEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
+        drawProjectedOrganicEye(context, {
+            x: faceEyeSpacing,
+            y: faceEyeYOffset,
+            z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, faceEyeSpacing, faceEyeYOffset),
+        }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + 0.7 + rightEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
+        drawProjectedOrganicMouth(context, [
+            {
+                x: -mouthHalfWidth,
+                y: mouthY,
+                z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, -mouthHalfWidth, mouthY),
+            },
+            {
+                x: size * morphologyProfile.face.mouthCenterOffsetRatio,
+                y: mouthY +
+                    size * morphologyProfile.face.mouthCurveDepthRatio * 0.38 +
+                    Math.sin(timeMs / 760 + animationPhase) * size * 0.01 +
+                    interaction.gazeY * size * 0.01,
+                z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, size * morphologyProfile.face.mouthCenterOffsetRatio, mouthY),
+            },
+            {
+                x: mouthHalfWidth,
+                y: mouthY,
+                z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, mouthHalfWidth, mouthY),
+            },
+        ], mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, palette, size);
+    },
+};
+/**
+ * Draws the atmospheric underwater glow behind the octopus mesh.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function drawOctopus3dAtmosphere(context, size, palette, sceneCenterX, sceneCenterY, interaction, timeMs) {
+    const glowGradient = context.createRadialGradient(sceneCenterX + interaction.gazeX * size * 0.1, sceneCenterY - size * 0.2 + interaction.gazeY * size * 0.05, size * 0.04, sceneCenterX, sceneCenterY - size * 0.04, size * 0.62);
+    glowGradient.addColorStop(0, `${palette.highlight}5c`);
+    glowGradient.addColorStop(0.36, `${palette.accent}24`);
+    glowGradient.addColorStop(1, `${palette.highlight}00`);
+    context.fillStyle = glowGradient;
+    context.fillRect(0, 0, size, size);
+    const lowerGradient = context.createRadialGradient(sceneCenterX + Math.sin(timeMs / 1700) * size * 0.05, sceneCenterY + size * 0.23, size * 0.08, sceneCenterX, sceneCenterY + size * 0.28, size * 0.5);
+    lowerGradient.addColorStop(0, `${palette.secondary}1d`);
+    lowerGradient.addColorStop(1, `${palette.secondary}00`);
+    context.fillStyle = lowerGradient;
+    context.fillRect(0, 0, size, size);
+}
+/**
+ * Draws the soft ground shadow below the octopus.
+ *
+ * Uses a scaled radial gradient instead of `context.filter = 'blur()'` to approximate the
+ * blurry ellipse without triggering a costly software rasterization pass on every frame.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function drawOctopus3dShadow(context, size, palette, interaction, timeMs) {
+    const cx = size * 0.5 + interaction.gazeX * size * 0.04;
+    const cy = size * 0.87 + Math.sin(timeMs / 920) * size * 0.008;
+    const rx = size * (0.18 + interaction.intensity * 0.02);
+    const ry = size * 0.06;
+    context.save();
+    context.translate(cx, cy);
+    context.scale(1, ry / rx);
+    const blurRadius = rx * 1.4;
+    const shadowGradient = context.createRadialGradient(0, 0, 0, 0, 0, blurRadius);
+    shadowGradient.addColorStop(0, `${palette.shadow}7a`);
+    shadowGradient.addColorStop(0.45, `${palette.shadow}44`);
+    shadowGradient.addColorStop(0.8, `${palette.shadow}1a`);
+    shadowGradient.addColorStop(1, `${palette.shadow}00`);
+    context.fillStyle = shadowGradient;
+    context.beginPath();
+    context.arc(0, 0, blurRadius, 0, Math.PI * 2);
+    context.fill();
+    context.restore();
+}
+/**
+ * Resolves visible projected patches for one rotated ellipsoid mesh.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function resolveVisibleEllipsoidPatches(options) {
+    const { center, radiusX, radiusY, radiusZ, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, verticalColorBias, outlineColor, } = options;
+    const latitudePatchCount = 10;
+    const longitudePatchCount = 18;
+    const surfacePatches = [];
+    for (let latitudeIndex = 0; latitudeIndex < latitudePatchCount; latitudeIndex++) {
+        const startLatitude = -Math.PI / 2 + (latitudeIndex / latitudePatchCount) * Math.PI;
+        const endLatitude = -Math.PI / 2 + ((latitudeIndex + 1) / latitudePatchCount) * Math.PI;
+        const verticalProgress = (latitudeIndex + 0.5) / latitudePatchCount;
+        for (let longitudeIndex = 0; longitudeIndex < longitudePatchCount; longitudeIndex++) {
+            const startLongitude = -Math.PI + (longitudeIndex / longitudePatchCount) * Math.PI * 2;
+            const endLongitude = -Math.PI + ((longitudeIndex + 1) / longitudePatchCount) * Math.PI * 2;
+            const localCorners = [
+                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, startLatitude, startLongitude),
+                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, startLatitude, endLongitude),
+                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, endLatitude, endLongitude),
+                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, endLatitude, startLongitude),
+            ];
+            const transformedCorners = localCorners.map((localCorner) => transformScenePoint(localCorner, center, rotationX, rotationY));
+            const surfaceNormal = normalizeVector3(crossProduct3D(subtractPoint3D(transformedCorners[1], transformedCorners[0]), subtractPoint3D(transformedCorners[2], transformedCorners[0])));
+            if (surfaceNormal.z <= 0.01) {
+                continue;
+            }
+            const projectedCorners = transformedCorners.map((transformedCorner) => projectScenePoint(transformedCorner, size, sceneCenterX, sceneCenterY));
+            surfacePatches.push({
+                corners: projectedCorners,
+                averageDepth: transformedCorners.reduce((depthSum, transformedCorner) => depthSum + transformedCorner.z, 0) /
+                    transformedCorners.length,
+                lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION), -1, 1),
+                fillStyle: resolveSurfacePatchFillStyle(palette, verticalProgress + verticalColorBias),
+                outlineColor,
+            });
+        }
+    }
+    return surfacePatches;
+}
+/**
+ * Samples one point on an ellipsoid aligned to the local axes.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function sampleEllipsoidPoint(radiusX, radiusY, radiusZ, latitude, longitude) {
+    const cosineLatitude = Math.cos(latitude);
+    return {
+        x: Math.sin(longitude) * cosineLatitude * radiusX,
+        y: Math.sin(latitude) * radiusY,
+        z: Math.cos(longitude) * cosineLatitude * radiusZ,
+    };
+}
+/**
+ * Resolves one base fill tone for a surface patch across the octopus body.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function resolveSurfacePatchFillStyle(palette, verticalProgress) {
+    const clampedVerticalProgress = clampNumber$1(verticalProgress, 0, 1);
+    if (clampedVerticalProgress < 0.2) {
+        return palette.highlight;
+    }
+    if (clampedVerticalProgress < 0.45) {
+        return palette.secondary;
+    }
+    if (clampedVerticalProgress < 0.8) {
+        return palette.primary;
+    }
+    return `${palette.shadow}f2`;
+}
+/**
+ * Draws one projected mesh patch with organic shading.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function drawSurfacePatch(context, surfacePatch) {
+    drawProjectedQuad(context, surfacePatch.corners, surfacePatch.fillStyle);
+    if (surfacePatch.lightIntensity > 0) {
+        drawProjectedQuad(context, surfacePatch.corners, `rgba(255, 255, 255, ${0.15 * surfacePatch.lightIntensity})`);
+    }
+    else if (surfacePatch.lightIntensity < 0) {
+        drawProjectedQuad(context, surfacePatch.corners, `rgba(0, 0, 0, ${0.24 * Math.abs(surfacePatch.lightIntensity)})`);
+    }
+    context.save();
+    context.beginPath();
+    context.moveTo(surfacePatch.corners[0].x, surfacePatch.corners[0].y);
+    for (let cornerIndex = 1; cornerIndex < surfacePatch.corners.length; cornerIndex++) {
+        context.lineTo(surfacePatch.corners[cornerIndex].x, surfacePatch.corners[cornerIndex].y);
+    }
+    context.closePath();
+    context.strokeStyle = surfacePatch.outlineColor;
+    context.lineWidth = Math.max(1, getProjectedQuadPerimeter(surfacePatch.corners) * 0.0044);
+    context.lineJoin = 'round';
+    context.stroke();
+    context.restore();
+}
+/**
+ * Creates the projected 3D tentacle strokes orbiting around the lower octopus body.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function createOctopusTentacleStrokes(options) {
+    const { createRandom, morphologyProfile, timeMs, size, center, radiusX, radiusY, radiusZ, rotationX, rotationY, sceneCenterX, sceneCenterY, animationPhase, } = options;
+    return Array.from({ length: morphologyProfile.tentacles.count }, (_, tentacleIndex) => {
+        const tentacleRandom = createRandom(`octopus3d-tentacle-${tentacleIndex}`);
+        const spreadProgress = morphologyProfile.tentacles.count === 1 ? 0.5 : tentacleIndex / (morphologyProfile.tentacles.count - 1);
+        const orbitAngle = -Math.PI * 0.92 + spreadProgress * Math.PI * 1.84 + (tentacleRandom() - 0.5) * 0.16;
+        const flowLength = size * (0.19 + morphologyProfile.tentacles.flowLengthScale * 0.075 + tentacleRandom() * 0.018);
+        const lateralReach = size *
+            (0.08 + morphologyProfile.tentacles.lateralReachScale * 0.05 + Math.abs(Math.sin(orbitAngle)) * 0.018);
+        const depthReach = size * (0.028 + morphologyProfile.tentacles.tipReachScale * 0.032);
+        const sway = Math.sin(timeMs / (760 + tentacleIndex * 36) + animationPhase + tentacleRandom() * Math.PI * 2);
+        const anchorPoint = {
+            x: Math.sin(orbitAngle) * radiusX * (0.84 + tentacleRandom() * 0.08),
+            y: radiusY * (0.22 + tentacleRandom() * 0.18),
+            z: Math.cos(orbitAngle) * radiusZ * (0.72 + tentacleRandom() * 0.12),
+        };
+        const controlPointOne = {
+            x: anchorPoint.x + Math.sin(orbitAngle) * lateralReach * 0.44,
+            y: anchorPoint.y + flowLength * 0.26,
+            z: anchorPoint.z + Math.cos(orbitAngle) * depthReach * 0.3 + sway * size * 0.012,
+        };
+        const controlPointTwo = {
+            x: anchorPoint.x +
+                Math.sin(orbitAngle) * lateralReach * (0.82 + morphologyProfile.tentacles.swayScale * 0.12),
+            y: anchorPoint.y + flowLength * 0.66,
+            z: anchorPoint.z + Math.cos(orbitAngle) * depthReach * 0.72 + sway * size * 0.02,
+        };
+        const endPoint = {
+            x: anchorPoint.x +
+                Math.sin(orbitAngle) * lateralReach * (1.02 + morphologyProfile.tentacles.tipWidthScale * 0.12) +
+                sway * size * 0.028,
+            y: anchorPoint.y + flowLength,
+            z: anchorPoint.z + Math.cos(orbitAngle) * depthReach + sway * size * 0.016,
+        };
+        const scenePoints = Array.from({ length: 12 }, (_, sampleIndex) => transformScenePoint(sampleCubicBezierPoint3D(anchorPoint, controlPointOne, controlPointTwo, endPoint, sampleIndex / 11), center, rotationX, rotationY));
+        const projectedPoints = scenePoints.map((scenePoint) => projectScenePoint(scenePoint, size, sceneCenterX, sceneCenterY));
+        const averageDepth = scenePoints.reduce((depthSum, scenePoint) => depthSum + scenePoint.z, 0) / scenePoints.length;
+        return {
+            projectedPoints,
+            averageDepth,
+            isFrontFacing: averageDepth >= center.z - size * 0.006,
+            baseWidth: size *
+                (0.019 +
+                    morphologyProfile.tentacles.baseWidthScale * 0.007 +
+                    tentacleRandom() * 0.003 +
+                    Math.abs(Math.sin(orbitAngle)) * 0.002),
+            tipWidth: size * (0.0046 + morphologyProfile.tentacles.tipWidthScale * 0.0018),
+            colorBias: tentacleRandom(),
+        };
+    });
+}
+/**
+ * Samples one point on a cubic Bezier curve in 3D.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function sampleCubicBezierPoint3D(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,
+        z: inverseProgress * inverseProgress * inverseProgress * startPoint.z +
+            3 * inverseProgress * inverseProgress * progress * controlPointOne.z +
+            3 * inverseProgress * progress * progress * controlPointTwo.z +
+            progress * progress * progress * endPoint.z,
+    };
+}
+/**
+ * Draws one projected tentacle stroke with a slim highlight ridge.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function drawTentacleStroke(context, tentacleStroke, palette) {
+    const projectedSegments = tentacleStroke.projectedPoints.length - 1;
+    for (let segmentIndex = 0; segmentIndex < projectedSegments; segmentIndex++) {
+        const startPoint = tentacleStroke.projectedPoints[segmentIndex];
+        const endPoint = tentacleStroke.projectedPoints[segmentIndex + 1];
+        const progress = segmentIndex / projectedSegments;
+        const width = tentacleStroke.baseWidth + (tentacleStroke.tipWidth - tentacleStroke.baseWidth) * progress;
+        context.beginPath();
+        context.moveTo(startPoint.x, startPoint.y);
+        context.lineTo(endPoint.x, endPoint.y);
+        context.strokeStyle = tentacleStroke.colorBias > 0.6 ? `${palette.secondary}f0` : `${palette.primary}f0`;
+        context.lineWidth = width;
+        context.lineCap = 'round';
+        context.stroke();
+        context.beginPath();
+        context.moveTo(startPoint.x, startPoint.y);
+        context.lineTo(endPoint.x, endPoint.y);
+        context.strokeStyle = tentacleStroke.isFrontFacing ? `${palette.highlight}80` : `${palette.highlight}40`;
+        context.lineWidth = Math.max(1, width * 0.34);
+        context.lineCap = 'round';
+        context.stroke();
+    }
+}
+/**
+ * Resolves the front surface depth on an ellipsoid for one local face point.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function resolveEllipsoidSurfaceDepth(radiusX, radiusY, radiusZ, x, y) {
+    const normalizedX = x / radiusX;
+    const normalizedY = y / radiusY;
+    const remainingDepthRatio = Math.max(0, 1 - normalizedX * normalizedX - normalizedY * normalizedY);
+    return Math.sqrt(remainingDepthRatio) * radiusZ;
+}
+
 /* eslint-disable no-magic-numbers */
 /**
  * Octopus avatar visual.
@@ -18129,14 +18135,14 @@ function resolveAvatarVisualId(value) {
 /**
  * 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`.
+ * The `META AVATAR` and `META VISUAL` commitments set 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');
+    constructor(type = 'META AVATAR') {
+        super(type);
     }
     /**
      * Short one-line description of META AVATAR.
@@ -18156,14 +18162,15 @@ class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition {
     get documentation() {
         const supportedVisuals = AVATAR_VISUALS.map((avatarVisual) => `\`${avatarVisual.id}\``).join(', ');
         return spaceTrim$1(`
-            # META AVATAR
+            # ${this.type}
 
             Sets the built-in avatar visual used for the agent when no explicit \`META IMAGE\` is provided.
+            \`META AVATAR\` and \`META VISUAL\` are equivalent.
 
             ## Key aspects
 
             - Does not modify the agent's behavior or responses.
-            - Only one \`META AVATAR\` should be used per agent.
+            - Only one \`META AVATAR\` or \`META VISUAL\` 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}.
@@ -18178,15 +18185,15 @@ class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition {
             \`\`\`
 
             \`\`\`book
-            Orb Assistant
+            Minecraft Assistant
 
-            META AVATAR orb
+            META VISUAL Minecraft2
             GOAL Answer in a calm and focused way.
             \`\`\`
         `);
     }
     applyToAgentModelRequirements(requirements, content) {
-        // META AVATAR doesn't modify the system message or model requirements.
+        // META AVATAR and META VISUAL don't modify the system message or model requirements.
         // It's handled separately in the parsing logic for profile avatar resolution.
         return requirements;
     }
@@ -27340,6 +27347,7 @@ const COMMITMENT_REGISTRY = [
     new ActionCommitmentDefinition('ACTIONS'),
     new ComponentCommitmentDefinition(),
     new MetaAvatarCommitmentDefinition(),
+    new MetaAvatarCommitmentDefinition('META VISUAL'),
     new MetaImageCommitmentDefinition(),
     new MetaColorCommitmentDefinition(),
     new MetaFontCommitmentDefinition(),
@@ -28682,6 +28690,7 @@ function hasHttpProtocol(value) {
  */
 const META_COMMITMENT_APPLIERS = {
     'META AVATAR': applyMetaAvatarContent,
+    'META VISUAL': applyMetaAvatarContent,
     'META LINK': applyMetaLinkContent,
     'META DOMAIN': applyMetaDomainContent,
     'META IMAGE': applyMetaImageContent,
@@ -28730,7 +28739,7 @@ function applyGenericMetaCommitment(state, content) {
     state.meta[metaType] = metaValue;
 }
 /**
- * Applies META AVATAR content into the canonical `meta.avatar` field.
+ * Applies META AVATAR / META VISUAL content into the canonical `meta.avatar` field.
  */
 function applyMetaAvatarContent(state, content) {
     const avatarVisualId = resolveAvatarVisualId(content);
@@ -29910,6 +29919,7 @@ const PROFILE_COMMITMENT_TYPES = new Set([
     'PERSONAE',
     'META',
     'META AVATAR',
+    'META VISUAL',
     'META IMAGE',
     'META LINK',
     'META DOMAIN',
@@ -30169,7 +30179,7 @@ function createStandaloneBookLanguageMarkdown() {
             4. **Add capabilities**
             Add only necessary \`USE*\` and/or \`MEMORY\` commitments.
             5. **Set profile metadata**
-            Add \`META DESCRIPTION\`, \`META AVATAR\` or \`META IMAGE\`, \`META INPUT PLACEHOLDER\`, and disclaimers if needed.
+            Add \`META DESCRIPTION\`, \`META AVATAR\` / \`META VISUAL\` or \`META IMAGE\`, \`META INPUT PLACEHOLDER\`, and disclaimers if needed.
             6. **Add first interaction**
             Add \`INITIAL MESSAGE\` and optionally sample \`USER MESSAGE\` / \`AGENT MESSAGE\` pairs.
             7. **Close for deterministic behavior (optional)**
@@ -35966,51 +35976,47 @@ function $isRunningInWebWorker() {
 // TODO: [🎺]
 
 /**
- * Creates a message with all registered LLM tools
+ * Path to the `.env` file which was used to configure LLM tools
  *
- * Note: This function is used to create a (error) message when there is no constructor for some LLM provider
- *
- * @private internal function of `createLlmToolsFromConfiguration` and `$provideLlmToolsFromEnv`
+ * Note: `$` is used to indicate that this variable is changed by side effect in `$provideLlmToolsConfigurationFromEnv` through `$setUsedEnvFilename`
  */
-function $registeredLlmToolsMessage() {
-    const registeredLlmToolsMessageContext = createRegisteredLlmToolsMessageContext();
-    if (registeredLlmToolsMessageContext.llmToolStatuses.length === 0) {
-        return renderNoRegisteredLlmToolsMessage(registeredLlmToolsMessageContext.usedEnvMessage);
-    }
-    return renderRegisteredLlmToolsMessage(registeredLlmToolsMessageContext);
-}
+let $usedEnvFilename = null;
 /**
- * Collects all state needed to render the provider summary.
+ * Shared state for the `.env` file used to configure LLM tools.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private internal state of `$registeredLlmToolsMessage`
  */
-function createRegisteredLlmToolsMessageContext() {
-    const isRunningInNode = $isRunningInNode();
-    const env = getAvailableEnvironmentVariables(isRunningInNode);
-    const registeredLlmToolRegisters = getRegisteredLlmToolRegisters();
-    return {
-        env,
-        llmToolStatuses: listRegisteredLlmToolStatuses(registeredLlmToolRegisters, env),
-        usedEnvMessage: createUsedEnvMessage(),
-        isRunningInNode,
-    };
-}
+const USED_ENV_FILENAME = {
+    set(filepath) {
+        $usedEnvFilename = filepath;
+    },
+    createMessage() {
+        return $usedEnvFilename === null
+            ? `Unknown \`.env\` file`
+            : spaceTrim$1(`
+                  Used \`.env\` file:
+                  ${$usedEnvFilename}
+              `);
+    },
+};
+
 /**
  * Reads environment variables relevant for provider configuration.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function getAvailableEnvironmentVariables(isRunningInNode) {
+function getAvailableRegisteredLlmToolsEnvironmentVariables(isRunningInNode) {
     if (isRunningInNode) {
         return process.env;
         // <- TODO: [⚛] Some DRY way how to get to `process.env` and pass it into functions - ACRY search for `env`
     }
     return {};
 }
+
 /**
  * Takes stable snapshots of both LLM provider registers.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function getRegisteredLlmToolRegisters() {
     return {
@@ -36018,62 +36024,30 @@ function getRegisteredLlmToolRegisters() {
         registeredTools: $llmToolsRegister.list(),
     };
 }
-/**
- * Lists provider entries enriched with installation and configuration state.
- *
- * @private internal function of `$registeredLlmToolsMessage`
- */
-function listRegisteredLlmToolStatuses({ registeredMetadata, registeredTools }, env) {
-    return listRegisteredLlmToolEntries(registeredMetadata, registeredTools).map((registeredLlmToolEntry) => createRegisteredLlmToolStatus({ registeredLlmToolEntry, registeredMetadata, registeredTools, env }));
-}
-/**
- * Merges provider entries from the metadata and constructor registers.
- *
- * @private internal function of `$registeredLlmToolsMessage`
- */
-function listRegisteredLlmToolEntries(registeredMetadata, registeredTools) {
-    const registeredLlmToolEntries = new Map();
-    for (const { title, packageName, className, envVariables } of registeredMetadata) {
-        addRegisteredLlmToolEntry(registeredLlmToolEntries, { title, packageName, className, envVariables });
-    }
-    for (const { packageName, className } of registeredTools) {
-        addRegisteredLlmToolEntry(registeredLlmToolEntries, { packageName, className });
-    }
-    return [...registeredLlmToolEntries.values()];
-}
-/**
- * Adds a provider entry only when the provider is not already present.
- *
- * @private internal function of `$registeredLlmToolsMessage`
- */
-function addRegisteredLlmToolEntry(registeredLlmToolEntries, registeredLlmToolEntry) {
-    const registeredLlmToolEntryKey = createRegisteredLlmToolEntryKey(registeredLlmToolEntry);
-    if (registeredLlmToolEntries.has(registeredLlmToolEntryKey)) {
-        return;
-    }
-    registeredLlmToolEntries.set(registeredLlmToolEntryKey, registeredLlmToolEntry);
-}
+
 /**
  * Creates a deduplication key for a provider entry.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function createRegisteredLlmToolEntryKey({ packageName, className }) {
     return `${packageName}::${className}`;
 }
+
 /**
  * Checks whether the given provider entry already exists in the target register list.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function hasRegisteredLlmToolEntry(registeredLlmToolEntries, registeredLlmToolEntry) {
     const registeredLlmToolEntryKey = createRegisteredLlmToolEntryKey(registeredLlmToolEntry);
     return registeredLlmToolEntries.some((listedRegisteredLlmToolEntry) => createRegisteredLlmToolEntryKey(listedRegisteredLlmToolEntry) === registeredLlmToolEntryKey);
 }
+
 /**
  * Builds the runtime status for one provider entry.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function createRegisteredLlmToolStatus({ registeredLlmToolEntry, registeredMetadata, registeredTools, env, }) {
     const availabilityStatus = createRegisteredLlmToolAvailabilityStatus(registeredLlmToolEntry, registeredMetadata, registeredTools);
@@ -36087,7 +36061,7 @@ function createRegisteredLlmToolStatus({ registeredLlmToolEntry, registeredMetad
 /**
  * Resolves whether the provider has metadata and a registered constructor.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function createRegisteredLlmToolAvailabilityStatus(registeredLlmToolEntry, registeredMetadata, registeredTools) {
     return {
@@ -36098,7 +36072,7 @@ function createRegisteredLlmToolAvailabilityStatus(registeredLlmToolEntry, regis
 /**
  * Resolves whether the provider has enough environment variables to be configured.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function createRegisteredLlmToolConfigurationStatus({ envVariables }, env) {
     return {
@@ -36109,7 +36083,7 @@ function createRegisteredLlmToolConfigurationStatus({ envVariables }, env) {
 /**
  * Checks whether all required environment variables are present for a provider.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function isRegisteredLlmToolFullyConfigured(envVariables, env) {
     if (envVariables === undefined || envVariables === null) {
@@ -36120,7 +36094,7 @@ function isRegisteredLlmToolFullyConfigured(envVariables, env) {
 /**
  * Checks whether at least one required environment variable is present for a provider.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function isRegisteredLlmToolPartiallyConfigured(envVariables, env) {
     if (envVariables === undefined || envVariables === null) {
@@ -36128,109 +36102,128 @@ function isRegisteredLlmToolPartiallyConfigured(envVariables, env) {
     }
     return envVariables.some((envVariableName) => env[envVariableName] !== undefined);
 }
+
 /**
- * Renders the fallback message for environments with no registered providers.
+ * Merges provider entries from the metadata and constructor registers.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function renderNoRegisteredLlmToolsMessage(usedEnvMessage) {
-    return spaceTrim$1((block) => `
-            No LLM providers are available.
-
-            ${block(usedEnvMessage)}
-      `);
+function listRegisteredLlmToolEntries(registeredMetadata, registeredTools) {
+    const registeredLlmToolEntries = new Map();
+    for (const { title, packageName, className, envVariables } of registeredMetadata) {
+        addRegisteredLlmToolEntry(registeredLlmToolEntries, { title, packageName, className, envVariables });
+    }
+    for (const { packageName, className } of registeredTools) {
+        addRegisteredLlmToolEntry(registeredLlmToolEntries, { packageName, className });
+    }
+    return [...registeredLlmToolEntries.values()];
 }
 /**
- * Renders the full provider status summary.
+ * Adds a provider entry only when the provider is not already present.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function renderRegisteredLlmToolsMessage({ env, llmToolStatuses, usedEnvMessage, isRunningInNode, }) {
-    return spaceTrim$1((block) => `
-
-            ${block(usedEnvMessage)}
-
-            Relevant environment variables:
-            ${block(renderRelevantEnvironmentVariables(env, llmToolStatuses))}
-
-            Available LLM providers are:
-            ${block(renderAvailableProviders(llmToolStatuses, env, isRunningInNode))}
-        `);
+function addRegisteredLlmToolEntry(registeredLlmToolEntries, registeredLlmToolEntry) {
+    const registeredLlmToolEntryKey = createRegisteredLlmToolEntryKey(registeredLlmToolEntry);
+    if (registeredLlmToolEntries.has(registeredLlmToolEntryKey)) {
+        return;
+    }
+    registeredLlmToolEntries.set(registeredLlmToolEntryKey, registeredLlmToolEntry);
 }
+
 /**
- * Renders the list of environment variables used by at least one registered provider.
+ * Lists provider entries enriched with installation and configuration state.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function renderRelevantEnvironmentVariables(env, llmToolStatuses) {
-    return listRelevantEnvironmentVariables(env, llmToolStatuses)
-        .map((envVariableName) => `- \`${envVariableName}\``)
-        .join('\n');
+function listRegisteredLlmToolStatuses({ registeredMetadata, registeredTools }, env) {
+    return listRegisteredLlmToolEntries(registeredMetadata, registeredTools).map((registeredLlmToolEntry) => createRegisteredLlmToolStatus({ registeredLlmToolEntry, registeredMetadata, registeredTools, env }));
 }
+
 /**
- * Lists environment variables that are both present and used by at least one provider.
+ * Collects all state needed to render the provider summary.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function listRelevantEnvironmentVariables(env, llmToolStatuses) {
-    return Object.keys(env).filter((envVariableName) => llmToolStatuses.some(({ envVariables }) => envVariables === null || envVariables === void 0 ? void 0 : envVariables.includes(envVariableName)));
+function createRegisteredLlmToolsMessageContext() {
+    const isRunningInNode = $isRunningInNode();
+    const env = getAvailableRegisteredLlmToolsEnvironmentVariables(isRunningInNode);
+    const registeredLlmToolRegisters = getRegisteredLlmToolRegisters();
+    return {
+        env,
+        llmToolStatuses: listRegisteredLlmToolStatuses(registeredLlmToolRegisters, env),
+        usedEnvMessage: USED_ENV_FILENAME.createMessage(),
+        isRunningInNode,
+    };
 }
+
 /**
- * Renders all provider lines in the status summary.
+ * Renders the fallback message for environments with no registered providers.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function renderAvailableProviders(llmToolStatuses, env, isRunningInNode) {
-    return llmToolStatuses
-        .map((llmToolStatus, index) => renderAvailableProvider(llmToolStatus, index, env, isRunningInNode))
-        .join('\n');
+function renderNoRegisteredLlmToolsMessage(usedEnvMessage) {
+    return spaceTrim$1((block) => `
+            No LLM providers are available.
+
+            ${block(usedEnvMessage)}
+      `);
 }
+
 /**
- * Renders one provider line in the status summary.
+ * Creates the configuration-status sentence for one provider.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function renderAvailableProvider(llmToolStatus, index, env, isRunningInNode) {
-    const providerMessage = createAvailableProviderMessage(llmToolStatus, index, env);
-    if (!isRunningInNode) {
-        return providerMessage;
+function createRegisteredLlmToolConfigurationStatusMessage({ envVariables, isFullyConfigured, isPartiallyConfigured }, env) {
+    if (isFullyConfigured) {
+        return `Configured`;
+    }
+    if (isPartiallyConfigured) {
+        return createPartiallyConfiguredStatusMessage(envVariables, env);
+    }
+    if (envVariables !== null) {
+        return createNotConfiguredStatusMessage(envVariables);
     }
-    return colorizeAvailableProviderMessage(providerMessage, llmToolStatus);
+    return `Not configured`;
+    // <- Note: Can not be configured via environment variables
 }
 /**
- * Creates the plain-text provider line before optional colorization.
+ * Creates the partial-configuration sentence including missing variables.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createAvailableProviderMessage(llmToolStatus, index, env) {
-    const { title, packageName, className } = llmToolStatus;
-    const providerStatusMessages = createProviderStatusMessages(llmToolStatus, env);
-    return spaceTrim$1(`
-        ${index + 1}) **${title}** \`${className}\` from \`${packageName}\`
-            ${providerStatusMessages.join('; ')}
-    `);
+function createPartiallyConfiguredStatusMessage(envVariables, env) {
+    return `Partially confugured, missing ${listMissingEnvironmentVariables(envVariables, env).join(' + ')}`;
 }
 /**
- * Creates the install and configuration fragments for one provider line.
+ * Creates the not-configured sentence including the expected environment variables.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+function createNotConfiguredStatusMessage(envVariables) {
+    return `Not configured, to configure set env ${envVariables === null || envVariables === void 0 ? void 0 : envVariables.join(' + ')}`;
+}
+/**
+ * Lists environment variables that are required but currently missing.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createProviderStatusMessages(llmToolStatus, env) {
-    return [createInstallationStatusMessage(llmToolStatus), createConfigurationStatusMessage(llmToolStatus, env)];
+function listMissingEnvironmentVariables(envVariables, env) {
+    return (envVariables === null || envVariables === void 0 ? void 0 : envVariables.filter((envVariable) => env[envVariable] === undefined)) || [];
 }
+
 /**
  * Creates the installation-status sentence for one provider.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createInstallationStatusMessage({ isMetadataAvailable, isInstalled, }) {
-    const installationStatusKey = createInstallationStatusKey(isMetadataAvailable, isInstalled);
+function createRegisteredLlmToolInstallationStatusMessage({ isMetadataAvailable, isInstalled, }) {
+    const installationStatusKey = createRegisteredLlmToolInstallationStatusKey(isMetadataAvailable, isInstalled);
     switch (installationStatusKey) {
         case 'missing-metadata-and-installation':
-            // TODO: [�][�] Maybe do allow to do auto-install if package not registered and not found
             return `Not installed and no metadata, looks like a unexpected behavior`;
         case 'metadata-without-installation':
-            // TODO: [�][�]
             return `Not installed`;
         case 'installation-without-metadata':
             return `No metadata but installed, looks like a unexpected behavior`;
@@ -36243,9 +36236,9 @@ function createInstallationStatusMessage({ isMetadataAvailable, isInstalled, })
 /**
  * Creates a stable installation-state key from metadata and constructor availability.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createInstallationStatusKey(isMetadataAvailable, isInstalled) {
+function createRegisteredLlmToolInstallationStatusKey(isMetadataAvailable, isInstalled) {
     if (!isMetadataAvailable && !isInstalled) {
         return 'missing-metadata-and-installation';
     }
@@ -36260,54 +36253,59 @@ function createInstallationStatusKey(isMetadataAvailable, isInstalled) {
     }
     return 'unknown';
 }
+
 /**
- * Creates the configuration-status sentence for one provider.
+ * Renders all provider lines in the status summary.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createConfigurationStatusMessage({ envVariables, isFullyConfigured, isPartiallyConfigured }, env) {
-    if (isFullyConfigured) {
-        return `Configured`;
-    }
-    if (isPartiallyConfigured) {
-        return createPartiallyConfiguredStatusMessage(envVariables, env);
-    }
-    if (envVariables !== null) {
-        return createNotConfiguredStatusMessage(envVariables);
-    }
-    return `Not configured`;
-    // <- Note: Can not be configured via environment variables
+function renderAvailableRegisteredLlmTools(llmToolStatuses, env, isRunningInNode) {
+    return llmToolStatuses
+        .map((llmToolStatus, index) => renderAvailableRegisteredLlmTool(llmToolStatus, index, env, isRunningInNode))
+        .join('\n');
 }
 /**
- * Creates the partial-configuration sentence including missing variables.
+ * Renders one provider line in the status summary.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createPartiallyConfiguredStatusMessage(envVariables, env) {
-    return `Partially confugured, missing ${listMissingEnvironmentVariables(envVariables, env).join(' + ')}`;
+function renderAvailableRegisteredLlmTool(llmToolStatus, index, env, isRunningInNode) {
+    const providerMessage = createAvailableRegisteredLlmToolMessage(llmToolStatus, index, env);
+    if (!isRunningInNode) {
+        return providerMessage;
+    }
+    return colorizeAvailableRegisteredLlmToolMessage(providerMessage, llmToolStatus);
 }
 /**
- * Creates the not-configured sentence including the expected environment variables.
+ * Creates the plain-text provider line before optional colorization.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createNotConfiguredStatusMessage(envVariables) {
-    return `Not configured, to configure set env ${envVariables === null || envVariables === void 0 ? void 0 : envVariables.join(' + ')}`;
+function createAvailableRegisteredLlmToolMessage(llmToolStatus, index, env) {
+    const { title, packageName, className } = llmToolStatus;
+    const providerStatusMessages = createRegisteredLlmToolStatusMessages(llmToolStatus, env);
+    return spaceTrim$1(`
+        ${index + 1}) **${title}** \`${className}\` from \`${packageName}\`
+            ${providerStatusMessages.join('; ')}
+    `);
 }
 /**
- * Lists environment variables that are required but currently missing.
+ * Creates the install and configuration fragments for one provider line.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function listMissingEnvironmentVariables(envVariables, env) {
-    return (envVariables === null || envVariables === void 0 ? void 0 : envVariables.filter((envVariable) => env[envVariable] === undefined)) || [];
+function createRegisteredLlmToolStatusMessages(llmToolStatus, env) {
+    return [
+        createRegisteredLlmToolInstallationStatusMessage(llmToolStatus),
+        createRegisteredLlmToolConfigurationStatusMessage(llmToolStatus, env),
+    ];
 }
 /**
  * Applies the same terminal coloring rules as the original summary renderer.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function colorizeAvailableProviderMessage(providerMessage, { isInstalled, isFullyConfigured, isPartiallyConfigured }) {
+function colorizeAvailableRegisteredLlmToolMessage(providerMessage, { isInstalled, isFullyConfigured, isPartiallyConfigured }) {
     if (isInstalled && isFullyConfigured) {
         return colors.green(providerMessage);
     }
@@ -36316,14 +36314,57 @@ function colorizeAvailableProviderMessage(providerMessage, { isInstalled, isFull
     }
     return colors.gray(providerMessage);
 }
+
+/**
+ * Renders the list of environment variables used by at least one registered provider.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+function renderRelevantRegisteredLlmToolsEnvironmentVariables(env, llmToolStatuses) {
+    return listRelevantRegisteredLlmToolsEnvironmentVariables(env, llmToolStatuses)
+        .map((envVariableName) => `- \`${envVariableName}\``)
+        .join('\n');
+}
+/**
+ * Lists environment variables that are both present and used by at least one provider.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+function listRelevantRegisteredLlmToolsEnvironmentVariables(env, llmToolStatuses) {
+    return Object.keys(env).filter((envVariableName) => llmToolStatuses.some(({ envVariables }) => envVariables === null || envVariables === void 0 ? void 0 : envVariables.includes(envVariableName)));
+}
+
+/**
+ * Renders the full provider status summary.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+function renderRegisteredLlmToolsMessage({ env, llmToolStatuses, usedEnvMessage, isRunningInNode, }) {
+    return spaceTrim$1((block) => `
+
+            ${block(usedEnvMessage)}
+
+            Relevant environment variables:
+            ${block(renderRelevantRegisteredLlmToolsEnvironmentVariables(env, llmToolStatuses))}
+
+            Available LLM providers are:
+            ${block(renderAvailableRegisteredLlmTools(llmToolStatuses, env, isRunningInNode))}
+        `);
+}
+
 /**
- * Creates the `.env` origin sentence used in the summary header.
+ * Creates a message with all registered LLM tools
+ *
+ * Note: This function is used to create a (error) message when there is no constructor for some LLM provider
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private internal function of `createLlmToolsFromConfiguration` and `$provideLlmToolsFromEnv`
  */
-function createUsedEnvMessage() {
-    return `Unknown \`.env\` file`
-        ;
+function $registeredLlmToolsMessage() {
+    const registeredLlmToolsMessageContext = createRegisteredLlmToolsMessageContext();
+    if (registeredLlmToolsMessageContext.llmToolStatuses.length === 0) {
+        return renderNoRegisteredLlmToolsMessage(registeredLlmToolsMessageContext.usedEnvMessage);
+    }
+    return renderRegisteredLlmToolsMessage(registeredLlmToolsMessageContext);
 }
 // TODO: [®] DRY Register logic
 // TODO: [🧠][⚛] Maybe pass env as argument