@speclynx/apidom-overlay 4.4.0 → 4.6.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.6.0](https://github.com/speclynx/apidom/compare/v4.5.0...v4.6.0) (2026-04-12)
+
+### Features
+
+- **overlay:** add tracing and restructure into realms ([#234](https://github.com/speclynx/apidom/issues/234)) ([3ae47c6](https://github.com/speclynx/apidom/commit/3ae47c6f8916b70db15704ade73af63210813c8c))
+
+# [4.5.0](https://github.com/speclynx/apidom/compare/v4.4.0...v4.5.0) (2026-04-12)
+
+### Features
+
+- **overlay:** add support for POJO ([#233](https://github.com/speclynx/apidom/issues/233)) ([810b8e4](https://github.com/speclynx/apidom/commit/810b8e4b10787f9982e449915fbc0c4d58c65e1d))
+
 # [4.4.0](https://github.com/speclynx/apidom/compare/v4.3.1...v4.4.0) (2026-04-12)
 
 ### Features

package/README.md

@@ -19,11 +19,11 @@ This package provides three levels of API for applying overlays:
 
 ### Applying from file/URL
 
-The default export parses an overlay document, resolves the target (from `targetURI` or the overlay's `extends` field),
+`applyOverlay` parses an overlay document, resolves the target (from `targetURI` or the overlay's `extends` field),
 and applies all actions. The target is parsed with style preservation for round-trip fidelity.
 
 ```js
-import applyOverlay from '@speclynx/apidom-overlay';
+import { applyOverlay } from '@speclynx/apidom-overlay';
 import { toYAML } from '@speclynx/apidom-core';
 
 // target from extends field
@@ -62,14 +62,12 @@ const target = refract({
 const result = applyOverlayApiDOM(overlay, target);
 ```
 
-### Applying a single action
-
-`applyAction` applies a single overlay action. Useful for programmatic, step-by-step application.
+`applyActionApiDOM` applies a single overlay action. Useful for programmatic, step-by-step application.
 
 ```js
 import { refract } from '@speclynx/apidom-datamodel';
 import { refractAction } from '@speclynx/apidom-ns-overlay-1';
-import { applyAction } from '@speclynx/apidom-overlay';
+import { applyActionApiDOM } from '@speclynx/apidom-overlay';
 
 const action = refractAction({
   target: '$.info.title',
@@ -77,7 +75,38 @@ const action = refractAction({
 });
 const target = refract({ info: { title: 'Old Title', version: '1.0.0' } });
 
-const result = applyAction(action, target);
+const result = applyActionApiDOM(action, target);
+```
+
+### Applying to plain JavaScript objects (POJO)
+
+`applyOverlayPOJO` and `applyActionPOJO` accept and return plain JavaScript objects —
+no need to manually refract or serialize.
+
+```js
+import { applyOverlayPOJO, applyActionPOJO } from '@speclynx/apidom-overlay';
+
+// full overlay
+const result = applyOverlayPOJO(
+  {
+    overlay: '1.1.0',
+    info: { title: 'My overlay', version: '1.0.0' },
+    actions: [
+      { target: '$.info.title', update: 'Renamed API' },
+    ],
+  },
+  {
+    openapi: '3.1.0',
+    info: { title: 'Original', version: '1.0.0' },
+  },
+);
+// result is a plain object: { openapi: '3.1.0', info: { title: 'Renamed API', version: '1.0.0' } }
+
+// single action
+const updated = applyActionPOJO(
+  { target: '$.info.title', update: 'New Title' },
+  { info: { title: 'Old Title' } },
+);
 ```
 
 ## Overlay spec semantics
@@ -95,17 +124,73 @@ The implementation follows [Overlay 1.1.0](https://spec.openapis.org/overlay/v1.
 | `remove: true` | Removes matched nodes; when combined with `update`, the update has no effect |
 | Action ordering | Applied sequentially — each action modifies the result of the previous |
 
+## Tracing
+
+Overlay application supports tracing to inspect what each action did during application.
+Pass a trace object via the `trace` option — it will be populated in place with step-by-step
+information about every action applied.
+
+```js
+import { applyOverlayApiDOM } from '@speclynx/apidom-overlay';
+
+const trace = {};
+const result = applyOverlayApiDOM(overlay, target, { trace });
+
+console.log(trace.failed);   // false
+console.log(trace.message);  // 'Overlay was successfully applied'
+
+for (const action of trace.actions) {
+  console.log(action.target);          // '$.info.title'
+  console.log(action.type);            // 'update' | 'copy' | 'remove' | 'noop'
+  console.log(action.matchCount);      // 1
+  console.log(action.normalizedPaths); // ["$['info']['title']"]
+  console.log(action.success);         // true
+}
+```
+
+When an action fails, the trace captures the error before it is re-thrown:
+
+```js
+const trace = {};
+try {
+  applyOverlayApiDOM(overlay, target, { trace });
+} catch (error) {
+  console.log(trace.failed);                // true
+  console.log(trace.failedAt);              // index of the failed action
+  console.log(trace.message);               // error message
+  console.log(trace.actions[trace.failedAt].error); // the OverlayError instance
+}
+```
+
+Tracing works across all API levels — ApiDOM elements, file/URL, and POJO:
+
+```js
+// single action (ApiDOM)
+const trace = {};
+applyActionApiDOM(action, target, { trace });
+console.log(trace.actions[0].type); // 'update'
+
+// file/URL
+const trace = {};
+await applyOverlay('/path/to/overlay.yaml', undefined, { trace });
+
+// POJO
+const trace = {};
+applyOverlayPOJO(overlay, target, { trace });
+```
+
 ## Options
 
 ### ApplyOptions
 
-Passed to `applyAction`, `applyOverlayApiDOM`, and `applyOverlay`:
+Passed to `applyActionApiDOM`, `applyOverlayApiDOM`, and `applyOverlay`:
 
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `deepmerge` | `DeepMergeUserOptions` | `{}` | Custom [deepmerge options](https://github.com/speclynx/apidom/blob/main/packages/apidom-core/src/merge/deepmerge.ts) from `@speclynx/apidom-core`. Default `customMerge` enforces Overlay spec type compatibility. |
 | `strict` | `boolean` | `false` | When `true`, throws `OverlayError` if any action's target JSONPath matches zero nodes. |
 | `immutable` | `boolean` | `true` | When `true` (default), returns a new element without mutating the input. Set to `false` for in-place mutation. |
+| `trace` | `OverlayTrace` | — | When provided, populated in place with action-by-action trace data. See [Tracing](#tracing). |
 
 ### ApplyOverlayOptions
 
@@ -136,10 +221,10 @@ All errors thrown by this package are instances of `OverlayError`, which extends
 Errors carry structured context for diagnostics:
 
 ```js
-import { applyAction, OverlayError } from '@speclynx/apidom-overlay';
+import { applyActionApiDOM, OverlayError } from '@speclynx/apidom-overlay';
 
 try {
-  applyAction(action, target);
+  applyActionApiDOM(action, target);
 } catch (error) {
   if (error instanceof OverlayError) {
     console.error(error.message);

package/dist/apidom-overlay.browser.js

@@ -11,99 +11,7 @@
 return /******/ (() => { // webpackBootstrap
 /******/ 	var __webpack_modules__ = ({
 
-/***/ 17621
-(__unused_webpack_module, __webpack_exports__, __webpack_require__) {
-
-"use strict";
-__webpack_require__.r(__webpack_exports__);
-/* harmony export */ __webpack_require__.d(__webpack_exports__, {
-/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
-/* harmony export */ });
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(96911);
-/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(26432);
-/* harmony import */ var _speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(29807);
-/* harmony import */ var _apply_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(3138);
-/* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(18436);
-
-
-
-
-
-
-/**
- * @public
- */
-
-const defaultOptions = {
-  parse: {
-    parserOpts: {
-      strict: false,
-      style: true,
-      'overlay-json-1': {
-        sourceMap: true,
-        style: false,
-        extends: true
-      },
-      'overlay-yaml-1': {
-        sourceMap: true,
-        style: false,
-        extends: true
-      }
-    }
-  },
-  resolve: {
-    resolverOpts: {
-      fileAllowList: ['*']
-    }
-  }
-};
-
-/**
- * Applies an overlay document from a file/URL to its target document.
- *
- * Parses the overlay, resolves the target from `targetURI` or the overlay's
- * `extends` field, parses the target with style preservation for round-trip fidelity,
- * and applies all overlay actions.
- *
- * @param overlayURI - URI to the overlay document (file path or URL)
- * @param targetURI - URI to the target document; if omitted, uses the overlay's `extends` field
- * @param options - apidom-reference options + overlay merge options
- * @returns ParseResultElement with the modified target document
- *
- * @public
- */
-const applyOverlay = async (overlayURI, targetURI, options = {
-  immutable: false,
-  strict: false
-}) => {
-  const mergedOptions = (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.mergeOptions)(defaultOptions, options);
-
-  // parse the overlay document along with document attached to `extends` field (if present)
-  const overlayParseResult = await (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.parse)(overlayURI, mergedOptions);
-  const overlayElement = overlayParseResult.api;
-  if (!(0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_1__.isOverlay1Element)(overlayElement)) {
-    throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__["default"](`Failed to parse overlay document "${overlayURI}"`);
-  }
-  let targetParseResult;
-  if (targetURI) {
-    const targetOptions = (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.mergeOptions)(defaultOptions, options);
-    targetParseResult = await (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.parse)(targetURI, targetOptions);
-  } else {
-    const extendsElement = overlayElement.get('extends');
-    targetParseResult = extendsElement?.meta?.get('parseResult');
-  }
-  if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isParseResultElement)(targetParseResult)) {
-    throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__["default"]('No target specified: provide targetURI or set the "extends" field in the overlay document');
-  }
-
-  // apply overlay actions to the target (returns targetParseResult with result replaced)
-  return (0,_apply_ts__WEBPACK_IMPORTED_MODULE_3__.applyOverlayApiDOM)(overlayParseResult, targetParseResult, options);
-};
-/* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (applyOverlay);
-
-/***/ },
-
-/***/ 3138
+/***/ 28216
 (__unused_webpack_module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -111,7 +19,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   applyAction: () => (/* binding */ applyAction),
 /* harmony export */   applyCopyAction: () => (/* binding */ applyCopyAction),
-/* harmony export */   applyOverlayApiDOM: () => (/* binding */ applyOverlayApiDOM),
+/* harmony export */   applyOverlay: () => (/* binding */ applyOverlay),
 /* harmony export */   applyRemoveAction: () => (/* binding */ applyRemoveAction),
 /* harmony export */   applyUpdateAction: () => (/* binding */ applyUpdateAction)
 /* harmony export */ });
@@ -125,6 +33,8 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(26432);
 /* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(18436);
 /* harmony import */ var _validate_ts__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(24338);
+/* harmony import */ var _trace_TraceBuilder_ts__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(90563);
+
 
 
 
@@ -136,6 +46,10 @@ __webpack_require__.r(__webpack_exports__);
  * @public
  */
 
+/**
+ * Internal options that carry the tracer instance.
+ */
+
 const defaultApplyOptions = {
   immutable: true,
   strict: false
@@ -277,6 +191,8 @@ const applyRemoveAction = (normalizedPaths, targetElement, options = defaultAppl
  * @public
  */
 const applyAction = (actionElement, targetElement, options = defaultApplyOptions) => {
+  const internalOpts = options;
+  const tracer = internalOpts.tracer ?? (options.trace ? new _trace_TraceBuilder_ts__WEBPACK_IMPORTED_MODULE_10__["default"](options.trace) : undefined);
   const actionValidation = (0,_validate_ts__WEBPACK_IMPORTED_MODULE_9__.validateAction)(actionElement);
   if (!actionValidation.valid) throw actionValidation.error;
   const targetExpression = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_3__["default"])(actionElement.target);
@@ -290,24 +206,53 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
   });
   if (matches.length === 0) {
     if (options.strict) {
-      throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"](`Action target "${targetExpression}" matched zero nodes (strict mode)`, {
+      const error = new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"](`Action target "${targetExpression}" matched zero nodes (strict mode)`, {
         action: actionElement
       });
+      tracer?.action({
+        target: targetExpression,
+        type: 'noop',
+        matchCount: 0,
+        normalizedPaths: [],
+        success: false,
+        error
+      });
+      throw error;
     }
+    tracer?.action({
+      target: targetExpression,
+      type: 'noop',
+      matchCount: 0,
+      normalizedPaths: []
+    });
     return targetElement;
   }
   try {
     // remove action
     const removeValue = actionElement.removeField;
     if (removeValue !== undefined && (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_3__["default"])(removeValue) === true) {
-      return applyRemoveAction(normalizedPaths, targetElement, options);
+      const result = applyRemoveAction(normalizedPaths, targetElement, options);
+      tracer?.action({
+        target: targetExpression,
+        type: 'remove',
+        matchCount: matches.length,
+        normalizedPaths
+      });
+      return result;
     }
 
     // update action
     if (actionElement.update !== undefined) {
       const nodesValidation = (0,_validate_ts__WEBPACK_IMPORTED_MODULE_9__.validateTargetNodes)(matches);
       if (!nodesValidation.valid) throw nodesValidation.error;
-      return applyUpdateAction(normalizedPaths, actionElement.update, targetElement, options);
+      const result = applyUpdateAction(normalizedPaths, actionElement.update, targetElement, options);
+      tracer?.action({
+        target: targetExpression,
+        type: 'update',
+        matchCount: matches.length,
+        normalizedPaths
+      });
+      return result;
     }
 
     // copy action
@@ -315,14 +260,35 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
       const nodesValidation = (0,_validate_ts__WEBPACK_IMPORTED_MODULE_9__.validateTargetNodes)(matches);
       if (!nodesValidation.valid) throw nodesValidation.error;
       const copyExpression = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_3__["default"])(actionElement.copy);
-      return applyCopyAction(normalizedPaths, copyExpression, targetElement, options);
+      const result = applyCopyAction(normalizedPaths, copyExpression, targetElement, options);
+      tracer?.action({
+        target: targetExpression,
+        type: 'copy',
+        matchCount: matches.length,
+        normalizedPaths
+      });
+      return result;
     }
+    tracer?.action({
+      target: targetExpression,
+      type: 'noop',
+      matchCount: matches.length,
+      normalizedPaths
+    });
     return targetElement;
   } catch (error) {
     // enrich OverlayError with action context, preserving original stack
     if (error instanceof _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"] && !error.action) {
       error.action = actionElement;
     }
+    tracer?.action({
+      target: targetExpression,
+      type: 'noop',
+      matchCount: matches.length,
+      normalizedPaths,
+      success: false,
+      error: error instanceof _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"] ? error : undefined
+    });
     throw error;
   }
 };
@@ -333,7 +299,7 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
  *
  * @public
  */
-const applyOverlayApiDOM = (overlayElement, targetElement, options = defaultApplyOptions) => {
+const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptions) => {
   const overlay = overlayElement instanceof _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"] ? overlayElement.api : overlayElement;
   if (!(0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_7__.isOverlay1Element)(overlay)) {
     throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"]('First argument must be an Overlay 1.x document');
@@ -350,8 +316,13 @@ const applyOverlayApiDOM = (overlayElement, targetElement, options = defaultAppl
   if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isArrayElement)(overlay.actions)) {
     return targetElement;
   }
+  const tracer = options.trace ? new _trace_TraceBuilder_ts__WEBPACK_IMPORTED_MODULE_10__["default"](options.trace) : undefined;
+  const internalOptions = tracer ? {
+    ...options,
+    tracer
+  } : options;
   for (const action of overlay.actions) {
-    target = applyAction(action, target, options);
+    target = applyAction(action, target, internalOptions);
   }
   if (targetElement instanceof _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"]) {
     targetElement.replaceResult(target);
@@ -362,6 +333,184 @@ const applyOverlayApiDOM = (overlayElement, targetElement, options = defaultAppl
 
 /***/ },
 
+/***/ 83942
+(__unused_webpack_module, __webpack_exports__, __webpack_require__) {
+
+"use strict";
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   applyAction: () => (/* binding */ applyAction),
+/* harmony export */   applyOverlay: () => (/* binding */ applyOverlay)
+/* harmony export */ });
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(10404);
+/* harmony import */ var _speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(44673);
+/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(35957);
+/* harmony import */ var _apidom_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(28216);
+
+
+
+
+
+/**
+ * Applies a single overlay action (POJO) to a target (POJO).
+ *
+ * @public
+ */
+const applyAction = (action, target, options) => (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_1__["default"])((0,_apidom_ts__WEBPACK_IMPORTED_MODULE_3__.applyAction)((0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__.refractAction)(action), (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.refract)(target), options));
+
+/**
+ * Applies an entire overlay document (POJO) to a target (POJO).
+ *
+ * @public
+ */
+const applyOverlay = (overlay, target, options) => (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_1__["default"])((0,_apidom_ts__WEBPACK_IMPORTED_MODULE_3__.applyOverlay)((0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__.refractOverlay1)(overlay), (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.refract)(target), options));
+
+/***/ },
+
+/***/ 42768
+(__unused_webpack_module, __webpack_exports__, __webpack_require__) {
+
+"use strict";
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
+/* harmony export */ });
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(96911);
+/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(26432);
+/* harmony import */ var _speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(29807);
+/* harmony import */ var _apidom_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(28216);
+/* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(18436);
+
+
+
+
+
+
+/**
+ * @public
+ */
+
+const defaultOptions = {
+  parse: {
+    parserOpts: {
+      strict: false,
+      style: true,
+      'overlay-json-1': {
+        sourceMap: true,
+        style: false,
+        extends: true
+      },
+      'overlay-yaml-1': {
+        sourceMap: true,
+        style: false,
+        extends: true
+      }
+    }
+  },
+  resolve: {
+    resolverOpts: {
+      fileAllowList: ['*']
+    }
+  }
+};
+
+/**
+ * Applies an overlay document from a file/URL to its target document.
+ *
+ * Parses the overlay, resolves the target from `targetURI` or the overlay's
+ * `extends` field, parses the target with style preservation for round-trip fidelity,
+ * and applies all overlay actions.
+ *
+ * @param overlayURI - URI to the overlay document (file path or URL)
+ * @param targetURI - URI to the target document; if omitted, uses the overlay's `extends` field
+ * @param options - apidom-reference options + overlay merge options
+ * @returns ParseResultElement with the modified target document
+ *
+ * @public
+ */
+const applyOverlay = async (overlayURI, targetURI, options = {
+  immutable: false,
+  strict: false
+}) => {
+  const mergedOptions = (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.mergeOptions)(defaultOptions, options);
+
+  // parse the overlay document along with document attached to `extends` field (if present)
+  const overlayParseResult = await (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.parse)(overlayURI, mergedOptions);
+  const overlayElement = overlayParseResult.api;
+  if (!(0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_1__.isOverlay1Element)(overlayElement)) {
+    throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__["default"](`Failed to parse overlay document "${overlayURI}"`);
+  }
+  let targetParseResult;
+  if (targetURI) {
+    const targetOptions = (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.mergeOptions)(defaultOptions, options);
+    targetParseResult = await (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.parse)(targetURI, targetOptions);
+  } else {
+    const extendsElement = overlayElement.get('extends');
+    targetParseResult = extendsElement?.meta?.get('parseResult');
+  }
+  if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isParseResultElement)(targetParseResult)) {
+    throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__["default"]('No target specified: provide targetURI or set the "extends" field in the overlay document');
+  }
+
+  // apply overlay actions to the target (returns targetParseResult with result replaced)
+  return (0,_apidom_ts__WEBPACK_IMPORTED_MODULE_3__.applyOverlay)(overlayParseResult, targetParseResult, options);
+};
+/* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (applyOverlay);
+
+/***/ },
+
+/***/ 90563
+(__unused_webpack_module, __webpack_exports__, __webpack_require__) {
+
+"use strict";
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
+/* harmony export */ });
+/**
+ * Collects trace entries during overlay application.
+ * Instantiated internally when `options.trace` is provided.
+ */
+class TraceBuilder {
+  #trace;
+  constructor(trace) {
+    this.#trace = trace;
+    this.#trace.actions = [];
+    this.#trace.failed = false;
+    this.#trace.failedAt = -1;
+    this.#trace.message = 'Overlay was successfully applied';
+  }
+  action(step) {
+    const {
+      target,
+      type,
+      matchCount,
+      normalizedPaths,
+      success = true,
+      error
+    } = step;
+    const position = this.#trace.actions.length;
+    this.#trace.actions.push({
+      target,
+      type,
+      matchCount,
+      normalizedPaths,
+      success,
+      ...(error !== undefined ? {
+        error
+      } : {})
+    });
+    if (!success) {
+      this.#trace.failed = true;
+      this.#trace.failedAt = position;
+      this.#trace.message = error?.message ?? 'Action failed';
+    }
+  }
+}
+/* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (TraceBuilder);
+
+/***/ },
+
 /***/ 18436
 (__unused_webpack_module, __webpack_exports__, __webpack_require__) {
 
@@ -100862,16 +101011,20 @@ var __webpack_exports__ = {};
 "use strict";
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
-/* harmony export */   OverlayError: () => (/* reexport safe */ _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_2__["default"]),
-/* harmony export */   applyAction: () => (/* reexport safe */ _apply_ts__WEBPACK_IMPORTED_MODULE_0__.applyAction),
-/* harmony export */   applyOverlayApiDOM: () => (/* reexport safe */ _apply_ts__WEBPACK_IMPORTED_MODULE_0__.applyOverlayApiDOM),
-/* harmony export */   "default": () => (/* reexport safe */ _apply_uri_ts__WEBPACK_IMPORTED_MODULE_3__["default"]),
-/* harmony export */   validateAction: () => (/* reexport safe */ _validate_ts__WEBPACK_IMPORTED_MODULE_1__.validateAction)
+/* harmony export */   OverlayError: () => (/* reexport safe */ _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__["default"]),
+/* harmony export */   applyActionApiDOM: () => (/* reexport safe */ _apply_realms_apidom_ts__WEBPACK_IMPORTED_MODULE_0__.applyAction),
+/* harmony export */   applyActionPOJO: () => (/* reexport safe */ _apply_realms_pojo_ts__WEBPACK_IMPORTED_MODULE_2__.applyAction),
+/* harmony export */   applyOverlay: () => (/* reexport safe */ _apply_realms_uri_ts__WEBPACK_IMPORTED_MODULE_1__["default"]),
+/* harmony export */   applyOverlayApiDOM: () => (/* reexport safe */ _apply_realms_apidom_ts__WEBPACK_IMPORTED_MODULE_0__.applyOverlay),
+/* harmony export */   applyOverlayPOJO: () => (/* reexport safe */ _apply_realms_pojo_ts__WEBPACK_IMPORTED_MODULE_2__.applyOverlay),
+/* harmony export */   validateAction: () => (/* reexport safe */ _validate_ts__WEBPACK_IMPORTED_MODULE_3__.validateAction)
 /* harmony export */ });
-/* harmony import */ var _apply_ts__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(3138);
-/* harmony import */ var _validate_ts__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(24338);
-/* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(18436);
-/* harmony import */ var _apply_uri_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(17621);
+/* harmony import */ var _apply_realms_apidom_ts__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(28216);
+/* harmony import */ var _apply_realms_uri_ts__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(42768);
+/* harmony import */ var _apply_realms_pojo_ts__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(83942);
+/* harmony import */ var _validate_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(24338);
+/* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(18436);
+