@promptbook/utils 0.111.0-4 → 0.112.0-100

package/esm/index.es.js

@@ -1,4 +1,4 @@
-import spaceTrim$2, { spaceTrim as spaceTrim$1 } from 'spacetrim';
+import { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import { basename } from 'path';
 import { randomBytes } from 'crypto';
 import { SHA256 } from 'crypto-js';
@@ -18,7 +18,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @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
@@ -28,16 +28,20 @@ const PROMPTBOOK_ENGINE_VERSION = '0.111.0-4';
  * 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;
 
 /**
- * @private util of `@promptbook/color`
+ * Class implementing take chain.
+ *
  * @de
+ *
+ * @private util of `@promptbook/color`
  */
 class TakeChain {
     constructor(value) {
@@ -54,9 +58,9 @@ class TakeChain {
  *
  * @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) {
@@ -234,9 +238,7 @@ const CSS_COLORS = {
     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.
@@ -266,6 +268,369 @@ function checkChannelValue(channelName, value) {
     }
 }
 
+/**
+ * Shared immutable channel storage and serialization helpers for `Color`.
+ *
+ * @private base class of Color
+ */
+class ColorValue {
+    constructor(red, green, blue, alpha = 255) {
+        this.red = red;
+        this.green = green;
+        this.blue = blue;
+        this.alpha = alpha;
+        checkChannelValue('Red', red);
+        checkChannelValue('Green', green);
+        checkChannelValue('Blue', blue);
+        checkChannelValue('Alpha', alpha);
+    }
+    /**
+     * Shortcut for `red` property
+     * Number from 0 to 255
+     * @alias red
+     */
+    get r() {
+        return this.red;
+    }
+    /**
+     * Shortcut for `green` property
+     * Number from 0 to 255
+     * @alias green
+     */
+    get g() {
+        return this.green;
+    }
+    /**
+     * Shortcut for `blue` property
+     * Number from 0 to 255
+     * @alias blue
+     */
+    get b() {
+        return this.blue;
+    }
+    /**
+     * Shortcut for `alpha` property
+     * Number from 0 (transparent) to 255 (opaque)
+     * @alias alpha
+     */
+    get a() {
+        return this.alpha;
+    }
+    /**
+     * Shortcut for `alpha` property
+     * Number from 0 (transparent) to 255 (opaque)
+     * @alias alpha
+     */
+    get opacity() {
+        return this.alpha;
+    }
+    /**
+     * Shortcut for 1-`alpha` property
+     */
+    get transparency() {
+        return 255 - this.alpha;
+    }
+    clone() {
+        return take(this.createColor(this.red, this.green, this.blue, this.alpha));
+    }
+    toString() {
+        return this.toHex();
+    }
+    toHex() {
+        if (this.alpha === 255) {
+            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}`;
+        }
+        else {
+            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
+        }
+    }
+    toRgb() {
+        if (this.alpha === 255) {
+            return `rgb(${this.red}, ${this.green}, ${this.blue})`;
+        }
+        else {
+            return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
+        }
+    }
+    toHsl() {
+        throw new Error(`Getting HSL is not implemented`);
+    }
+}
+
+/**
+ * Checks if the given value is a valid hex color string
+ *
+ * @param value - value to check
+ * @returns true if the value is a valid hex color string (e.g., `#009edd`, `#fff`, etc.)
+ *
+ * @private function of Color
+ */
+function isHexColorString(value) {
+    return (typeof value === 'string' && /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(value));
+}
+
+/**
+ * Constant for short hex lengths.
+ */
+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
  *
@@ -273,7 +638,7 @@ function checkChannelValue(channelName, value) {
  *
  * @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
@@ -346,30 +711,7 @@ class Color {
      * @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
@@ -399,73 +741,7 @@ class Color {
      * @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
@@ -474,52 +750,7 @@ class Color {
      * @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
@@ -528,25 +759,7 @@ class Color {
      * @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
@@ -555,39 +768,7 @@ class Color {
      * @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
@@ -599,7 +780,7 @@ class Color {
      * @returns Color object
      */
     static fromValues(red, green, blue, alpha = 255) {
-        return take(new Color(red, green, blue, alpha));
+        return Color.fromColorChannels({ red, green, blue, alpha });
     }
     /**
      * Checks if the given value is a valid Color object.
@@ -632,8 +813,7 @@ class Color {
      * @returns true if the value is a valid hex color string (e.g., `#009edd`, `#fff`, etc.)
      */
     static isHexColorString(value) {
-        return (typeof value === 'string' &&
-            /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(value));
+        return isHexColorString(value);
     }
     /**
      * Creates new Color object
@@ -646,107 +826,15 @@ class Color {
      * @param alpha number from 0 (transparent) to 255 (opaque)
      */
     constructor(red, green, blue, alpha = 255) {
-        this.red = red;
-        this.green = green;
-        this.blue = blue;
-        this.alpha = alpha;
-        checkChannelValue('Red', red);
-        checkChannelValue('Green', green);
-        checkChannelValue('Blue', blue);
-        checkChannelValue('Alpha', alpha);
+        super(red, green, blue, alpha);
     }
-    /**
-     * Shortcut for `red` property
-     * Number from 0 to 255
-     * @alias red
-     */
-    get r() {
-        return this.red;
+    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
@@ -808,9 +896,7 @@ function hslToRgb(hue, saturation, lightness) {
     }
     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
@@ -856,9 +942,7 @@ function rgbToHsl(red, green, blue) {
     }
     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
@@ -876,9 +960,7 @@ function lighten(amount) {
         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
@@ -896,9 +978,36 @@ function saturate(amount) {
         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
@@ -942,6 +1051,9 @@ const PROMPTBOOK_COLOR = Color.fromString('promptbook');
     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'),
 });
@@ -991,6 +1103,31 @@ const VALUE_STRINGS = {
  * @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.
@@ -1019,6 +1156,7 @@ parseInt(process.env.API_REQUEST_TIMEOUT || '90000');
  * Orders JSON object by keys
  *
  * @returns The same type of object as the input re-ordered
+ *
  * @public exported from `@promptbook/utils`
  */
 function orderJson(options) {
@@ -1037,6 +1175,7 @@ function orderJson(options) {
  * 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) {
@@ -1053,9 +1192,7 @@ function $deepFreeze(objectValue) {
     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
@@ -1065,7 +1202,7 @@ function $deepFreeze(objectValue) {
 function getErrorReportUrl(error) {
     const report = {
         title: `🐜 Error report from ${NAME}`,
-        body: spaceTrim$2((block) => `
+        body: spaceTrim$1((block) => `
 
 
             \`${error.name || 'Error'}\` has occurred in the [${NAME}], please look into it @${ADMIN_GITHUB_NAME}.
@@ -1191,125 +1328,187 @@ function assertsError(whatWasThrown) {
  * - 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$2((block) => `
-                        \`${name}\` is Date
+}
+/**
+ * Checks object-like values and dispatches special unsupported built-ins.
+ *
+ * @private function of `checkSerializableAsJson`
+ */
+function checkSerializableObject(context, objectValue) {
+    checkUnsupportedObjectType(context, objectValue);
+    checkSerializableObjectEntries(context, objectValue);
+    assertJsonStringificationSucceeds(context, objectValue);
+}
+/**
+ * Rejects built-in objects that must be converted before JSON serialization.
+ *
+ * @private function of `checkSerializableAsJson`
+ */
+function checkUnsupportedObjectType(context, objectValue) {
+    if (objectValue instanceof Date) {
+        throw new UnexpectedError(spaceTrim$1((block) => `
+                    \`${context.name}\` is Date
 
-                        Use \`string_date_iso8601\` instead
+                    Use \`string_date_iso8601\` instead
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
-                    `));
-        }
-        else if (value instanceof Map) {
-            throw new UnexpectedError(`${name} is Map`);
-        }
-        else if (value instanceof Set) {
-            throw new UnexpectedError(`${name} is Set`);
-        }
-        else if (value instanceof RegExp) {
-            throw new UnexpectedError(`${name} is RegExp`);
-        }
-        else if (value instanceof Error) {
-            throw new UnexpectedError(spaceTrim$2((block) => `
-                        \`${name}\` is unserialized Error
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
+                `));
+    }
+    if (objectValue instanceof Map) {
+        throw new UnexpectedError(`${context.name} is Map`);
+    }
+    if (objectValue instanceof Set) {
+        throw new UnexpectedError(`${context.name} is Set`);
+    }
+    if (objectValue instanceof RegExp) {
+        throw new UnexpectedError(`${context.name} is RegExp`);
+    }
+    if (objectValue instanceof Error) {
+        throw new UnexpectedError(spaceTrim$1((block) => `
+                    \`${context.name}\` is unserialized Error
 
-                        Use function \`serializeError\`
+                    Use function \`serializeError\`
 
-                        Additional message for \`${name}\`:
-                        ${block(message || '(nothing)')}
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
 
-                    `));
+                `));
+    }
+}
+/**
+ * Recursively checks object properties while preserving omitted `undefined` keys.
+ *
+ * @private function of `checkSerializableAsJson`
+ */
+function checkSerializableObjectEntries(context, objectValue) {
+    for (const [subName, subValue] of Object.entries(objectValue)) {
+        if (subValue === undefined) {
+            // Note: undefined in object is serializable - it is just omitted
+            continue;
         }
-        else {
-            for (const [subName, subValue] of Object.entries(value)) {
-                if (subValue === undefined) {
-                    // Note: undefined in object is serializable - it is just omitted
-                    continue;
-                }
-                checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
-            }
-            try {
-                JSON.stringify(value); // <- TODO: [0]
-            }
-            catch (error) {
-                assertsError(error);
-                throw new UnexpectedError(spaceTrim$2((block) => `
-                            \`${name}\` is not serializable
+        checkSerializableAsJson({
+            ...context,
+            name: `${context.name}.${subName}`,
+            value: subValue,
+        });
+    }
+}
+/**
+ * Uses `JSON.stringify` as the final guard for cases like circular references.
+ *
+ * @private function of `checkSerializableAsJson`
+ */
+function assertJsonStringificationSucceeds(context, objectValue) {
+    try {
+        JSON.stringify(objectValue); // <- TODO: [0]
+    }
+    catch (error) {
+        assertsError(error);
+        throw new UnexpectedError(spaceTrim$1((block) => `
+                    \`${context.name}\` is not serializable
 
-                            ${block(error.stack || error.message)}
+                    ${block(error.stack || error.message)}
 
-                            Additional message for \`${name}\`:
-                            ${block(message || '(nothing)')}
-                        `));
+                    Additional message for \`${context.name}\`:
+                    ${block(context.message || '(nothing)')}
+                `));
+    }
+    /*
+    TODO: [0] Is there some more elegant way to check circular references?
+    const seen = new Set();
+    const stack = [{ value }];
+    while (stack.length > 0) {
+        const { value } = stack.pop()!;
+        if (typeof value === 'object' && value !== null) {
+            if (seen.has(value)) {
+                throw new UnexpectedError(`${name} has circular reference`);
             }
-            /*
-            TODO: [0] Is there some more elegant way to check circular references?
-            const seen = new Set();
-            const stack = [{ value }];
-            while (stack.length > 0) {
-                const { value } = stack.pop()!;
-                if (typeof value === 'object' && value !== null) {
-                    if (seen.has(value)) {
-                        throw new UnexpectedError(`${name} has circular reference`);
-                    }
-                    seen.add(value);
-                    if (Array.isArray(value)) {
-                        stack.push(...value.map((value) => ({ value })));
-                    } else {
-                        stack.push(...Object.values(value).map((value) => ({ value })));
-                    }
-                }
+            seen.add(value);
+            if (Array.isArray(value)) {
+                stack.push(...value.map((value) => ({ value })));
+            } else {
+                stack.push(...Object.values(value).map((value) => ({ value })));
             }
-            */
-            return;
         }
     }
-    else {
-        throw new UnexpectedError(spaceTrim$2((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$1((block) => `
+                \`${context.name}\` is unknown type
+
+                Additional message for \`${context.name}\`:
+                ${block(context.message || '(nothing)')}
+            `));
+}
 
 /**
  * Creates a deep clone of the given object
@@ -1319,6 +1518,7 @@ function checkSerializableAsJson(options) {
  *
  * @param objectValue The object to clone.
  * @returns A deep, writable clone of the input object.
+ *
  * @public exported from `@promptbook/utils`
  */
 function deepClone(objectValue) {
@@ -1335,9 +1535,7 @@ function deepClone(objectValue) {
     > 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
@@ -1350,6 +1548,7 @@ function deepClone(objectValue) {
  * 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) {
@@ -1369,9 +1568,7 @@ function exportJson(options) {
     $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
@@ -1411,9 +1608,7 @@ const RESERVED_PARAMETER_NAMES = exportJson({
         // <- 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.
@@ -1425,6 +1620,7 @@ const RESERVED_PARAMETER_NAMES = exportJson({
  * @returns The camelCase formatted string.
  * @example 'helloWorld'
  * @example 'iLovePromptbook'
+ *
  * @public exported from `@promptbook/utils`
  */
 function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
@@ -1465,14 +1661,13 @@ function normalizeTo_camelCase(text, _isFirstLetterCapital = false) {
     }
     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) {
@@ -1521,9 +1716,7 @@ function isValidFilePath(filename) {
     }
     return false;
 }
-/**
- * TODO: [🍏] Implement for MacOs
- */
+// TODO: [🍏] Implement for MacOs
 
 /**
  * Tests if given string is valid URL.
@@ -1556,6 +1749,9 @@ function isValidUrl(url) {
     }
 }
 
+/**
+ * Collection of default diacritics removal map.
+ */
 const defaultDiacriticsRemovalMap = [
     {
         base: 'A',
@@ -1807,6 +2003,7 @@ for (let i = 0; i < defaultDiacriticsRemovalMap.length; i++) {
  *
  * @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) {
@@ -1815,9 +2012,7 @@ function removeDiacritics(input) {
         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.
@@ -1828,6 +2023,7 @@ function removeDiacritics(input) {
  * @returns The kebab-case formatted string.
  * @example 'hello-world'
  * @example 'i-love-promptbook'
+ *
  * @public exported from `@promptbook/utils`
  */
 function normalizeToKebabCase(text) {
@@ -1868,9 +2064,7 @@ function normalizeToKebabCase(text) {
     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
@@ -1879,6 +2073,7 @@ function normalizeToKebabCase(text) {
  *
  * @param text with emojis
  * @returns text without emojis
+ *
  * @public exported from `@promptbook/utils`
  */
 function removeEmojis(text) {
@@ -1898,6 +2093,7 @@ function removeEmojis(text) {
  * @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) {
@@ -2016,13 +2212,11 @@ function renderPromptbookMermaid(pipelineJson, options) {
         `);
     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
@@ -2068,15 +2262,28 @@ class AuthenticationError extends Error {
 }
 
 /**
- * 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);
     }
 }
 
@@ -2092,9 +2299,7 @@ class DatabaseError extends Error {
         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
@@ -2112,10 +2317,11 @@ class EnvironmentMismatchError extends Error {
 /**
  * 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) {
@@ -2230,9 +2436,7 @@ class ParseError extends Error {
         Object.setPrototypeOf(this, ParseError.prototype);
     }
 }
-/**
- * TODO: Maybe split `ParseError` and `ApplyError`
- */
+// TODO: Maybe split `ParseError` and `ApplyError`
 
 /**
  * Generates random token
@@ -2240,16 +2444,15 @@ class ParseError extends Error {
  * 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 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
@@ -2266,9 +2469,7 @@ class PipelineExecutionError extends Error {
         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)
@@ -2335,6 +2536,7 @@ const PROMPTBOOK_ERRORS = {
     WrappedError,
     NotAllowed,
     DatabaseError,
+    ConflictError,
     // TODO: [🪑]> VersionMismatchError,
 };
 /**
@@ -2369,9 +2571,7 @@ const ALL_ERRORS = {
     ...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
@@ -2387,7 +2587,7 @@ function deserializeError(error, isStackAddedToMessage = true) {
         message = `${name}: ${message}`;
     }
     if (isStackAddedToMessage && stack !== undefined && stack !== '') {
-        message = spaceTrim$2((block) => `
+        message = spaceTrim$1((block) => `
                 ${block(message)}
 
                 Original stack trace:
@@ -2408,7 +2608,7 @@ function serializeError(error) {
     const { name, message, stack } = error;
     const { id } = error;
     if (!Object.keys(ALL_ERRORS).includes(name)) {
-        console.error(spaceTrim$2((block) => `
+        console.error(spaceTrim$1((block) => `
 
                     Cannot serialize error with name "${name}"
 
@@ -2434,8 +2634,9 @@ function serializeError(error) {
  * @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;
@@ -2514,7 +2715,7 @@ function jsonParse(value) {
     }
     else if (typeof value !== 'string') {
         console.error('Can not parse JSON from non-string value.', { text: value });
-        throw new Error(spaceTrim$2(`
+        throw new Error(spaceTrim$1(`
                     Can not parse JSON from non-string value.
 
                     The value type: ${typeof value}
@@ -2528,7 +2729,7 @@ function jsonParse(value) {
         if (!(error instanceof Error)) {
             throw error;
         }
-        throw new Error(spaceTrim$2((block) => `
+        throw new Error(spaceTrim$1((block) => `
                     ${block(error.message)}
 
                     The expected JSON text:
@@ -2594,8 +2795,8 @@ function numberToString(value) {
  * 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
@@ -2646,12 +2847,13 @@ function valueToString(value) {
  * 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) {
@@ -2713,13 +2915,30 @@ function templateParameters(template, parameters) {
     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 {
@@ -2731,59 +2950,30 @@ function normalizeJsonString(value) {
 }
 /**
  * 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() === '') {
@@ -2792,10 +2982,12 @@ function shouldInlineParameterValue(value) {
     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
@@ -2804,17 +2996,34 @@ function escapePromptParameterValue(value, options) {
     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';
@@ -2830,6 +3039,8 @@ function buildAlphabeticParameterName(index) {
  * Converts a positive integer into a Roman numeral string.
  *
  * @param value Positive integer value.
+ *
+ * @private function of ParameterNaming
  */
 function toRomanNumeral(value) {
     const romanTable = [
@@ -2858,24 +3069,30 @@ function toRomanNumeral(value) {
     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 },
@@ -2888,6 +3105,8 @@ const PARAMETER_NAME_STRATEGIES = [
  * 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();
@@ -2904,9 +3123,11 @@ function collectBracketedParameterTokens(values) {
     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;
@@ -2923,34 +3144,49 @@ function buildParameterNames(values) {
     }
     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$2((block) => `
+    return spaceTrim$1((block) => `
             **Parameters:**
             ${block(entries.join('\n'))}
 
@@ -2959,6 +3195,55 @@ function buildParametersSection(items) {
             - 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
  *
@@ -2970,30 +3255,31 @@ function buildParametersSection(items) {
  * @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$2(strings.join('')));
+        return new PromptString(spaceTrim$1(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,
@@ -3013,9 +3299,9 @@ function prompt(strings, ...values) {
         const parameterName = parameterNamesOrdered[i];
         return parameterName === undefined
             ? `${result}${stringsItem}`
-            : `${result}${stringsItem}${formatParameterPlaceholder(parameterName)}`;
+            : `${result}${stringsItem}${ParameterSection.formatParameterPlaceholder(parameterName)}`;
     }, '');
-    pipelineString = spaceTrim$2(pipelineString);
+    pipelineString = spaceTrim$1(pipelineString);
     try {
         pipelineString = templateParameters(pipelineString, parameters);
     }
@@ -3024,21 +3310,23 @@ function prompt(strings, ...values) {
             throw error;
         }
         console.error({ pipelineString, parameters, parameterNames: parameterNamesOrdered, error });
-        throw new UnexpectedError(spaceTrim$2((block) => `
+        throw new UnexpectedError(spaceTrim$1((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);
@@ -3048,7 +3336,7 @@ function prompt(strings, ...values) {
             value: entry.stringValue,
             jsonValue: entry.jsonValue,
         }));
-        pipelineString = `${pipelineString}\n\n${buildParametersSection(parameterItems)}`;
+        pipelineString = `${pipelineString}\n\n${ParameterSection.buildParametersSection(parameterItems)}`;
     }
     return new PromptString(pipelineString);
 }
@@ -3061,14 +3349,22 @@ function prompt(strings, ...values) {
  * 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.
@@ -3103,7 +3399,7 @@ function isClientVersionCompatible(version) {
  */
 function formatClientVersionMismatchMessage(clientVersion) {
     const reportedVersion = clientVersion !== null && clientVersion !== void 0 ? clientVersion : 'unknown';
-    return spaceTrim$2(`
+    return spaceTrim$1(`
         A new version of Promptbook is available.
         Please refresh the page to keep using the latest experience (currently using v${reportedVersion}).
     `);
@@ -3155,9 +3451,7 @@ function getClientVersionFromHeaders(headers) {
     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)
@@ -3174,9 +3468,7 @@ function $isRunningInBrowser() {
         return false;
     }
 }
-/**
- * TODO: [🎺]
- */
+// TODO: [🎺]
 
 /**
  * Detects if the code is running in jest environment
@@ -3194,9 +3486,7 @@ function $isRunningInJest() {
         return false;
     }
 }
-/**
- * TODO: [🎺]
- */
+// TODO: [🎺]
 
 /**
  * Detects if the code is running in a Node.js environment
@@ -3213,9 +3503,7 @@ function $isRunningInNode() {
         return false;
     }
 }
-/**
- * TODO: [🎺]
- */
+// TODO: [🎺]
 
 /**
  * Detects if the code is running in a web worker
@@ -3235,9 +3523,7 @@ function $isRunningInWebWorker() {
         return false;
     }
 }
-/**
- * TODO: [🎺]
- */
+// TODO: [🎺]
 
 /**
  * Returns information about the current runtime environment
@@ -3254,9 +3540,7 @@ function $detectRuntimeEnvironment() {
         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.
@@ -3270,10 +3554,8 @@ const CHARACTERS_PER_STANDARD_LINE = 63;
  * @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
@@ -3289,10 +3571,8 @@ function countCharacters(text) {
     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
@@ -3310,10 +3590,8 @@ function countLines(text) {
     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
@@ -3325,10 +3603,8 @@ function countLines(text) {
 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
@@ -3338,10 +3614,8 @@ function countPages(text) {
 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
@@ -3359,10 +3633,8 @@ function splitIntoSentences(text) {
 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
@@ -3376,11 +3648,9 @@ function countWords(text) {
     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
@@ -3395,10 +3665,8 @@ const CountUtils = {
     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
@@ -3406,11 +3674,9 @@ const CountUtils = {
  * @public exported from `@promptbook/utils`
  */
 function computeHash(value) {
-    return SHA256(hexEncoder.parse(spaceTrim$2(valueToString(value)))).toString( /* hex */);
+    return SHA256(hexEncoder.parse(spaceTrim$1(valueToString(value)))).toString( /* hex */);
 }
-/**
- * TODO: [🥬][🥬] Use this ACRY
- */
+// TODO: [🥬][🥬] Use this ACRY
 
 /**
  * Makes first letter of a string uppercase
@@ -3587,6 +3853,9 @@ const ADJECTIVES$1 = [
     'prvotní',
     'hbitý',
 ];
+/**
+ * Collection of nouns.
+ */
 const NOUNS$1 = [
     'jablko',
     'nebe',
@@ -3800,6 +4069,9 @@ const NOUNS$1 = [
     'okno',
     'chodba',
 ];
+/**
+ * Collection of verbs.
+ */
 const VERBS$1 = [
     'skáče',
     'tančí',
@@ -3972,9 +4244,7 @@ const LINGUISTIC_HASH_WORD_LISTS_CS = {
     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
 
 /**
  * @@@
@@ -4230,6 +4500,9 @@ const ADJECTIVES = [
     'macro',
     'mini',
 ];
+/**
+ * Collection of nouns.
+ */
 const NOUNS = [
     'apple',
     'sky',
@@ -4469,6 +4742,9 @@ const NOUNS = [
     'roof',
     'floor',
 ];
+/**
+ * Collection of verbs.
+ */
 const VERBS = [
     'jumping',
     'dancing',
@@ -4664,9 +4940,7 @@ const LINGUISTIC_HASH_WORD_LISTS_EN = {
     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.
@@ -4841,8 +5115,9 @@ function normalizeLinguisticHashWordCount(wordCount) {
 /**
  * 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`
@@ -4861,6 +5136,7 @@ async function linguisticHash(input, wordCount, language) {
  * 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() {
@@ -4868,6 +5144,8 @@ function $getCurrentDate() {
 }
 
 /**
+ * Handles debounce.
+ *
  * @public exported from `@promptbook/utils`
  */
 function debounce(fn, delay) {
@@ -4946,10 +5224,8 @@ function parseNumber(value) {
     }
     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
@@ -4971,6 +5247,7 @@ function decapitalize(word) {
  * @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) {
@@ -5024,6 +5301,7 @@ function normalizeTo_SCREAMING_CASE(text) {
  *
  * @param {string} input
  * @returns {Set} of keywords without diacritics in lowercase
+ *
  * @public exported from `@promptbook/utils`
  */
 function parseKeywordsFromString(input) {
@@ -5058,6 +5336,7 @@ function isValidKeyword(keyword) {
  * @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) {
@@ -5076,6 +5355,7 @@ function nameToUriPart(name) {
  * @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) {
@@ -5105,6 +5385,7 @@ function normalizeMessageText(text) {
  * @returns
  * @example 'HelloWorld'
  * @example 'ILovePromptbook'
+ *
  * @public exported from `@promptbook/utils`
  */
 function normalizeTo_PascalCase(text) {
@@ -5120,6 +5401,7 @@ function normalizeTo_PascalCase(text) {
  * @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) {
@@ -5144,6 +5426,7 @@ function normalizeWhitespaces(sentence) {
  *
  * @param input of any kind
  * @returns {Set} of keywords without diacritics in lowercase
+ *
  * @public exported from `@promptbook/utils`
  */
 function parseKeywords(input) {
@@ -5165,10 +5448,8 @@ function parseKeywords(input) {
         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
@@ -5182,6 +5463,7 @@ function parseKeywords(input) {
  *
  * @param text optionally quoted text
  * @returns text without quotes
+ *
  * @public exported from `@promptbook/utils`
  */
 function removeQuotes(text) {
@@ -5200,6 +5482,7 @@ function removeQuotes(text) {
  * @param haystack
  * @param needle
  * @returns
+ *
  * @public exported from `@promptbook/utils`
  */
 function searchKeywords(haystack, needle) {
@@ -5210,9 +5493,7 @@ function searchKeywords(haystack, needle) {
     }
     return true;
 }
-/**
- * TODO: Rename to `isKeywordInKeywords`
- */
+// TODO: Rename to `isKeywordInKeywords`
 
 /**
  * Adds suffix to the URL
@@ -5236,6 +5517,7 @@ function suffixUrl(value, suffix) {
  *
  * @param text optionally quoted text
  * @returns text without quotes
+ *
  * @public exported from `@promptbook/utils`
  */
 function unwrapResult(text, options) {
@@ -5310,15 +5592,14 @@ function unwrapResult(text, options) {
         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) {
@@ -5338,6 +5619,7 @@ function extractParameterNames(template) {
  *
  * @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) {
@@ -5359,9 +5641,7 @@ function clonePipeline(pipeline) {
         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';`
 /**
@@ -5380,7 +5660,6 @@ function clonePipeline(pipeline) {
  * - `Symbol` objects are not serializable
  * - And much more...
  *
- *
  * @public exported from `@promptbook/utils`
  */
 function isSerializableAsJson(value) {
@@ -5392,14 +5671,12 @@ function isSerializableAsJson(value) {
         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) {
@@ -5423,9 +5700,7 @@ function jsonStringsToJsons(object) {
     }
     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.
@@ -5435,7 +5710,10 @@ function jsonStringsToJsons(object) {
 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)) {
@@ -5451,7 +5729,7 @@ function serializeToPromptbookJavascript(value) {
         imports.push(`import { Color } from '@promptbook/color';`);
     }
     else if (typeof value === 'string') {
-        const trimmed = spaceTrim$2(value);
+        const trimmed = spaceTrim$1(value);
         if (trimmed.includes('\n')) {
             // Multiline string -> use `spaceTrim`
             serializedValue = `spaceTrim(\`\n${value.replace(/`/g, '\\`')}\n\`)`;
@@ -5485,14 +5763,13 @@ function serializeToPromptbookJavascript(value) {
     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) {
@@ -5504,14 +5781,13 @@ function difference(a, b, isEqual = (a, b) => a === b) {
     }
     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) {
@@ -5537,6 +5813,7 @@ function intersection(...sets) {
  * 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) {
@@ -5568,6 +5845,7 @@ function isValidEmail(email) {
  * 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) {
@@ -5579,15 +5857,14 @@ function isRootPath(value) {
     }
     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) {
@@ -5620,12 +5897,13 @@ function isValidSemanticVersion(version) {
  * 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) {
@@ -5648,7 +5926,8 @@ function isValidPromptbookVersion(version) {
  *
  * @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') ||
@@ -5656,7 +5935,7 @@ function isHostnameOnPrivateNetwork(hostname) {
         hostname.endsWith('.test') ||
         hostname === '127.0.0.1' ||
         hostname === '::1') {
-        return true;
+        return !allowLocalhost;
     }
     if (hostname.includes(':')) {
         // IPv6
@@ -5679,15 +5958,17 @@ function isHostnameOnPrivateNetwork(hostname) {
  * - `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);
 }
 
 /**
@@ -5719,9 +6000,7 @@ function isValidAgentUrl(url) {
     */
     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.
@@ -5752,9 +6031,7 @@ function isValidPipelineUrl(url) {
     */
     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
@@ -5770,5 +6047,5 @@ function isValidUuid(value) {
     return /^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$/i.test(value);
 }
 
-export { $deepFreeze, $detectRuntimeEnvironment, $getCurrentDate, $isRunningInBrowser, $isRunningInJest, $isRunningInNode, $isRunningInWebWorker, BOOK_LANGUAGE_VERSION, CHARACTERS_PER_STANDARD_LINE, CLIENT_LATEST_VERSION, CLIENT_VERSION_HEADER, ClientVersionMismatchError, CountUtils, DIACRITIC_VARIANTS_LETTERS, LINES_PER_STANDARD_PAGE, PROMPTBOOK_ENGINE_VERSION, PromptString, SMALL_NUMBER, VALUE_STRINGS, attachClientVersionHeader, capitalize, checkSerializableAsJson, clonePipeline, computeHash, countCharacters, countLines, countPages, countParagraphs, countSentences, countWords, debounce, decapitalize, deepClone, deserializeError, difference, exportJson, extractParameterNames, forEachAsync, formatClientVersionMismatchMessage, getClientVersionFromHeaders, intersection, isClientVersionCompatible, isHostnameOnPrivateNetwork, isRootPath, isSerializableAsJson, isUrlOnPrivateNetwork, isValidAgentUrl, isValidCsvString, isValidEmail, isValidFilePath, isValidJavascriptName, isValidJsonString, isValidKeyword, isValidPipelineUrl, isValidPromptbookVersion, isValidSemanticVersion, isValidUrl, isValidUuid, isValidXmlString, jsonParse, jsonStringsToJsons, linguisticHash, nameToUriPart, nameToUriParts, normalizeMessageText, normalizeToKebabCase, normalizeTo_PascalCase, normalizeTo_SCREAMING_CASE, normalizeTo_camelCase, normalizeTo_snake_case, normalizeWhitespaces, numberToString, orderJson, parseKeywords, parseKeywordsFromString, parseNumber, prompt, promptTemplate, removeDiacritics, removeEmojis, removeQuotes, renderPromptbookMermaid, searchKeywords, serializeError, serializeToPromptbookJavascript, spaceTrim, splitIntoSentences, suffixUrl, templateParameters, titleToName, union, unwrapResult, valueToString };
+export { $deepFreeze, $detectRuntimeEnvironment, $getCurrentDate, $isRunningInBrowser, $isRunningInJest, $isRunningInNode, $isRunningInWebWorker, BOOK_LANGUAGE_VERSION, CHARACTERS_PER_STANDARD_LINE, CLIENT_LATEST_VERSION, CLIENT_VERSION_HEADER, ClientVersionMismatchError, CountUtils, DIACRITIC_VARIANTS_LETTERS, LINES_PER_STANDARD_PAGE, PROMPTBOOK_ENGINE_VERSION, PromptString, SMALL_NUMBER, VALUE_STRINGS, attachClientVersionHeader, capitalize, checkSerializableAsJson, clonePipeline, computeHash, countCharacters, countLines, countPages, countParagraphs, countSentences, countWords, debounce, decapitalize, deepClone, deserializeError, difference, escapeRegExp, exportJson, extractParameterNames, forEachAsync, formatClientVersionMismatchMessage, getClientVersionFromHeaders, intersection, isClientVersionCompatible, isHostnameOnPrivateNetwork, isRootPath, isSerializableAsJson, isUrlOnPrivateNetwork, isValidAgentUrl, isValidCsvString, isValidEmail, isValidFilePath, isValidJavascriptName, isValidJsonString, isValidKeyword, isValidPipelineUrl, isValidPromptbookVersion, isValidSemanticVersion, isValidUrl, isValidUuid, isValidXmlString, jsonParse, jsonStringsToJsons, linguisticHash, nameToUriPart, nameToUriParts, normalizeMessageText, normalizeToKebabCase, normalizeTo_PascalCase, normalizeTo_SCREAMING_CASE, normalizeTo_camelCase, normalizeTo_snake_case, normalizeWhitespaces, numberToString, orderJson, parseKeywords, parseKeywordsFromString, parseNumber, prompt, promptTemplate, removeDiacritics, removeEmojis, removeQuotes, renderPromptbookMermaid, searchKeywords, serializeError, serializeToPromptbookJavascript, spaceTrim, splitIntoSentences, suffixUrl, templateParameters, titleToName, union, unwrapResult, valueToString };
 //# sourceMappingURL=index.es.js.map