@promptbook/utils 0.111.0-4 → 0.112.0-11

package/esm/index.es.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-11';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -266,6 +266,188 @@ function checkChannelValue(channelName, value) {
     }
 }
 
+const SHORT_HEX_LENGTHS = new Set([3, 4]);
+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();
+}
+function parseShortHexChannel(char, onError) {
+    if (!char) {
+        return onError();
+    }
+    const parsed = parseInt(char, 16);
+    if (Number.isNaN(parsed)) {
+        return onError();
+    }
+    return parsed * 16;
+}
+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;
+}
+
+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,
+    };
+}
+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),
+    };
+}
+
+const RGB_REGEX = /^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+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]),
+    };
+}
+function parseChannelValue(value) {
+    if (value.endsWith('%')) {
+        const percent = parseFloat(value);
+        return Math.round((percent / 100) * 255);
+    }
+    return Math.round(parseFloat(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);
+}
+
+const HSL_REGEX_PATTERN = /^hsl\(\s*([0-9.]+)\s*,\s*([0-9.]+)%\s*,\s*([0-9.]+)%\s*\)$/;
+const RGB_REGEX_PATTERN = /^rgb\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
+const RGBA_REGEX_PATTERN = /^rgba\(\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*,\s*([0-9.%-]+)\s*\)$/;
 /**
  * Color object represents an RGB color with alpha channel
  *
@@ -346,29 +528,24 @@ class Color {
      * @returns Color object
      */
     static fromString(color) {
-        if (CSS_COLORS[color]) {
-            return Color.fromString(CSS_COLORS[color]);
-            // -----
+        const trimmed = color.trim();
+        if (CSS_COLORS[trimmed]) {
+            return Color.fromString(CSS_COLORS[trimmed]);
         }
-        else if (Color.isHexColorString(color)) {
-            return Color.fromHex(color);
-            // -----
+        else if (Color.isHexColorString(trimmed)) {
+            return Color.fromHex(trimmed);
         }
-        else if (/^hsl\(\s*(\d+)\s*,\s*(\d+(?:\.\d+)?%)\s*,\s*(\d+(?:\.\d+)?%)\)$/.test(color)) {
-            return Color.fromHsl(color);
-            // -----
+        if (HSL_REGEX_PATTERN.test(trimmed)) {
+            return Color.fromHsl(trimmed);
         }
-        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 (RGB_REGEX_PATTERN.test(trimmed)) {
+            return Color.fromRgbString(trimmed);
         }
-        else if (/^rgba\((\s*[0-9-.%]+\s*,?){4}\)$/.test(color)) {
-            return Color.fromRgbaString(color);
-            // -----
+        else if (RGBA_REGEX_PATTERN.test(trimmed)) {
+            return Color.fromRgbaString(trimmed);
         }
         else {
-            throw new Error(`Can not create a new Color instance from string "${color}".`);
+            throw new Error(`Can not create a new Color instance from string "${trimmed}".`);
         }
     }
     /**
@@ -399,73 +576,8 @@ 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));
+        const { red, green, blue, alpha } = parseHexColor(hex);
+        return take(new Color(red, green, blue, alpha));
     }
     /**
      * Creates a new Color instance from color in hsl format
@@ -474,52 +586,8 @@ 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));
+        const { red, green, blue, alpha } = parseHslColor(hsl);
+        return take(new Color(red, green, blue, alpha));
     }
     /**
      * Creates a new Color instance from color in rgb format
@@ -528,25 +596,8 @@ 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));
+        const { red, green, blue, alpha } = parseRgbColor(rgb);
+        return take(new Color(red, green, blue, alpha));
     }
     /**
      * Creates a new Color instance from color in rbga format
@@ -555,39 +606,8 @@ 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));
+        const { red, green, blue, alpha } = parseRgbaColor(rgba);
+        return take(new Color(red, green, blue, alpha));
     }
     /**
      * Creates a new Color for color channels values
@@ -731,22 +751,6 @@ class Color {
         throw new Error(`Getting HSL is not implemented`);
     }
 }
-/**
- * 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
@@ -942,6 +946,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'),
 });
@@ -2080,6 +2087,19 @@ class CollectionError extends Error {
     }
 }
 
+/**
+ * Signals that the requested operation could not be completed because the target already exists.
+ *
+ * @public exported from `@promptbook/core`
+ */
+class ConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConflictError';
+        Object.setPrototypeOf(this, ConflictError.prototype);
+    }
+}
+
 /**
  * This error indicates error from the database
  *
@@ -2335,6 +2355,7 @@ const PROMPTBOOK_ERRORS = {
     WrappedError,
     NotAllowed,
     DatabaseError,
+    ConflictError,
     // TODO: [🪑]> VersionMismatchError,
 };
 /**
@@ -2713,13 +2734,29 @@ 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 +2768,27 @@ 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.
- *
- * @param value Candidate value.
- */
-function isPromptString(value) {
-    return value instanceof PromptString;
-}
-/**
- * Decides whether a value is safe to inline directly into the prompt.
+ * Decides whether a parameter can be inlined safely.
  *
- * @param value Parameter value as string.
+ * @param value Parameter rendered as string.
+ * @private function of ParameterEscaping
  */
 function shouldInlineParameterValue(value) {
     if (value.trim() === '') {
@@ -2792,10 +2797,11 @@ 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 +2810,32 @@ 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 +2851,7 @@ 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 +2880,28 @@ 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 +2914,7 @@ 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 +2931,10 @@ 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,28 +2951,40 @@ 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
@@ -2959,6 +2999,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
  *
@@ -2976,24 +3065,24 @@ function prompt(strings, ...values) {
     if (values.length === 0) {
         return new PromptString(spaceTrim$2(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,7 +3102,7 @@ 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);
     try {
@@ -3031,14 +3120,16 @@ function prompt(strings, ...values) {
                   
                 `));
     }
-    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 +3139,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);
 }
@@ -3070,6 +3161,15 @@ const promptTemplate = prompt;
  * 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.
  *
@@ -5648,7 +5748,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 +5757,7 @@ function isHostnameOnPrivateNetwork(hostname) {
         hostname.endsWith('.test') ||
         hostname === '127.0.0.1' ||
         hostname === '::1') {
-        return true;
+        return !allowLocalhost;
     }
     if (hostname.includes(':')) {
         // IPv6
@@ -5679,15 +5780,16 @@ 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);
 }
 
 /**
@@ -5770,5 +5872,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