@promptbook/google 0.111.0-4 → 0.112.0-100

package/umd/index.umd.js

@@ -1,12 +1,11 @@
 (function (global, factory) {
     typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('crypto'), require('spacetrim'), require('colors')) :
     typeof define === 'function' && define.amd ? define(['exports', 'crypto', 'spacetrim', 'colors'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-google"] = {}, global.crypto, global.spaceTrim$1, global.colors));
-})(this, (function (exports, crypto, spaceTrim$1, colors) { 'use strict';
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-google"] = {}, global.crypto, global.spacetrim, global.colors));
+})(this, (function (exports, crypto, spacetrim, colors) { 'use strict';
 
     function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
-    var spaceTrim__default = /*#__PURE__*/_interopDefaultLegacy(spaceTrim$1);
     var colors__default = /*#__PURE__*/_interopDefaultLegacy(colors);
 
     // ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
@@ -23,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.111.0-4';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-100';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -35,16 +34,15 @@
      * Note: `$` is used to indicate that this function is not a pure function - it is not deterministic
      * Note: This function is cryptographically secure (it uses crypto.randomBytes internally)
      *
-     * @private internal helper function
      * @returns secure random token
+     *
+     * @private internal helper function
      */
     function $randomToken(randomness) {
         return crypto.randomBytes(randomness).toString('hex');
     }
-    /**
-     * TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
-     * TODO: Maybe use nanoid instead https://github.com/ai/nanoid
-     */
+    // TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
+    // TODO: Maybe use nanoid instead https://github.com/ai/nanoid
 
     /**
      * This error indicates errors during the execution of the pipeline
@@ -61,9 +59,7 @@
             Object.setPrototypeOf(this, PipelineExecutionError.prototype);
         }
     }
-    /**
-     * TODO: [🧠][🌂] Add id to all errors
-     */
+    // TODO: [🧠][🌂] Add id to all errors
 
     /**
      * Counts number of characters in the text
@@ -79,10 +75,8 @@
         text = text.replace(/\p{Extended_Pictographic}(\u{200D}\p{Extended_Pictographic})*/gu, '-');
         return text.length;
     }
-    /**
-     * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
-     * TODO: [🧠][✌️] Make some Promptbook-native token system
-     */
+    // TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+    // TODO: [🧠][✌️] Make some Promptbook-native token system
 
     /**
      * Number of characters per standard line with 11pt Arial font size.
@@ -96,10 +90,8 @@
      * @public exported from `@promptbook/utils`
      */
     const LINES_PER_STANDARD_PAGE = 44;
-    /**
-     * TODO: [🧠] Should be this `constants.ts` or `config.ts`?
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // TODO: [🧠] Should be this `constants.ts` or `config.ts`?
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Counts number of lines in the text
@@ -117,10 +109,8 @@
         const lines = text.split(/\r?\n/);
         return lines.reduce((count, line) => count + Math.max(Math.ceil(line.length / CHARACTERS_PER_STANDARD_LINE), 1), 0);
     }
-    /**
-     * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
-     * TODO: [🧠][✌️] Make some Promptbook-native token system
-     */
+    // TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+    // TODO: [🧠][✌️] Make some Promptbook-native token system
 
     /**
      * Counts number of pages in the text
@@ -132,10 +122,8 @@
     function countPages(text) {
         return Math.ceil(countLines(text) / LINES_PER_STANDARD_PAGE);
     }
-    /**
-     * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
-     * TODO: [🧠][✌️] Make some Promptbook-native token system
-     */
+    // TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+    // TODO: [🧠][✌️] Make some Promptbook-native token system
 
     /**
      * Counts number of paragraphs in the text
@@ -145,10 +133,8 @@
     function countParagraphs(text) {
         return text.split(/\n\s*\n/).filter((paragraph) => paragraph.trim() !== '').length;
     }
-    /**
-     * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
-     * TODO: [🧠][✌️] Make some Promptbook-native token system
-     */
+    // TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+    // TODO: [🧠][✌️] Make some Promptbook-native token system
 
     /**
      * Split text into sentences
@@ -166,11 +152,12 @@
     function countSentences(text) {
         return splitIntoSentences(text).length;
     }
+    // TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+    // TODO: [🧠][✌️] Make some Promptbook-native token system
+
     /**
-     * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
-     * TODO: [🧠][✌️] Make some Promptbook-native token system
+     * Collection of default diacritics removal map.
      */
-
     const defaultDiacriticsRemovalMap = [
         {
             base: 'A',
@@ -422,6 +409,7 @@
      *
      * @param input The string containing diacritics to be normalized.
      * @returns The string with diacritics removed or normalized.
+     *
      * @public exported from `@promptbook/utils`
      */
     function removeDiacritics(input) {
@@ -430,9 +418,7 @@
             return DIACRITIC_VARIANTS_LETTERS[character] || character;
         });
     }
-    /**
-     * TODO: [Ж] Variant for cyrillic (and in general non-latin) letters
-     */
+    // TODO: [Ж] Variant for cyrillic (and in general non-latin) letters
 
     /**
      * Counts number of words in the text
@@ -446,11 +432,9 @@
         text = text.replace(/([a-z])([A-Z])/g, '$1 $2');
         return text.split(/[^a-zа-я0-9]+/i).filter((word) => word.length > 0).length;
     }
-    /**
-     * TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
-     * TODO: [🧠][✌️] Make some Promptbook-native token system
-     * TODO: [✌️] `countWords` should be just `splitWords(...).length`, and all other counters should use this pattern as well
-     */
+    // TODO: [🥴] Implement counting in formats - like JSON, CSV, XML,...
+    // TODO: [🧠][✌️] Make some Promptbook-native token system
+    // TODO: [✌️] `countWords` should be just `splitWords(...).length`, and all other counters should use this pattern as well
 
     /**
      * Helper of usage compute
@@ -478,6 +462,7 @@
      * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
      *
      * @returns The same object as the input, but deeply frozen
+     *
      * @public exported from `@promptbook/utils`
      */
     function $deepFreeze(objectValue) {
@@ -494,9 +479,7 @@
         Object.freeze(objectValue);
         return objectValue;
     }
-    /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
-     */
+    // TODO: [🧠] Is there a way how to meaningfully test this utility
 
     /**
      * Represents the uncertain value
@@ -517,6 +500,7 @@
      */
     $deepFreeze({
         price: ZERO_VALUE,
+        duration: ZERO_VALUE,
         input: {
             tokensCount: ZERO_VALUE,
             charactersCount: ZERO_VALUE,
@@ -543,6 +527,7 @@
      */
     $deepFreeze({
         price: UNCERTAIN_ZERO_VALUE,
+        duration: UNCERTAIN_ZERO_VALUE,
         input: {
             tokensCount: UNCERTAIN_ZERO_VALUE,
             charactersCount: UNCERTAIN_ZERO_VALUE,
@@ -562,9 +547,7 @@
             pagesCount: UNCERTAIN_ZERO_VALUE,
         },
     });
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Make UncertainNumber
@@ -600,9 +583,7 @@
             return false;
         }
     }
-    /**
-     * TODO: [🎺]
-     */
+    // TODO: [🎺]
 
     /**
      * Simple wrapper `new Date().toISOString()`
@@ -610,6 +591,7 @@
      * Note: `$` is used to indicate that this function is not a pure function - it is not deterministic because it depends on the current time
      *
      * @returns string_date branded type
+     *
      * @public exported from `@promptbook/utils`
      */
     function $getCurrentDate() {
@@ -620,16 +602,20 @@
      * Trims string from all 4 sides
      *
      * Note: This is a re-exported function from the `spacetrim` package which is
-     *       Developed by same author @hejny as this package
+     * Developed by same author @hejny as this package
      *
-     * @public exported from `@promptbook/utils`
      * @see https://github.com/hejny/spacetrim#usage
+     *
+     * @public exported from `@promptbook/utils`
      */
-    const spaceTrim = spaceTrim$1.spaceTrim;
+    const spaceTrim = spacetrim.spaceTrim;
 
     /**
-     * @private util of `@promptbook/color`
+     * Class implementing take chain.
+     *
      * @de
+     *
+     * @private util of `@promptbook/color`
      */
     class TakeChain {
         constructor(value) {
@@ -646,9 +632,9 @@
      *
      * @param {*} initialValue - The initial value.
      * @returns {Proxy<WithTake<TValue>>} - A proxy object with a `take` method.
+     * @deprecated [🤡] Use some better functional library instead of `TakeChain`
      *
      * @private util of `@promptbook/color`
-     * @deprecated [🤡] Use some better functional library instead of `TakeChain`
      */
     function take(initialValue) {
         if (initialValue instanceof TakeChain) {
@@ -826,9 +812,7 @@
         yellow: '#ffff00',
         yellowgreen: '#9acd32',
     };
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // 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.
@@ -858,6 +842,369 @@
         }
     }
 
+    /**
+     * Shared immutable channel storage and serialization helpers for `Color`.
+     *
+     * @private base class of Color
+     */
+    class ColorValue {
+        constructor(red, green, blue, alpha = 255) {
+            this.red = red;
+            this.green = green;
+            this.blue = blue;
+            this.alpha = alpha;
+            checkChannelValue('Red', red);
+            checkChannelValue('Green', green);
+            checkChannelValue('Blue', blue);
+            checkChannelValue('Alpha', alpha);
+        }
+        /**
+         * Shortcut for `red` property
+         * Number from 0 to 255
+         * @alias red
+         */
+        get r() {
+            return this.red;
+        }
+        /**
+         * Shortcut for `green` property
+         * Number from 0 to 255
+         * @alias green
+         */
+        get g() {
+            return this.green;
+        }
+        /**
+         * Shortcut for `blue` property
+         * Number from 0 to 255
+         * @alias blue
+         */
+        get b() {
+            return this.blue;
+        }
+        /**
+         * Shortcut for `alpha` property
+         * Number from 0 (transparent) to 255 (opaque)
+         * @alias alpha
+         */
+        get a() {
+            return this.alpha;
+        }
+        /**
+         * Shortcut for `alpha` property
+         * Number from 0 (transparent) to 255 (opaque)
+         * @alias alpha
+         */
+        get opacity() {
+            return this.alpha;
+        }
+        /**
+         * Shortcut for 1-`alpha` property
+         */
+        get transparency() {
+            return 255 - this.alpha;
+        }
+        clone() {
+            return take(this.createColor(this.red, this.green, this.blue, this.alpha));
+        }
+        toString() {
+            return this.toHex();
+        }
+        toHex() {
+            if (this.alpha === 255) {
+                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}`;
+            }
+            else {
+                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
+            }
+        }
+        toRgb() {
+            if (this.alpha === 255) {
+                return `rgb(${this.red}, ${this.green}, ${this.blue})`;
+            }
+            else {
+                return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
+            }
+        }
+        toHsl() {
+            throw new Error(`Getting HSL is not implemented`);
+        }
+    }
+
+    /**
+     * Checks if the given value is a valid hex color string
+     *
+     * @param value - value to check
+     * @returns true if the value is a valid hex color string (e.g., `#009edd`, `#fff`, etc.)
+     *
+     * @private function of Color
+     */
+    function isHexColorString(value) {
+        return (typeof value === 'string' && /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(value));
+    }
+
+    /**
+     * Constant for short hex lengths.
+     */
+    const SHORT_HEX_LENGTHS = new Set([3, 4]);
+    /**
+     * Constant for long hex lengths.
+     */
+    const LONG_HEX_LENGTHS = new Set([6, 8]);
+    /**
+     * Parses a hex string into RGBA channel values.
+     *
+     * @param hex - Hex value such as `#09d`, `009edd`, `#009eddff`.
+     * @returns RGBA channel values.
+     *
+     * @private function of Color
+     */
+    function parseHexColor(hex) {
+        const sanitized = hex.startsWith('#') ? hex.substring(1) : hex;
+        const throwInvalidHex = () => {
+            throw new Error(`Can not parse color from hex string "${hex}"`);
+        };
+        if (SHORT_HEX_LENGTHS.has(sanitized.length)) {
+            return {
+                red: parseShortHexChannel(sanitized.charAt(0), throwInvalidHex),
+                green: parseShortHexChannel(sanitized.charAt(1), throwInvalidHex),
+                blue: parseShortHexChannel(sanitized.charAt(2), throwInvalidHex),
+                alpha: sanitized.length === 4 ? parseShortHexChannel(sanitized.charAt(3), throwInvalidHex) : 255,
+            };
+        }
+        if (LONG_HEX_LENGTHS.has(sanitized.length)) {
+            return {
+                red: parseLongHexChannel(sanitized, 0, throwInvalidHex),
+                green: parseLongHexChannel(sanitized, 2, throwInvalidHex),
+                blue: parseLongHexChannel(sanitized, 4, throwInvalidHex),
+                alpha: sanitized.length === 8 ? parseLongHexChannel(sanitized, 6, throwInvalidHex) : 255,
+            };
+        }
+        return throwInvalidHex();
+    }
+    /**
+     * Parses short hex channel.
+     */
+    function parseShortHexChannel(char, onError) {
+        if (!char) {
+            return onError();
+        }
+        const parsed = parseInt(char, 16);
+        if (Number.isNaN(parsed)) {
+            return onError();
+        }
+        return parsed * 16;
+    }
+    /**
+     * Parses long hex channel.
+     */
+    function parseLongHexChannel(hex, start, onError) {
+        const segment = hex.substr(start, 2);
+        if (segment.length < 2) {
+            return onError();
+        }
+        const parsed = parseInt(segment, 16);
+        if (Number.isNaN(parsed)) {
+            return onError();
+        }
+        return parsed;
+    }
+
+    /**
+     * Pattern matching hsl.
+     */
+    const HSL_REGEX = /^hsl\(\s*([0-9.]+)\s*,\s*([0-9.]+)%\s*,\s*([0-9.]+)%\s*\)$/;
+    /**
+     * Parses an HSL string into RGBA channel values.
+     *
+     * @param hsl - HSL string such as `hsl(197.1, 100%, 43.3%)`.
+     * @returns RGBA channel values.
+     *
+     * @private function of Color
+     */
+    function parseHslColor(hsl) {
+        const match = hsl.match(HSL_REGEX);
+        if (!match) {
+            throw new Error(`Invalid hsl string format: "${hsl}"`);
+        }
+        const hue = parseFloat(match[1]);
+        const saturation = parseFloat(match[2]) / 100;
+        const lightness = parseFloat(match[3]) / 100;
+        const { red, green, blue } = convertHslToRgb(hue, saturation, lightness);
+        return {
+            red,
+            green,
+            blue,
+            alpha: 255,
+        };
+    }
+    /**
+     * Handles convert hsl to Rgb.
+     */
+    function convertHslToRgb(h, s, l) {
+        const c = (1 - Math.abs(2 * l - 1)) * s;
+        const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+        const m = l - c / 2;
+        let r1 = 0;
+        let g1 = 0;
+        let b1 = 0;
+        if (h >= 0 && h < 60) {
+            r1 = c;
+            g1 = x;
+        }
+        else if (h >= 60 && h < 120) {
+            r1 = x;
+            g1 = c;
+        }
+        else if (h >= 120 && h < 180) {
+            g1 = c;
+            b1 = x;
+        }
+        else if (h >= 180 && h < 240) {
+            g1 = x;
+            b1 = c;
+        }
+        else if (h >= 240 && h < 300) {
+            r1 = x;
+            b1 = c;
+        }
+        else if (h >= 300 && h < 360) {
+            r1 = c;
+            b1 = x;
+        }
+        return {
+            red: Math.round((r1 + m) * 255),
+            green: Math.round((g1 + m) * 255),
+            blue: Math.round((b1 + m) * 255),
+        };
+    }
+
+    /**
+     * Pattern matching RGB.
+     */
+    const RGB_REGEX = /^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+    /**
+     * Pattern matching rgba.
+     */
+    const RGBA_REGEX = /^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+    /**
+     * Parses an RGB string into RGBA channel values.
+     *
+     * @param rgb - RGB string such as `rgb(0%, 62%, 86.7%)`.
+     * @returns RGBA channel values.
+     *
+     * @private function of Color
+     */
+    function parseRgbColor(rgb) {
+        const match = rgb.match(RGB_REGEX);
+        if (!match) {
+            throw new Error(`Invalid rgb string format: "${rgb}"`);
+        }
+        return {
+            red: parseChannelValue(match[1]),
+            green: parseChannelValue(match[2]),
+            blue: parseChannelValue(match[3]),
+            alpha: 255,
+        };
+    }
+    /**
+     * Parses an RGBA string into RGBA channel values.
+     *
+     * @param rgba - RGBA string such as `rgba(0, 158, 221, 0.5)`.
+     * @returns RGBA channel values.
+     *
+     * @private function of Color
+     */
+    function parseRgbaColor(rgba) {
+        const match = rgba.match(RGBA_REGEX);
+        if (!match) {
+            throw new Error(`Invalid rgba string format: "${rgba}"`);
+        }
+        return {
+            red: parseChannelValue(match[1]),
+            green: parseChannelValue(match[2]),
+            blue: parseChannelValue(match[3]),
+            alpha: parseAlphaValue(match[4]),
+        };
+    }
+    /**
+     * Parses channel value.
+     */
+    function parseChannelValue(value) {
+        if (value.endsWith('%')) {
+            const percent = parseFloat(value);
+            return Math.round((percent / 100) * 255);
+        }
+        return Math.round(parseFloat(value));
+    }
+    /**
+     * Parses alpha value.
+     */
+    function parseAlphaValue(value) {
+        if (value.endsWith('%')) {
+            const percent = parseFloat(value);
+            return Math.round((percent / 100) * 255);
+        }
+        const parsed = parseFloat(value);
+        if (parsed <= 1) {
+            return Math.round(parsed * 255);
+        }
+        return Math.round(parsed);
+    }
+
+    /**
+     * Pattern matching hsl regex.
+     *
+     * @private function of Color
+     */
+    const HSL_REGEX_PATTERN = /^hsl\(\s*([0-9.]+)\s*,\s*([0-9.]+)%\s*,\s*([0-9.]+)%\s*\)$/;
+    /**
+     * Pattern matching RGB regex.
+     *
+     * @private function of Color
+     */
+    const RGB_REGEX_PATTERN = /^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+    /**
+     * Pattern matching rgba regex.
+     *
+     * @private function of Color
+     */
+    const RGBA_REGEX_PATTERN = /^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+    /**
+     * Parses a supported color string into RGBA channels.
+     *
+     * @param color as a string for example `#009edd`, `rgb(0,158,221)`, `rgb(0%,62%,86.7%)`, `hsl(197.1,100%,43.3%)`, `red`, `darkgrey`,...
+     * @returns RGBA channel values.
+     *
+     * @private function of Color
+     */
+    function parseColorString(color) {
+        const trimmed = color.trim();
+        const cssColor = CSS_COLORS[trimmed];
+        if (cssColor) {
+            return parseColorString(cssColor);
+        }
+        else if (isHexColorString(trimmed)) {
+            return parseHexColor(trimmed);
+        }
+        if (HSL_REGEX_PATTERN.test(trimmed)) {
+            return parseHslColor(trimmed);
+        }
+        else if (RGB_REGEX_PATTERN.test(trimmed)) {
+            return parseRgbColor(trimmed);
+        }
+        else if (RGBA_REGEX_PATTERN.test(trimmed)) {
+            return parseRgbaColor(trimmed);
+        }
+        else {
+            throw new Error(`Can not create a new Color instance from string "${trimmed}".`);
+        }
+    }
+
     /**
      * Color object represents an RGB color with alpha channel
      *
@@ -865,7 +1212,7 @@
      *
      * @public exported from `@promptbook/color`
      */
-    class Color {
+    class Color extends ColorValue {
         /**
          * Creates a new Color instance from miscellaneous formats
          * - It can receive Color instance and just return the same instance
@@ -938,30 +1285,7 @@
          * @returns Color object
          */
         static fromString(color) {
-            if (CSS_COLORS[color]) {
-                return Color.fromString(CSS_COLORS[color]);
-                // -----
-            }
-            else if (Color.isHexColorString(color)) {
-                return Color.fromHex(color);
-                // -----
-            }
-            else if (/^hsl\(\s*(\d+)\s*,\s*(\d+(?:\.\d+)?%)\s*,\s*(\d+(?:\.\d+)?%)\)$/.test(color)) {
-                return Color.fromHsl(color);
-                // -----
-            }
-            else if (/^rgb\((\s*[0-9-.%]+\s*,?){3}\)$/.test(color)) {
-                // TODO: [0] Should be fromRgbString and fromRgbaString one or two functions
-                return Color.fromRgbString(color);
-                // -----
-            }
-            else if (/^rgba\((\s*[0-9-.%]+\s*,?){4}\)$/.test(color)) {
-                return Color.fromRgbaString(color);
-                // -----
-            }
-            else {
-                throw new Error(`Can not create a new Color instance from string "${color}".`);
-            }
+            return Color.fromColorChannels(parseColorString(color));
         }
         /**
          * Gets common color
@@ -973,91 +1297,25 @@
             if (!CSS_COLORS[key]) {
                 throw new Error(`"${key}" is not a common css color.`);
             }
-            return Color.fromString(CSS_COLORS[key]);
-        }
-        /**
-         * Creates a new Color instance from average color of given image
-         *
-         * @param image as a source for example `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAA1JREFUGFdjYJh39z8ABJgCe/ZvAS4AAAAASUVORK5CYII=`
-         * @returns Color object
-         */
-        static async fromImage(image) {
-            return Color.fromHex(`#009edd`);
-        }
-        /**
-         * Creates a new Color instance from color in hex format
-         *
-         * @param color in hex for example `#009edd`, `009edd`, `#555`,...
-         * @returns Color object
-         */
-        static fromHex(hex) {
-            const hexOriginal = hex;
-            if (hex.startsWith('#')) {
-                hex = hex.substring(1);
-            }
-            if (hex.length === 3) {
-                return Color.fromHex3(hex);
-            }
-            if (hex.length === 4) {
-                return Color.fromHex4(hex);
-            }
-            if (hex.length === 6) {
-                return Color.fromHex6(hex);
-            }
-            if (hex.length === 8) {
-                return Color.fromHex8(hex);
-            }
-            throw new Error(`Can not parse color from hex string "${hexOriginal}"`);
-        }
-        /**
-         * Creates a new Color instance from color in hex format with 3 color digits (without alpha channel)
-         *
-         * @param color in hex for example `09d`
-         * @returns Color object
-         */
-        static fromHex3(hex) {
-            const r = parseInt(hex.substr(0, 1), 16) * 16;
-            const g = parseInt(hex.substr(1, 1), 16) * 16;
-            const b = parseInt(hex.substr(2, 1), 16) * 16;
-            return take(new Color(r, g, b));
-        }
-        /**
-         * Creates a new Color instance from color in hex format with 4 digits (with alpha channel)
-         *
-         * @param color in hex for example `09df`
-         * @returns Color object
-         */
-        static fromHex4(hex) {
-            const r = parseInt(hex.substr(0, 1), 16) * 16;
-            const g = parseInt(hex.substr(1, 1), 16) * 16;
-            const b = parseInt(hex.substr(2, 1), 16) * 16;
-            const a = parseInt(hex.substr(3, 1), 16) * 16;
-            return take(new Color(r, g, b, a));
+            return Color.fromString(CSS_COLORS[key]);
         }
         /**
-         * Creates a new Color instance from color in hex format with 6 color digits (without alpha channel)
+         * Creates a new Color instance from average color of given image
          *
-         * @param color in hex for example `009edd`
+         * @param image as a source for example `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAA1JREFUGFdjYJh39z8ABJgCe/ZvAS4AAAAASUVORK5CYII=`
          * @returns Color object
          */
-        static fromHex6(hex) {
-            const r = parseInt(hex.substr(0, 2), 16);
-            const g = parseInt(hex.substr(2, 2), 16);
-            const b = parseInt(hex.substr(4, 2), 16);
-            return take(new Color(r, g, b));
+        static async fromImage(image) {
+            return Color.fromHex(`#009edd`);
         }
         /**
-         * Creates a new Color instance from color in hex format with 8 color digits (with alpha channel)
+         * Creates a new Color instance from color in hex format
          *
-         * @param color in hex for example `009edd`
+         * @param color in hex for example `#009edd`, `009edd`, `#555`,...
          * @returns Color object
          */
-        static fromHex8(hex) {
-            const r = parseInt(hex.substr(0, 2), 16);
-            const g = parseInt(hex.substr(2, 2), 16);
-            const b = parseInt(hex.substr(4, 2), 16);
-            const a = parseInt(hex.substr(6, 2), 16);
-            return take(new Color(r, g, b, a));
+        static fromHex(hex) {
+            return Color.fromColorChannels(parseHexColor(hex));
         }
         /**
          * Creates a new Color instance from color in hsl format
@@ -1066,52 +1324,7 @@
          * @returns Color object
          */
         static fromHsl(hsl) {
-            const match = hsl.match(/^hsl\(\s*([0-9.]+)\s*,\s*([0-9.]+)%\s*,\s*([0-9.]+)%\s*\)$/);
-            if (!match) {
-                throw new Error(`Invalid hsl string format: "${hsl}"`);
-            }
-            const h = parseFloat(match[1]);
-            const s = parseFloat(match[2]) / 100;
-            const l = parseFloat(match[3]) / 100;
-            // HSL to RGB conversion
-            const c = (1 - Math.abs(2 * l - 1)) * s;
-            const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
-            const m = l - c / 2;
-            let r1 = 0, g1 = 0, b1 = 0;
-            if (h >= 0 && h < 60) {
-                r1 = c;
-                g1 = x;
-                b1 = 0;
-            }
-            else if (h >= 60 && h < 120) {
-                r1 = x;
-                g1 = c;
-                b1 = 0;
-            }
-            else if (h >= 120 && h < 180) {
-                r1 = 0;
-                g1 = c;
-                b1 = x;
-            }
-            else if (h >= 180 && h < 240) {
-                r1 = 0;
-                g1 = x;
-                b1 = c;
-            }
-            else if (h >= 240 && h < 300) {
-                r1 = x;
-                g1 = 0;
-                b1 = c;
-            }
-            else if (h >= 300 && h < 360) {
-                r1 = c;
-                g1 = 0;
-                b1 = x;
-            }
-            const r = Math.round((r1 + m) * 255);
-            const g = Math.round((g1 + m) * 255);
-            const b = Math.round((b1 + m) * 255);
-            return take(new Color(r, g, b));
+            return Color.fromColorChannels(parseHslColor(hsl));
         }
         /**
          * Creates a new Color instance from color in rgb format
@@ -1120,25 +1333,7 @@
          * @returns Color object
          */
         static fromRgbString(rgb) {
-            const match = rgb.match(/^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/);
-            if (!match) {
-                throw new Error(`Invalid rgb string format: "${rgb}"`);
-            }
-            const parseChannel = (value) => {
-                if (value.endsWith('%')) {
-                    // Percentage value
-                    const percent = parseFloat(value);
-                    return Math.round((percent / 100) * 255);
-                }
-                else {
-                    // Numeric value
-                    return Math.round(parseFloat(value));
-                }
-            };
-            const r = parseChannel(match[1]);
-            const g = parseChannel(match[2]);
-            const b = parseChannel(match[3]);
-            return take(new Color(r, g, b));
+            return Color.fromColorChannels(parseRgbColor(rgb));
         }
         /**
          * Creates a new Color instance from color in rbga format
@@ -1147,39 +1342,7 @@
          * @returns Color object
          */
         static fromRgbaString(rgba) {
-            const match = rgba.match(/^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/);
-            if (!match) {
-                throw new Error(`Invalid rgba string format: "${rgba}"`);
-            }
-            const parseChannel = (value) => {
-                if (value.endsWith('%')) {
-                    const percent = parseFloat(value);
-                    return Math.round((percent / 100) * 255);
-                }
-                else {
-                    return Math.round(parseFloat(value));
-                }
-            };
-            const parseAlpha = (value) => {
-                if (value.endsWith('%')) {
-                    const percent = parseFloat(value);
-                    return Math.round((percent / 100) * 255);
-                }
-                else {
-                    const alphaFloat = parseFloat(value);
-                    // If alpha is between 0 and 1, treat as float
-                    if (alphaFloat <= 1) {
-                        return Math.round(alphaFloat * 255);
-                    }
-                    // Otherwise, treat as 0-255
-                    return Math.round(alphaFloat);
-                }
-            };
-            const r = parseChannel(match[1]);
-            const g = parseChannel(match[2]);
-            const b = parseChannel(match[3]);
-            const a = parseAlpha(match[4]);
-            return take(new Color(r, g, b, a));
+            return Color.fromColorChannels(parseRgbaColor(rgba));
         }
         /**
          * Creates a new Color for color channels values
@@ -1191,7 +1354,7 @@
          * @returns Color object
          */
         static fromValues(red, green, blue, alpha = 255) {
-            return take(new Color(red, green, blue, alpha));
+            return Color.fromColorChannels({ red, green, blue, alpha });
         }
         /**
          * Checks if the given value is a valid Color object.
@@ -1224,8 +1387,7 @@
          * @returns true if the value is a valid hex color string (e.g., `#009edd`, `#fff`, etc.)
          */
         static isHexColorString(value) {
-            return (typeof value === 'string' &&
-                /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(value));
+            return isHexColorString(value);
         }
         /**
          * Creates new Color object
@@ -1238,107 +1400,15 @@
          * @param alpha number from 0 (transparent) to 255 (opaque)
          */
         constructor(red, green, blue, alpha = 255) {
-            this.red = red;
-            this.green = green;
-            this.blue = blue;
-            this.alpha = alpha;
-            checkChannelValue('Red', red);
-            checkChannelValue('Green', green);
-            checkChannelValue('Blue', blue);
-            checkChannelValue('Alpha', alpha);
-        }
-        /**
-         * 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(new Color(this.red, this.green, this.blue, this.alpha));
-        }
-        toString() {
-            return this.toHex();
-        }
-        toHex() {
-            if (this.alpha === 255) {
-                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}`;
-            }
-            else {
-                return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
-            }
+            super(red, green, blue, alpha);
         }
-        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)}%)`;
-            }
+        createColor(red, green, blue, alpha) {
+            return new Color(red, green, blue, alpha);
         }
-        toHsl() {
-            throw new Error(`Getting HSL is not implemented`);
+        static fromColorChannels({ red, green, blue, alpha }) {
+            return take(new Color(red, green, blue, alpha));
         }
     }
-    /**
-     * TODO: [🥻] Split Color class and color type
-     * TODO: For each method a corresponding static method should be created
-     *       Like clone can be done by color.clone() OR Color.clone(color)
-     * TODO: Probably as an independent LIB OR add to LIB xyzt (ask @roseckyj)
-     * TODO: !! Transfer back to Collboard (whole directory)
-     * TODO: Maybe [🏌️‍♂️] change ACRY toString => (toHex) toRgb when there will be toRgb and toRgba united
-     * TODO: Convert getters to methods - getters only for values
-     * TODO: Write tests
-     * TODO: Getters for alpha, opacity, transparency, r, b, g, h, s, l, a,...
-     * TODO: [0] Should be fromRgbString and fromRgbaString one or two functions + one or two regex
-     * TODO: Use rgb, rgba, hsl for testing and parsing with the same regex
-     * TODO: Regex for rgb, rgba, hsl does not support all options like deg, rad, turn,...
-     * TODO: Convolution matrix
-     * TODO: Maybe connect with textures
-     */
 
     /**
      * Makes color transformer which returns a grayscale version of the color
@@ -1400,9 +1470,7 @@
         }
         return [Math.round(red * 255), Math.round(green * 255), Math.round(blue * 255)];
     }
-    /**
-     * TODO: Properly name all used internal variables
-     */
+    // TODO: Properly name all used internal variables
 
     /**
      * Converts RGB values to HSL values
@@ -1448,9 +1516,7 @@
         }
         return [hue, saturation, lightness];
     }
-    /**
-     * TODO: Properly name all used internal variables
-     */
+    // TODO: Properly name all used internal variables
 
     /**
      * Makes color transformer which lighten the given color
@@ -1468,9 +1534,7 @@
             return Color.fromValues(r, g, b, alpha);
         };
     }
-    /**
-     * TODO: Maybe implement by mix+hsl
-     */
+    // TODO: Maybe implement by mix+hsl
 
     /**
      * Makes color transformer which saturate the given color
@@ -1488,9 +1552,36 @@
             return Color.fromValues(r, g, b, alpha);
         };
     }
+    // TODO: Maybe implement by mix+hsl
+
+    /**
+     * Stable root directory used for Promptbook-owned temporary files and caches.
+     *
+     * @private internal utility for Promptbook temporary folders
+     */
+    const PROMPTBOOK_TEMPORARY_DIRECTORY = '.promptbook';
+    /**
+     * Builds one normalized project-relative path inside Promptbook's dedicated temporary root.
+     *
+     * The returned path intentionally uses `/` separators so the same helper can be reused from
+     * Node.js and edge-safe code without depending on the Node `path` module.
+     *
+     * @private internal utility for Promptbook temporary folders
+     */
+    function getPromptbookTemporaryPath(...pathSegments) {
+        const normalizedPathSegments = pathSegments.flatMap(splitPathSegments).filter(Boolean);
+        return [PROMPTBOOK_TEMPORARY_DIRECTORY, ...normalizedPathSegments].join('/');
+    }
     /**
-     * TODO: Maybe implement by mix+hsl
+     * Normalizes one raw path segment into slash-delimited pieces without empty items.
      */
+    function splitPathSegments(pathSegment) {
+        return pathSegment
+            .split(/[\\/]+/u)
+            .map((segment) => segment.trim())
+            .filter(Boolean);
+    }
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Name for the Promptbook
@@ -1534,6 +1625,9 @@
         LINE: Color.fromHex('#eeeeee'),
         SEPARATOR: Color.fromHex('#cccccc'),
         COMMITMENT: Color.fromHex('#DA0F78'),
+        NOTE_COMMITMENT: Color.fromHex('#8080807e'),
+        TODO_COMMITMENT_TEXT: Color.fromHex('#000000'),
+        TODO_COMMITMENT_BACKGROUND: Color.fromHex('#FFEB3B'),
         PARAMETER: Color.fromHex('#8e44ad'),
         CODE_BLOCK: Color.fromHex('#7700ffff'),
     });
@@ -1583,6 +1677,31 @@
      * @public exported from `@promptbook/utils`
      */
     const SMALL_NUMBER = 0.001;
+    // <- TODO: [🕝] Make also `AGENTS_DIRNAME_ALTERNATIVES`
+    /**
+     * Where to store the temporary downloads
+     *
+     * Note: When the folder does not exist, it is created recursively
+     *
+     * @public exported from `@promptbook/core`
+     */
+`./${getPromptbookTemporaryPath('download-cache')}`;
+    /**
+     * Where to store the cache of executions for promptbook CLI
+     *
+     * Note: When the folder does not exist, it is created recursively
+     *
+     * @public exported from `@promptbook/core`
+     */
+`./${getPromptbookTemporaryPath('execution-cache')}`;
+    /**
+     * Where to store the scrape cache
+     *
+     * Note: When the folder does not exist, it is created recursively
+     *
+     * @public exported from `@promptbook/core`
+     */
+`./${getPromptbookTemporaryPath('scrape-cache')}`;
     // <- TODO: [🧜‍♂️]
     /**
      * Default settings for parsing and generating CSV files in Promptbook.
@@ -1611,6 +1730,7 @@
      * Orders JSON object by keys
      *
      * @returns The same type of object as the input re-ordered
+     *
      * @public exported from `@promptbook/utils`
      */
     function orderJson(options) {
@@ -1630,7 +1750,7 @@
     function getErrorReportUrl(error) {
         const report = {
             title: `🐜 Error report from ${NAME}`,
-            body: spaceTrim__default["default"]((block) => `
+            body: spacetrim.spaceTrim((block) => `
 
 
             \`${error.name || 'Error'}\` has occurred in the [${NAME}], please look into it @${ADMIN_GITHUB_NAME}.
@@ -1673,7 +1793,7 @@
      */
     class UnexpectedError extends Error {
         constructor(message) {
-            super(spaceTrim$1.spaceTrim((block) => `
+            super(spacetrim.spaceTrim((block) => `
                     ${block(message)}
 
                     Note: This error should not happen.
@@ -1699,7 +1819,7 @@
         constructor(whatWasThrown) {
             const tag = `[🤮]`;
             console.error(tag, whatWasThrown);
-            super(spaceTrim$1.spaceTrim(`
+            super(spacetrim.spaceTrim(`
                 Non-Error object was thrown
 
                 Note: Look for ${tag} in the console for more details
@@ -1756,125 +1876,187 @@
      * - And much more...
      *
      * @throws UnexpectedError if the value is not serializable as JSON
+     *
      * @public exported from `@promptbook/utils`
      */
     function checkSerializableAsJson(options) {
-        const { value, name, message } = options;
+        checkSerializableValue(options);
+    }
+    // TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
+    // TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
+    // Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
+    /**
+     * Checks one value and dispatches to the appropriate specialized validator.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableValue(options) {
+        const { value } = options;
+        if (isSerializablePrimitive(value)) {
+            return;
+        }
         if (value === undefined) {
-            throw new UnexpectedError(`${name} is undefined`);
+            throw new UnexpectedError(`${options.name} is undefined`);
         }
-        else if (value === null) {
-            return;
+        if (typeof value === 'symbol') {
+            throw new UnexpectedError(`${options.name} is symbol`);
         }
-        else if (typeof value === 'boolean') {
-            return;
+        if (typeof value === 'function') {
+            throw new UnexpectedError(`${options.name} is function`);
         }
-        else if (typeof value === 'number' && !isNaN(value)) {
+        if (Array.isArray(value)) {
+            checkSerializableArray(options, value);
             return;
         }
-        else if (typeof value === 'string') {
+        if (value !== null && typeof value === 'object') {
+            checkSerializableObject(options, value);
             return;
         }
-        else if (typeof value === 'symbol') {
-            throw new UnexpectedError(`${name} is symbol`);
-        }
-        else if (typeof value === 'function') {
-            throw new UnexpectedError(`${name} is function`);
-        }
-        else if (typeof value === 'object' && Array.isArray(value)) {
-            for (let i = 0; i < value.length; i++) {
-                checkSerializableAsJson({ name: `${name}[${i}]`, value: value[i], message });
-            }
+        throwUnknownTypeError(options);
+    }
+    /**
+     * Checks the primitive values that are directly JSON serializable.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function isSerializablePrimitive(value) {
+        return (value === null ||
+            typeof value === 'boolean' ||
+            (typeof value === 'number' && !isNaN(value)) ||
+            typeof value === 'string');
+    }
+    /**
+     * Recursively checks JSON array items.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableArray(context, arrayValue) {
+        for (let index = 0; index < arrayValue.length; index++) {
+            checkSerializableAsJson({
+                ...context,
+                name: `${context.name}[${index}]`,
+                value: arrayValue[index],
+            });
         }
-        else if (typeof value === 'object') {
-            if (value instanceof Date) {
-                throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                        \`${name}\` is Date
+    }
+    /**
+     * Checks object-like values and dispatches special unsupported built-ins.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableObject(context, objectValue) {
+        checkUnsupportedObjectType(context, objectValue);
+        checkSerializableObjectEntries(context, objectValue);
+        assertJsonStringificationSucceeds(context, objectValue);
+    }
+    /**
+     * Rejects built-in objects that must be converted before JSON serialization.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkUnsupportedObjectType(context, objectValue) {
+        if (objectValue instanceof Date) {
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                    \`${context.name}\` is Date
 
-                        Use \`string_date_iso8601\` instead
+                    Use \`string_date_iso8601\` instead
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
-                    `));
-            }
-            else if (value instanceof Map) {
-                throw new UnexpectedError(`${name} is Map`);
-            }
-            else if (value instanceof Set) {
-                throw new UnexpectedError(`${name} is Set`);
-            }
-            else if (value instanceof RegExp) {
-                throw new UnexpectedError(`${name} is RegExp`);
-            }
-            else if (value instanceof Error) {
-                throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                        \`${name}\` is unserialized Error
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
+                `));
+        }
+        if (objectValue instanceof Map) {
+            throw new UnexpectedError(`${context.name} is Map`);
+        }
+        if (objectValue instanceof Set) {
+            throw new UnexpectedError(`${context.name} is Set`);
+        }
+        if (objectValue instanceof RegExp) {
+            throw new UnexpectedError(`${context.name} is RegExp`);
+        }
+        if (objectValue instanceof Error) {
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                    \`${context.name}\` is unserialized Error
 
-                        Use function \`serializeError\`
+                    Use function \`serializeError\`
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
 
-                    `));
+                `));
+        }
+    }
+    /**
+     * Recursively checks object properties while preserving omitted `undefined` keys.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function checkSerializableObjectEntries(context, objectValue) {
+        for (const [subName, subValue] of Object.entries(objectValue)) {
+            if (subValue === undefined) {
+                // Note: undefined in object is serializable - it is just omitted
+                continue;
             }
-            else {
-                for (const [subName, subValue] of Object.entries(value)) {
-                    if (subValue === undefined) {
-                        // Note: undefined in object is serializable - it is just omitted
-                        continue;
-                    }
-                    checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
-                }
-                try {
-                    JSON.stringify(value); // <- TODO: [0]
-                }
-                catch (error) {
-                    assertsError(error);
-                    throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                            \`${name}\` is not serializable
+            checkSerializableAsJson({
+                ...context,
+                name: `${context.name}.${subName}`,
+                value: subValue,
+            });
+        }
+    }
+    /**
+     * Uses `JSON.stringify` as the final guard for cases like circular references.
+     *
+     * @private function of `checkSerializableAsJson`
+     */
+    function assertJsonStringificationSucceeds(context, objectValue) {
+        try {
+            JSON.stringify(objectValue); // <- TODO: [0]
+        }
+        catch (error) {
+            assertsError(error);
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                    \`${context.name}\` is not serializable
 
-                            ${block(error.stack || error.message)}
+                    ${block(error.stack || error.message)}
 
-                            Additional message for \`${name}\`:
-                            ${block(message || '(nothing)')}
-                        `));
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
+                `));
+        }
+        /*
+        TODO: [0] Is there some more elegant way to check circular references?
+        const seen = new Set();
+        const stack = [{ value }];
+        while (stack.length > 0) {
+            const { value } = stack.pop()!;
+            if (typeof value === 'object' && value !== null) {
+                if (seen.has(value)) {
+                    throw new UnexpectedError(`${name} has circular reference`);
                 }
-                /*
-                TODO: [0] Is there some more elegant way to check circular references?
-                const seen = new Set();
-                const stack = [{ value }];
-                while (stack.length > 0) {
-                    const { value } = stack.pop()!;
-                    if (typeof value === 'object' && value !== null) {
-                        if (seen.has(value)) {
-                            throw new UnexpectedError(`${name} has circular reference`);
-                        }
-                        seen.add(value);
-                        if (Array.isArray(value)) {
-                            stack.push(...value.map((value) => ({ value })));
-                        } else {
-                            stack.push(...Object.values(value).map((value) => ({ value })));
-                        }
-                    }
+                seen.add(value);
+                if (Array.isArray(value)) {
+                    stack.push(...value.map((value) => ({ value })));
+                } else {
+                    stack.push(...Object.values(value).map((value) => ({ value })));
                 }
-                */
-                return;
             }
         }
-        else {
-            throw new UnexpectedError(spaceTrim__default["default"]((block) => `
-                    \`${name}\` is unknown type
-
-                    Additional message for \`${name}\`:
-                    ${block(message || '(nothing)')}
-                `));
-        }
+        */
     }
     /**
-     * TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
-     * TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
-     * Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
+     * Throws the fallback error for unsupported value types like `bigint` and `NaN`.
+     *
+     * @private function of `checkSerializableAsJson`
      */
+    function throwUnknownTypeError(context) {
+        throw new UnexpectedError(spacetrim.spaceTrim((block) => `
+                \`${context.name}\` is unknown type
+
+                Additional message for \`${context.name}\`:
+                ${block(context.message || '(nothing)')}
+            `));
+    }
 
     /**
      * Creates a deep clone of the given object
@@ -1884,6 +2066,7 @@
      *
      * @param objectValue The object to clone.
      * @returns A deep, writable clone of the input object.
+     *
      * @public exported from `@promptbook/utils`
      */
     function deepClone(objectValue) {
@@ -1900,9 +2083,7 @@
         > return Object.assign({}, objectValue);
         */
     }
-    /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
-     */
+    // TODO: [🧠] Is there a way how to meaningfully test this utility
 
     /**
      * Utility to export a JSON object from a function
@@ -1915,6 +2096,7 @@
      * Note: This function does not mutates the given object
      *
      * @returns The same type of object as the input but read-only and re-ordered
+     *
      * @public exported from `@promptbook/utils`
      */
     function exportJson(options) {
@@ -1934,9 +2116,7 @@
         $deepFreeze(orderedValue);
         return orderedValue;
     }
-    /**
-     * TODO: [🧠] Is there a way how to meaningfully test this utility
-     */
+    // TODO: [🧠] Is there a way how to meaningfully test this utility
 
     /**
      * Nonce which is used for replacing things in strings
@@ -1976,9 +2156,7 @@
             // <- TODO: Add [emoji] + instructions ACRY when adding new reserved parameter
         ],
     });
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * This error type indicates that some limit was reached
@@ -2026,8 +2204,8 @@
      * This is useful and used in the `templateParameters` function
      *
      * Note: This function is not just calling `toString` method
-     *       It's more complex and can handle this conversion specifically for LLM models
-     *       See `VALUE_STRINGS`
+     * It's more complex and can handle this conversion specifically for LLM models
+     * See `VALUE_STRINGS`
      *
      * Note: There are 2 similar functions
      * - `valueToString` converts value to string for LLM models as human-readable string
@@ -2078,12 +2256,13 @@
      * Replaces parameters in template with values from parameters object
      *
      * Note: This function is not places strings into string,
-     *       It's more complex and can handle this operation specifically for LLM models
+     * It's more complex and can handle this operation specifically for LLM models
      *
      * @param template the template with parameters in {curly} braces
      * @param parameters the object with parameters
      * @returns the template with replaced parameters
      * @throws {PipelineExecutionError} if parameter is not defined, not closed, or not opened
+     *
      * @public exported from `@promptbook/utils`
      */
     function templateParameters(template, parameters) {
@@ -2226,7 +2405,7 @@
                 const modelName = modelRequirements.modelName ||
                     ((_a = availableModels.find(({ modelVariant }) => modelVariant === 'CHAT')) === null || _a === void 0 ? void 0 : _a.modelName);
                 if (!modelName) {
-                    throw new PipelineExecutionError(spaceTrim__default["default"](`
+                    throw new PipelineExecutionError(spacetrim.spaceTrim(`
                         Can not determine which model to use.
 
                         You need to provide at least one of:
@@ -2304,8 +2483,10 @@
                     throw new PipelineExecutionError('No response message');
                 }
                 const complete = $getCurrentDate();
+                const duration = uncertainNumber((new Date(complete).getTime() - new Date(start).getTime()) / 1000);
                 const usage = {
                     price: UNCERTAIN_ZERO_VALUE,
+                    duration,
                     input: {
                         tokensCount: uncertainNumber(rawResponse.usage.promptTokens),
                         ...computeUsageCounts(rawPromptContent),
@@ -2349,9 +2530,10 @@
     /**
      * List of available Google models with descriptions
      *
-     * Note: Synced with official API docs at 2025-11-19
+     * Note: Synced with official API docs at 2026-03-22
      *
      * @see https://ai.google.dev/models/gemini
+     *
      * @public exported from `@promptbook/google`
      */
     const GOOGLE_MODELS = exportJson({
@@ -2370,8 +2552,8 @@
                 modelName: 'gemini-2.5-pro',
                 modelDescription: 'State-of-the-art thinking model with 1M token context window capable of reasoning over complex problems in code, math, and STEM. Features enhanced thinking capabilities, advanced multimodal understanding, and superior performance on analytical tasks. Ideal for complex enterprise applications requiring maximum intelligence and reasoning.',
                 pricing: {
-                    prompt: pricing(`$7.00 / 1M tokens`),
-                    output: pricing(`$21.00 / 1M tokens`),
+                    prompt: pricing(`$1.25 / 1M tokens`),
+                    output: pricing(`$10.00 / 1M tokens`),
                 },
             },
             {
@@ -2380,8 +2562,8 @@
                 modelName: 'gemini-2.5-flash',
                 modelDescription: 'Best model in terms of price-performance with 1M token context window offering well-rounded capabilities. Features adaptive thinking, cost efficiency, and enhanced reasoning for large-scale processing. Ideal for low-latency, high-volume tasks that require thinking and agentic use cases.',
                 pricing: {
-                    prompt: pricing(`$0.35 / 1M tokens`),
-                    output: pricing(`$1.05 / 1M tokens`),
+                    prompt: pricing(`$0.30 / 1M tokens`),
+                    output: pricing(`$2.50 / 1M tokens`),
                 },
             },
             {
@@ -2390,8 +2572,8 @@
                 modelName: 'gemini-2.5-flash-lite',
                 modelDescription: 'Cost-efficient Gemini 2.5 Flash model optimized for high throughput with 1M token context window. Features thinking capabilities while maintaining the most cost-efficient pricing. Perfect for real-time, low-latency use cases requiring good quality at scale.',
                 pricing: {
-                    prompt: pricing(`$0.20 / 1M tokens`),
-                    output: pricing(`$0.60 / 1M tokens`),
+                    prompt: pricing(`$0.10 / 1M tokens`),
+                    output: pricing(`$0.40 / 1M tokens`),
                 },
             },
             {
@@ -2566,12 +2748,10 @@
             },
         ],
     });
-    /**
-     * TODO: [🧠] Add information about context window sizes, capabilities, and relative performance characteristics
-     * TODO: [🎰] Some mechanism to auto-update available models
-     * TODO: [🧠] Verify pricing information is current with Google's official documentation
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // TODO: [🧠] Add information about context window sizes, capabilities, and relative performance characteristics
+    // TODO: [🎰] Some mechanism to auto-update available models
+    // TODO: [🧠] Verify pricing information is current with Google's official documentation
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Profile for Google Gemini provider
@@ -2581,7 +2761,13 @@
         fullname: 'Google Gemini',
         color: '#4285f4',
     };
+    /**
+     * Constant for default google generative AI base URL.
+     */
     const DEFAULT_GOOGLE_GENERATIVE_AI_BASE_URL = 'https://generativelanguage.googleapis.com/v1beta';
+    /**
+     * Map of google image response modalities.
+     */
     const GOOGLE_IMAGE_RESPONSE_MODALITIES = {
         responseModalities: ['TEXT', 'IMAGE'],
     };
@@ -2702,6 +2888,7 @@
                 }
                 const image = extractGoogleImageData(rawResponse);
                 const complete = $getCurrentDate();
+                const duration = uncertainNumber((new Date(complete).getTime() - new Date(start).getTime()) / 1000);
                 const usageMetadata = rawResponse.usageMetadata;
                 return exportJson({
                     name: 'promptResult',
@@ -2716,6 +2903,7 @@
                         },
                         usage: {
                             price: uncertainNumber(),
+                            duration,
                             input: {
                                 tokensCount: uncertainNumber(usageMetadata === null || usageMetadata === void 0 ? void 0 : usageMetadata.promptTokenCount),
                                 ...computeUsageCounts(rawPromptContent),
@@ -2741,11 +2929,9 @@
     }, {
         packageName: '@promptbook/google',
         className: 'GoogleExecutionTools',
-    });
-    /**
-     * TODO: !!!!! Rename to `createGoogleLlmExecutionTools`, `...GoogleLlmExecutionTools`
-     * TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
-     */
+    }); /* <- Note: [🤛] */
+    // TODO: !!!!! Rename to `createGoogleLlmExecutionTools`, `...GoogleLlmExecutionTools`
+    // TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
 
     /**
      * This error type indicates that some part of the code is not implemented yet
@@ -2754,7 +2940,7 @@
      */
     class NotYetImplementedError extends Error {
         constructor(message) {
-            super(spaceTrim$1.spaceTrim((block) => `
+            super(spacetrim.spaceTrim((block) => `
                     ${block(message)}
 
                     Note: This feature is not implemented yet but it will be soon.
@@ -2776,7 +2962,7 @@
      *
      * Note: `$` is used to indicate that this function is not a pure function - it access global scope
      *
-     *  @private internal function of `$Register`
+     * @private internal function of `$Register`
      */
     function $getGlobalScope() {
         return Function('return this')();
@@ -2791,6 +2977,7 @@
      * @returns The normalized text in SCREAMING_CASE format.
      * @example 'HELLO_WORLD'
      * @example 'I_LOVE_PROMPTBOOK'
+     *
      * @public exported from `@promptbook/utils`
      */
     function normalizeTo_SCREAMING_CASE(text) {
@@ -2848,6 +3035,7 @@
      * @returns The normalized text in snake_case format.
      * @example 'hello_world'
      * @example 'i_love_promptbook'
+     *
      * @public exported from `@promptbook/utils`
      */
     function normalizeTo_snake_case(text) {
@@ -2906,13 +3094,13 @@
      * Register for LLM tools.
      *
      * Note: `$` is used to indicate that this interacts with the global scope
+     *
      * @singleton Only one instance of each register is created per build, but there can be more instances across different builds or environments.
+     *
      * @public exported from `@promptbook/core`
      */
     const $llmToolsRegister = new $Register('llm_execution_tools_constructors');
-    /**
-     * TODO: [®] DRY Register logic
-     */
+    // TODO: [®] DRY Register logic
 
     /**
      * Registration of LLM provider
@@ -2924,10 +3112,8 @@
      * @public exported from `@promptbook/cli`
      */
     const _GoogleRegistration = $llmToolsRegister.register(createGoogleExecutionTools);
-    /**
-     * TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     exports.BOOK_LANGUAGE_VERSION = BOOK_LANGUAGE_VERSION;
     exports.GOOGLE_MODELS = GOOGLE_MODELS;