feat(content): introduce marker-based anchor handling and cleanup resolvers

- Added `ContentScriptMarkerContract` for marker management.
- Replaced `contentScriptAnchorAttribute` with marker attribute logic.
- Refactored `Node` and introduced `MarkerNode` wrapping for marker operations.
- Abstracted marker logic into `AbstractMarker` and `AttributeMarker`.
- Updated related definitions and resolved configurations for marker integration.

Author: Addon Stack

src/entry/content/core/AbstractMarker.ts

@@ -0,0 +1,77 @@
+import {ContentScriptAnchor, ContentScriptMarkerContract, ContentScriptMarkerValue} from "@typing/content";
+
+export default abstract class implements ContentScriptMarkerContract {
+    public abstract marked(): Element[];
+
+    public abstract mark(element: Element, value: ContentScriptMarkerValue): boolean;
+
+    public abstract unmark(element: Element): boolean;
+
+    public abstract isMarked(element: Element): boolean;
+
+    public abstract value(element: Element): ContentScriptMarkerValue | undefined;
+
+    protected constructor(protected anchor: ContentScriptAnchor) {}
+
+    public for(anchor: ContentScriptAnchor): ContentScriptMarkerContract {
+        this.anchor = anchor;
+
+        return this;
+    }
+
+    public pending(): Element[] {
+        const elements: Element[] = [];
+
+        let resolved = this.anchor;
+
+        if (resolved instanceof Element) {
+            if (!this.isMarked(resolved)) {
+                elements.push(resolved);
+            }
+        } else if (typeof resolved === "string") {
+            if (resolved.startsWith("/")) {
+                elements.push(...this.queryXpath(resolved));
+            } else {
+                elements.push(...this.querySelector(resolved));
+            }
+        }
+
+        return elements;
+    }
+
+    public mount(element: Element): boolean {
+        return this.mark(element, ContentScriptMarkerValue.Mounded);
+    }
+
+    public unmount(element: Element): boolean {
+        return this.mark(element, ContentScriptMarkerValue.Unmounted);
+    }
+
+    public reset(): ContentScriptMarkerContract {
+        for (const element of this.marked()) {
+            this.unmark(element);
+        }
+
+        return this;
+    }
+
+    protected querySelector(selector: string): Element[] {
+        return Array.from(document.querySelectorAll(selector));
+    }
+
+    protected queryXpath(xpath: string): Element[] {
+        const elements: Element[] = [];
+
+        const result = document.evaluate(xpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+
+        for (let i = 0; i < result.snapshotLength; i++) {
+            elements.push(result.snapshotItem(i) as Element);
+        }
+
+        return elements;
+    }
+
+    protected isValidValue(value: any): value is ContentScriptMarkerValue {
+        return [ContentScriptMarkerValue.Unmounted, ContentScriptMarkerValue.Mounded].includes(value);
+    }
+}

src/entry/content/core/AttributeMarker.ts

@@ -0,0 +1,61 @@
+import {customAlphabet} from "nanoid";
+
+import AbstractMarker from "./AbstractMarker";
+
+import {ContentScriptAnchor, ContentScriptMarkerValue} from "@typing/content";
+
+export default class extends AbstractMarker {
+    protected readonly attr: string;
+
+    constructor(anchor?: ContentScriptAnchor) {
+        super(anchor);
+
+        const generateId = customAlphabet("abcdefghijklmnopqrstuvwxyz", 7);
+
+        this.attr = `data-${generateId()}`;
+    }
+
+    public isMarked(element: Element): boolean {
+        return element.hasAttribute(this.attr);
+    }
+
+    public mark(element: Element, value: ContentScriptMarkerValue): boolean {
+        element.setAttribute(this.attr, value);
+
+        return true;
+    }
+
+    public marked(): Element[] {
+        const anchor = this.anchor;
+
+        if (anchor instanceof Element) {
+            if (this.isMarked(anchor)) {
+                return [anchor];
+            }
+
+            return [];
+        }
+
+        return Array.from(document.querySelectorAll(`${anchor}[${this.attr}]`));
+    }
+
+    public unmark(element: Element): boolean {
+        element.removeAttribute(this.attr);
+
+        return true;
+    }
+
+    public value(element: Element): ContentScriptMarkerValue | undefined {
+        const value = element.getAttribute(this.attr);
+
+        return this.isValidValue(value) ? value : undefined;
+    }
+
+    protected querySelector(selector: string): Element[] {
+        return super.querySelector(`${selector}:not([${this.attr}])`);
+    }
+
+    protected queryXpath(xpath: string): Element[] {
+        return super.queryXpath(`(${xpath})[not(@${this.attr})]`);
+    }
+}

src/entry/content/core/Builder.ts

@@ -14,20 +14,26 @@ import {
 
 import ManagedContext from "./ManagedContext";
 import EventEmitter from "./EventEmitter";
+import AttributeMarker from "./AttributeMarker";
 
 import {
     ContentScriptAnchor,
     ContentScriptAnchorGetter,
-    ContentScriptAnchorResolver,
     ContentScriptBuilder,
     ContentScriptContainerCreator,
     ContentScriptContainerFactory,
     ContentScriptContainerOptions,
     ContentScriptContainerTag,
     ContentScriptContext,
     ContentScriptDefinition,
+    ContentScriptMarker,
+    ContentScriptMarkerContract,
+    ContentScriptMarkerGetter,
+    ContentScriptMarkerResolver,
+    ContentScriptMarkerType,
     ContentScriptMountFunction,
     ContentScriptNode,
+    ContentScriptOptions,
     ContentScriptRenderHandler,
     ContentScriptRenderValue,
     ContentScriptResolvedDefinition,
@@ -45,6 +51,8 @@ export default abstract class extends Builder implements ContentScriptBuilder {
 
     protected readonly context = new ManagedContext(this.emitter);
 
+    protected marker: ContentScriptMarkerContract = new AttributeMarker();
+
     protected unwatch?: () => void;
 
     protected abstract createNode(anchor: Element): Promise<ContentScriptNode>;
@@ -56,6 +64,7 @@ export default abstract class extends Builder implements ContentScriptBuilder {
 
         this.definition = {
             ...definition,
+            marker: this.resolveMarker(definition.marker),
             anchor: this.resolveAnchor(definition.anchor),
             mount: this.resolveMount(definition.mount),
             container: this.resolveContainer(definition.container),
@@ -64,7 +73,25 @@ export default abstract class extends Builder implements ContentScriptBuilder {
         };
     }
 
-    protected resolveAnchor(anchor?: ContentScriptAnchor | ContentScriptAnchorGetter): ContentScriptAnchorResolver {
+    protected resolveMarker(marker: ContentScriptMarkerType | ContentScriptMarkerGetter): ContentScriptMarkerResolver {
+        return async (options: ContentScriptOptions) => {
+            if (typeof marker === "function") {
+                marker = await marker(options);
+            }
+
+            if (!marker) {
+                marker = ContentScriptMarker.Attribute;
+            }
+
+            if (typeof marker === "string") {
+                return new AttributeMarker();
+            }
+
+            return marker;
+        };
+    }
+
+    protected resolveAnchor(anchor?: ContentScriptAnchor | ContentScriptAnchorGetter): ContentScriptAnchorGetter {
         return contentScriptAnchorResolver(anchor);
     }
 
@@ -105,7 +132,9 @@ export default abstract class extends Builder implements ContentScriptBuilder {
     public async build(): Promise<void> {
         await this.destroy();
 
-        const {render, main, anchor, container, watch, mount, ...options} = this.definition;
+        const {render, main, anchor, marker, container, watch, mount, ...options} = this.definition;
+
+        this.marker = await marker(options);
 
         await main?.(this.context, options);
 
@@ -123,13 +152,17 @@ export default abstract class extends Builder implements ContentScriptBuilder {
     public async destroy(): Promise<void> {
         this.unwatch?.();
         this.unwatch = undefined;
+
+        this.marker.reset();
     }
 
     protected async processing(): Promise<void> {
         await this.lock.acquireAsync();
 
         try {
-            const anchors = await this.definition.anchor();
+            const anchor = await this.definition.anchor();
+
+            const anchors = this.marker.for(anchor).pending();
 
             await Promise.allSettled(anchors.map(this.processAnchor.bind(this)));
         } finally {

src/entry/content/core/MarkerNode.ts

@@ -0,0 +1,28 @@
+import {ContentScriptMarkerContract, ContentScriptNode} from "@typing/content";
+
+export default class implements ContentScriptNode {
+    constructor(
+        protected readonly node: ContentScriptNode,
+        protected readonly marker: ContentScriptMarkerContract
+    ) {}
+
+    public get anchor(): Element {
+        return this.node.anchor;
+    }
+
+    public get container(): Element | undefined {
+        return this.node.container;
+    }
+
+    public mount(): boolean | undefined | void {
+        this.marker.mount(this.anchor);
+
+        return this.node.mount();
+    }
+
+    public unmount(): boolean | undefined | void {
+        this.marker.unmount(this.anchor);
+
+        return this.node.unmount();
+    }
+}

src/entry/content/core/MountBuilder.ts

@@ -1,6 +1,7 @@
 import Builder from "./Builder";
 import Node from "./Node";
 import MountNode from "./MountNode";
+import MarkerNode from "./MarkerNode";
 
 import {ContentScriptNode, ContentScriptProps, ContentScriptRenderValue} from "@typing/content";
 
@@ -42,7 +43,7 @@ export default abstract class extends Builder {
             container = (await this.definition.container(this.getProps(anchor))) as Element | undefined;
         }
 
-        return new MountNode(new Node(anchor, container), this.definition.mount);
+        return new MountNode(new MarkerNode(new Node(anchor, container), this.marker), this.definition.mount);
     }
 
     protected cleanupNode(anchor: Element): void {

src/entry/content/core/Node.ts

@@ -1,17 +1,8 @@
-import {contentScriptAnchorAttribute} from "./resolvers";
-
 import {ContentScriptNode} from "@typing/content";
 
-enum NodeMark {
-    Mounded = "1",
-    Unmounted = "0",
-}
-
 export default class implements ContentScriptNode {
     private readonly _container?: Element;
 
-    private readonly attr = contentScriptAnchorAttribute;
-
     constructor(
         public readonly anchor: Element,
         public container?: Element
@@ -22,8 +13,6 @@ export default class implements ContentScriptNode {
     }
 
     public mount(): boolean {
-        this.mark();
-
         if (!this.container && this._container) {
             this.container = this._container.cloneNode(false) as Element;
 
@@ -34,8 +23,6 @@ export default class implements ContentScriptNode {
     }
 
     public unmount(): boolean {
-        this.unmark();
-
         if (this.container) {
             this.container.remove();
             this.container = undefined;
@@ -45,18 +32,4 @@ export default class implements ContentScriptNode {
 
         return false;
     }
-
-    protected mark(): this {
-        let id = this.anchor.getAttribute(this.attr);
-
-        if (typeof id !== "string" || id.length === 0 || id === NodeMark.Unmounted) {
-            this.anchor.setAttribute(this.attr, NodeMark.Mounded);
-        }
-
-        return this;
-    }
-
-    protected unmark(): void {
-        this.anchor.setAttribute(this.attr, NodeMark.Unmounted);
-    }
 }