@gravity-ui/aikit 2.4.0 → 2.5.0

package/build/cjs/package.json

@@ -1 +1 @@
-{"version":"2.4.0","type":"commonjs","sideEffects":["*.css","*.scss"]}
+{"version":"2.5.0","type":"commonjs","sideEffects":["*.css","*.scss"]}

package/build/cjs/utils/aiAgentContext/AIAgentContext.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { AIAgentContextAPI, AIAgentContextValue } from "./types.js";
+declare const AIAgentContext: React.Context<AIAgentContextValue<unknown> | null>;
+/** Raw context — internal use only, not exported from the package. */
+export { AIAgentContext as _AIAgentContext };
+/**
+ * Provider that manages the AI data registry.
+ * Wrap your app or chat area with this to enable AIData collection.
+ */
+export declare function AIAgentContextProvider({ children }: {
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook for consumers to access registered AI data.
+ * Returns { getData } where getData() returns the current list of all entries.
+ * If no AIAgentContextProvider exists above, getData() returns [].
+ *
+ * Generic `T` is the **expected** shape of `data` for this consumer — not validated
+ * or guaranteed at runtime. The registry is populated by arbitrary `AIData`
+ * registrations; entries may not match `T`.
+ */
+export declare function useAIAgentContext<T = unknown>(): AIAgentContextAPI<T>;

package/build/cjs/utils/aiAgentContext/AIAgentContext.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._AIAgentContext = void 0;
+exports.AIAgentContextProvider = AIAgentContextProvider;
+exports.useAIAgentContext = useAIAgentContext;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const AIAgentContext = (0, react_1.createContext)(null);
+exports._AIAgentContext = AIAgentContext;
+/**
+ * Provider that manages the AI data registry.
+ * Wrap your app or chat area with this to enable AIData collection.
+ */
+function AIAgentContextProvider({ children }) {
+    const registryRef = (0, react_1.useRef)(new Map());
+    const contextValue = (0, react_1.useMemo)(() => ({
+        register: (id, getter) => {
+            registryRef.current.set(id, getter);
+        },
+        unregister: (id) => {
+            registryRef.current.delete(id);
+        },
+        getData: () => Array.from(registryRef.current.values()).map((getter) => {
+            const { label, data } = getter();
+            return { label, data };
+        }),
+    }), []);
+    return (0, jsx_runtime_1.jsx)(AIAgentContext.Provider, { value: contextValue, children: children });
+}
+/**
+ * Hook for consumers to access registered AI data.
+ * Returns { getData } where getData() returns the current list of all entries.
+ * If no AIAgentContextProvider exists above, getData() returns [].
+ *
+ * Generic `T` is the **expected** shape of `data` for this consumer — not validated
+ * or guaranteed at runtime. The registry is populated by arbitrary `AIData`
+ * registrations; entries may not match `T`.
+ */
+function useAIAgentContext() {
+    const ctx = (0, react_1.useContext)(AIAgentContext);
+    const getData = (0, react_1.useCallback)(() => {
+        if (!ctx)
+            return [];
+        return ctx.getData();
+    }, [ctx]);
+    return (0, react_1.useMemo)(() => ({ getData }), [getData]);
+}
+//# sourceMappingURL=AIAgentContext.js.map

package/build/cjs/utils/aiAgentContext/AIAgentContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AIAgentContext.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/AIAgentContext.tsx"],"names":[],"mappings":";;;AAaA,wDAqBC;AAWD,8CASC;;AAtDD,iCAAqF;AAIrF,MAAM,cAAc,GAAG,IAAA,qBAAa,EAA6B,IAAI,CAAC,CAAC;AAG7C,yCAAe;AAEzC;;;GAGG;AACH,SAAgB,sBAAsB,CAAC,EAAC,QAAQ,EAA8B;IAC1E,MAAM,WAAW,GAAG,IAAA,cAAM,EAAC,IAAI,GAAG,EAA6B,CAAC,CAAC;IAEjE,MAAM,YAAY,GAAG,IAAA,eAAO,EACxB,GAAG,EAAE,CAAC,CAAC;QACH,QAAQ,EAAE,CAAC,EAAU,EAAE,MAAyB,EAAE,EAAE;YAChD,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACxC,CAAC;QACD,UAAU,EAAE,CAAC,EAAU,EAAE,EAAE;YACvB,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,EAAE,GAAkB,EAAE,CACzB,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;YACpD,MAAM,EAAC,KAAK,EAAE,IAAI,EAAC,GAAG,MAAM,EAAE,CAAC;YAC/B,OAAO,EAAC,KAAK,EAAE,IAAI,EAAC,CAAC;QACzB,CAAC,CAAC;KACT,CAAC,EACF,EAAE,CACL,CAAC;IAEF,OAAO,uBAAC,cAAc,CAAC,QAAQ,IAAC,KAAK,EAAE,YAAY,YAAG,QAAQ,GAA2B,CAAC;AAC9F,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,iBAAiB;IAC7B,MAAM,GAAG,GAAG,IAAA,kBAAU,EAAC,cAAc,CAAC,CAAC;IAEvC,MAAM,OAAO,GAAG,IAAA,mBAAW,EAAC,GAAqB,EAAE;QAC/C,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,CAAC;QACpB,OAAO,GAAG,CAAC,OAAO,EAAsB,CAAC;IAC7C,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEV,OAAO,IAAA,eAAO,EAAC,GAAG,EAAE,CAAC,CAAC,EAAC,OAAO,EAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;AACjD,CAAC","sourcesContent":["import React, {createContext, useCallback, useContext, useMemo, useRef} from 'react';\n\nimport type {AIAgentContextAPI, AIAgentContextValue, AIDataEntry, AIDataProps} from './types';\n\nconst AIAgentContext = createContext<AIAgentContextValue | null>(null);\n\n/** Raw context — internal use only, not exported from the package. */\nexport {AIAgentContext as _AIAgentContext};\n\n/**\n * Provider that manages the AI data registry.\n * Wrap your app or chat area with this to enable AIData collection.\n */\nexport function AIAgentContextProvider({children}: {children: React.ReactNode}) {\n    const registryRef = useRef(new Map<string, () => AIDataProps>());\n\n    const contextValue = useMemo<AIAgentContextValue>(\n        () => ({\n            register: (id: string, getter: () => AIDataProps) => {\n                registryRef.current.set(id, getter);\n            },\n            unregister: (id: string) => {\n                registryRef.current.delete(id);\n            },\n            getData: (): AIDataEntry[] =>\n                Array.from(registryRef.current.values()).map((getter) => {\n                    const {label, data} = getter();\n                    return {label, data};\n                }),\n        }),\n        [],\n    );\n\n    return <AIAgentContext.Provider value={contextValue}>{children}</AIAgentContext.Provider>;\n}\n\n/**\n * Hook for consumers to access registered AI data.\n * Returns { getData } where getData() returns the current list of all entries.\n * If no AIAgentContextProvider exists above, getData() returns [].\n *\n * Generic `T` is the **expected** shape of `data` for this consumer — not validated\n * or guaranteed at runtime. The registry is populated by arbitrary `AIData`\n * registrations; entries may not match `T`.\n */\nexport function useAIAgentContext<T = unknown>(): AIAgentContextAPI<T> {\n    const ctx = useContext(AIAgentContext);\n\n    const getData = useCallback((): AIDataEntry<T>[] => {\n        if (!ctx) return [];\n        return ctx.getData() as AIDataEntry<T>[];\n    }, [ctx]);\n\n    return useMemo(() => ({getData}), [getData]);\n}\n"]}

package/build/cjs/utils/aiAgentContext/AIData.d.ts

@@ -0,0 +1,17 @@
+import type { AIDataProps } from "./types.js";
+/**
+ * Hook to register data in the AI agent context.
+ *
+ * Registration happens in `useEffect`, so `getData()` is only meaningful
+ * **after mount** of components that register data. Do not call `getData()`
+ * synchronously during render or in `useLayoutEffect` in the same commit.
+ *
+ * Uses a ref + getter pattern: the registry stores `() => propsRef.current`
+ * so `getData()` always reads the latest props without re-registering on every render.
+ */
+export declare function useProvideAIData<T>(props: AIDataProps<T>): void;
+/**
+ * Component that registers data in the AI agent context.
+ * Pure side-effect — renders nothing.
+ */
+export declare function AIData<T>(props: AIDataProps<T>): null;

package/build/cjs/utils/aiAgentContext/AIData.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useProvideAIData = useProvideAIData;
+exports.AIData = AIData;
+const react_1 = require("react");
+const AIAgentContext_1 = require("./AIAgentContext.js");
+/**
+ * Hook to register data in the AI agent context.
+ *
+ * Registration happens in `useEffect`, so `getData()` is only meaningful
+ * **after mount** of components that register data. Do not call `getData()`
+ * synchronously during render or in `useLayoutEffect` in the same commit.
+ *
+ * Uses a ref + getter pattern: the registry stores `() => propsRef.current`
+ * so `getData()` always reads the latest props without re-registering on every render.
+ */
+function useProvideAIData(props) {
+    const ctx = (0, react_1.useContext)(AIAgentContext_1._AIAgentContext);
+    const id = (0, react_1.useId)();
+    const propsRef = (0, react_1.useRef)(props);
+    propsRef.current = props;
+    (0, react_1.useEffect)(() => {
+        if (!ctx) {
+            // eslint-disable-next-line no-console
+            console.warn('useProvideAIData must be used inside AIAgentContextProvider');
+            return;
+        }
+        ctx.register(id, () => propsRef.current);
+        // eslint-disable-next-line consistent-return
+        return () => {
+            ctx.unregister(id);
+        };
+    }, [ctx, id]);
+}
+/**
+ * Component that registers data in the AI agent context.
+ * Pure side-effect — renders nothing.
+ */
+function AIData(props) {
+    useProvideAIData(props);
+    return null;
+}
+//# sourceMappingURL=AIData.js.map

package/build/cjs/utils/aiAgentContext/AIData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AIData.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/AIData.ts"],"names":[],"mappings":";;AAeA,4CAqBC;AAMD,wBAGC;AA7CD,iCAA2D;AAE3D,wDAAiD;AAGjD;;;;;;;;;GASG;AACH,SAAgB,gBAAgB,CAAI,KAAqB;IACrD,MAAM,GAAG,GAAG,IAAA,kBAAU,EAAC,gCAAe,CAAC,CAAC;IACxC,MAAM,EAAE,GAAG,IAAA,aAAK,GAAE,CAAC;IACnB,MAAM,QAAQ,GAAG,IAAA,cAAM,EAAC,KAAK,CAAC,CAAC;IAC/B,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAC;IAEzB,IAAA,iBAAS,EAAC,GAAG,EAAE;QACX,IAAI,CAAC,GAAG,EAAE,CAAC;YACP,sCAAsC;YACtC,OAAO,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;YAE5E,OAAO;QACX,CAAC;QAED,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAEzC,6CAA6C;QAC7C,OAAO,GAAG,EAAE;YACR,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACvB,CAAC,CAAC;IACN,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,SAAgB,MAAM,CAAI,KAAqB;IAC3C,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,OAAO,IAAI,CAAC;AAChB,CAAC","sourcesContent":["import {useContext, useEffect, useId, useRef} from 'react';\n\nimport {_AIAgentContext} from './AIAgentContext';\nimport type {AIDataProps} from './types';\n\n/**\n * Hook to register data in the AI agent context.\n *\n * Registration happens in `useEffect`, so `getData()` is only meaningful\n * **after mount** of components that register data. Do not call `getData()`\n * synchronously during render or in `useLayoutEffect` in the same commit.\n *\n * Uses a ref + getter pattern: the registry stores `() => propsRef.current`\n * so `getData()` always reads the latest props without re-registering on every render.\n */\nexport function useProvideAIData<T>(props: AIDataProps<T>): void {\n    const ctx = useContext(_AIAgentContext);\n    const id = useId();\n    const propsRef = useRef(props);\n    propsRef.current = props;\n\n    useEffect(() => {\n        if (!ctx) {\n            // eslint-disable-next-line no-console\n            console.warn('useProvideAIData must be used inside AIAgentContextProvider');\n\n            return;\n        }\n\n        ctx.register(id, () => propsRef.current);\n\n        // eslint-disable-next-line consistent-return\n        return () => {\n            ctx.unregister(id);\n        };\n    }, [ctx, id]);\n}\n\n/**\n * Component that registers data in the AI agent context.\n * Pure side-effect — renders nothing.\n */\nexport function AIData<T>(props: AIDataProps<T>): null {\n    useProvideAIData(props);\n    return null;\n}\n"]}

package/build/cjs/utils/aiAgentContext/buildAIContextSystemPrompt.d.ts

@@ -0,0 +1,7 @@
+import type { AIDataEntry, BuildAIContextOptions } from "./types.js";
+/**
+ * Formats AI data entries into a system prompt string.
+ * Uses YAML-like format by default, can be overridden via options.formatData.
+ * Uses prompt builder to build the system prompt from **Template Literal**. See `createDefaultSystemPromptBuilder` for more details.
+ */
+export declare function buildAIContextSystemPrompt<T = unknown>(entries: AIDataEntry<T>[], options?: BuildAIContextOptions<T>): string;

package/build/cjs/utils/aiAgentContext/buildAIContextSystemPrompt.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAIContextSystemPrompt = buildAIContextSystemPrompt;
+const templateStrings_1 = require("./templateStrings.js");
+const toYamlLike_1 = require("./toYamlLike.js");
+/**
+ * Formats AI data entries into a system prompt string.
+ * Uses YAML-like format by default, can be overridden via options.formatData.
+ * Uses prompt builder to build the system prompt from **Template Literal**. See `createDefaultSystemPromptBuilder` for more details.
+ */
+function buildAIContextSystemPrompt(entries, options = {}) {
+    var _a, _b;
+    if (entries.length === 0)
+        return '';
+    const builder = (0, templateStrings_1.createDefaultSystemPromptBuilder)(entries, {
+        formatData: (_a = options.formatData) !== null && _a !== void 0 ? _a : toYamlLike_1.toYamlLike,
+    });
+    const template = (_b = options.template) !== null && _b !== void 0 ? _b : templateStrings_1.DEFAULT_SYSTEM_PROMPT_TEMPLATE;
+    return builder(...template);
+}
+//# sourceMappingURL=buildAIContextSystemPrompt.js.map

package/build/cjs/utils/aiAgentContext/buildAIContextSystemPrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildAIContextSystemPrompt.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/buildAIContextSystemPrompt.ts"],"names":[],"mappings":";;AASA,gEAaC;AAtBD,0DAAmG;AACnG,gDAAwC;AAGxC;;;;GAIG;AACH,SAAgB,0BAA0B,CACtC,OAAyB,EACzB,UAAoC,EAAE;;IAEtC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,OAAO,GAAG,IAAA,kDAAgC,EAAI,OAAO,EAAE;QACzD,UAAU,EAAE,MAAA,OAAO,CAAC,UAAU,mCAAI,uBAAU;KAC/C,CAAC,CAAC;IAEH,MAAM,QAAQ,GAA2B,MAAA,OAAO,CAAC,QAAQ,mCAAI,gDAA8B,CAAC;IAE5F,OAAO,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;AAChC,CAAC","sourcesContent":["import {DEFAULT_SYSTEM_PROMPT_TEMPLATE, createDefaultSystemPromptBuilder} from './templateStrings';\nimport {toYamlLike} from './toYamlLike';\nimport type {AIDataEntry, BuildAIContextOptions, PromptBuilderParams} from './types';\n\n/**\n * Formats AI data entries into a system prompt string.\n * Uses YAML-like format by default, can be overridden via options.formatData.\n * Uses prompt builder to build the system prompt from **Template Literal**. See `createDefaultSystemPromptBuilder` for more details.\n */\nexport function buildAIContextSystemPrompt<T = unknown>(\n    entries: AIDataEntry<T>[],\n    options: BuildAIContextOptions<T> = {},\n): string {\n    if (entries.length === 0) return '';\n\n    const builder = createDefaultSystemPromptBuilder<T>(entries, {\n        formatData: options.formatData ?? toYamlLike,\n    });\n\n    const template: PromptBuilderParams<T> = options.template ?? DEFAULT_SYSTEM_PROMPT_TEMPLATE;\n\n    return builder(...template);\n}\n"]}

package/build/cjs/utils/aiAgentContext/index.d.ts

@@ -0,0 +1,5 @@
+export { AIAgentContextProvider, useAIAgentContext } from "./AIAgentContext.js";
+export { AIData, useProvideAIData } from "./AIData.js";
+export { buildAIContextSystemPrompt } from "./buildAIContextSystemPrompt.js";
+export { AIPrompt, DEFAULT_SYSTEM_PROMPT_TEMPLATE } from "./templateStrings.js";
+export type { AIDataProps, AIDataEntry, AIAgentContextAPI, BuildAIContextOptions, PromptBuilder, PromptBuilderParams, PromptBuilderExpression, PromptBuilderExpressionOptions, } from "./types.js";

package/build/cjs/utils/aiAgentContext/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SYSTEM_PROMPT_TEMPLATE = exports.AIPrompt = exports.buildAIContextSystemPrompt = exports.useProvideAIData = exports.AIData = exports.useAIAgentContext = exports.AIAgentContextProvider = void 0;
+// Components
+var AIAgentContext_1 = require("./AIAgentContext.js");
+Object.defineProperty(exports, "AIAgentContextProvider", { enumerable: true, get: function () { return AIAgentContext_1.AIAgentContextProvider; } });
+Object.defineProperty(exports, "useAIAgentContext", { enumerable: true, get: function () { return AIAgentContext_1.useAIAgentContext; } });
+var AIData_1 = require("./AIData.js");
+Object.defineProperty(exports, "AIData", { enumerable: true, get: function () { return AIData_1.AIData; } });
+Object.defineProperty(exports, "useProvideAIData", { enumerable: true, get: function () { return AIData_1.useProvideAIData; } });
+// Utilities
+var buildAIContextSystemPrompt_1 = require("./buildAIContextSystemPrompt.js");
+Object.defineProperty(exports, "buildAIContextSystemPrompt", { enumerable: true, get: function () { return buildAIContextSystemPrompt_1.buildAIContextSystemPrompt; } });
+var templateStrings_1 = require("./templateStrings.js");
+Object.defineProperty(exports, "AIPrompt", { enumerable: true, get: function () { return templateStrings_1.AIPrompt; } });
+Object.defineProperty(exports, "DEFAULT_SYSTEM_PROMPT_TEMPLATE", { enumerable: true, get: function () { return templateStrings_1.DEFAULT_SYSTEM_PROMPT_TEMPLATE; } });
+//# sourceMappingURL=index.js.map

package/build/cjs/utils/aiAgentContext/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/index.ts"],"names":[],"mappings":";;;AAAA,aAAa;AACb,sDAA2E;AAAnE,wHAAA,sBAAsB,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AACjD,sCAAkD;AAA1C,gGAAA,MAAM,OAAA;AAAE,0GAAA,gBAAgB,OAAA;AAEhC,YAAY;AACZ,8EAAwE;AAAhE,wIAAA,0BAA0B,OAAA;AAClC,wDAA2E;AAAnE,2GAAA,QAAQ,OAAA;AAAE,iIAAA,8BAA8B,OAAA","sourcesContent":["// Components\nexport {AIAgentContextProvider, useAIAgentContext} from './AIAgentContext';\nexport {AIData, useProvideAIData} from './AIData';\n\n// Utilities\nexport {buildAIContextSystemPrompt} from './buildAIContextSystemPrompt';\nexport {AIPrompt, DEFAULT_SYSTEM_PROMPT_TEMPLATE} from './templateStrings';\n\n// Types\nexport type {\n    AIDataProps,\n    AIDataEntry,\n    AIAgentContextAPI,\n    BuildAIContextOptions,\n    PromptBuilder,\n    PromptBuilderParams,\n    PromptBuilderExpression,\n    PromptBuilderExpressionOptions,\n} from './types';\n"]}

package/build/cjs/utils/aiAgentContext/templateStrings.d.ts

@@ -0,0 +1,4 @@
+import { AIDataEntry, AnyDepthArray, PromptBuilder, PromptBuilderExpression, PromptBuilderExpressionOptions, PromptBuilderParams } from "./types.js";
+export declare function AIPrompt<T = unknown>(templateParts: TemplateStringsArray, ...functions: (string | AnyDepthArray<string> | PromptBuilderExpression<T>)[]): PromptBuilderParams<T>;
+export declare function createDefaultSystemPromptBuilder<T = unknown>(entries: AIDataEntry<T>[], options: PromptBuilderExpressionOptions<T>): PromptBuilder<T>;
+export declare const DEFAULT_SYSTEM_PROMPT_TEMPLATE: [templateParts: string[], ...functions: (string | AnyDepthArray<string> | PromptBuilderExpression<any>)[]];

package/build/cjs/utils/aiAgentContext/templateStrings.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SYSTEM_PROMPT_TEMPLATE = void 0;
+exports.AIPrompt = AIPrompt;
+exports.createDefaultSystemPromptBuilder = createDefaultSystemPromptBuilder;
+function AIPrompt(templateParts, ...functions) {
+    return [[...templateParts.raw], ...functions];
+}
+function createDefaultSystemPromptBuilder(entries, options) {
+    return (templateParts, ...functions) => {
+        const out = [];
+        for (let i = 0; i < templateParts.length; i++) {
+            const part = templateParts[i];
+            out.push(part);
+            const fn = functions[i];
+            if (fn) {
+                const result = typeof fn === 'function' ? fn(entries, options) : fn;
+                if (typeof result === 'string') {
+                    out.push(result);
+                }
+                if (Array.isArray(result)) {
+                    // @ts-expect-error - we know that the result is an array of strings, but TS can't handle it (Type instantiation is excessively deep and possibly infinite.)
+                    out.push(result.flat(Infinity).join('\n\n'));
+                }
+            }
+        }
+        return out.join('');
+    };
+}
+exports.DEFAULT_SYSTEM_PROMPT_TEMPLATE = AIPrompt `Meta information provided by the user about the current page they are on:
+
+${(entries, options) => entries.map((entry) => {
+    const formatted = options.formatData(entry.data);
+    return [`### ${entry.label}`, formatted];
+})}
+`;
+//# sourceMappingURL=templateStrings.js.map

package/build/cjs/utils/aiAgentContext/templateStrings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templateStrings.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/templateStrings.ts"],"names":[],"mappings":";;;AASA,4BAKC;AAED,4EAgCC;AAvCD,SAAgB,QAAQ,CACpB,aAAmC,EACnC,GAAG,SAA0E;IAE7E,OAAO,CAAC,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC;AAClD,CAAC;AAED,SAAgB,gCAAgC,CAC5C,OAAyB,EACzB,OAA0C;IAE1C,OAAO,CACH,aAAuB,EACvB,GAAG,SAA0E,EACvE,EAAE;QACR,MAAM,GAAG,GAAG,EAAE,CAAC;QAEf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5C,MAAM,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;YAC9B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAEf,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;YAExB,IAAI,EAAE,EAAE,CAAC;gBACL,MAAM,MAAM,GAAG,OAAO,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAEpE,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;oBAC7B,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACrB,CAAC;gBAED,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;oBACxB,4JAA4J;oBAC5J,GAAG,CAAC,IAAI,CAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC/D,CAAC;YACL,CAAC;QACL,CAAC;QAED,OAAO,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC;AACN,CAAC;AAEY,QAAA,8BAA8B,GAAG,QAAQ,CAAK;;EAEzD,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CACnB,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;IAClB,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEjD,OAAO,CAAC,OAAO,KAAK,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;AAC7C,CAAC,CAAC;CACL,CAAC","sourcesContent":["import {\n    AIDataEntry,\n    AnyDepthArray,\n    PromptBuilder,\n    PromptBuilderExpression,\n    PromptBuilderExpressionOptions,\n    PromptBuilderParams,\n} from './types';\n\nexport function AIPrompt<T = unknown>(\n    templateParts: TemplateStringsArray,\n    ...functions: (string | AnyDepthArray<string> | PromptBuilderExpression<T>)[]\n): PromptBuilderParams<T> {\n    return [[...templateParts.raw], ...functions];\n}\n\nexport function createDefaultSystemPromptBuilder<T = unknown>(\n    entries: AIDataEntry<T>[],\n    options: PromptBuilderExpressionOptions<T>,\n): PromptBuilder<T> {\n    return (\n        templateParts: string[],\n        ...functions: (string | AnyDepthArray<string> | PromptBuilderExpression<T>)[]\n    ): string => {\n        const out = [];\n\n        for (let i = 0; i < templateParts.length; i++) {\n            const part = templateParts[i];\n            out.push(part);\n\n            const fn = functions[i];\n\n            if (fn) {\n                const result = typeof fn === 'function' ? fn(entries, options) : fn;\n\n                if (typeof result === 'string') {\n                    out.push(result);\n                }\n\n                if (Array.isArray(result)) {\n                    // @ts-expect-error - we know that the result is an array of strings, but TS can't handle it (Type instantiation is excessively deep and possibly infinite.)\n                    out.push((result.flat(Infinity) as string[]).join('\\n\\n'));\n                }\n            }\n        }\n\n        return out.join('');\n    };\n}\n\nexport const DEFAULT_SYSTEM_PROMPT_TEMPLATE = AIPrompt<any>`Meta information provided by the user about the current page they are on:\n\n${(entries, options) =>\n    entries.map((entry) => {\n        const formatted = options.formatData(entry.data);\n\n        return [`### ${entry.label}`, formatted];\n    })}\n`;\n"]}

package/build/cjs/utils/aiAgentContext/toYamlLike.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Simple YAML-like serializer for plain JS values.
+ * Handles: string, number, boolean, null/undefined, arrays, plain objects.
+ * Falls back to String() for unsupported types.
+ * Internal helper — not exported from the package.
+ */
+export declare function toYamlLike(data: unknown, indent?: number): string;

package/build/cjs/utils/aiAgentContext/toYamlLike.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toYamlLike = toYamlLike;
+const CIRCULAR_REF = '[Circular]';
+function indentLines(text, spaces) {
+    const prefix = ' '.repeat(spaces);
+    return text
+        .split('\n')
+        .map((line) => `${prefix}${line}`)
+        .join('\n');
+}
+function isComplexValue(val) {
+    if (val === null || val === undefined) {
+        return false;
+    }
+    if (Array.isArray(val)) {
+        return val.length > 0;
+    }
+    if (typeof val === 'object') {
+        return Object.keys(val).length > 0;
+    }
+    if (typeof val === 'string') {
+        return val.includes('\n');
+    }
+    return false;
+}
+function withVisitedObject(value, visited, serialize) {
+    if (visited.has(value)) {
+        return CIRCULAR_REF;
+    }
+    visited.add(value);
+    try {
+        return serialize();
+    }
+    finally {
+        visited.delete(value);
+    }
+}
+function isVisitedReference(val, visited) {
+    return typeof val === 'object' && val !== null && visited.has(val);
+}
+function formatKeyValue(key, val, keyPrefix, indent, visited) {
+    if (isVisitedReference(val, visited)) {
+        return `${keyPrefix}${key}: ${CIRCULAR_REF}`;
+    }
+    if (isComplexValue(val)) {
+        return `${keyPrefix}${key}:\n${toYamlLikeInternal(val, indent + 2, visited)}`;
+    }
+    return `${keyPrefix}${key}: ${toYamlLikeInternal(val, indent + 2, visited)}`;
+}
+/**
+ * Simple YAML-like serializer for plain JS values.
+ * Handles: string, number, boolean, null/undefined, arrays, plain objects.
+ * Falls back to String() for unsupported types.
+ * Internal helper — not exported from the package.
+ */
+function toYamlLike(data, indent = 0) {
+    return toYamlLikeInternal(data, indent, new Set());
+}
+function toYamlLikeInternal(data, indent, visited) {
+    if (data === null || data === undefined)
+        return 'null';
+    if (typeof data === 'string') {
+        if (data.includes('\n')) {
+            return `|\n${indentLines(data, indent + 2)}`;
+        }
+        return data;
+    }
+    if (typeof data === 'number' || typeof data === 'boolean') {
+        return String(data);
+    }
+    if (Array.isArray(data)) {
+        if (data.length === 0)
+            return '[]';
+        return withVisitedObject(data, visited, () => data
+            .map((item) => {
+            const prefix = `${' '.repeat(indent)}- `;
+            if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+                return withVisitedObject(item, visited, () => {
+                    const entries = Object.entries(item);
+                    if (entries.length === 0)
+                        return `${prefix}{}`;
+                    const [firstKey, firstVal] = entries[0];
+                    const firstLine = formatKeyValue(firstKey, firstVal, `${' '.repeat(indent)}- `, indent, visited);
+                    const rest = entries
+                        .slice(1)
+                        .map(([key, val]) => formatKeyValue(key, val, ' '.repeat(indent + 2), indent + 2, visited))
+                        .join('\n');
+                    return rest ? `${firstLine}\n${rest}` : firstLine;
+                });
+            }
+            return `${prefix}${toYamlLikeInternal(item, indent + 2, visited)}`;
+        })
+            .join('\n'));
+    }
+    if (typeof data === 'object') {
+        return withVisitedObject(data, visited, () => {
+            const entries = Object.entries(data);
+            if (entries.length === 0)
+                return '{}';
+            return entries
+                .map(([key, val]) => formatKeyValue(key, val, ' '.repeat(indent), indent, visited))
+                .join('\n');
+        });
+    }
+    return String(data);
+}
+//# sourceMappingURL=toYamlLike.js.map

package/build/cjs/utils/aiAgentContext/toYamlLike.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toYamlLike.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/toYamlLike.ts"],"names":[],"mappings":"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","sourcesContent":["const CIRCULAR_REF = '[Circular]';\n\nfunction indentLines(text: string, spaces: number): string {\n    const prefix = ' '.repeat(spaces);\n    return text\n        .split('\\n')\n        .map((line) => `${prefix}${line}`)\n        .join('\\n');\n}\n\nfunction isComplexValue(val: unknown): boolean {\n    if (val === null || val === undefined) {\n        return false;\n    }\n    if (Array.isArray(val)) {\n        return val.length > 0;\n    }\n    if (typeof val === 'object') {\n        return Object.keys(val).length > 0;\n    }\n    if (typeof val === 'string') {\n        return val.includes('\\n');\n    }\n    return false;\n}\n\nfunction withVisitedObject<T extends object>(\n    value: T,\n    visited: Set<object>,\n    serialize: () => string,\n): string {\n    if (visited.has(value)) {\n        return CIRCULAR_REF;\n    }\n    visited.add(value);\n    try {\n        return serialize();\n    } finally {\n        visited.delete(value);\n    }\n}\n\nfunction isVisitedReference(val: unknown, visited: Set<object>): val is object {\n    return typeof val === 'object' && val !== null && visited.has(val);\n}\n\nfunction formatKeyValue(\n    key: string,\n    val: unknown,\n    keyPrefix: string,\n    indent: number,\n    visited: Set<object>,\n): string {\n    if (isVisitedReference(val, visited)) {\n        return `${keyPrefix}${key}: ${CIRCULAR_REF}`;\n    }\n    if (isComplexValue(val)) {\n        return `${keyPrefix}${key}:\\n${toYamlLikeInternal(val, indent + 2, visited)}`;\n    }\n    return `${keyPrefix}${key}: ${toYamlLikeInternal(val, indent + 2, visited)}`;\n}\n\n/**\n * Simple YAML-like serializer for plain JS values.\n * Handles: string, number, boolean, null/undefined, arrays, plain objects.\n * Falls back to String() for unsupported types.\n * Internal helper — not exported from the package.\n */\nexport function toYamlLike(data: unknown, indent = 0): string {\n    return toYamlLikeInternal(data, indent, new Set());\n}\n\nfunction toYamlLikeInternal(data: unknown, indent: number, visited: Set<object>): string {\n    if (data === null || data === undefined) return 'null';\n\n    if (typeof data === 'string') {\n        if (data.includes('\\n')) {\n            return `|\\n${indentLines(data, indent + 2)}`;\n        }\n        return data;\n    }\n\n    if (typeof data === 'number' || typeof data === 'boolean') {\n        return String(data);\n    }\n\n    if (Array.isArray(data)) {\n        if (data.length === 0) return '[]';\n\n        return withVisitedObject(data, visited, () =>\n            data\n                .map((item) => {\n                    const prefix = `${' '.repeat(indent)}- `;\n                    if (typeof item === 'object' && item !== null && !Array.isArray(item)) {\n                        return withVisitedObject(item, visited, () => {\n                            const entries = Object.entries(item);\n                            if (entries.length === 0) return `${prefix}{}`;\n                            const [firstKey, firstVal] = entries[0];\n                            const firstLine = formatKeyValue(\n                                firstKey,\n                                firstVal,\n                                `${' '.repeat(indent)}- `,\n                                indent,\n                                visited,\n                            );\n                            const rest = entries\n                                .slice(1)\n                                .map(([key, val]) =>\n                                    formatKeyValue(\n                                        key,\n                                        val,\n                                        ' '.repeat(indent + 2),\n                                        indent + 2,\n                                        visited,\n                                    ),\n                                )\n                                .join('\\n');\n                            return rest ? `${firstLine}\\n${rest}` : firstLine;\n                        });\n                    }\n                    return `${prefix}${toYamlLikeInternal(item, indent + 2, visited)}`;\n                })\n                .join('\\n'),\n        );\n    }\n\n    if (typeof data === 'object') {\n        return withVisitedObject(data, visited, () => {\n            const entries = Object.entries(data as Record<string, unknown>);\n            if (entries.length === 0) return '{}';\n\n            return entries\n                .map(([key, val]) => formatKeyValue(key, val, ' '.repeat(indent), indent, visited))\n                .join('\\n');\n        });\n    }\n\n    return String(data);\n}\n"]}

package/build/cjs/utils/aiAgentContext/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Props for AIData component and useProvideAIData hook
+ */
+export interface AIDataProps<T = unknown> {
+    /** Human-readable description of what this data represents */
+    label: string;
+    /** The actual data to expose to the AI agent */
+    data: T;
+}
+/**
+ * Entry returned by getData()
+ */
+export interface AIDataEntry<T = unknown> {
+    /** Human-readable description of what this data represents */
+    label: string;
+    /** The actual data */
+    data: T;
+}
+/**
+ * Public API returned by useAIAgentContext()
+ */
+export interface AIAgentContextAPI<T = unknown> {
+    /** Returns the current list of all registered data entries */
+    getData: () => AIDataEntry<T>[];
+}
+export type AnyDepthArray<T> = Array<T | AnyDepthArray<T>>;
+/**
+ * Expression for a prompt builder, used to build the part of system prompt.
+ * Returns the string part of the system prompt.
+ */
+export type PromptBuilderExpression<T = unknown> = (entries: AIDataEntry<T>[], options: PromptBuilderExpressionOptions<T>) => string | AnyDepthArray<string>;
+export interface PromptBuilderExpressionOptions<T = unknown> {
+    formatData: (data: T) => string;
+}
+/**
+ * Prompt builder **Tagged Template Literal** function.
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates
+ */
+export type PromptBuilder<T = unknown> = (templateParts: string[], ...functions: (string | AnyDepthArray<string> | PromptBuilderExpression<T>)[]) => string;
+export type PromptBuilderParams<T = unknown> = Parameters<PromptBuilder<T>>;
+/**
+ * Options for buildAIContextSystemPrompt
+ */
+export interface BuildAIContextOptions<T = unknown> {
+    /**
+     * System prompt **template literal**. Use this, if you want to customize the system prompt or create on the fly.
+     * If not provided, a default system prompt template literal will be used (see example below).
+     *
+     * Use `AIPrompt` helper function to create a valid template.
+     *
+     * If you ever worked with styled-components, this is similar to the `styled` function.
+     *
+     * @example
+     * ```ts
+     * // Like in styled-components, use backticks to create a template literal.
+     * AIPrompt`Meta information provided by the user about the current page they are on:
+     *
+     * ${(entries, options) => entries.map((entry) =>
+     *     // Each function inside the template literal has access to the entries and options from context:
+     *     `### ${entry.label}\n${options.formatData(entry.data)}`
+     * )}
+     * `
+     *
+     * ```
+     */
+    template?: PromptBuilderParams<T>;
+    /**
+     * Custom data formatter.
+     * This function is used to convert JS objects to a LLM-readable string.
+     *
+     * Defaults to YAML-like serializer.
+     *
+     * @example
+     * ```ts
+     * formatData: (data) => JSON.stringify(data, null, 2)
+     * ```
+     */
+    formatData?: (data: unknown) => string;
+}
+/**
+ * Internal context value. Not exported to consumers.
+ */
+export interface AIAgentContextValue<T = unknown> {
+    register: (id: string, getter: () => AIDataProps<T>) => void;
+    unregister: (id: string) => void;
+    getData: () => AIDataEntry<T>[];
+}

package/build/cjs/utils/aiAgentContext/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/build/cjs/utils/aiAgentContext/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Props for AIData component and useProvideAIData hook\n */\nexport interface AIDataProps<T = unknown> {\n    /** Human-readable description of what this data represents */\n    label: string;\n    /** The actual data to expose to the AI agent */\n    data: T;\n}\n\n/**\n * Entry returned by getData()\n */\nexport interface AIDataEntry<T = unknown> {\n    /** Human-readable description of what this data represents */\n    label: string;\n    /** The actual data */\n    data: T;\n}\n\n/**\n * Public API returned by useAIAgentContext()\n */\nexport interface AIAgentContextAPI<T = unknown> {\n    /** Returns the current list of all registered data entries */\n    getData: () => AIDataEntry<T>[];\n}\n\nexport type AnyDepthArray<T> = Array<T | AnyDepthArray<T>>;\n\n/**\n * Expression for a prompt builder, used to build the part of system prompt.\n * Returns the string part of the system prompt.\n */\nexport type PromptBuilderExpression<T = unknown> = (\n    entries: AIDataEntry<T>[],\n    options: PromptBuilderExpressionOptions<T>,\n) => string | AnyDepthArray<string>;\n\nexport interface PromptBuilderExpressionOptions<T = unknown> {\n    formatData: (data: T) => string;\n}\n\n/**\n * Prompt builder **Tagged Template Literal** function.\n * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates\n */\nexport type PromptBuilder<T = unknown> = (\n    templateParts: string[],\n    ...functions: (string | AnyDepthArray<string> | PromptBuilderExpression<T>)[]\n) => string;\n\nexport type PromptBuilderParams<T = unknown> = Parameters<PromptBuilder<T>>;\n\n/**\n * Options for buildAIContextSystemPrompt\n */\nexport interface BuildAIContextOptions<T = unknown> {\n    /**\n     * System prompt **template literal**. Use this, if you want to customize the system prompt or create on the fly.\n     * If not provided, a default system prompt template literal will be used (see example below).\n     *\n     * Use `AIPrompt` helper function to create a valid template.\n     *\n     * If you ever worked with styled-components, this is similar to the `styled` function.\n     *\n     * @example\n     * ```ts\n     * // Like in styled-components, use backticks to create a template literal.\n     * AIPrompt`Meta information provided by the user about the current page they are on:\n     *\n     * ${(entries, options) => entries.map((entry) =>\n     *     // Each function inside the template literal has access to the entries and options from context:\n     *     `### ${entry.label}\\n${options.formatData(entry.data)}`\n     * )}\n     * `\n     *\n     * ```\n     */\n    template?: PromptBuilderParams<T>;\n    /**\n     * Custom data formatter.\n     * This function is used to convert JS objects to a LLM-readable string.\n     *\n     * Defaults to YAML-like serializer.\n     *\n     * @example\n     * ```ts\n     * formatData: (data) => JSON.stringify(data, null, 2)\n     * ```\n     */\n    formatData?: (data: unknown) => string;\n}\n\n/**\n * Internal context value. Not exported to consumers.\n */\nexport interface AIAgentContextValue<T = unknown> {\n    register: (id: string, getter: () => AIDataProps<T>) => void;\n    unregister: (id: string) => void;\n    getData: () => AIDataEntry<T>[];\n}\n"]}

package/build/cjs/utils/index.d.ts

@@ -3,4 +3,5 @@ export * from "./messageUtils.js";
 export * from "./validation.js";
 export * from "./messageTypeRegistry.js";
 export * from "./clipboardUtils.js";
+export * from "./aiAgentContext/index.js";
 export * from "./toolset/index.js";

package/build/cjs/utils/index.js

@@ -7,5 +7,6 @@ tslib_1.__exportStar(require("./messageUtils.js"), exports);
 tslib_1.__exportStar(require("./validation.js"), exports);
 tslib_1.__exportStar(require("./messageTypeRegistry.js"), exports);
 tslib_1.__exportStar(require("./clipboardUtils.js"), exports);
+tslib_1.__exportStar(require("./aiAgentContext/index.js"), exports);
 tslib_1.__exportStar(require("./toolset/index.js"), exports);
 //# sourceMappingURL=index.js.map

package/build/cjs/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"../../../src","sources":["utils/index.ts"],"names":[],"mappings":";;;AAAA,mBAAmB;AACnB,yDAA4B;AAC5B,4DAA+B;AAC/B,0DAA6B;AAC7B,mEAAsC;AACtC,8DAAiC;AACjC,6DAA0B","sourcesContent":["// Export utilities\nexport * from './chatUtils';\nexport * from './messageUtils';\nexport * from './validation';\nexport * from './messageTypeRegistry';\nexport * from './clipboardUtils';\nexport * from './toolset';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"../../../src","sources":["utils/index.ts"],"names":[],"mappings":";;;AAAA,mBAAmB;AACnB,yDAA4B;AAC5B,4DAA+B;AAC/B,0DAA6B;AAC7B,mEAAsC;AACtC,8DAAiC;AACjC,oEAAiC;AACjC,6DAA0B","sourcesContent":["// Export utilities\nexport * from './chatUtils';\nexport * from './messageUtils';\nexport * from './validation';\nexport * from './messageTypeRegistry';\nexport * from './clipboardUtils';\nexport * from './aiAgentContext';\nexport * from './toolset';\n"]}

package/build/esm/package.json

@@ -1 +1 @@
-{"version":"2.4.0","type":"module","sideEffects":["*.css","*.scss"]}
+{"version":"2.5.0","type":"module","sideEffects":["*.css","*.scss"]}

package/build/esm/utils/aiAgentContext/AIAgentContext.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { AIAgentContextAPI, AIAgentContextValue } from "./types.js";
+declare const AIAgentContext: React.Context<AIAgentContextValue<unknown> | null>;
+/** Raw context — internal use only, not exported from the package. */
+export { AIAgentContext as _AIAgentContext };
+/**
+ * Provider that manages the AI data registry.
+ * Wrap your app or chat area with this to enable AIData collection.
+ */
+export declare function AIAgentContextProvider({ children }: {
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook for consumers to access registered AI data.
+ * Returns { getData } where getData() returns the current list of all entries.
+ * If no AIAgentContextProvider exists above, getData() returns [].
+ *
+ * Generic `T` is the **expected** shape of `data` for this consumer — not validated
+ * or guaranteed at runtime. The registry is populated by arbitrary `AIData`
+ * registrations; entries may not match `T`.
+ */
+export declare function useAIAgentContext<T = unknown>(): AIAgentContextAPI<T>;

package/build/esm/utils/aiAgentContext/AIAgentContext.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useMemo, useRef } from 'react';
+const AIAgentContext = createContext(null);
+/** Raw context — internal use only, not exported from the package. */
+export { AIAgentContext as _AIAgentContext };
+/**
+ * Provider that manages the AI data registry.
+ * Wrap your app or chat area with this to enable AIData collection.
+ */
+export function AIAgentContextProvider({ children }) {
+    const registryRef = useRef(new Map());
+    const contextValue = useMemo(() => ({
+        register: (id, getter) => {
+            registryRef.current.set(id, getter);
+        },
+        unregister: (id) => {
+            registryRef.current.delete(id);
+        },
+        getData: () => Array.from(registryRef.current.values()).map((getter) => {
+            const { label, data } = getter();
+            return { label, data };
+        }),
+    }), []);
+    return _jsx(AIAgentContext.Provider, { value: contextValue, children: children });
+}
+/**
+ * Hook for consumers to access registered AI data.
+ * Returns { getData } where getData() returns the current list of all entries.
+ * If no AIAgentContextProvider exists above, getData() returns [].
+ *
+ * Generic `T` is the **expected** shape of `data` for this consumer — not validated
+ * or guaranteed at runtime. The registry is populated by arbitrary `AIData`
+ * registrations; entries may not match `T`.
+ */
+export function useAIAgentContext() {
+    const ctx = useContext(AIAgentContext);
+    const getData = useCallback(() => {
+        if (!ctx)
+            return [];
+        return ctx.getData();
+    }, [ctx]);
+    return useMemo(() => ({ getData }), [getData]);
+}
+//# sourceMappingURL=AIAgentContext.js.map

package/build/esm/utils/aiAgentContext/AIAgentContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AIAgentContext.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/AIAgentContext.tsx"],"names":[],"mappings":";AAAA,OAAc,EAAC,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAC,MAAM,OAAO,CAAC;AAIrF,MAAM,cAAc,GAAG,aAAa,CAA6B,IAAI,CAAC,CAAC;AAEvE,sEAAsE;AACtE,OAAO,EAAC,cAAc,IAAI,eAAe,EAAC,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,EAAC,QAAQ,EAA8B;IAC1E,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,GAAG,EAA6B,CAAC,CAAC;IAEjE,MAAM,YAAY,GAAG,OAAO,CACxB,GAAG,EAAE,CAAC,CAAC;QACH,QAAQ,EAAE,CAAC,EAAU,EAAE,MAAyB,EAAE,EAAE;YAChD,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACxC,CAAC;QACD,UAAU,EAAE,CAAC,EAAU,EAAE,EAAE;YACvB,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,EAAE,GAAkB,EAAE,CACzB,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;YACpD,MAAM,EAAC,KAAK,EAAE,IAAI,EAAC,GAAG,MAAM,EAAE,CAAC;YAC/B,OAAO,EAAC,KAAK,EAAE,IAAI,EAAC,CAAC;QACzB,CAAC,CAAC;KACT,CAAC,EACF,EAAE,CACL,CAAC;IAEF,OAAO,KAAC,cAAc,CAAC,QAAQ,IAAC,KAAK,EAAE,YAAY,YAAG,QAAQ,GAA2B,CAAC;AAC9F,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB;IAC7B,MAAM,GAAG,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAEvC,MAAM,OAAO,GAAG,WAAW,CAAC,GAAqB,EAAE;QAC/C,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,CAAC;QACpB,OAAO,GAAG,CAAC,OAAO,EAAsB,CAAC;IAC7C,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEV,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,EAAC,OAAO,EAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;AACjD,CAAC","sourcesContent":["import React, {createContext, useCallback, useContext, useMemo, useRef} from 'react';\n\nimport type {AIAgentContextAPI, AIAgentContextValue, AIDataEntry, AIDataProps} from './types';\n\nconst AIAgentContext = createContext<AIAgentContextValue | null>(null);\n\n/** Raw context — internal use only, not exported from the package. */\nexport {AIAgentContext as _AIAgentContext};\n\n/**\n * Provider that manages the AI data registry.\n * Wrap your app or chat area with this to enable AIData collection.\n */\nexport function AIAgentContextProvider({children}: {children: React.ReactNode}) {\n    const registryRef = useRef(new Map<string, () => AIDataProps>());\n\n    const contextValue = useMemo<AIAgentContextValue>(\n        () => ({\n            register: (id: string, getter: () => AIDataProps) => {\n                registryRef.current.set(id, getter);\n            },\n            unregister: (id: string) => {\n                registryRef.current.delete(id);\n            },\n            getData: (): AIDataEntry[] =>\n                Array.from(registryRef.current.values()).map((getter) => {\n                    const {label, data} = getter();\n                    return {label, data};\n                }),\n        }),\n        [],\n    );\n\n    return <AIAgentContext.Provider value={contextValue}>{children}</AIAgentContext.Provider>;\n}\n\n/**\n * Hook for consumers to access registered AI data.\n * Returns { getData } where getData() returns the current list of all entries.\n * If no AIAgentContextProvider exists above, getData() returns [].\n *\n * Generic `T` is the **expected** shape of `data` for this consumer — not validated\n * or guaranteed at runtime. The registry is populated by arbitrary `AIData`\n * registrations; entries may not match `T`.\n */\nexport function useAIAgentContext<T = unknown>(): AIAgentContextAPI<T> {\n    const ctx = useContext(AIAgentContext);\n\n    const getData = useCallback((): AIDataEntry<T>[] => {\n        if (!ctx) return [];\n        return ctx.getData() as AIDataEntry<T>[];\n    }, [ctx]);\n\n    return useMemo(() => ({getData}), [getData]);\n}\n"]}

package/build/esm/utils/aiAgentContext/AIData.d.ts

@@ -0,0 +1,17 @@
+import type { AIDataProps } from "./types.js";
+/**
+ * Hook to register data in the AI agent context.
+ *
+ * Registration happens in `useEffect`, so `getData()` is only meaningful
+ * **after mount** of components that register data. Do not call `getData()`
+ * synchronously during render or in `useLayoutEffect` in the same commit.
+ *
+ * Uses a ref + getter pattern: the registry stores `() => propsRef.current`
+ * so `getData()` always reads the latest props without re-registering on every render.
+ */
+export declare function useProvideAIData<T>(props: AIDataProps<T>): void;
+/**
+ * Component that registers data in the AI agent context.
+ * Pure side-effect — renders nothing.
+ */
+export declare function AIData<T>(props: AIDataProps<T>): null;

package/build/esm/utils/aiAgentContext/AIData.js

@@ -0,0 +1,39 @@
+import { useContext, useEffect, useId, useRef } from 'react';
+import { _AIAgentContext } from "./AIAgentContext.js";
+/**
+ * Hook to register data in the AI agent context.
+ *
+ * Registration happens in `useEffect`, so `getData()` is only meaningful
+ * **after mount** of components that register data. Do not call `getData()`
+ * synchronously during render or in `useLayoutEffect` in the same commit.
+ *
+ * Uses a ref + getter pattern: the registry stores `() => propsRef.current`
+ * so `getData()` always reads the latest props without re-registering on every render.
+ */
+export function useProvideAIData(props) {
+    const ctx = useContext(_AIAgentContext);
+    const id = useId();
+    const propsRef = useRef(props);
+    propsRef.current = props;
+    useEffect(() => {
+        if (!ctx) {
+            // eslint-disable-next-line no-console
+            console.warn('useProvideAIData must be used inside AIAgentContextProvider');
+            return;
+        }
+        ctx.register(id, () => propsRef.current);
+        // eslint-disable-next-line consistent-return
+        return () => {
+            ctx.unregister(id);
+        };
+    }, [ctx, id]);
+}
+/**
+ * Component that registers data in the AI agent context.
+ * Pure side-effect — renders nothing.
+ */
+export function AIData(props) {
+    useProvideAIData(props);
+    return null;
+}
+//# sourceMappingURL=AIData.js.map

package/build/esm/utils/aiAgentContext/AIData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AIData.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/AIData.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAC,MAAM,OAAO,CAAC;AAE3D,OAAO,EAAC,eAAe,EAAC,4BAAyB;AAGjD;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAI,KAAqB;IACrD,MAAM,GAAG,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC;IACxC,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC;IACnB,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/B,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAC;IAEzB,SAAS,CAAC,GAAG,EAAE;QACX,IAAI,CAAC,GAAG,EAAE,CAAC;YACP,sCAAsC;YACtC,OAAO,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;YAE5E,OAAO;QACX,CAAC;QAED,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAEzC,6CAA6C;QAC7C,OAAO,GAAG,EAAE;YACR,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACvB,CAAC,CAAC;IACN,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAI,KAAqB;IAC3C,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,OAAO,IAAI,CAAC;AAChB,CAAC","sourcesContent":["import {useContext, useEffect, useId, useRef} from 'react';\n\nimport {_AIAgentContext} from './AIAgentContext';\nimport type {AIDataProps} from './types';\n\n/**\n * Hook to register data in the AI agent context.\n *\n * Registration happens in `useEffect`, so `getData()` is only meaningful\n * **after mount** of components that register data. Do not call `getData()`\n * synchronously during render or in `useLayoutEffect` in the same commit.\n *\n * Uses a ref + getter pattern: the registry stores `() => propsRef.current`\n * so `getData()` always reads the latest props without re-registering on every render.\n */\nexport function useProvideAIData<T>(props: AIDataProps<T>): void {\n    const ctx = useContext(_AIAgentContext);\n    const id = useId();\n    const propsRef = useRef(props);\n    propsRef.current = props;\n\n    useEffect(() => {\n        if (!ctx) {\n            // eslint-disable-next-line no-console\n            console.warn('useProvideAIData must be used inside AIAgentContextProvider');\n\n            return;\n        }\n\n        ctx.register(id, () => propsRef.current);\n\n        // eslint-disable-next-line consistent-return\n        return () => {\n            ctx.unregister(id);\n        };\n    }, [ctx, id]);\n}\n\n/**\n * Component that registers data in the AI agent context.\n * Pure side-effect — renders nothing.\n */\nexport function AIData<T>(props: AIDataProps<T>): null {\n    useProvideAIData(props);\n    return null;\n}\n"]}

package/build/esm/utils/aiAgentContext/buildAIContextSystemPrompt.d.ts

@@ -0,0 +1,7 @@
+import type { AIDataEntry, BuildAIContextOptions } from "./types.js";
+/**
+ * Formats AI data entries into a system prompt string.
+ * Uses YAML-like format by default, can be overridden via options.formatData.
+ * Uses prompt builder to build the system prompt from **Template Literal**. See `createDefaultSystemPromptBuilder` for more details.
+ */
+export declare function buildAIContextSystemPrompt<T = unknown>(entries: AIDataEntry<T>[], options?: BuildAIContextOptions<T>): string;

package/build/esm/utils/aiAgentContext/buildAIContextSystemPrompt.js

@@ -0,0 +1,18 @@
+import { DEFAULT_SYSTEM_PROMPT_TEMPLATE, createDefaultSystemPromptBuilder } from "./templateStrings.js";
+import { toYamlLike } from "./toYamlLike.js";
+/**
+ * Formats AI data entries into a system prompt string.
+ * Uses YAML-like format by default, can be overridden via options.formatData.
+ * Uses prompt builder to build the system prompt from **Template Literal**. See `createDefaultSystemPromptBuilder` for more details.
+ */
+export function buildAIContextSystemPrompt(entries, options = {}) {
+    var _a, _b;
+    if (entries.length === 0)
+        return '';
+    const builder = createDefaultSystemPromptBuilder(entries, {
+        formatData: (_a = options.formatData) !== null && _a !== void 0 ? _a : toYamlLike,
+    });
+    const template = (_b = options.template) !== null && _b !== void 0 ? _b : DEFAULT_SYSTEM_PROMPT_TEMPLATE;
+    return builder(...template);
+}
+//# sourceMappingURL=buildAIContextSystemPrompt.js.map

package/build/esm/utils/aiAgentContext/buildAIContextSystemPrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildAIContextSystemPrompt.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/buildAIContextSystemPrompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,8BAA8B,EAAE,gCAAgC,EAAC,6BAA0B;AACnG,OAAO,EAAC,UAAU,EAAC,wBAAqB;AAGxC;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACtC,OAAyB,EACzB,UAAoC,EAAE;;IAEtC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,OAAO,GAAG,gCAAgC,CAAI,OAAO,EAAE;QACzD,UAAU,EAAE,MAAA,OAAO,CAAC,UAAU,mCAAI,UAAU;KAC/C,CAAC,CAAC;IAEH,MAAM,QAAQ,GAA2B,MAAA,OAAO,CAAC,QAAQ,mCAAI,8BAA8B,CAAC;IAE5F,OAAO,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;AAChC,CAAC","sourcesContent":["import {DEFAULT_SYSTEM_PROMPT_TEMPLATE, createDefaultSystemPromptBuilder} from './templateStrings';\nimport {toYamlLike} from './toYamlLike';\nimport type {AIDataEntry, BuildAIContextOptions, PromptBuilderParams} from './types';\n\n/**\n * Formats AI data entries into a system prompt string.\n * Uses YAML-like format by default, can be overridden via options.formatData.\n * Uses prompt builder to build the system prompt from **Template Literal**. See `createDefaultSystemPromptBuilder` for more details.\n */\nexport function buildAIContextSystemPrompt<T = unknown>(\n    entries: AIDataEntry<T>[],\n    options: BuildAIContextOptions<T> = {},\n): string {\n    if (entries.length === 0) return '';\n\n    const builder = createDefaultSystemPromptBuilder<T>(entries, {\n        formatData: options.formatData ?? toYamlLike,\n    });\n\n    const template: PromptBuilderParams<T> = options.template ?? DEFAULT_SYSTEM_PROMPT_TEMPLATE;\n\n    return builder(...template);\n}\n"]}

package/build/esm/utils/aiAgentContext/index.d.ts

@@ -0,0 +1,5 @@
+export { AIAgentContextProvider, useAIAgentContext } from "./AIAgentContext.js";
+export { AIData, useProvideAIData } from "./AIData.js";
+export { buildAIContextSystemPrompt } from "./buildAIContextSystemPrompt.js";
+export { AIPrompt, DEFAULT_SYSTEM_PROMPT_TEMPLATE } from "./templateStrings.js";
+export type { AIDataProps, AIDataEntry, AIAgentContextAPI, BuildAIContextOptions, PromptBuilder, PromptBuilderParams, PromptBuilderExpression, PromptBuilderExpressionOptions, } from "./types.js";

package/build/esm/utils/aiAgentContext/index.js

@@ -0,0 +1,7 @@
+// Components
+export { AIAgentContextProvider, useAIAgentContext } from "./AIAgentContext.js";
+export { AIData, useProvideAIData } from "./AIData.js";
+// Utilities
+export { buildAIContextSystemPrompt } from "./buildAIContextSystemPrompt.js";
+export { AIPrompt, DEFAULT_SYSTEM_PROMPT_TEMPLATE } from "./templateStrings.js";
+//# sourceMappingURL=index.js.map

package/build/esm/utils/aiAgentContext/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/index.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,OAAO,EAAC,sBAAsB,EAAE,iBAAiB,EAAC,4BAAyB;AAC3E,OAAO,EAAC,MAAM,EAAE,gBAAgB,EAAC,oBAAiB;AAElD,YAAY;AACZ,OAAO,EAAC,0BAA0B,EAAC,wCAAqC;AACxE,OAAO,EAAC,QAAQ,EAAE,8BAA8B,EAAC,6BAA0B","sourcesContent":["// Components\nexport {AIAgentContextProvider, useAIAgentContext} from './AIAgentContext';\nexport {AIData, useProvideAIData} from './AIData';\n\n// Utilities\nexport {buildAIContextSystemPrompt} from './buildAIContextSystemPrompt';\nexport {AIPrompt, DEFAULT_SYSTEM_PROMPT_TEMPLATE} from './templateStrings';\n\n// Types\nexport type {\n    AIDataProps,\n    AIDataEntry,\n    AIAgentContextAPI,\n    BuildAIContextOptions,\n    PromptBuilder,\n    PromptBuilderParams,\n    PromptBuilderExpression,\n    PromptBuilderExpressionOptions,\n} from './types';\n"]}

package/build/esm/utils/aiAgentContext/templateStrings.d.ts

@@ -0,0 +1,4 @@
+import { AIDataEntry, AnyDepthArray, PromptBuilder, PromptBuilderExpression, PromptBuilderExpressionOptions, PromptBuilderParams } from "./types.js";
+export declare function AIPrompt<T = unknown>(templateParts: TemplateStringsArray, ...functions: (string | AnyDepthArray<string> | PromptBuilderExpression<T>)[]): PromptBuilderParams<T>;
+export declare function createDefaultSystemPromptBuilder<T = unknown>(entries: AIDataEntry<T>[], options: PromptBuilderExpressionOptions<T>): PromptBuilder<T>;
+export declare const DEFAULT_SYSTEM_PROMPT_TEMPLATE: [templateParts: string[], ...functions: (string | AnyDepthArray<string> | PromptBuilderExpression<any>)[]];

package/build/esm/utils/aiAgentContext/templateStrings.js

@@ -0,0 +1,32 @@
+export function AIPrompt(templateParts, ...functions) {
+    return [[...templateParts.raw], ...functions];
+}
+export function createDefaultSystemPromptBuilder(entries, options) {
+    return (templateParts, ...functions) => {
+        const out = [];
+        for (let i = 0; i < templateParts.length; i++) {
+            const part = templateParts[i];
+            out.push(part);
+            const fn = functions[i];
+            if (fn) {
+                const result = typeof fn === 'function' ? fn(entries, options) : fn;
+                if (typeof result === 'string') {
+                    out.push(result);
+                }
+                if (Array.isArray(result)) {
+                    // @ts-expect-error - we know that the result is an array of strings, but TS can't handle it (Type instantiation is excessively deep and possibly infinite.)
+                    out.push(result.flat(Infinity).join('\n\n'));
+                }
+            }
+        }
+        return out.join('');
+    };
+}
+export const DEFAULT_SYSTEM_PROMPT_TEMPLATE = AIPrompt `Meta information provided by the user about the current page they are on:
+
+${(entries, options) => entries.map((entry) => {
+    const formatted = options.formatData(entry.data);
+    return [`### ${entry.label}`, formatted];
+})}
+`;
+//# sourceMappingURL=templateStrings.js.map

package/build/esm/utils/aiAgentContext/templateStrings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templateStrings.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/templateStrings.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,QAAQ,CACpB,aAAmC,EACnC,GAAG,SAA0E;IAE7E,OAAO,CAAC,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,gCAAgC,CAC5C,OAAyB,EACzB,OAA0C;IAE1C,OAAO,CACH,aAAuB,EACvB,GAAG,SAA0E,EACvE,EAAE;QACR,MAAM,GAAG,GAAG,EAAE,CAAC;QAEf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5C,MAAM,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;YAC9B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAEf,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;YAExB,IAAI,EAAE,EAAE,CAAC;gBACL,MAAM,MAAM,GAAG,OAAO,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAEpE,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;oBAC7B,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACrB,CAAC;gBAED,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;oBACxB,4JAA4J;oBAC5J,GAAG,CAAC,IAAI,CAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC/D,CAAC;YACL,CAAC;QACL,CAAC;QAED,OAAO,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC;AACN,CAAC;AAED,MAAM,CAAC,MAAM,8BAA8B,GAAG,QAAQ,CAAK;;EAEzD,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CACnB,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;IAClB,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEjD,OAAO,CAAC,OAAO,KAAK,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;AAC7C,CAAC,CAAC;CACL,CAAC","sourcesContent":["import {\n    AIDataEntry,\n    AnyDepthArray,\n    PromptBuilder,\n    PromptBuilderExpression,\n    PromptBuilderExpressionOptions,\n    PromptBuilderParams,\n} from './types';\n\nexport function AIPrompt<T = unknown>(\n    templateParts: TemplateStringsArray,\n    ...functions: (string | AnyDepthArray<string> | PromptBuilderExpression<T>)[]\n): PromptBuilderParams<T> {\n    return [[...templateParts.raw], ...functions];\n}\n\nexport function createDefaultSystemPromptBuilder<T = unknown>(\n    entries: AIDataEntry<T>[],\n    options: PromptBuilderExpressionOptions<T>,\n): PromptBuilder<T> {\n    return (\n        templateParts: string[],\n        ...functions: (string | AnyDepthArray<string> | PromptBuilderExpression<T>)[]\n    ): string => {\n        const out = [];\n\n        for (let i = 0; i < templateParts.length; i++) {\n            const part = templateParts[i];\n            out.push(part);\n\n            const fn = functions[i];\n\n            if (fn) {\n                const result = typeof fn === 'function' ? fn(entries, options) : fn;\n\n                if (typeof result === 'string') {\n                    out.push(result);\n                }\n\n                if (Array.isArray(result)) {\n                    // @ts-expect-error - we know that the result is an array of strings, but TS can't handle it (Type instantiation is excessively deep and possibly infinite.)\n                    out.push((result.flat(Infinity) as string[]).join('\\n\\n'));\n                }\n            }\n        }\n\n        return out.join('');\n    };\n}\n\nexport const DEFAULT_SYSTEM_PROMPT_TEMPLATE = AIPrompt<any>`Meta information provided by the user about the current page they are on:\n\n${(entries, options) =>\n    entries.map((entry) => {\n        const formatted = options.formatData(entry.data);\n\n        return [`### ${entry.label}`, formatted];\n    })}\n`;\n"]}

package/build/esm/utils/aiAgentContext/toYamlLike.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Simple YAML-like serializer for plain JS values.
+ * Handles: string, number, boolean, null/undefined, arrays, plain objects.
+ * Falls back to String() for unsupported types.
+ * Internal helper — not exported from the package.
+ */
+export declare function toYamlLike(data: unknown, indent?: number): string;

package/build/esm/utils/aiAgentContext/toYamlLike.js

@@ -0,0 +1,105 @@
+const CIRCULAR_REF = '[Circular]';
+function indentLines(text, spaces) {
+    const prefix = ' '.repeat(spaces);
+    return text
+        .split('\n')
+        .map((line) => `${prefix}${line}`)
+        .join('\n');
+}
+function isComplexValue(val) {
+    if (val === null || val === undefined) {
+        return false;
+    }
+    if (Array.isArray(val)) {
+        return val.length > 0;
+    }
+    if (typeof val === 'object') {
+        return Object.keys(val).length > 0;
+    }
+    if (typeof val === 'string') {
+        return val.includes('\n');
+    }
+    return false;
+}
+function withVisitedObject(value, visited, serialize) {
+    if (visited.has(value)) {
+        return CIRCULAR_REF;
+    }
+    visited.add(value);
+    try {
+        return serialize();
+    }
+    finally {
+        visited.delete(value);
+    }
+}
+function isVisitedReference(val, visited) {
+    return typeof val === 'object' && val !== null && visited.has(val);
+}
+function formatKeyValue(key, val, keyPrefix, indent, visited) {
+    if (isVisitedReference(val, visited)) {
+        return `${keyPrefix}${key}: ${CIRCULAR_REF}`;
+    }
+    if (isComplexValue(val)) {
+        return `${keyPrefix}${key}:\n${toYamlLikeInternal(val, indent + 2, visited)}`;
+    }
+    return `${keyPrefix}${key}: ${toYamlLikeInternal(val, indent + 2, visited)}`;
+}
+/**
+ * Simple YAML-like serializer for plain JS values.
+ * Handles: string, number, boolean, null/undefined, arrays, plain objects.
+ * Falls back to String() for unsupported types.
+ * Internal helper — not exported from the package.
+ */
+export function toYamlLike(data, indent = 0) {
+    return toYamlLikeInternal(data, indent, new Set());
+}
+function toYamlLikeInternal(data, indent, visited) {
+    if (data === null || data === undefined)
+        return 'null';
+    if (typeof data === 'string') {
+        if (data.includes('\n')) {
+            return `|\n${indentLines(data, indent + 2)}`;
+        }
+        return data;
+    }
+    if (typeof data === 'number' || typeof data === 'boolean') {
+        return String(data);
+    }
+    if (Array.isArray(data)) {
+        if (data.length === 0)
+            return '[]';
+        return withVisitedObject(data, visited, () => data
+            .map((item) => {
+            const prefix = `${' '.repeat(indent)}- `;
+            if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+                return withVisitedObject(item, visited, () => {
+                    const entries = Object.entries(item);
+                    if (entries.length === 0)
+                        return `${prefix}{}`;
+                    const [firstKey, firstVal] = entries[0];
+                    const firstLine = formatKeyValue(firstKey, firstVal, `${' '.repeat(indent)}- `, indent, visited);
+                    const rest = entries
+                        .slice(1)
+                        .map(([key, val]) => formatKeyValue(key, val, ' '.repeat(indent + 2), indent + 2, visited))
+                        .join('\n');
+                    return rest ? `${firstLine}\n${rest}` : firstLine;
+                });
+            }
+            return `${prefix}${toYamlLikeInternal(item, indent + 2, visited)}`;
+        })
+            .join('\n'));
+    }
+    if (typeof data === 'object') {
+        return withVisitedObject(data, visited, () => {
+            const entries = Object.entries(data);
+            if (entries.length === 0)
+                return '{}';
+            return entries
+                .map(([key, val]) => formatKeyValue(key, val, ' '.repeat(indent), indent, visited))
+                .join('\n');
+        });
+    }
+    return String(data);
+}
+//# sourceMappingURL=toYamlLike.js.map

package/build/esm/utils/aiAgentContext/toYamlLike.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toYamlLike.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/toYamlLike.ts"],"names":[],"mappings":"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","sourcesContent":["const CIRCULAR_REF = '[Circular]';\n\nfunction indentLines(text: string, spaces: number): string {\n    const prefix = ' '.repeat(spaces);\n    return text\n        .split('\\n')\n        .map((line) => `${prefix}${line}`)\n        .join('\\n');\n}\n\nfunction isComplexValue(val: unknown): boolean {\n    if (val === null || val === undefined) {\n        return false;\n    }\n    if (Array.isArray(val)) {\n        return val.length > 0;\n    }\n    if (typeof val === 'object') {\n        return Object.keys(val).length > 0;\n    }\n    if (typeof val === 'string') {\n        return val.includes('\\n');\n    }\n    return false;\n}\n\nfunction withVisitedObject<T extends object>(\n    value: T,\n    visited: Set<object>,\n    serialize: () => string,\n): string {\n    if (visited.has(value)) {\n        return CIRCULAR_REF;\n    }\n    visited.add(value);\n    try {\n        return serialize();\n    } finally {\n        visited.delete(value);\n    }\n}\n\nfunction isVisitedReference(val: unknown, visited: Set<object>): val is object {\n    return typeof val === 'object' && val !== null && visited.has(val);\n}\n\nfunction formatKeyValue(\n    key: string,\n    val: unknown,\n    keyPrefix: string,\n    indent: number,\n    visited: Set<object>,\n): string {\n    if (isVisitedReference(val, visited)) {\n        return `${keyPrefix}${key}: ${CIRCULAR_REF}`;\n    }\n    if (isComplexValue(val)) {\n        return `${keyPrefix}${key}:\\n${toYamlLikeInternal(val, indent + 2, visited)}`;\n    }\n    return `${keyPrefix}${key}: ${toYamlLikeInternal(val, indent + 2, visited)}`;\n}\n\n/**\n * Simple YAML-like serializer for plain JS values.\n * Handles: string, number, boolean, null/undefined, arrays, plain objects.\n * Falls back to String() for unsupported types.\n * Internal helper — not exported from the package.\n */\nexport function toYamlLike(data: unknown, indent = 0): string {\n    return toYamlLikeInternal(data, indent, new Set());\n}\n\nfunction toYamlLikeInternal(data: unknown, indent: number, visited: Set<object>): string {\n    if (data === null || data === undefined) return 'null';\n\n    if (typeof data === 'string') {\n        if (data.includes('\\n')) {\n            return `|\\n${indentLines(data, indent + 2)}`;\n        }\n        return data;\n    }\n\n    if (typeof data === 'number' || typeof data === 'boolean') {\n        return String(data);\n    }\n\n    if (Array.isArray(data)) {\n        if (data.length === 0) return '[]';\n\n        return withVisitedObject(data, visited, () =>\n            data\n                .map((item) => {\n                    const prefix = `${' '.repeat(indent)}- `;\n                    if (typeof item === 'object' && item !== null && !Array.isArray(item)) {\n                        return withVisitedObject(item, visited, () => {\n                            const entries = Object.entries(item);\n                            if (entries.length === 0) return `${prefix}{}`;\n                            const [firstKey, firstVal] = entries[0];\n                            const firstLine = formatKeyValue(\n                                firstKey,\n                                firstVal,\n                                `${' '.repeat(indent)}- `,\n                                indent,\n                                visited,\n                            );\n                            const rest = entries\n                                .slice(1)\n                                .map(([key, val]) =>\n                                    formatKeyValue(\n                                        key,\n                                        val,\n                                        ' '.repeat(indent + 2),\n                                        indent + 2,\n                                        visited,\n                                    ),\n                                )\n                                .join('\\n');\n                            return rest ? `${firstLine}\\n${rest}` : firstLine;\n                        });\n                    }\n                    return `${prefix}${toYamlLikeInternal(item, indent + 2, visited)}`;\n                })\n                .join('\\n'),\n        );\n    }\n\n    if (typeof data === 'object') {\n        return withVisitedObject(data, visited, () => {\n            const entries = Object.entries(data as Record<string, unknown>);\n            if (entries.length === 0) return '{}';\n\n            return entries\n                .map(([key, val]) => formatKeyValue(key, val, ' '.repeat(indent), indent, visited))\n                .join('\\n');\n        });\n    }\n\n    return String(data);\n}\n"]}

package/build/esm/utils/aiAgentContext/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Props for AIData component and useProvideAIData hook
+ */
+export interface AIDataProps<T = unknown> {
+    /** Human-readable description of what this data represents */
+    label: string;
+    /** The actual data to expose to the AI agent */
+    data: T;
+}
+/**
+ * Entry returned by getData()
+ */
+export interface AIDataEntry<T = unknown> {
+    /** Human-readable description of what this data represents */
+    label: string;
+    /** The actual data */
+    data: T;
+}
+/**
+ * Public API returned by useAIAgentContext()
+ */
+export interface AIAgentContextAPI<T = unknown> {
+    /** Returns the current list of all registered data entries */
+    getData: () => AIDataEntry<T>[];
+}
+export type AnyDepthArray<T> = Array<T | AnyDepthArray<T>>;
+/**
+ * Expression for a prompt builder, used to build the part of system prompt.
+ * Returns the string part of the system prompt.
+ */
+export type PromptBuilderExpression<T = unknown> = (entries: AIDataEntry<T>[], options: PromptBuilderExpressionOptions<T>) => string | AnyDepthArray<string>;
+export interface PromptBuilderExpressionOptions<T = unknown> {
+    formatData: (data: T) => string;
+}
+/**
+ * Prompt builder **Tagged Template Literal** function.
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates
+ */
+export type PromptBuilder<T = unknown> = (templateParts: string[], ...functions: (string | AnyDepthArray<string> | PromptBuilderExpression<T>)[]) => string;
+export type PromptBuilderParams<T = unknown> = Parameters<PromptBuilder<T>>;
+/**
+ * Options for buildAIContextSystemPrompt
+ */
+export interface BuildAIContextOptions<T = unknown> {
+    /**
+     * System prompt **template literal**. Use this, if you want to customize the system prompt or create on the fly.
+     * If not provided, a default system prompt template literal will be used (see example below).
+     *
+     * Use `AIPrompt` helper function to create a valid template.
+     *
+     * If you ever worked with styled-components, this is similar to the `styled` function.
+     *
+     * @example
+     * ```ts
+     * // Like in styled-components, use backticks to create a template literal.
+     * AIPrompt`Meta information provided by the user about the current page they are on:
+     *
+     * ${(entries, options) => entries.map((entry) =>
+     *     // Each function inside the template literal has access to the entries and options from context:
+     *     `### ${entry.label}\n${options.formatData(entry.data)}`
+     * )}
+     * `
+     *
+     * ```
+     */
+    template?: PromptBuilderParams<T>;
+    /**
+     * Custom data formatter.
+     * This function is used to convert JS objects to a LLM-readable string.
+     *
+     * Defaults to YAML-like serializer.
+     *
+     * @example
+     * ```ts
+     * formatData: (data) => JSON.stringify(data, null, 2)
+     * ```
+     */
+    formatData?: (data: unknown) => string;
+}
+/**
+ * Internal context value. Not exported to consumers.
+ */
+export interface AIAgentContextValue<T = unknown> {
+    register: (id: string, getter: () => AIDataProps<T>) => void;
+    unregister: (id: string) => void;
+    getData: () => AIDataEntry<T>[];
+}

package/build/esm/utils/aiAgentContext/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/esm/utils/aiAgentContext/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"../../../../src","sources":["utils/aiAgentContext/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Props for AIData component and useProvideAIData hook\n */\nexport interface AIDataProps<T = unknown> {\n    /** Human-readable description of what this data represents */\n    label: string;\n    /** The actual data to expose to the AI agent */\n    data: T;\n}\n\n/**\n * Entry returned by getData()\n */\nexport interface AIDataEntry<T = unknown> {\n    /** Human-readable description of what this data represents */\n    label: string;\n    /** The actual data */\n    data: T;\n}\n\n/**\n * Public API returned by useAIAgentContext()\n */\nexport interface AIAgentContextAPI<T = unknown> {\n    /** Returns the current list of all registered data entries */\n    getData: () => AIDataEntry<T>[];\n}\n\nexport type AnyDepthArray<T> = Array<T | AnyDepthArray<T>>;\n\n/**\n * Expression for a prompt builder, used to build the part of system prompt.\n * Returns the string part of the system prompt.\n */\nexport type PromptBuilderExpression<T = unknown> = (\n    entries: AIDataEntry<T>[],\n    options: PromptBuilderExpressionOptions<T>,\n) => string | AnyDepthArray<string>;\n\nexport interface PromptBuilderExpressionOptions<T = unknown> {\n    formatData: (data: T) => string;\n}\n\n/**\n * Prompt builder **Tagged Template Literal** function.\n * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates\n */\nexport type PromptBuilder<T = unknown> = (\n    templateParts: string[],\n    ...functions: (string | AnyDepthArray<string> | PromptBuilderExpression<T>)[]\n) => string;\n\nexport type PromptBuilderParams<T = unknown> = Parameters<PromptBuilder<T>>;\n\n/**\n * Options for buildAIContextSystemPrompt\n */\nexport interface BuildAIContextOptions<T = unknown> {\n    /**\n     * System prompt **template literal**. Use this, if you want to customize the system prompt or create on the fly.\n     * If not provided, a default system prompt template literal will be used (see example below).\n     *\n     * Use `AIPrompt` helper function to create a valid template.\n     *\n     * If you ever worked with styled-components, this is similar to the `styled` function.\n     *\n     * @example\n     * ```ts\n     * // Like in styled-components, use backticks to create a template literal.\n     * AIPrompt`Meta information provided by the user about the current page they are on:\n     *\n     * ${(entries, options) => entries.map((entry) =>\n     *     // Each function inside the template literal has access to the entries and options from context:\n     *     `### ${entry.label}\\n${options.formatData(entry.data)}`\n     * )}\n     * `\n     *\n     * ```\n     */\n    template?: PromptBuilderParams<T>;\n    /**\n     * Custom data formatter.\n     * This function is used to convert JS objects to a LLM-readable string.\n     *\n     * Defaults to YAML-like serializer.\n     *\n     * @example\n     * ```ts\n     * formatData: (data) => JSON.stringify(data, null, 2)\n     * ```\n     */\n    formatData?: (data: unknown) => string;\n}\n\n/**\n * Internal context value. Not exported to consumers.\n */\nexport interface AIAgentContextValue<T = unknown> {\n    register: (id: string, getter: () => AIDataProps<T>) => void;\n    unregister: (id: string) => void;\n    getData: () => AIDataEntry<T>[];\n}\n"]}

package/build/esm/utils/index.d.ts

@@ -3,4 +3,5 @@ export * from "./messageUtils.js";
 export * from "./validation.js";
 export * from "./messageTypeRegistry.js";
 export * from "./clipboardUtils.js";
+export * from "./aiAgentContext/index.js";
 export * from "./toolset/index.js";

package/build/esm/utils/index.js

@@ -4,5 +4,6 @@ export * from "./messageUtils.js";
 export * from "./validation.js";
 export * from "./messageTypeRegistry.js";
 export * from "./clipboardUtils.js";
+export * from "./aiAgentContext/index.js";
 export * from "./toolset/index.js";
 //# sourceMappingURL=index.js.map

package/build/esm/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"../../../src","sources":["utils/index.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,+BAA4B;AAC5B,kCAA+B;AAC/B,gCAA6B;AAC7B,yCAAsC;AACtC,oCAAiC;AACjC,mCAA0B","sourcesContent":["// Export utilities\nexport * from './chatUtils';\nexport * from './messageUtils';\nexport * from './validation';\nexport * from './messageTypeRegistry';\nexport * from './clipboardUtils';\nexport * from './toolset';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"../../../src","sources":["utils/index.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,+BAA4B;AAC5B,kCAA+B;AAC/B,gCAA6B;AAC7B,yCAAsC;AACtC,oCAAiC;AACjC,0CAAiC;AACjC,mCAA0B","sourcesContent":["// Export utilities\nexport * from './chatUtils';\nexport * from './messageUtils';\nexport * from './validation';\nexport * from './messageTypeRegistry';\nexport * from './clipboardUtils';\nexport * from './aiAgentContext';\nexport * from './toolset';\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravity-ui/aikit",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Gravity UI base kit for building ai assistant chats",
   "license": "MIT",
   "type": "commonjs",
@@ -98,6 +98,16 @@
         "default": "./build/cjs/utils/clipboardUtils.js"
       }
     },
+    "./utils/aiAgentContext": {
+      "import": {
+        "types": "./build/esm/utils/aiAgentContext/index.d.ts",
+        "default": "./build/esm/utils/aiAgentContext/index.js"
+      },
+      "require": {
+        "types": "./build/cjs/utils/aiAgentContext/index.d.ts",
+        "default": "./build/cjs/utils/aiAgentContext/index.js"
+      }
+    },
     "./utils/toolset": {
       "import": {
         "types": "./build/esm/utils/toolset/index.d.ts",