@promptbook/utils 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('spacetrim'), require('path'), require('crypto'), require('crypto-js'), require('crypto-js/enc-hex')) :
     typeof define === 'function' && define.amd ? define(['exports', 'spacetrim', 'path', 'crypto', 'crypto-js', 'crypto-js/enc-hex'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-utils"] = {}, global.spaceTrim$1, global.path, global.crypto, global.cryptoJs, global.hexEncoder));
-})(this, (function (exports, spaceTrim$1, path, crypto, cryptoJs, hexEncoder) { 'use strict';
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-utils"] = {}, global.spacetrim, global.path, global.crypto, global.cryptoJs, global.hexEncoder));
+})(this, (function (exports, spacetrim, path, crypto, cryptoJs, hexEncoder) { 'use strict';
 
     function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
-    var spaceTrim__default = /*#__PURE__*/_interopDefaultLegacy(spaceTrim$1);
     var hexEncoder__default = /*#__PURE__*/_interopDefaultLegacy(hexEncoder);
 
     // ⚠️ 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
@@ -33,16 +32,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) {
@@ -59,9 +62,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) {
@@ -239,9 +242,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.
@@ -271,6 +272,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
      *
@@ -278,7 +642,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
@@ -351,30 +715,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
@@ -404,73 +745,7 @@
          * @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));
-        }
-        /**
-         * Creates a new Color instance from color in hex format with 6 color digits (without alpha channel)
-         *
-         * @param color in hex for example `009edd`
-         * @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));
-        }
-        /**
-         * Creates a new Color instance from color in hex format with 8 color digits (with alpha channel)
-         *
-         * @param color in hex for example `009edd`
-         * @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));
+            return Color.fromColorChannels(parseHexColor(hex));
         }
         /**
          * Creates a new Color instance from color in hsl format
@@ -479,52 +754,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
@@ -533,25 +763,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
@@ -560,39 +772,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
@@ -604,7 +784,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.
@@ -637,8 +817,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
@@ -651,107 +830,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);
+            super(red, green, blue, alpha);
         }
-        /**
-         * Shortcut for `red` property
-         * Number from 0 to 255
-         * @alias red
-         */
-        get r() {
-            return this.red;
+        createColor(red, green, blue, alpha) {
+            return new Color(red, green, blue, alpha);
         }
-        /**
-         * 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')}`;
-            }
-        }
-        toRgb() {
-            if (this.alpha === 255) {
-                return `rgb(${this.red}, ${this.green}, ${this.blue})`;
-            }
-            else {
-                return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
-            }
-        }
-        toHsl() {
-            throw new Error(`Getting HSL is not implemented`);
+        static fromColorChannels({ red, green, blue, alpha }) {
+            return take(new Color(red, green, blue, alpha));
         }
     }
-    /**
-     * 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
@@ -813,9 +900,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
@@ -861,9 +946,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
@@ -881,9 +964,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
@@ -901,9 +982,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';
     /**
-     * TODO: Maybe implement by mix+hsl
+     * 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('/');
+    }
+    /**
+     * 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
@@ -947,6 +1055,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'),
     });
@@ -996,6 +1107,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.
@@ -1024,6 +1160,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) {
@@ -1042,6 +1179,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) {
@@ -1058,9 +1196,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
 
     /**
      * Make error report URL for the given error
@@ -1070,7 +1206,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}.
@@ -1113,7 +1249,7 @@
      */
     class UnexpectedError extends Error {
         constructor(message) {
-            super(spaceTrim$1.spaceTrim((block) => `
+            super(spacetrim.spaceTrim((block) => `
                     ${block(message)}
 
                     Note: This error should not happen.
@@ -1139,7 +1275,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
@@ -1196,125 +1332,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
@@ -1324,6 +1522,7 @@
      *
      * @param objectValue The object to clone.
      * @returns A deep, writable clone of the input object.
+     *
      * @public exported from `@promptbook/utils`
      */
     function deepClone(objectValue) {
@@ -1340,9 +1539,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
@@ -1355,6 +1552,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) {
@@ -1374,9 +1572,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
@@ -1416,9 +1612,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
 
     /**
      * Normalizes a given text to camelCase format.
@@ -1430,6 +1624,7 @@
      * @returns The camelCase formatted string.
      * @example 'helloWorld'
      * @example 'iLovePromptbook'
+     *
      * @public exported from `@promptbook/utils`
      */
     function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
@@ -1470,14 +1665,13 @@
         }
         return normalizedName;
     }
-    /**
-     * TODO: [🌺] Use some intermediate util splitWords
-     */
+    // TODO: [🌺] Use some intermediate util splitWords
 
     /**
      * Tests if given string is valid file path.
      *
      * Note: This does not check if the file exists only if the path is valid
+     *
      * @public exported from `@promptbook/utils`
      */
     function isValidFilePath(filename) {
@@ -1526,9 +1720,7 @@
         }
         return false;
     }
-    /**
-     * TODO: [🍏] Implement for MacOs
-     */
+    // TODO: [🍏] Implement for MacOs
 
     /**
      * Tests if given string is valid URL.
@@ -1561,6 +1753,9 @@
         }
     }
 
+    /**
+     * Collection of default diacritics removal map.
+     */
     const defaultDiacriticsRemovalMap = [
         {
             base: 'A',
@@ -1812,6 +2007,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) {
@@ -1820,9 +2016,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
 
     /**
      * Converts a given text to kebab-case format.
@@ -1833,6 +2027,7 @@
      * @returns The kebab-case formatted string.
      * @example 'hello-world'
      * @example 'i-love-promptbook'
+     *
      * @public exported from `@promptbook/utils`
      */
     function normalizeToKebabCase(text) {
@@ -1873,9 +2068,7 @@
         normalizedName = normalizedName.replace(/-$/, '');
         return normalizedName;
     }
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Removes emojis from a string and fix whitespaces
@@ -1884,6 +2077,7 @@
      *
      * @param text with emojis
      * @returns text without emojis
+     *
      * @public exported from `@promptbook/utils`
      */
     function removeEmojis(text) {
@@ -1903,6 +2097,7 @@
      * @param value The title string to be converted to a name.
      * @returns A normalized name derived from the input title.
      * @example 'Hello World!' -> 'hello-world'
+     *
      * @public exported from `@promptbook/utils`
      */
     function titleToName(value) {
@@ -1987,7 +2182,7 @@
             .filter(([MERMAID_NAME]) => (inputAndIntermediateParametersMermaid + outputParametersMermaid).includes(MERMAID_NAME))
             .map(([MERMAID_NAME, title]) => `${MERMAID_NAME}((${title})):::${MERMAID_NAME}`)
             .join('\n');
-        const promptbookMermaid = spaceTrim$1.spaceTrim((block) => `
+        const promptbookMermaid = spacetrim.spaceTrim((block) => `
 
             %% 🔮 Tip: Open this on GitHub or in the VSCode website to see the Mermaid graph visually
 
@@ -2021,13 +2216,11 @@
         `);
         return promptbookMermaid;
     }
-    /**
-     * TODO: [🧠] FOREACH in mermaid graph
-     * TODO: [🧠] Knowledge in mermaid graph
-     * TODO: [🧠] Personas in mermaid graph
-     * TODO: Maybe use some Mermaid package instead of string templating
-     * TODO: [🕌] When more than 2 functionalities, split into separate functions
-     */
+    // TODO: [🧠] FOREACH in mermaid graph
+    // TODO: [🧠] Knowledge in mermaid graph
+    // TODO: [🧠] Personas in mermaid graph
+    // TODO: Maybe use some Mermaid package instead of string templating
+    // TODO: [🕌] When more than 2 functionalities, split into separate functions
 
     /**
      * This error indicates problems parsing the format value
@@ -2073,15 +2266,28 @@
     }
 
     /**
-     * This error indicates that the pipeline collection cannot be properly loaded
+     * This error indicates that the pipeline collection cannot be properly loaded
+     *
+     * @public exported from `@promptbook/core`
+     */
+    class CollectionError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = 'CollectionError';
+            Object.setPrototypeOf(this, CollectionError.prototype);
+        }
+    }
+
+    /**
+     * Signals that the requested operation could not be completed because the target already exists.
      *
      * @public exported from `@promptbook/core`
      */
-    class CollectionError extends Error {
+    class ConflictError extends Error {
         constructor(message) {
             super(message);
-            this.name = 'CollectionError';
-            Object.setPrototypeOf(this, CollectionError.prototype);
+            this.name = 'ConflictError';
+            Object.setPrototypeOf(this, ConflictError.prototype);
         }
     }
 
@@ -2097,9 +2303,7 @@
             Object.setPrototypeOf(this, DatabaseError.prototype);
         }
     }
-    /**
-     * TODO: [🐱‍🚀] Explain that NotFoundError ([🐱‍🚀] and other specific errors) has priority over DatabaseError in some contexts
-     */
+    // TODO: [🐱‍🚀] Explain that NotFoundError ([🐱‍🚀] and other specific errors) has priority over DatabaseError in some contexts
 
     /**
      * This error type indicates that you try to use a feature that is not available in the current environment
@@ -2117,10 +2321,11 @@
     /**
      * This error occurs when some expectation is not met in the execution of the pipeline
      *
-     * @public exported from `@promptbook/core`
      * Note: Do not throw this error, its reserved for `checkExpectations` and `createPipelineExecutor` and public ONLY to be serializable through remote server
      * Note: Always thrown in `checkExpectations` and catched in `createPipelineExecutor` and rethrown as `PipelineExecutionError`
      * Note: This is a kindof subtype of PipelineExecutionError
+     *
+     * @public exported from `@promptbook/core`
      */
     class ExpectError extends Error {
         constructor(message) {
@@ -2163,7 +2368,7 @@
      */
     class MissingToolsError extends Error {
         constructor(message) {
-            super(spaceTrim$1.spaceTrim((block) => `
+            super(spacetrim.spaceTrim((block) => `
                     ${block(message)}
 
                     Note: You have probably forgot to provide some tools for pipeline execution or preparation
@@ -2207,7 +2412,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.
@@ -2235,9 +2440,7 @@
             Object.setPrototypeOf(this, ParseError.prototype);
         }
     }
-    /**
-     * TODO: Maybe split `ParseError` and `ApplyError`
-     */
+    // TODO: Maybe split `ParseError` and `ApplyError`
 
     /**
      * Generates random token
@@ -2245,16 +2448,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
@@ -2271,9 +2473,7 @@
             Object.setPrototypeOf(this, PipelineExecutionError.prototype);
         }
     }
-    /**
-     * TODO: [🧠][🌂] Add id to all errors
-     */
+    // TODO: [🧠][🌂] Add id to all errors
 
     /**
      * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
@@ -2340,6 +2540,7 @@
         WrappedError,
         NotAllowed,
         DatabaseError,
+        ConflictError,
         // TODO: [🪑]> VersionMismatchError,
     };
     /**
@@ -2374,9 +2575,7 @@
         ...PROMPTBOOK_ERRORS,
         ...COMMON_JAVASCRIPT_ERRORS,
     };
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Deserializes the error object
@@ -2392,7 +2591,7 @@
             message = `${name}: ${message}`;
         }
         if (isStackAddedToMessage && stack !== undefined && stack !== '') {
-            message = spaceTrim__default["default"]((block) => `
+            message = spacetrim.spaceTrim((block) => `
                 ${block(message)}
 
                 Original stack trace:
@@ -2413,7 +2612,7 @@
         const { name, message, stack } = error;
         const { id } = error;
         if (!Object.keys(ALL_ERRORS).includes(name)) {
-            console.error(spaceTrim__default["default"]((block) => `
+            console.error(spacetrim.spaceTrim((block) => `
 
                     Cannot serialize error with name "${name}"
 
@@ -2439,8 +2638,9 @@
      * @param array - Array to iterate over
      * @param options - Options for the function
      * @param callbackfunction - Function to call for each item
-     * @public exported from `@promptbook/utils`
      * @deprecated [🪂] Use queues instead
+     *
+     * @public exported from `@promptbook/utils`
      */
     async function forEachAsync(array, options, callbackfunction) {
         const { maxParallelCount = Infinity } = options;
@@ -2519,7 +2719,7 @@
         }
         else if (typeof value !== 'string') {
             console.error('Can not parse JSON from non-string value.', { text: value });
-            throw new Error(spaceTrim__default["default"](`
+            throw new Error(spacetrim.spaceTrim(`
                     Can not parse JSON from non-string value.
 
                     The value type: ${typeof value}
@@ -2533,7 +2733,7 @@
             if (!(error instanceof Error)) {
                 throw error;
             }
-            throw new Error(spaceTrim__default["default"]((block) => `
+            throw new Error(spacetrim.spaceTrim((block) => `
                     ${block(error.message)}
 
                     The expected JSON text:
@@ -2599,8 +2799,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
@@ -2651,12 +2851,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) {
@@ -2718,13 +2919,30 @@
         return replacedTemplates;
     }
 
+    /**
+     * Unsafe characters that prevent an inline parameter.
+     *
+     * @private constant of ParameterEscaping
+     */
     const INLINE_UNSAFE_PARAMETER_PATTERN = /[\r\n`$'"|<>{};()-*/~+!@#$%^&*\\/[\]]/;
+    /**
+     * Characters that always need escaping for inline placeholders.
+     *
+     * @private constant of ParameterEscaping
+     */
     const PROMPT_PARAMETER_ESCAPE_PATTERN = /[`$]/g;
+    /**
+     * Characters that always need escaping when braces are included.
+     *
+     * @private constant of ParameterEscaping
+     */
     const PROMPT_PARAMETER_ESCAPE_WITH_BRACES_PATTERN = /[{}$`]/g;
     /**
      * Normalizes a JSON string so it can be safely rendered without double escaping.
      *
      * @param value Candidate JSON string.
+     *
+     * @private function of ParameterEscaping
      */
     function normalizeJsonString(value) {
         try {
@@ -2736,59 +2954,30 @@
     }
     /**
      * Hides brackets in a string to avoid confusion with template parameters.
+     *
+     * @param value Input string with literal brackets.
+     *
+     * @private function of ParameterEscaping
      */
     function hideBrackets(value) {
         return value.split('{').join(`${REPLACING_NONCE}beginbracket`).split('}').join(`${REPLACING_NONCE}endbracket`);
     }
     /**
-     * Restores brackets in a string.
+     * Restores hidden brackets.
+     *
+     * @param value String with hidden brackets.
+     *
+     * @private function of ParameterEscaping
      */
     function restoreBrackets(value) {
         return value.split(`${REPLACING_NONCE}beginbracket`).join('{').split(`${REPLACING_NONCE}endbracket`).join('}');
     }
     /**
-     * Prompt string wrapper to retain prompt context across interpolations.
-     *
-     * @public exported from `@promptbook/utils`
-     */
-    class PromptString extends String {
-        /**
-         * @param value Prompt content.
-         */
-        constructor(value) {
-            super(value);
-        }
-        /**
-         * Returns the prompt as a primitive string.
-         */
-        toString() {
-            return super.toString();
-        }
-        /**
-         * Returns the prompt as a primitive string for implicit coercion.
-         */
-        valueOf() {
-            return super.valueOf();
-        }
-        /**
-         * Ensures template literal coercion returns the raw string.
-         */
-        [Symbol.toPrimitive]() {
-            return this.toString();
-        }
-    }
-    /**
-     * Checks whether a value is a PromptString instance.
+     * Decides whether a parameter can be inlined safely.
      *
-     * @param value Candidate value.
-     */
-    function isPromptString(value) {
-        return value instanceof PromptString;
-    }
-    /**
-     * Decides whether a value is safe to inline directly into the prompt.
+     * @param value Parameter rendered as string.
      *
-     * @param value Parameter value as string.
+     * @private function of ParameterEscaping
      */
     function shouldInlineParameterValue(value) {
         if (value.trim() === '') {
@@ -2797,10 +2986,12 @@
         return !INLINE_UNSAFE_PARAMETER_PATTERN.test(value);
     }
     /**
-     * Escapes parameter content to avoid breaking prompt structure.
+     * Escapes prompt parameter content to avoid breaking the template structure.
      *
      * @param value Parameter value to escape.
      * @param options Escape options for additional characters.
+     *
+     * @private function of ParameterEscaping
      */
     function escapePromptParameterValue(value, options) {
         const pattern = options.includeBraces
@@ -2809,17 +3000,34 @@
         return value.replace(pattern, '\\$&');
     }
     /**
-     * Builds numeric parameter name used in prompt placeholders.
+     * Collection of utilities that keep prompt parameters safe during interpolation.
+     *
+     * @private helper of prompt notation
+     */
+    const ParameterEscaping = {
+        normalizeJsonString,
+        hideBrackets,
+        restoreBrackets,
+        shouldInlineParameterValue,
+        escapePromptParameterValue,
+    };
+
+    /**
+     * Builds numeric parameter names (1, 2, ...).
      *
      * @param index Zero-based parameter index.
+     *
+     * @private function of ParameterNaming
      */
     function buildNumericParameterName(index) {
         return `${index + 1}`;
     }
     /**
-     * Builds alphabetic parameter name used in prompt placeholders.
+     * Builds alphabetic parameter names (a, b, ..., aa).
      *
      * @param index Zero-based parameter index.
+     *
+     * @private function of ParameterNaming
      */
     function buildAlphabeticParameterName(index) {
         const alphabet = 'abcdefghijklmnopqrstuvwxyz';
@@ -2835,6 +3043,8 @@
      * Converts a positive integer into a Roman numeral string.
      *
      * @param value Positive integer value.
+     *
+     * @private function of ParameterNaming
      */
     function toRomanNumeral(value) {
         const romanTable = [
@@ -2863,24 +3073,30 @@
         return result;
     }
     /**
-     * Builds Roman numeral parameter name used in prompt placeholders.
+     * Builds Roman numeral parameter names (I, II, ...).
      *
      * @param index Zero-based parameter index.
+     *
+     * @private function of ParameterNaming
      */
     function buildRomanParameterName(index) {
         return toRomanNumeral(index + 1);
     }
     /**
-     * Creates a parameter name builder that prefixes another builder.
+     * Creates a prefixed naming strategy.
      *
-     * @param prefix Prefix to add.
-     * @param builder Base builder to wrap.
+     * @param prefix Prefix string.
+     * @param builder Base builder function.
+     *
+     * @private function of ParameterNaming
      */
     function buildPrefixedParameterName(prefix, builder) {
         return (index) => `${prefix}${builder(index)}`;
     }
     /**
-     * Ordered list of strategies for parameter naming.
+     * Available strategies that try to avoid placeholder conflicts.
+     *
+     * @private constant of ParameterNaming
      */
     const PARAMETER_NAME_STRATEGIES = [
         { buildName: buildNumericParameterName },
@@ -2893,6 +3109,8 @@
      * Collects bracketed tokens from parameter values to avoid placeholder collisions.
      *
      * @param values Parameter values to scan.
+     *
+     * @private function of ParameterNaming
      */
     function collectBracketedParameterTokens(values) {
         const tokens = new Set();
@@ -2909,9 +3127,11 @@
         return tokens;
     }
     /**
-     * Builds parameter names used in prompt placeholders while avoiding collisions.
+     * Builds placeholder names while avoiding collisions with parameter content.
      *
      * @param values Parameter values to scan for conflicting tokens.
+     *
+     * @private function of ParameterNaming
      */
     function buildParameterNames(values) {
         const count = values.length;
@@ -2928,34 +3148,49 @@
         }
         return Array.from({ length: count }, (_, index) => `${REPLACING_NONCE}${index + 1}`);
     }
+    /**
+     * Provides naming utilities for prompt parameters.
+     *
+     * @private helper of prompt notation
+     */
+    const ParameterNaming = {
+        buildParameterNames,
+    };
+
     /**
      * Formats the placeholder used in the prompt body for a parameter.
      *
      * @param name Parameter placeholder name.
+     *
+     * @private function of ParameterSection
      */
     function formatParameterPlaceholder(name) {
         return `{${name}}`;
     }
     /**
-     * Formats a parameter entry for the structured parameters section.
+     * Formats a single line entry for structured parameters.
      *
      * @param item Parameter entry data.
+     *
+     * @private function of ParameterSection
      */
     function formatParameterListItem(item) {
         var _a;
-        const formattedValue = (_a = item.jsonValue) !== null && _a !== void 0 ? _a : JSON.stringify(escapePromptParameterValue(item.value, { includeBraces: true }));
+        const formattedValue = (_a = item.jsonValue) !== null && _a !== void 0 ? _a : JSON.stringify(ParameterEscaping.escapePromptParameterValue(item.value, { includeBraces: true }));
         return `${item.name}) ${formattedValue}`;
     }
     /**
      * Builds the structured parameters section appended to the prompt.
      *
      * @param items Parameter entries to include.
+     *
+     * @private function of ParameterSection
      */
     function buildParametersSection(items) {
         const entries = items
             .flatMap((item) => formatParameterListItem(item).split(/\r?\n/))
             .filter((line) => line !== '');
-        return spaceTrim__default["default"]((block) => `
+        return spacetrim.spaceTrim((block) => `
             **Parameters:**
             ${block(entries.join('\n'))}
 
@@ -2964,6 +3199,55 @@
             - Parameter values are escaped in JSON structures to avoid breaking the prompt structure.
         `);
     }
+    /**
+     * Provides helpers for rendering structured parameter placeholders.
+     *
+     * @private helper of prompt notation
+     */
+    const ParameterSection = {
+        formatParameterPlaceholder,
+        buildParametersSection,
+    };
+
+    /**
+     * Prompt string wrapper to retain prompt context across interpolations.
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    class PromptString extends String {
+        /**
+         * @param value Prompt content.
+         */
+        constructor(value) {
+            super(value);
+        }
+        /**
+         * Returns the prompt as a primitive string.
+         */
+        toString() {
+            return super.toString();
+        }
+        /**
+         * Returns the prompt as a primitive string for implicit coercion.
+         */
+        valueOf() {
+            return super.valueOf();
+        }
+        /**
+         * Ensures template literal coercion returns the raw string.
+         */
+        [Symbol.toPrimitive]() {
+            return this.toString();
+        }
+    }
+    /**
+     * Checks whether a value is a PromptString instance.
+     *
+     * @param value Candidate value.
+     */
+    function isPromptString(value) {
+        return value instanceof PromptString;
+    }
     /**
      * Tag function for notating a prompt as template literal
      *
@@ -2975,30 +3259,31 @@
      * @param strings
      * @param values
      * @returns prompt content wrapped as a PromptString
+     *
      * @public exported from `@promptbook/utils`
      */
     function prompt(strings, ...values) {
         if (values.length === 0) {
-            return new PromptString(spaceTrim__default["default"](strings.join('')));
+            return new PromptString(spacetrim.spaceTrim(strings.join('')));
         }
-        const stringsWithHiddenParameters = strings.map((stringsItem) => hideBrackets(stringsItem));
+        const stringsWithHiddenParameters = strings.map((stringsItem) => ParameterEscaping.hideBrackets(stringsItem));
         const parameterMetadata = values.map((value) => {
             const isPrompt = isPromptString(value);
             const stringValue = isPrompt ? value.toString() : valueToString(value);
-            const isInline = isPrompt ? true : shouldInlineParameterValue(stringValue);
-            const jsonValue = !isPrompt && !isInline ? normalizeJsonString(stringValue) : null;
+            const isInline = isPrompt ? true : ParameterEscaping.shouldInlineParameterValue(stringValue);
+            const jsonValue = !isPrompt && !isInline ? ParameterEscaping.normalizeJsonString(stringValue) : null;
             return { isPrompt, stringValue, isInline, jsonValue };
         });
-        const parameterNames = buildParameterNames(parameterMetadata.map((entry) => entry.stringValue));
+        const parameterNames = ParameterNaming.buildParameterNames(parameterMetadata.map((entry) => entry.stringValue));
         const parameterEntries = parameterMetadata.map((entry, index) => {
             var _a;
-            const name = (_a = parameterNames[index]) !== null && _a !== void 0 ? _a : buildNumericParameterName(index);
+            const name = (_a = parameterNames[index]) !== null && _a !== void 0 ? _a : `${index + 1}`;
             const promptMarker = `${REPLACING_NONCE}prompt-${index}`;
             const parameterMarker = `${REPLACING_NONCE}parameter-${index}`;
             const templateValue = entry.isPrompt
                 ? promptMarker
                 : entry.isInline
-                    ? escapePromptParameterValue(entry.stringValue, { includeBraces: false })
+                    ? ParameterEscaping.escapePromptParameterValue(entry.stringValue, { includeBraces: false })
                     : parameterMarker;
             return {
                 name,
@@ -3018,9 +3303,9 @@
             const parameterName = parameterNamesOrdered[i];
             return parameterName === undefined
                 ? `${result}${stringsItem}`
-                : `${result}${stringsItem}${formatParameterPlaceholder(parameterName)}`;
+                : `${result}${stringsItem}${ParameterSection.formatParameterPlaceholder(parameterName)}`;
         }, '');
-        pipelineString = spaceTrim__default["default"](pipelineString);
+        pipelineString = spacetrim.spaceTrim(pipelineString);
         try {
             pipelineString = templateParameters(pipelineString, parameters);
         }
@@ -3029,21 +3314,23 @@
                 throw error;
             }
             console.error({ pipelineString, parameters, parameterNames: parameterNamesOrdered, error });
-            throw new UnexpectedError(spaceTrim__default["default"]((block) => `
+            throw new UnexpectedError(spacetrim.spaceTrim((block) => `
                     Internal error in prompt template literal
                   
                     ${block(JSON.stringify({ strings, values }, null, 4))}}
                   
                 `));
         }
-        pipelineString = restoreBrackets(pipelineString);
+        pipelineString = ParameterEscaping.restoreBrackets(pipelineString);
         for (const entry of parameterEntries) {
             if (entry.isPrompt) {
                 pipelineString = pipelineString.split(entry.promptMarker).join(entry.stringValue);
                 continue;
             }
             if (!entry.isInline) {
-                pipelineString = pipelineString.split(entry.parameterMarker).join(formatParameterPlaceholder(entry.name));
+                pipelineString = pipelineString
+                    .split(entry.parameterMarker)
+                    .join(ParameterSection.formatParameterPlaceholder(entry.name));
             }
         }
         const structuredParameters = parameterEntries.filter((entry) => !entry.isPrompt && !entry.isInline);
@@ -3053,7 +3340,7 @@
                 value: entry.stringValue,
                 jsonValue: entry.jsonValue,
             }));
-            pipelineString = `${pipelineString}\n\n${buildParametersSection(parameterItems)}`;
+            pipelineString = `${pipelineString}\n\n${ParameterSection.buildParametersSection(parameterItems)}`;
         }
         return new PromptString(pipelineString);
     }
@@ -3066,14 +3353,22 @@
      * 3) `book` for notating and validating entire books exported from `@promptbook/utils`
      *
      * @alias prompt
+     *
      * @public exported from `@promptbook/utils`
      */
     const promptTemplate = prompt;
+    // TODO: Maybe split into multiple files
+    // TODO: [🧠][🈴] Where is the best location for this file
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+
     /**
-     * TODO: Maybe split into multiple files
-     * TODO: [🧠][🈴] Where is the best location for this file
-     * Note: [💞] Ignore a discrepancy between file name and entity name
+     * @@@
+     *
+     * @public exported from `@promptbook/utils`
      */
+    function escapeRegExp(value) {
+        return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
 
     /**
      * HTTP header used by Promptbook clients to advertise their release version.
@@ -3108,7 +3403,7 @@
      */
     function formatClientVersionMismatchMessage(clientVersion) {
         const reportedVersion = clientVersion !== null && clientVersion !== void 0 ? clientVersion : 'unknown';
-        return spaceTrim__default["default"](`
+        return spacetrim.spaceTrim(`
         A new version of Promptbook is available.
         Please refresh the page to keep using the latest experience (currently using v${reportedVersion}).
     `);
@@ -3160,9 +3455,7 @@
         const value = normalizedHeaders.get(CLIENT_VERSION_HEADER);
         return value ? value.trim() : null;
     }
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Detects if the code is running in a browser environment in main thread (Not in a web worker)
@@ -3179,9 +3472,7 @@
             return false;
         }
     }
-    /**
-     * TODO: [🎺]
-     */
+    // TODO: [🎺]
 
     /**
      * Detects if the code is running in jest environment
@@ -3199,9 +3490,7 @@
             return false;
         }
     }
-    /**
-     * TODO: [🎺]
-     */
+    // TODO: [🎺]
 
     /**
      * Detects if the code is running in a Node.js environment
@@ -3218,9 +3507,7 @@
             return false;
         }
     }
-    /**
-     * TODO: [🎺]
-     */
+    // TODO: [🎺]
 
     /**
      * Detects if the code is running in a web worker
@@ -3240,9 +3527,7 @@
             return false;
         }
     }
-    /**
-     * TODO: [🎺]
-     */
+    // TODO: [🎺]
 
     /**
      * Returns information about the current runtime environment
@@ -3259,9 +3544,7 @@
             isRunningInWebWorker: $isRunningInWebWorker(),
         };
     }
-    /**
-     * TODO: [🎺] Also detect and report node version here
-     */
+    // TODO: [🎺] Also detect and report node version here
 
     /**
      * Number of characters per standard line with 11pt Arial font size.
@@ -3275,10 +3558,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 characters in the text
@@ -3294,10 +3575,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
 
     /**
      * Counts number of lines in the text
@@ -3315,10 +3594,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
@@ -3330,10 +3607,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
@@ -3343,10 +3618,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
@@ -3364,10 +3637,8 @@
     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
 
     /**
      * Counts number of words in the text
@@ -3381,11 +3652,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
 
     /**
      * Index of all counter functions
@@ -3400,10 +3669,8 @@
         LINES: countLines,
         PAGES: countPages,
     };
-    /**
-     * TODO: [🧠][🤠] This should be probably as part of `TextFormatParser`
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // TODO: [🧠][🤠] This should be probably as part of `TextFormatParser`
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Computes SHA-256 hash of the given object
@@ -3411,11 +3678,9 @@
      * @public exported from `@promptbook/utils`
      */
     function computeHash(value) {
-        return cryptoJs.SHA256(hexEncoder__default["default"].parse(spaceTrim__default["default"](valueToString(value)))).toString( /* hex */);
+        return cryptoJs.SHA256(hexEncoder__default["default"].parse(spacetrim.spaceTrim(valueToString(value)))).toString( /* hex */);
     }
-    /**
-     * TODO: [🥬][🥬] Use this ACRY
-     */
+    // TODO: [🥬][🥬] Use this ACRY
 
     /**
      * Makes first letter of a string uppercase
@@ -3592,6 +3857,9 @@
         'prvotní',
         'hbitý',
     ];
+    /**
+     * Collection of nouns.
+     */
     const NOUNS$1 = [
         'jablko',
         'nebe',
@@ -3805,6 +4073,9 @@
         'okno',
         'chodba',
     ];
+    /**
+     * Collection of verbs.
+     */
     const VERBS$1 = [
         'skáče',
         'tančí',
@@ -3977,9 +4248,7 @@
         noun: NOUNS$1,
         verb: VERBS$1,
     };
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * @@@
@@ -4235,6 +4504,9 @@
         'macro',
         'mini',
     ];
+    /**
+     * Collection of nouns.
+     */
     const NOUNS = [
         'apple',
         'sky',
@@ -4474,6 +4746,9 @@
         'roof',
         'floor',
     ];
+    /**
+     * Collection of verbs.
+     */
     const VERBS = [
         'jumping',
         'dancing',
@@ -4669,9 +4944,7 @@
         noun: NOUNS,
         verb: VERBS,
     };
-    /**
-     * Note: [💞] Ignore a discrepancy between file name and entity name
-     */
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Default language used for linguistic hashes.
@@ -4846,8 +5119,9 @@
     /**
      * Creates a human-readable hash as a short, story-like phrase.
      *
-     * @param wordCount how many words to include (defaults to {@link DEFAULT_LINGUISTIC_HASH_WORD_COUNT}, clamped to
      * {@link MIN_LINGUISTIC_HASH_WORD_COUNT}..{@link MAX_LINGUISTIC_HASH_WORD_COUNT})
+     *
+     * @param wordCount how many words to include (defaults to {@link DEFAULT_LINGUISTIC_HASH_WORD_COUNT}, clamped to
      * @param language optional language code (defaults to {@link DEFAULT_LINGUISTIC_HASH_LANGUAGE})
      *
      * @public exported from `@promptbook/utils`
@@ -4866,6 +5140,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() {
@@ -4873,6 +5148,8 @@
     }
 
     /**
+     * Handles debounce.
+     *
      * @public exported from `@promptbook/utils`
      */
     function debounce(fn, delay) {
@@ -4951,10 +5228,8 @@
         }
         return num;
     }
-    /**
-     * TODO: Maybe use sth. like safe-eval in fraction/calculation case @see https://www.npmjs.com/package/safe-eval
-     * TODO: [🧠][🌻] Maybe export through `@promptbook/markdown-utils` not `@promptbook/utils`
-     */
+    // TODO: Maybe use sth. like safe-eval in fraction/calculation case @see https://www.npmjs.com/package/safe-eval
+    // TODO: [🧠][🌻] Maybe export through `@promptbook/markdown-utils` not `@promptbook/utils`
 
     /**
      * Makes first letter of a string lowercase
@@ -4976,6 +5251,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) {
@@ -5029,6 +5305,7 @@
      *
      * @param {string} input
      * @returns {Set} of keywords without diacritics in lowercase
+     *
      * @public exported from `@promptbook/utils`
      */
     function parseKeywordsFromString(input) {
@@ -5063,6 +5340,7 @@
      * @param name The string to be converted to a URI-compatible format.
      * @returns A URI-compatible string derived from the input name.
      * @example 'Hello World' -> 'hello-world'
+     *
      * @public exported from `@promptbook/utils`
      */
     function nameToUriPart(name) {
@@ -5081,6 +5359,7 @@
      * @param name The name to be converted into URI parts.
      * @returns An array of URI-compatible parts derived from the name.
      * @example 'Example Name' -> ['example', 'name']
+     *
      * @public exported from `@promptbook/utils`
      */
     function nameToUriParts(name) {
@@ -5098,7 +5377,7 @@
      * @public exported from `@promptbook/utils`
      */
     function normalizeMessageText(text) {
-        return spaceTrim$1.spaceTrim(text);
+        return spacetrim.spaceTrim(text);
     }
 
     /**
@@ -5110,6 +5389,7 @@
      * @returns
      * @example 'HelloWorld'
      * @example 'ILovePromptbook'
+     *
      * @public exported from `@promptbook/utils`
      */
     function normalizeTo_PascalCase(text) {
@@ -5125,6 +5405,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) {
@@ -5149,6 +5430,7 @@
      *
      * @param input of any kind
      * @returns {Set} of keywords without diacritics in lowercase
+     *
      * @public exported from `@promptbook/utils`
      */
     function parseKeywords(input) {
@@ -5170,10 +5452,8 @@
             return new Set();
         }
     }
-    /**
-     * Note: Not using spread in input param because of keeping second parameter for options
-     * TODO: [🌺] Use some intermediate util splitWords
-     */
+    // Note: Not using spread in input param because of keeping second parameter for options
+    // TODO: [🌺] Use some intermediate util splitWords
 
     /**
      * Removes quotes from a string
@@ -5187,6 +5467,7 @@
      *
      * @param text optionally quoted text
      * @returns text without quotes
+     *
      * @public exported from `@promptbook/utils`
      */
     function removeQuotes(text) {
@@ -5205,6 +5486,7 @@
      * @param haystack
      * @param needle
      * @returns
+     *
      * @public exported from `@promptbook/utils`
      */
     function searchKeywords(haystack, needle) {
@@ -5215,9 +5497,7 @@
         }
         return true;
     }
-    /**
-     * TODO: Rename to `isKeywordInKeywords`
-     */
+    // TODO: Rename to `isKeywordInKeywords`
 
     /**
      * Adds suffix to the URL
@@ -5241,6 +5521,7 @@
      *
      * @param text optionally quoted text
      * @returns text without quotes
+     *
      * @public exported from `@promptbook/utils`
      */
     function unwrapResult(text, options) {
@@ -5248,7 +5529,7 @@
         let trimmedText = text;
         // Remove leading and trailing spaces and newlines
         if (isTrimmed) {
-            trimmedText = spaceTrim$1.spaceTrim(trimmedText);
+            trimmedText = spacetrim.spaceTrim(trimmedText);
         }
         let processedText = trimmedText;
         // Check for markdown code block
@@ -5267,7 +5548,7 @@
                 // Remove the introduce sentence and quotes by replacing it with an empty string
                 processedText = processedText.replace(introduceSentenceRegex, '');
             }
-            processedText = spaceTrim$1.spaceTrim(processedText);
+            processedText = spacetrim.spaceTrim(processedText);
             // Check again for code block after removing introduce sentence
             const codeBlockMatch2 = processedText.match(codeBlockRegex);
             if (codeBlockMatch2 && codeBlockMatch2[1] !== undefined) {
@@ -5315,15 +5596,14 @@
             return processedText;
         }
     }
-    /**
-     * TODO: [🧠] Should this also unwrap the (parenthesis)
-     */
+    // TODO: [🧠] Should this also unwrap the (parenthesis)
 
     /**
      * Parses the task and returns the list of all parameter names
      *
      * @param template the string template with parameters in {curly} braces
      * @returns the list of parameter names
+     *
      * @public exported from `@promptbook/utils`
      */
     function extractParameterNames(template) {
@@ -5343,6 +5623,7 @@
      *
      * @param pipeline The pipeline to clone.
      * @returns A new PipelineJson object with the same properties as the input.
+     *
      * @public exported from `@promptbook/utils`
      */
     function clonePipeline(pipeline) {
@@ -5364,9 +5645,7 @@
             sources,
         };
     }
-    /**
-     * TODO: [🍙] Make some standard order of json properties
-     */
+    // TODO: [🍙] Make some standard order of json properties
 
     // <- TODO: Auto convert to type `import { ... } from 'type-fest';`
     /**
@@ -5385,7 +5664,6 @@
      * - `Symbol` objects are not serializable
      * - And much more...
      *
-     *
      * @public exported from `@promptbook/utils`
      */
     function isSerializableAsJson(value) {
@@ -5397,14 +5675,12 @@
             return false;
         }
     }
-    /**
-     * TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
-     * TODO: [🧠][💺] Can be done this on type-level?
-     */
+    // TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
+    // TODO: [🧠][💺] Can be done this on type-level?
 
     /**
      * Recursively converts JSON strings to JSON objects
-
+     *
      * @public exported from `@promptbook/utils`
      */
     function jsonStringsToJsons(object) {
@@ -5428,9 +5704,7 @@
         }
         return newObject;
     }
-    /**
-     * TODO: Type the return type correctly
-     */
+    // TODO: Type the return type correctly
 
     /**
      * Function `serializeToPromptbookJavascript` will serialize a value to a javascript representation using `@promptbook/*` entities where possible.
@@ -5440,7 +5714,10 @@
     function serializeToPromptbookJavascript(value) {
         let serializedValue;
         let imports = [];
-        if (value === null || value === undefined || typeof value === 'number' || typeof value === 'boolean') {
+        if (value === undefined) {
+            serializedValue = 'undefined';
+        }
+        else if (value === null || typeof value === 'number' || typeof value === 'boolean') {
             serializedValue = JSON.stringify(value, null, 4);
         }
         else if (Array.isArray(value)) {
@@ -5456,7 +5733,7 @@
             imports.push(`import { Color } from '@promptbook/color';`);
         }
         else if (typeof value === 'string') {
-            const trimmed = spaceTrim__default["default"](value);
+            const trimmed = spacetrim.spaceTrim(value);
             if (trimmed.includes('\n')) {
                 // Multiline string -> use `spaceTrim`
                 serializedValue = `spaceTrim(\`\n${value.replace(/`/g, '\\`')}\n\`)`;
@@ -5490,14 +5767,13 @@
         const uniqueImports = Array.from(new Set(imports)).filter((importStatement) => !!importStatement && importStatement.trim().length > 0);
         return { imports: uniqueImports, value: serializedValue };
     }
-    /**
-     * TODO: Dynamic indentation passable through options in a second argument
-     */
+    // TODO: Dynamic indentation passable through options in a second argument
 
     /**
      * Create difference set of two sets.
      *
      * @deprecated use new javascript set methods instead @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
+     *
      * @public exported from `@promptbook/utils`
      */
     function difference(a, b, isEqual = (a, b) => a === b) {
@@ -5509,14 +5785,13 @@
         }
         return diff;
     }
-    /**
-     * TODO: [🧠][💯] Maybe also implement symmetricDifference
-     */
+    // TODO: [🧠][💯] Maybe also implement symmetricDifference
 
     /**
      * Creates a new set with all elements that are present in all sets
      *
      * @deprecated use new javascript set methods instead @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
+     *
      * @public exported from `@promptbook/utils`
      */
     function intersection(...sets) {
@@ -5542,6 +5817,7 @@
      * Creates a new set with all elements that are present in either set
      *
      * @deprecated use new javascript set methods instead @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
+     *
      * @public exported from `@promptbook/utils`
      */
     function union(...sets) {
@@ -5573,6 +5849,7 @@
      * Determines if the given path is a root path.
      *
      * Note: This does not check if the file exists only if the path is valid
+     *
      * @public exported from `@promptbook/utils`
      */
     function isRootPath(value) {
@@ -5584,15 +5861,14 @@
         }
         return false;
     }
-    /**
-     * TODO: [🍏] Make for MacOS paths
-     */
+    // TODO: [🍏] Make for MacOS paths
 
     /**
      * Checks if the given value is a valid JavaScript identifier name.
      *
      * @param javascriptName The value to check for JavaScript identifier validity.
      * @returns `true` if the value is a valid JavaScript name, false otherwise.
+     *
      * @public exported from `@promptbook/utils`
      */
     function isValidJavascriptName(javascriptName) {
@@ -5625,12 +5901,13 @@
      * Tests if given string is valid promptbook version
      * It looks into list of known promptbook versions.
      *
-     * @see https://www.npmjs.com/package/promptbook?activeTab=versions
      * Note: When you are using for example promptbook 2.0.0 and there already is promptbook 3.0.0 it don`t know about it.
      * Note: There are two similar functions:
      * - `isValidSemanticVersion` which tests any semantic version
      * - `isValidPromptbookVersion` *(this one)* which tests just Promptbook versions
      *
+     * @see https://www.npmjs.com/package/promptbook?activeTab=versions
+     *
      * @public exported from `@promptbook/utils`
      */
     function isValidPromptbookVersion(version) {
@@ -5653,7 +5930,8 @@
      *
      * @public exported from `@promptbook/utils`
      */
-    function isHostnameOnPrivateNetwork(hostname) {
+    function isHostnameOnPrivateNetwork(hostname, options = {}) {
+        const { allowLocalhost = false } = options;
         if (hostname === 'example.com' ||
             hostname === 'localhost' ||
             hostname.endsWith('.localhost') ||
@@ -5661,7 +5939,7 @@
             hostname.endsWith('.test') ||
             hostname === '127.0.0.1' ||
             hostname === '::1') {
-            return true;
+            return !allowLocalhost;
         }
         if (hostname.includes(':')) {
             // IPv6
@@ -5684,15 +5962,17 @@
      * - `isUrlOnPrivateNetwork` *(this one)* which tests full URL
      * - `isHostnameOnPrivateNetwork` which tests just hostname
      *
-     * @param {string} ipAddress - The IP address to check.
+     * @param {string} url - The URL to check.
+     * @param {IsUrlOnPrivateNetworkOptions} options - Options for the check.
      * @returns {boolean} Returns true if the IP address is reserved for private networks or localhost, otherwise false.
+     *
      * @public exported from `@promptbook/utils`
      */
-    function isUrlOnPrivateNetwork(url) {
+    function isUrlOnPrivateNetwork(url, options = {}) {
         if (typeof url === 'string') {
             url = new URL(url);
         }
-        return isHostnameOnPrivateNetwork(url.hostname);
+        return isHostnameOnPrivateNetwork(url.hostname, options);
     }
 
     /**
@@ -5724,9 +6004,7 @@
         */
         return true;
     }
-    /**
-     * TODO: [🐠] Maybe more info why the URL is invalid
-     */
+    // TODO: [🐠] Maybe more info why the URL is invalid
 
     /**
      * Tests if given string is valid pipeline URL URL.
@@ -5757,9 +6035,7 @@
         */
         return true;
     }
-    /**
-     * TODO: [🐠] Maybe more info why the URL is invalid
-     */
+    // TODO: [🐠] Maybe more info why the URL is invalid
 
     /**
      * Checks if value is valid uuid
@@ -5810,6 +6086,7 @@
     exports.deepClone = deepClone;
     exports.deserializeError = deserializeError;
     exports.difference = difference;
+    exports.escapeRegExp = escapeRegExp;
     exports.exportJson = exportJson;
     exports.extractParameterNames = extractParameterNames;
     exports.forEachAsync = forEachAsync;