@envive-ai/react-hooks 0.1.0

package/src/application/service/domMutationObserver.ts

@@ -0,0 +1,320 @@
+import { DomMutationObserverContinuation } from 'src/application/models/domMutationContinuation';
+import { DomMutationListenerState } from './domMutations/domMutationListenerState';
+import Logger from '../logging/logger';
+import { DomMutationListener } from './domMutations/domMutationListener';
+import { DomObservationStrategy } from '../models/domObservationStrategy';
+
+/**
+ * - When used before page load/render, an unoptimized MutationObserver callback can significantly delay page load time,
+ *   especially on complex pages.
+ * - The callback runs as a microtask and can block further DOM processing, often firing hundreds or even thousands of times
+ *   per second on a complex page. Many libraries don't optimize for this, resulting in clean-looking but potentially slow code.
+ *
+ * Best Practices for MutationObserver Optimization:
+ * - **Profiling:** Use DevTools Profiler to ensure the observer callback uses less than 0.1% of total CPU during page load.
+ * - **Avoid Forced Layouts:** Refrain from triggering synchronous layouts by accessing properties like `offsetTop`.
+ * - **Prefer Native DOM:** Use native DOM methods instead of complex frameworks like jQuery to reduce overhead.
+ * - **Use `attributeFilter`:** When observing attributes, limit the observations to specific attributes, e.g., `attributeFilter: ['attr1', 'attr2']`.
+ * - **Non-recursive Observations:** Observe direct parent elements with `subtree: false` whenever possible. For instance, initially observe `document` recursively, disconnect on success, and reattach a non-recursive observer to the parent element.
+ * - **Direct Element Access:** When waiting for a single element with an `id`, use `getElementById` instead of looping over the `mutations` array.
+ * - **HTMLCollection Checks:** For rare elements (e.g., `<iframe>` or `<object>`), use live HTMLCollections from `getElementsByTagName` or `getElementsByClassName` rather than enumerating mutations, especially with large numbers of mutations.
+ * - **Avoid `querySelectorAll`:** Use `querySelector` first for an initial check; if successful, proceed with `querySelectorAll` only when absolutely necessary. This combo is often faster on average.
+ * - **Legacy Browser Compatibility:**
+ *   - Avoid `Array` methods like `forEach`, `filter`, etc., and ES2015 loops (`for...of`) in pre-2018 Chrome for MutationObserver callbacks,
+ *     as these can be up to 100x slower than traditional `for` loops.
+ *   - Alternatively, use a fast functional library like lodash on older browsers. Chrome 2018+ inlines array methods efficiently.
+ * - **Scheduled Re-checking:** For visual updates, if you can determine elements are offscreen, disconnect the observer and use `setTimeout(fn, 0)` to delay processing until initial parsing/layout is complete. After that, use `requestAnimationFrame` for chunked processing.
+ * - **Debounce Long Processing:** If the callback processing is lengthy, causing unresponsiveness or jank, use debouncing by accumulating mutations in an array and scheduling processing with `setTimeout`, `requestIdleCallback`, or `requestAnimationFrame`.
+ *
+ * Example of Debounce Setup:
+ * ```typescript
+ * const queue: MutationRecord[] = [];
+ * const mo = new MutationObserver(mutations => {
+ *   if (!queue.length) requestAnimationFrame(process);
+ *   queue.push(...mutations);
+ * });
+ * function process() {
+ *   for (const mutations of queue) {
+ *     // Processing logic
+ *   }
+ *   queue.length = 0;
+ * }
+ * ```
+ * Note: `requestAnimationFrame` only triggers when the page is visible.
+ */
+class DomMutationObserver {
+  private static observerVersion = 'v1.24';
+
+  private static individualObservers = false;
+
+  private static deferredExecutionDelay = 500;
+
+  private static startingPollingInterval = 250;
+
+  private static endingPollingInterval = 2000;
+
+  private static useDebounce = true;
+
+  private static listeners: DomMutationListenerState[] = [];
+
+  private static mutationsQueuePerListener: Map<DomMutationListenerState, MutationRecord[]> =
+    new Map();
+
+  private static mutationsQueue: MutationRecord[] = [];
+
+  private static observationStrategy: DomObservationStrategy = DomObservationStrategy.None;
+
+  static addDomMutationListener(listener: DomMutationListener): void {
+    // check if the listener is already added
+    const existingListener = this.listeners.find(
+      (l) => l.getListener().getName() === listener.getName(),
+    );
+    if (existingListener) {
+      // remove
+      Logger.logDebug(
+        `DomMutationObserver::addDomMutationListener removing existing listener ${existingListener.getListener().getName()}`,
+      );
+      this.disconnect(existingListener.getListener());
+      // remove it from the list
+      this.listeners = this.listeners.filter(
+        (l) => l.getListener().getName() !== listener.getName(),
+      );
+    }
+    const listenerState = new DomMutationListenerState(listener);
+    this.listeners.push(listenerState);
+  }
+
+  static invokeListener(l: DomMutationListenerState) {
+    if (l.getCurrentState() === DomMutationObserverContinuation.STOP) {
+      return;
+    }
+
+    const previousState = l.getCurrentState();
+    try {
+      const continuation = l.getListener().onDomChange();
+      l.setCurrentState(continuation);
+      l.incrementCurrentTryCount();
+      if (l.getListener().triesMax() > 0 && l.getCurrentTryCount() >= l.getListener().triesMax()) {
+        l.setCurrentState(DomMutationObserverContinuation.STOP);
+        Logger.logDebug(
+          `DomMutationObserver invokeListener ${l.getListener().getName()} tries exceeded! max: ${l.getListener().triesMax()} current: ${l.getCurrentTryCount()}`,
+        );
+      }
+    } catch (e) {
+      Logger.logError(
+        `DomMutationObserver invokeListener ${l?.getListener()?.getName()} state:${previousState}->${DomMutationObserverContinuation.STOP} error: ${e}`,
+        e,
+      );
+      l.setCurrentState(DomMutationObserverContinuation.STOP); // Un-trapped exceptions halt the observer
+    }
+  }
+
+  static observeOnDomReady(strategy: DomObservationStrategy) {
+    Logger.logDebug(`DomMutationObserver::observeOnDomReady ${document.readyState}`);
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', () => {
+        this.observe(strategy);
+      });
+    } else {
+      this.observe(strategy);
+    }
+  }
+
+  static observe(strategyRequested: DomObservationStrategy) {
+    // We can only use the given polling strategy if no prior strategy has been set
+    // This is to prevent the listeners from being re-attached with a different strategy
+    // and have multiple strategies running at the same time!
+    if (this.observationStrategy === DomObservationStrategy.None) {
+      this.observationStrategy = strategyRequested;
+    }
+
+    const strategy = this.observationStrategy;
+    const listenersNotBound = this.listeners.filter((l) => !l.getIsAttached());
+    if (listenersNotBound.length === 0) {
+      Logger.logDebug(
+        `DomMutationObserver::observe (${this.observerVersion}) no listeners to attach (${listenersNotBound.length}/${this.listeners.length})`,
+      );
+      return;
+    }
+
+    Logger.logInfo(
+      `DomMutationObserver::observe (${this.observerVersion}) listeners to attach strategy=${strategy} (${listenersNotBound.length}/${this.listeners.length})`,
+    );
+
+    switch (strategy) {
+      case DomObservationStrategy.Polling:
+        this.observeByPolling(listenersNotBound);
+        break;
+      default:
+        if (this.useDebounce) {
+          if (this.individualObservers) {
+            this.observeIndividuallyWithDebounce(listenersNotBound);
+          } else {
+            this.observeCollectivelyWithDebounce(listenersNotBound);
+          }
+        } else {
+          if (this.individualObservers) {
+            this.observeIndividually(listenersNotBound);
+          } else {
+            this.observeCollectively(listenersNotBound);
+          }
+        }
+        break;
+    }
+
+    listenersNotBound.forEach((l) => {
+      l.setIsAttached(true);
+    });
+
+    DomMutationObserver.runOnceImmediatelyIfRequired(listenersNotBound);
+  }
+
+  private static runOnceImmediatelyIfRequired(listenersNotBound: DomMutationListenerState[]) {
+    listenersNotBound.forEach((l) => {
+      l.setIsAttached(true);
+      if (l.getListener().runOnceImmediately()) {
+        this.invokeListener(l);
+      }
+    });
+  }
+
+  private static observeIndividuallyWithDebounce(listenersNotBound: DomMutationListenerState[]) {
+    for (let i = 0; i < listenersNotBound.length; i++) {
+      // in some older browsers forEach is less performant
+      const l = listenersNotBound[i];
+      const observer = new MutationObserver((mutations) => {
+        // Avoid blocking the main thread and allow the browser to render, letting the callback run in the next microtask
+        let mutationQueueForListener = this.mutationsQueuePerListener.get(l);
+        if (!mutationQueueForListener) {
+          this.mutationsQueuePerListener.set(l, []);
+          mutationQueueForListener = this.mutationsQueuePerListener.get(l) || [];
+        }
+        // requestAnimationFrame or setTimeout can be used here
+        if (!mutationQueueForListener.length) {
+          setTimeout(() => {
+            this.invokeListener(l);
+            mutationQueueForListener.length = 0;
+          }, this.deferredExecutionDelay);
+        }
+        mutationQueueForListener.push(...mutations);
+      });
+      observer.observe(document.body, { childList: true, subtree: true });
+    }
+  }
+
+  private static observeIndividually(listenersNotBound: DomMutationListenerState[]) {
+    for (let i = 0; i < listenersNotBound.length; i++) {
+      // in some older browsers forEach is less performant
+      const l = listenersNotBound[i];
+      const observer = new MutationObserver(() => {
+        if (l.getCurrentState() === DomMutationObserverContinuation.CONTINUE) {
+          l.setCurrentState(DomMutationObserverContinuation.EXECUTING);
+          // Avoid blocking the main thread and allow the browser to render, letting the callback run in the next microtask
+          setTimeout(() => {
+            this.invokeListener(l);
+          }, this.deferredExecutionDelay);
+        }
+      });
+      observer.observe(document.body, { childList: true, subtree: true });
+    }
+  }
+
+  private static observeCollectivelyWithDebounce(listenersNotBound: DomMutationListenerState[]) {
+    const observer = new MutationObserver((mutations) => {
+      if (!this.mutationsQueue.length) {
+        setTimeout(() => {
+          for (let i = 0; i < listenersNotBound.length; i++) {
+            // in some older browsers forEach is less performant
+            const l = listenersNotBound[i];
+            if (l.getCurrentState() === DomMutationObserverContinuation.CONTINUE) {
+              l.setCurrentState(DomMutationObserverContinuation.EXECUTING);
+              this.invokeListener(l);
+            }
+          }
+          this.mutationsQueue.length = 0;
+        }, this.deferredExecutionDelay);
+      }
+      this.mutationsQueue.push(...mutations);
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+  }
+
+  private static observeCollectively(listenersNotBound: DomMutationListenerState[]) {
+    const observer = new MutationObserver(() => {
+      // Avoid blocking the main thread and allow the browser to render, letting the callback run in the next microtask
+      setTimeout(() => {
+        for (let i = 0; i < listenersNotBound.length; i++) {
+          // in some older browsers forEach is less performant
+          const l = listenersNotBound[i];
+          if (l.getCurrentState() === DomMutationObserverContinuation.CONTINUE) {
+            l.setCurrentState(DomMutationObserverContinuation.EXECUTING);
+            this.invokeListener(l);
+          }
+        }
+      }, this.deferredExecutionDelay);
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+  }
+
+  private static poll(
+    fn: () => Promise<void>,
+    startingInterval: number,
+    endingInterval: number,
+  ): void {
+    let intervalScalingStep = 1;
+    const executePoll = async () => {
+      try {
+        await fn();
+      } catch (error) {
+        Logger.logWarn('Polling error:', error);
+      } finally {
+        let interval = startingInterval * intervalScalingStep;
+        // take the min of the interval and the ending interval
+        interval = Math.min(interval, endingInterval);
+        if (interval < endingInterval) {
+          intervalScalingStep++;
+        }
+        setTimeout(executePoll, interval);
+      }
+    };
+    executePoll().then((_) => Logger.logDebug('Polling started'));
+  }
+
+  private static observeByPolling(listenersNotBound: DomMutationListenerState[]) {
+    this.poll(
+      async () => {
+        for (let i = 0; i < listenersNotBound.length; i++) {
+          // in some older browsers forEach is less performant
+          const l = listenersNotBound[i];
+          if (l.getCurrentState() === DomMutationObserverContinuation.CONTINUE) {
+            l.setCurrentState(DomMutationObserverContinuation.EXECUTING);
+            this.invokeListener(l);
+          }
+        }
+      },
+      this.startingPollingInterval,
+      this.endingPollingInterval,
+    );
+  }
+
+  static disconnect(listener: DomMutationListener) {
+    const listenerState = this.listeners.find((l) => l.getListener() === listener);
+
+    if (!listenerState) {
+      Logger.logDebug(`DomMutationObserver::disconnect listener not found`, undefined);
+    } else {
+      Logger.logDebug(`DomMutationObserver::disconnect listener found`, undefined);
+      listenerState.setCurrentState(DomMutationObserverContinuation.STOP);
+    }
+  }
+
+  static setStartingPollingInterval(interval: number) {
+    this.startingPollingInterval = interval;
+  }
+
+  static setEndingPollingInterval(interval: number) {
+    this.endingPollingInterval = interval;
+  }
+}
+
+export { DomMutationObserver };

package/src/application/service/domMutations/GridInsertionService.ts

@@ -0,0 +1,123 @@
+import Logger from 'src/application/logging/logger';
+import {
+  DOMInsertionService,
+  DOMInsertionType,
+} from 'src/application/service/domMutations/domInsertionService';
+
+enum GridInsertionType {
+  FIXED_1 = 'fixed-1',
+  FIXED_2 = 'fixed-2',
+  FIXED_3 = 'fixed-3',
+  FIXED_4 = 'fixed-4',
+  FIXED_5 = 'fixed-5',
+  FIXED_6 = 'fixed-6',
+  FIXED_7 = 'fixed-7',
+  FIXED_8 = 'fixed-8',
+  FIXED_9 = 'fixed-9',
+  FIXED_12 = 'fixed-12',
+  FIXED_13 = 'fixed-13',
+  ROW_1 = 'row-1',
+  ROW_2 = 'row-2',
+  ROW_3 = 'row-3',
+  ROW_4 = 'row-4',
+}
+
+class GridInsertionService {
+  static insert(
+    gridInsertionType: GridInsertionType,
+    targetElement: Element,
+    nodeToInsert: HTMLElement,
+    insertionType: DOMInsertionType,
+  ) {
+    switch (gridInsertionType) {
+      case GridInsertionType.FIXED_1:
+        GridInsertionService.fixedInsert(targetElement, 1, nodeToInsert, insertionType);
+        break;
+      case GridInsertionType.FIXED_2:
+        GridInsertionService.fixedInsert(targetElement, 2, nodeToInsert, insertionType);
+        break;
+      case GridInsertionType.FIXED_3:
+        GridInsertionService.fixedInsert(targetElement, 3, nodeToInsert, insertionType);
+        break;
+      case GridInsertionType.FIXED_4:
+        GridInsertionService.fixedInsert(targetElement, 4, nodeToInsert, insertionType);
+        break;
+      case GridInsertionType.FIXED_5:
+        GridInsertionService.fixedInsert(targetElement, 5, nodeToInsert, insertionType);
+        break;
+      case GridInsertionType.FIXED_6:
+        GridInsertionService.fixedInsert(targetElement, 6, nodeToInsert, insertionType);
+        break;
+      case GridInsertionType.FIXED_7:
+        GridInsertionService.fixedInsert(targetElement, 7, nodeToInsert, insertionType);
+        break;
+      case GridInsertionType.FIXED_8:
+        GridInsertionService.fixedInsert(targetElement, 8, nodeToInsert, insertionType);
+        break;
+      case GridInsertionType.FIXED_9:
+        GridInsertionService.fixedInsert(targetElement, 9, nodeToInsert, insertionType);
+        break;
+      case GridInsertionType.FIXED_12:
+        GridInsertionService.fixedInsert(targetElement, 12, nodeToInsert, insertionType);
+        break;
+      case GridInsertionType.FIXED_13:
+        GridInsertionService.fixedInsert(targetElement, 13, nodeToInsert, insertionType);
+        break;
+      case GridInsertionType.ROW_1:
+        GridInsertionService.rowInsert(targetElement, nodeToInsert, 1);
+        break;
+      case GridInsertionType.ROW_2:
+        GridInsertionService.rowInsert(targetElement, nodeToInsert, 2);
+        break;
+      case GridInsertionType.ROW_3:
+        GridInsertionService.rowInsert(targetElement, nodeToInsert, 3);
+        break;
+      case GridInsertionType.ROW_4:
+        GridInsertionService.rowInsert(targetElement, nodeToInsert, 4);
+        break;
+      default:
+        Logger.logError(
+          `Skipping grid insertion: invalid grid insertion type "${gridInsertionType}". \
+          Valid types are: ${Object.keys(GridInsertionType).join(', ')}`,
+          undefined,
+        );
+    }
+  }
+
+  /**
+   * Inserts a node into a grid row at the specified index starting from index 1. If the index
+   * is higher than the total number of rows, the node will be inserted at the end of the grid.
+   * This function does not make any assumptions about the column span of the inserted node - that
+   * should be handled by the orgConfig instead.
+   *
+   * @param targetElement - The target element to insert the node into.
+   * @param nodeToInsert - The node to insert into the grid.
+   * @param rowIndex - The index of the row to insert the node into.
+   */
+  static rowInsert(targetElement: Element, nodeToInsert: HTMLElement, rowIndex: number) {
+    const node = nodeToInsert;
+    node.style.gridRow = rowIndex.toString();
+    node.style.gridColumn = '1/-1';
+    DOMInsertionService.insert(targetElement, node, DOMInsertionType.APPEND_CHILD);
+  }
+
+  static fixedInsert(
+    targetElement: Element,
+    insertionGridIndex: number,
+    nodeToInsert: HTMLElement,
+    insertionType: DOMInsertionType,
+  ) {
+    const childCount = targetElement.children.length;
+    const actualIndex = Math.min(insertionGridIndex - 1, childCount - 1);
+    const targetChild = targetElement.children[actualIndex];
+
+    if (!targetChild) {
+      Logger.logWarn('Skipping grid insertion: grid has no elements', undefined);
+      return;
+    }
+
+    DOMInsertionService.insert(targetChild, nodeToInsert, insertionType);
+  }
+}
+
+export { GridInsertionType, GridInsertionService };

package/src/application/service/domMutations/dataLayer/dataLayerEventsListener.ts

@@ -0,0 +1,99 @@
+import { OrgAnalyticsGoogleAnalyticsConfig } from 'src/application/models/api/orgAnalyticsConfig';
+import { DomMutationListener } from '../domMutationListener';
+import { DomMutationObserverContinuation } from '../../../models/domMutationContinuation';
+import Logger from '../../../logging/logger';
+import { WindowDataLayerService } from '../../windowDataLayerService';
+import { StringUtils } from '../../../utils/stringUtils';
+
+class DataLayerEventsListener implements DomMutationListener {
+  private readonly onDataLayerPush: (event: object) => void;
+
+  private readonly eventsToIntercept: string[] = [];
+
+  private readonly windowDataLayerService: WindowDataLayerService;
+
+  constructor(
+    onDataLayerPush: (event: object) => void,
+    eventsToIntercept: string[],
+    gaConfig: OrgAnalyticsGoogleAnalyticsConfig,
+  ) {
+    Logger.logDebug('[spiffy-ai] DataLayerEventsListener created', undefined);
+    this.onDataLayerPush = onDataLayerPush;
+    this.eventsToIntercept = eventsToIntercept;
+    this.windowDataLayerService = WindowDataLayerService.getSingletonInstanceOf(gaConfig);
+  }
+
+  runOnceImmediately(): boolean {
+    return true;
+  }
+
+  triesMax(): number {
+    return 10;
+  }
+
+  onDomChange(): DomMutationObserverContinuation {
+    if (!WindowDataLayerService.isDataLayerAvailable()) {
+      return DomMutationObserverContinuation.CONTINUE;
+    }
+
+    Logger.logDebug(`[spiffy-ai] ${this.getName()} [subscribing] to DataLayer push events`);
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const This = this;
+
+    function dataLayerPushProxyMethod() {
+      try {
+        // flatten the event if it is an array
+        const allArguments = WindowDataLayerService.tryFlattenArguments(arguments);
+        let event = allArguments[0];
+        if (!event) {
+          Logger.logDebug(
+            `[spiffy-ai] ${This.getName()} dataLayer event undefined. all_arguments=`,
+            allArguments,
+          );
+          return;
+        }
+
+        if (event?.length > 1) {
+          if (event[0] === 'event') {
+            const eventName = StringUtils.trimToNull(event[1]) || '';
+            if (This.eventsToIntercept.includes(eventName)) {
+              Logger.logDebug(
+                `[spiffy-ai] ${This.getName()} [datalayer-event] (1) event_name=${eventName} events_to_intercept=${This.eventsToIntercept} all_arguments=`,
+                allArguments,
+              );
+              event[2]['event'] = eventName;
+              This.onDataLayerPush(event[2]);
+              return;
+            }
+          }
+        }
+
+        let eventName = StringUtils.trimToNull(event['event']) || '';
+        if (!eventName && event['0']) {
+          // Handle this case: [Arguments] { '0': { event: 'event1' } }
+          eventName = StringUtils.trimToNull(event['0']['event']) || '';
+          event = event['0'];
+        }
+
+        if (This.eventsToIntercept.includes(eventName)) {
+          Logger.logDebug(
+            `[spiffy-ai] ${This.getName()} [datalayer-event] (2) event_name=${eventName} events_to_intercept=${This.eventsToIntercept} all_arguments=`,
+            arguments,
+          );
+          This.onDataLayerPush(event);
+        }
+      } catch (e) {
+        Logger.logError(`[spiffy-ai] ${This.getName()} Error in dataLayer.push: `, e);
+      }
+    }
+
+    this.windowDataLayerService.wrapWithProxyMethod('push', dataLayerPushProxyMethod);
+    return DomMutationObserverContinuation.STOP;
+  }
+
+  getName(): string {
+    return 'DataLayerEventsListener';
+  }
+}
+
+export { DataLayerEventsListener };

package/src/application/service/domMutations/domInsertionService.ts

@@ -0,0 +1,90 @@
+enum DOMInsertionType {
+  AFTER = 'after',
+  BEFORE = 'before',
+  ADJACENT_AFTER_BEGIN = 'adjacent-after-begin',
+  ADJACENT_BEFORE_BEGIN = 'adjacent-before-begin',
+  ADJACENT_AFTER_END = 'adjacent-after-end',
+  ADJACENT_BEFORE_END = 'adjacent-before-end',
+  APPEND_CHILD = 'append-child',
+  NONE = 'none',
+}
+
+export const DOMInsertionTypeToInsertPosition = (type: DOMInsertionType): InsertPosition => {
+  switch (type) {
+    case DOMInsertionType.ADJACENT_AFTER_BEGIN:
+      return 'afterbegin';
+    case DOMInsertionType.BEFORE:
+    case DOMInsertionType.ADJACENT_BEFORE_BEGIN:
+      return 'beforebegin';
+    case DOMInsertionType.ADJACENT_BEFORE_END:
+      return 'beforeend';
+    case DOMInsertionType.AFTER:
+    case DOMInsertionType.ADJACENT_AFTER_END:
+    default:
+      return 'afterend';
+  }
+};
+
+class DOMInsertionService {
+  static insert(
+    targetElement: Element,
+    nodeToInsert: HTMLElement,
+    insertionType: DOMInsertionType,
+  ) {
+    switch (insertionType) {
+      case DOMInsertionType.AFTER:
+        targetElement.after(nodeToInsert);
+        break;
+      case DOMInsertionType.BEFORE:
+        targetElement.before(nodeToInsert);
+        break;
+      case DOMInsertionType.ADJACENT_AFTER_BEGIN:
+        targetElement.insertAdjacentElement('afterbegin', nodeToInsert);
+        break;
+      case DOMInsertionType.ADJACENT_BEFORE_BEGIN:
+        targetElement.insertAdjacentElement('beforebegin', nodeToInsert);
+        break;
+      case DOMInsertionType.ADJACENT_AFTER_END:
+        targetElement.insertAdjacentElement('afterend', nodeToInsert);
+        break;
+      case DOMInsertionType.ADJACENT_BEFORE_END:
+        targetElement.insertAdjacentElement('beforeend', nodeToInsert);
+        break;
+      case DOMInsertionType.APPEND_CHILD:
+        targetElement.appendChild(nodeToInsert);
+        break;
+      case DOMInsertionType.NONE:
+        // No insertion
+        break;
+      // This should only happen if a new insertion type is added and not handled in the switch statement
+      default:
+        throw new Error(`Invalid insertion type: ${insertionType}`);
+    }
+  }
+
+  /**
+   * Get the insertion point for the widget.
+   * @param selector - The selector to find the insertion point.
+   * @param selectionIndex - For multiple matches, pick the nth element. Can be negative to insert from the end (-1 is the last element). (optional, default first)
+   * @returns The insertion point element or null if not found.
+   */
+  static getInsertionPoint(selector: string, selectionIndex?: number): Element | null {
+    let elem: Element | null = null;
+    if (selectionIndex === undefined || selectionIndex === 0) {
+      elem = document.querySelector(selector);
+      if (elem?.parentElement) {
+        return elem;
+      }
+    } else {
+      const elems = document.querySelectorAll(selector);
+      const minLength = selectionIndex > 0 ? selectionIndex + 1 : -selectionIndex;
+      const index = selectionIndex > 0 ? selectionIndex : elems.length + selectionIndex;
+      if (elems.length >= minLength && elems[index].parentElement) {
+        return elems[index];
+      }
+    }
+    return null;
+  }
+}
+
+export { DOMInsertionService, DOMInsertionType };

package/src/application/service/domMutations/domMutationListener.ts

@@ -0,0 +1,15 @@
+import { DomMutationObserverContinuation } from '../../models/domMutationContinuation';
+
+interface DomMutationListener {
+  getName(): string;
+
+  runOnceImmediately(): boolean;
+
+  disconnect?(): void;
+
+  triesMax(): number;
+
+  onDomChange(): DomMutationObserverContinuation;
+}
+
+export type { DomMutationListener };