@speclynx/apidom-overlay 4.4.0 → 4.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-overlay",
-  "version": "4.4.0",
+  "version": "4.6.0",
   "description": "Apply Overlay 1.x.y documents to API definitions.",
   "keywords": [
     "apidom",
@@ -53,12 +53,12 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-core": "4.4.0",
-    "@speclynx/apidom-datamodel": "4.4.0",
-    "@speclynx/apidom-error": "4.4.0",
-    "@speclynx/apidom-json-path": "4.4.0",
-    "@speclynx/apidom-ns-overlay-1": "4.4.0",
-    "@speclynx/apidom-reference": "4.4.0"
+    "@speclynx/apidom-core": "4.6.0",
+    "@speclynx/apidom-datamodel": "4.6.0",
+    "@speclynx/apidom-error": "4.6.0",
+    "@speclynx/apidom-json-path": "4.6.0",
+    "@speclynx/apidom-ns-overlay-1": "4.6.0",
+    "@speclynx/apidom-reference": "4.6.0"
   },
   "files": [
     "src/**/*.mjs",
@@ -70,5 +70,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "5bf5f346de1f59b813bb87d232566827ee9d9798"
+  "gitHead": "c3cec30492f0e186ffdc7b1a761a016dab98b9d4"
 }

package/src/{apply.cjs → apply/realms/apidom.cjs}

@@ -2,17 +2,22 @@
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 exports.__esModule = true;
-exports.applyUpdateAction = exports.applyRemoveAction = exports.applyOverlayApiDOM = exports.applyCopyAction = exports.applyAction = void 0;
+exports.applyUpdateAction = exports.applyRemoveAction = exports.applyOverlay = exports.applyCopyAction = exports.applyAction = void 0;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomCore = require("@speclynx/apidom-core");
 var _apidomJsonPath = require("@speclynx/apidom-json-path");
 var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
-var _OverlayError = _interopRequireDefault(require("./errors/OverlayError.cjs"));
-var _validate = require("./validate.cjs");
+var _OverlayError = _interopRequireDefault(require("../../errors/OverlayError.cjs"));
+var _validate = require("../../validate.cjs");
+var _TraceBuilder = _interopRequireDefault(require("../trace/TraceBuilder.cjs"));
 /**
  * @public
  */
 
+/**
+ * Internal options that carry the tracer instance.
+ */
+
 const defaultApplyOptions = {
   immutable: true,
   strict: false
@@ -157,6 +162,8 @@ const applyRemoveAction = (normalizedPaths, targetElement, options = defaultAppl
  */
 exports.applyRemoveAction = applyRemoveAction;
 const applyAction = (actionElement, targetElement, options = defaultApplyOptions) => {
+  const internalOpts = options;
+  const tracer = internalOpts.tracer ?? (options.trace ? new _TraceBuilder.default(options.trace) : undefined);
   const actionValidation = (0, _validate.validateAction)(actionElement);
   if (!actionValidation.valid) throw actionValidation.error;
   const targetExpression = (0, _apidomCore.toValue)(actionElement.target);
@@ -170,24 +177,53 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
   });
   if (matches.length === 0) {
     if (options.strict) {
-      throw new _OverlayError.default(`Action target "${targetExpression}" matched zero nodes (strict mode)`, {
+      const error = new _OverlayError.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, _apidomCore.toValue)(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.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
@@ -195,14 +231,35 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
       const nodesValidation = (0, _validate.validateTargetNodes)(matches);
       if (!nodesValidation.valid) throw nodesValidation.error;
       const copyExpression = (0, _apidomCore.toValue)(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 _OverlayError.default && !error.action) {
       error.action = actionElement;
     }
+    tracer?.action({
+      target: targetExpression,
+      type: 'noop',
+      matchCount: matches.length,
+      normalizedPaths,
+      success: false,
+      error: error instanceof _OverlayError.default ? error : undefined
+    });
     throw error;
   }
 };
@@ -214,7 +271,7 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
  * @public
  */
 exports.applyAction = applyAction;
-const applyOverlayApiDOM = (overlayElement, targetElement, options = defaultApplyOptions) => {
+const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptions) => {
   const overlay = overlayElement instanceof _apidomDatamodel.ParseResultElement ? overlayElement.api : overlayElement;
   if (!(0, _apidomNsOverlay.isOverlay1Element)(overlay)) {
     throw new _OverlayError.default('First argument must be an Overlay 1.x document');
@@ -231,8 +288,13 @@ const applyOverlayApiDOM = (overlayElement, targetElement, options = defaultAppl
   if (!(0, _apidomDatamodel.isArrayElement)(overlay.actions)) {
     return targetElement;
   }
+  const tracer = options.trace ? new _TraceBuilder.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 _apidomDatamodel.ParseResultElement) {
     targetElement.replaceResult(target);
@@ -240,4 +302,4 @@ const applyOverlayApiDOM = (overlayElement, targetElement, options = defaultAppl
   }
   return target;
 };
-exports.applyOverlayApiDOM = applyOverlayApiDOM;
+exports.applyOverlay = applyOverlay;

package/src/{apply.mjs → apply/realms/apidom.mjs}

@@ -2,11 +2,15 @@ import { isObjectElement, isArrayElement, cloneDeep, ParseResultElement } from '
 import { deepmerge, toValue } from '@speclynx/apidom-core';
 import { evaluate, NormalizedPath } from '@speclynx/apidom-json-path';
 import { isOverlay1Element } from '@speclynx/apidom-ns-overlay-1';
-import OverlayError from "./errors/OverlayError.mjs";
-import { validateAction, validateTargetNodes } from "./validate.mjs";
+import OverlayError from "../../errors/OverlayError.mjs";
+import { validateAction, validateTargetNodes } from "../../validate.mjs";
+import TraceBuilder from "../trace/TraceBuilder.mjs";
 /**
  * @public
  */
+/**
+ * Internal options that carry the tracer instance.
+ */
 const defaultApplyOptions = {
   immutable: true,
   strict: false
@@ -148,6 +152,8 @@ export const applyRemoveAction = (normalizedPaths, targetElement, options = defa
  * @public
  */
 export const applyAction = (actionElement, targetElement, options = defaultApplyOptions) => {
+  const internalOpts = options;
+  const tracer = internalOpts.tracer ?? (options.trace ? new TraceBuilder(options.trace) : undefined);
   const actionValidation = validateAction(actionElement);
   if (!actionValidation.valid) throw actionValidation.error;
   const targetExpression = toValue(actionElement.target);
@@ -161,24 +167,53 @@ export const applyAction = (actionElement, targetElement, options = defaultApply
   });
   if (matches.length === 0) {
     if (options.strict) {
-      throw new OverlayError(`Action target "${targetExpression}" matched zero nodes (strict mode)`, {
+      const error = new OverlayError(`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 && toValue(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 = 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
@@ -186,14 +221,35 @@ export const applyAction = (actionElement, targetElement, options = defaultApply
       const nodesValidation = validateTargetNodes(matches);
       if (!nodesValidation.valid) throw nodesValidation.error;
       const copyExpression = toValue(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 OverlayError && !error.action) {
       error.action = actionElement;
     }
+    tracer?.action({
+      target: targetExpression,
+      type: 'noop',
+      matchCount: matches.length,
+      normalizedPaths,
+      success: false,
+      error: error instanceof OverlayError ? error : undefined
+    });
     throw error;
   }
 };
@@ -204,7 +260,7 @@ export const applyAction = (actionElement, targetElement, options = defaultApply
  *
  * @public
  */
-export const applyOverlayApiDOM = (overlayElement, targetElement, options = defaultApplyOptions) => {
+export const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptions) => {
   const overlay = overlayElement instanceof ParseResultElement ? overlayElement.api : overlayElement;
   if (!isOverlay1Element(overlay)) {
     throw new OverlayError('First argument must be an Overlay 1.x document');
@@ -221,8 +277,13 @@ export const applyOverlayApiDOM = (overlayElement, targetElement, options = defa
   if (!isArrayElement(overlay.actions)) {
     return targetElement;
   }
+  const tracer = options.trace ? new TraceBuilder(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 ParseResultElement) {
     targetElement.replaceResult(target);

package/src/apply/realms/pojo.cjs

@@ -0,0 +1,23 @@
+"use strict";
+
+exports.__esModule = true;
+exports.applyOverlay = exports.applyAction = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
+var _apidom = require("./apidom.cjs");
+/**
+ * Applies a single overlay action (POJO) to a target (POJO).
+ *
+ * @public
+ */
+const applyAction = (action, target, options) => (0, _apidomCore.toValue)((0, _apidom.applyAction)((0, _apidomNsOverlay.refractAction)(action), (0, _apidomDatamodel.refract)(target), options));
+
+/**
+ * Applies an entire overlay document (POJO) to a target (POJO).
+ *
+ * @public
+ */
+exports.applyAction = applyAction;
+const applyOverlay = (overlay, target, options) => (0, _apidomCore.toValue)((0, _apidom.applyOverlay)((0, _apidomNsOverlay.refractOverlay1)(overlay), (0, _apidomDatamodel.refract)(target), options));
+exports.applyOverlay = applyOverlay;

package/src/apply/realms/pojo.mjs

@@ -0,0 +1,17 @@
+import { refract } from '@speclynx/apidom-datamodel';
+import { toValue } from '@speclynx/apidom-core';
+import { refractAction, refractOverlay1 } from '@speclynx/apidom-ns-overlay-1';
+import { applyAction as applyActionApiDOM, applyOverlay as applyOverlayApiDOM } from "./apidom.mjs";
+/**
+ * Applies a single overlay action (POJO) to a target (POJO).
+ *
+ * @public
+ */
+export const applyAction = (action, target, options) => toValue(applyActionApiDOM(refractAction(action), refract(target), options));
+
+/**
+ * Applies an entire overlay document (POJO) to a target (POJO).
+ *
+ * @public
+ */
+export const applyOverlay = (overlay, target, options) => toValue(applyOverlayApiDOM(refractOverlay1(overlay), refract(target), options));

package/src/{apply-uri.cjs → apply/realms/uri.cjs}

@@ -6,8 +6,8 @@ exports.default = void 0;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
 var _apidomReference = require("@speclynx/apidom-reference");
-var _apply = require("./apply.cjs");
-var _OverlayError = _interopRequireDefault(require("./errors/OverlayError.cjs"));
+var _apidom = require("./apidom.cjs");
+var _OverlayError = _interopRequireDefault(require("../../errors/OverlayError.cjs"));
 /**
  * @public
  */
@@ -75,6 +75,6 @@ const applyOverlay = async (overlayURI, targetURI, options = {
   }
 
   // apply overlay actions to the target (returns targetParseResult with result replaced)
-  return (0, _apply.applyOverlayApiDOM)(overlayParseResult, targetParseResult, options);
+  return (0, _apidom.applyOverlay)(overlayParseResult, targetParseResult, options);
 };
 var _default = exports.default = applyOverlay;

package/src/{apply-uri.mjs → apply/realms/uri.mjs}

@@ -1,8 +1,8 @@
 import { isParseResultElement } from '@speclynx/apidom-datamodel';
 import { isOverlay1Element } from '@speclynx/apidom-ns-overlay-1';
 import { parse, mergeOptions } from '@speclynx/apidom-reference';
-import { applyOverlayApiDOM } from "./apply.mjs";
-import OverlayError from "./errors/OverlayError.mjs";
+import { applyOverlay as applyOverlayApiDOM } from "./apidom.mjs";
+import OverlayError from "../../errors/OverlayError.mjs";
 /**
  * @public
  */

package/src/apply/trace/TraceBuilder.cjs

@@ -0,0 +1,45 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+/**
+ * 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';
+    }
+  }
+}
+var _default = exports.default = TraceBuilder;

package/src/apply/trace/TraceBuilder.mjs

@@ -0,0 +1,41 @@
+/**
+ * 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';
+    }
+  }
+}
+export default TraceBuilder;

package/src/apply/trace/index.cjs

@@ -0,0 +1,7 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.TraceBuilder = void 0;
+var _TraceBuilder = _interopRequireDefault(require("./TraceBuilder.cjs"));
+exports.TraceBuilder = _TraceBuilder.default;

package/src/apply/trace/index.mjs

@@ -0,0 +1 @@
+export { default as TraceBuilder } from "./TraceBuilder.mjs";

package/src/apply/trace/types.cjs

@@ -0,0 +1,3 @@
+"use strict";
+
+exports.__esModule = true;

package/src/apply/trace/types.mjs

@@ -0,0 +1 @@
+export {};

package/src/index.cjs

@@ -2,13 +2,16 @@
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 exports.__esModule = true;
-exports.validateAction = exports.default = exports.applyOverlayApiDOM = exports.applyAction = exports.OverlayError = void 0;
-var _apply = require("./apply.cjs");
-exports.applyAction = _apply.applyAction;
-exports.applyOverlayApiDOM = _apply.applyOverlayApiDOM;
+exports.validateAction = exports.applyOverlayPOJO = exports.applyOverlayApiDOM = exports.applyOverlay = exports.applyActionPOJO = exports.applyActionApiDOM = exports.OverlayError = void 0;
+var _apidom = require("./apply/realms/apidom.cjs");
+exports.applyActionApiDOM = _apidom.applyAction;
+exports.applyOverlayApiDOM = _apidom.applyOverlay;
+var _uri = _interopRequireDefault(require("./apply/realms/uri.cjs"));
+exports.applyOverlay = _uri.default;
+var _pojo = require("./apply/realms/pojo.cjs");
+exports.applyActionPOJO = _pojo.applyAction;
+exports.applyOverlayPOJO = _pojo.applyOverlay;
 var _validate = require("./validate.cjs");
 exports.validateAction = _validate.validateAction;
 var _OverlayError = _interopRequireDefault(require("./errors/OverlayError.cjs"));
-exports.OverlayError = _OverlayError.default;
-var _applyUri = _interopRequireDefault(require("./apply-uri.cjs"));
-exports.default = _applyUri.default;
+exports.OverlayError = _OverlayError.default;

package/src/index.mjs

@@ -1,4 +1,5 @@
-export { applyAction, applyOverlayApiDOM } from "./apply.mjs";
+export { applyAction as applyActionApiDOM, applyOverlay as applyOverlayApiDOM } from "./apply/realms/apidom.mjs";
+export { default as applyOverlay } from "./apply/realms/uri.mjs";
+export { applyAction as applyActionPOJO, applyOverlay as applyOverlayPOJO } from "./apply/realms/pojo.mjs";
 export { validateAction } from "./validate.mjs";
-export { default as OverlayError } from "./errors/OverlayError.mjs";
-export { default } from "./apply-uri.mjs";
+export { default as OverlayError } from "./errors/OverlayError.mjs";

package/types/apidom-overlay.d.ts

@@ -7,13 +7,39 @@ import { MemberElement } from '@speclynx/apidom-datamodel';
 import { Overlay1Element } from '@speclynx/apidom-ns-overlay-1';
 import { ParseResultElement } from '@speclynx/apidom-datamodel';
 
+/**
+ * Trace entry for a single overlay action application.
+ *
+ * @public
+ */
+export declare interface ActionTrace {
+    readonly target: string;
+    readonly type: ActionTraceType;
+    readonly matchCount: number;
+    readonly normalizedPaths: string[];
+    readonly success: boolean;
+    readonly error?: OverlayError;
+}
+
+/**
+ * @public
+ */
+export declare type ActionTraceType = 'update' | 'copy' | 'remove' | 'noop';
+
 /**
  * Applies a single overlay action to a target element.
  * Immutable — returns a new element with the action applied.
  *
  * @public
  */
-export declare const applyAction: (actionElement: ActionElement, targetElement: Element_2, options?: ApplyOptions) => Element_2;
+export declare const applyActionApiDOM: (actionElement: ActionElement, targetElement: Element_2, options?: ApplyOptions) => Element_2;
+
+/**
+ * Applies a single overlay action (POJO) to a target (POJO).
+ *
+ * @public
+ */
+export declare const applyActionPOJO: (action: Record<string, unknown>, target: Record<string, unknown>, options?: ApplyOptions) => unknown;
 
 /**
  * @public
@@ -22,6 +48,7 @@ export declare interface ApplyOptions {
     readonly deepmerge?: DeepMergeUserOptions;
     readonly strict?: boolean;
     readonly immutable?: boolean;
+    readonly trace?: OverlayTrace;
 }
 
 /**
@@ -38,8 +65,7 @@ export declare interface ApplyOptions {
  *
  * @public
  */
-declare const applyOverlay: (overlayURI: string, targetURI?: string, options?: ApplyOverlayOptions) => Promise<ParseResultElement>;
-export default applyOverlay;
+export declare const applyOverlay: (overlayURI: string, targetURI?: string, options?: ApplyOverlayOptions) => Promise<ParseResultElement>;
 
 /**
  * Applies an entire overlay document to a target element.
@@ -55,6 +81,13 @@ export declare const applyOverlayApiDOM: <T extends Element_2 | ParseResultEleme
 export declare interface ApplyOverlayOptions extends Partial<ApiDOMReferenceOptions>, ApplyOptions {
 }
 
+/**
+ * Applies an entire overlay document (POJO) to a target (POJO).
+ *
+ * @public
+ */
+export declare const applyOverlayPOJO: (overlay: Record<string, unknown>, target: Record<string, unknown>, options?: ApplyOptions) => unknown;
+
 /**
  * @public
  */
@@ -74,6 +107,19 @@ export declare interface OverlayErrorOptions {
     readonly [key: string]: unknown;
 }
 
+/**
+ * Top-level trace container populated during overlay application.
+ * Pass as `trace` option — it will be mutated in place.
+ *
+ * @public
+ */
+export declare interface OverlayTrace {
+    actions: ActionTrace[];
+    failed: boolean;
+    failedAt: number;
+    message: string;
+}
+
 /**
  * Validates that an ActionElement has the correct shape per the Overlay spec.
  *