AdguardTeam
diff --git a/‎CHANGELOG.md‎
Lines changed: 7 additions & 2 deletions b/‎CHANGELOG.md‎
Lines changed: 7 additions & 2 deletions
diff --git a/‎README.md‎
Lines changed: 145 additions & 0 deletions b/‎README.md‎
Lines changed: 145 additions & 0 deletions
diff --git a/‎package.json‎
Lines changed: 2 additions & 1 deletion b/‎package.json‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎pnpm-lock.yaml‎
Lines changed: 8 additions & 0 deletions b/‎pnpm-lock.yaml‎
Lines changed: 8 additions & 0 deletions
diff --git a/‎src/helpers/index.ts‎
Lines changed: 1 addition & 0 deletions b/‎src/helpers/index.ts‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎src/helpers/node-text-utils.ts‎
Lines changed: 9 additions & 30 deletions b/‎src/helpers/node-text-utils.ts‎
Lines changed: 9 additions & 30 deletions
@@ -12,6 +12,11 @@ The format is based on [Keep a Changelog], and this project adheres to [Semantic
 
 ## [Unreleased]
 
+### Added
+
+- TypeScript types for CoreLibs provided [`ContentScriptApi`](./README.md#scriptlets-api--content-script-api).
+- Trusted Types API utility - [`PolicyApi`](./README.md#scriptlets-api--content-script-api--policy-api).
+
 ### Changed
 
 - Improved docs for `json-prune`, `xml-prune` and `trusted-prune-inbound-object` scriptlets [#392]
@@ -39,8 +44,8 @@ The format is based on [Keep a Changelog], and this project adheres to [Semantic
 
 - issue with incorrectly removing content from parsed array when using the `json-prune` scriptlet [#482]
 
-  [v2.1.6]: https://github.com/AdguardTeam/Scriptlets/compare/v2.1.5...v2.1.6
-  [#482]: https://github.com/AdguardTeam/Scriptlets/issues/482
+[v2.1.6]: https://github.com/AdguardTeam/Scriptlets/compare/v2.1.5...v2.1.6
+[#482]: https://github.com/AdguardTeam/Scriptlets/issues/482
 
 ## [v2.1.5] - 2025-02-28
 
 
@@ -29,6 +29,8 @@ AdGuard's Scriptlets and Redirect resources library which provides extended capa
         - [`getScriptletFunction()`](#scriptlets-api--getScriptletFunction)
         - [Properties](#scriptlets-api-properties)
             - [`SCRIPTLETS_VERSION`](#scriptlets-api--version)
+        - [`ContentScriptApi`](#scriptlets-api--content-script-api)
+            - [`PolicyApi`](#scriptlets-api--content-script-api--policy-api)
     - [Redirects API](#redirects-api)
         - [Redirects class](#redirects-api--redirects-class)
         - [`getRedirect()`](#redirects-api--getRedirect)
@@ -463,9 +465,19 @@ interface Source {
      * scriptlet can be called multiple times.
      */
     uniqueId?: string;
+    /**
+     * Instance of content script provided API.
+     *
+     * Property optional because:
+     * - for backwards compatibility.
+     * - currently only CoreLibs provides this API.
+     */
+    api?: ContentScriptApi;
 }
 ```
 
+see also [`ContentScriptApi`](#scriptlets-api--content-script-api) for more details.
+
 #### <a name="scriptlets-api--getScriptletFunction"></a> `getScriptletFunction()`
 
 ```typescript
@@ -490,6 +502,139 @@ type: `string`
 
 Current version of scriptlets library.
 
+#### <a name="scriptlets-api--content-script-api"></a> `ContentScriptApi`
+
+API provided by CoreLibs content script.
+
+This API is used to provide a set of utilities and shared state for scriptlets
+running in the context of a web page. Particularly, it includes:
+
+```typescript
+export interface ContentScriptApi {
+    /**
+     * Trusted Types Policy API utilities.
+     */
+    readonly policy: PolicyApi;
+
+    /**
+     * Shared state between different script and scriptlet rules.
+     *
+     * This object acts as a centralized repository for shared data.
+     * - Keys represent the unique identifiers or names of the shared data.
+     * - Values can be of any type and should correspond to the specific data shared across script rules.
+     *
+     * Example:.
+     * ```adguard
+     * ! Modify in one script rule
+     * #%#api.shared.testKey = 'testValue'
+     *
+     * ! Access in another (logs 'testValue')
+     * #%#console.log(api.shared.testKey)
+     * ```
+     */
+    readonly shared: Record<string, unknown>;
+}
+```
+
+##### <a name="scriptlets-api--content-script-api--policy-api"></a> `PolicyApi`
+
+Trusted Types Policy API utility.
+
+This interface extends the native `TrustedTypePolicy` and `TrustedTypePolicyFactory`
+to provide a more user-friendly API for working with Trusted Types. In case if
+environment doesn't support Trusted Types API, it provides polyfilled methods
+and properties to ensure compatibility.
+
+```typescript
+export interface PolicyApi extends TrustedTypePolicy, TrustedTypePolicyFactory {
+    /**
+     * Is Trusted Types API supported.
+     */
+    isSupported: boolean;
+
+    /**
+     * TrustedType enum attached to PolicyApi.
+     *
+     * Reason why we attach it to instance because inside
+     * of script and scriptlet we can't import and to not
+     * pollute global env with custom variables.
+     *
+     * @example
+     * api.policy.TrustedType.HTML // "TrustedHTML"
+     */
+    TrustedType: typeof TrustedType;
+
+    /**
+     * Creates Trusted Type depending on `type`:
+     * - `TrustedHTML`
+     * - `TrustedScript`
+     * - `TrustedScriptURL`
+     * - or returns back `input` if none of them applicable.
+     *
+     * @example
+     * divElement.innerHTML = api.policy.create(api.policy.TrustedType.HTML, '<div></div>');
+     *
+     * @param type Trusted Type.
+     * @param input Input from which creates Trusted Type.
+     * @returns Created value.
+     */
+    create(type: TrustedType, input: string): string;
+
+    /**
+     * Converts `value` of `attribute` into one of the Trusted Types:
+     * - `TrustedHTML`
+     * - `TrustedScript`
+     * - `TrustedScriptURL`
+     * - or returns back `value` if none of them applicable (`null`).
+     *
+     * @example
+     * const trustedScriptURL = api.policy.convertAttributeToTrusted("script", "src", 'SOME_URL');
+     * scriptElement.setAttribute("src", trustedScriptURL);
+     *
+     * @param tagName Name of an HTML tag.
+     * @param attribute Attribute.
+     * @param value Value of attribute that needs to be converted.
+     * @param elementNS Element namespace, if empty defaults to the HTML namespace.
+     * @param attrNS Attribute namespace, if empty defaults to null.
+     * @returns Converted value.
+     */
+    convertAttributeToTrusted(
+        tagName: string,
+        attribute: string,
+        value: string,
+        elementNS?: string,
+        attrNS?: string,
+    ): string;
+
+    /**
+     * Converts `value` of `property` into one of the Trusted Types:
+     * - `TrustedHTML`
+     * - `TrustedScript`
+     * - `TrustedScriptURL`
+     * - or returns back `value` if none of them applicable (`null`).
+     *
+     * @example
+     * divElement.innerHTML = api.policy.convertPropertyToTrusted("div", "innerHTML", "<div></div>");
+     *
+     * @param tagName Name of an HTML tag.
+     * @param property Property.
+     * @param value Value or property.
+     * @param elementNS Element namespace, if empty defaults to the HTML namespace.
+     * @returns Converted value.
+     */
+    convertPropertyToTrusted(
+        tagName: string,
+        property: string,
+        value: string,
+        elementNS?: string,
+    ): string;
+}
+```
+
+- [TrustedTypePolicy](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy) interface
+- [TrustedTypePolicyFactory](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory) interface
+
+
 ### <a name="redirects-api"></a> Redirects API
 
 You are welcome to use redirects as a CJS modules or ESM modules:
 
@@ -1,6 +1,6 @@
 {
     "name": "@adguard/scriptlets",
-    "version": "2.1.7",
+    "version": "2.2.0",
     "description": "AdGuard's JavaScript library of Scriptlets and Redirect resources",
     "type": "module",
     "scripts": {
@@ -89,6 +89,7 @@
         "@swc/core": "^1.8.0",
         "@types/js-yaml": "^3.12.10",
         "@types/node": "^22.7.9",
+        "@types/trusted-types": "^2.0.7",
         "@typescript-eslint/eslint-plugin": "^5.52.0",
         "@typescript-eslint/parser": "^5.62.0",
         "axios": "^1.7.7",
 
@@ -37,4 +37,5 @@ export * from './random-id';
 export * from './throttle';
 export * from './shadow-dom-utils';
 export * from './node-text-utils';
+export * from './trusted-types-utils';
 export * from './value-matchers';
@@ -3,17 +3,7 @@ import { nodeListToArray } from './array-utils';
 import { getAddedNodes } from './observer';
 import { toRegExp } from './string-utils';
 import { type Source } from '../scriptlets';
-
-declare global {
-    interface Window {
-        trustedTypes?: {
-            createPolicy: (
-                name: string,
-                rules: { createScript: (input: string) => string }
-            ) => { createScript: (input: string) => string };
-        };
-    }
-}
+import { getTrustedTypesApi } from './trusted-types-utils';
 
 type NodeHandler = (nodes: Node[]) => void;
 
@@ -121,28 +111,17 @@ export const replaceNodeText = (
 ): void => {
     const { textContent } = node;
     if (textContent) {
+        let modifiedText = textContent.replace(pattern, replacement);
+
         // For websites that use Trusted Types
         // https://w3c.github.io/webappsec-trusted-types/dist/spec/
-        if (
-            node.nodeName === 'SCRIPT'
-            && window.trustedTypes
-            && window.trustedTypes.createPolicy
-        ) {
-            // The name for the trusted-types policy should only be 'AGPolicy',because corelibs can
-            // allow our policy if the server has restricted the creation of a trusted-types policy with
-            // the directive 'Content-Security-Policy: trusted-types <policyName>;`.
-            // If such a header is presented in the server response, corelibs adds permission to create
-            // the 'AGPolicy' policy with the 'allow-duplicates' option to prevent errors.
-            // See AG-18204 for details.
-            const policy = window.trustedTypes.createPolicy('AGPolicy', {
-                createScript: (string) => string,
-            });
-            const modifiedText = textContent.replace(pattern, replacement);
-            const trustedReplacement = policy.createScript(modifiedText);
-            node.textContent = trustedReplacement;
-        } else {
-            node.textContent = textContent.replace(pattern, replacement);
+        if (node.nodeName === 'SCRIPT') {
+            const trustedTypesApi = getTrustedTypesApi(source);
+            modifiedText = trustedTypesApi.createScript(modifiedText);
         }
+
+        node.textContent = modifiedText;
+
         hit(source);
     }
 };