@preference-sl/pref-viewer 2.16.0 → 2.16.2-beta.0

package/src/panzoom-controller.js

@@ -27,6 +27,7 @@ import Panzoom from "@panzoom/panzoom/dist/panzoom.es.js";
  *  - wrapper (HTMLElement): The DOM element to apply pan/zoom interactions to.
  *  - options (object): Configuration options for Panzoom (e.g., minScale, maxScale, step).
  *  - changedCallback (function): Optional callback invoked when the pan/zoom state changes.
+ *  - clickCallback (function): Optional callback invoked with the original event after a gesture is classified as a click.
  *
  * Public Methods:
  *  - enable(): Enables the Panzoom instance and initializes it if not already enabled.
@@ -40,7 +41,7 @@ import Panzoom from "@panzoom/panzoom/dist/panzoom.es.js";
  *
  * Getters:
  *  - panzoom: Returns the current Panzoom instance or null if not initialized.
- *  - state: Returns the current pan/zoom state (moved, scaled, maximized, minimized).
+ *  - state: Returns the current pan/zoom transform and semantic state.
  *
  * Private Methods:
  *  - #bindHandlers(): Pre-binds reusable event handlers to preserve stable references.
@@ -81,6 +82,9 @@ export default class PanzoomController {
         totalCounter: 0,
     };
     #state = {
+        x: 0,
+        y: 0,
+        scale: 1,
         moved: false,
         scaled: false,
         maximized: false,
@@ -89,6 +93,7 @@ export default class PanzoomController {
     #wrapper = null;
     
     #changedCallback = null;
+    #clickCallback = null;
     #handlers = {
         panzoomStart: null,
         panzoomChange: null,
@@ -100,10 +105,11 @@ export default class PanzoomController {
         wheel: null,
     };
     
-    constructor(wrapper = null, options = {}, changedCallback = null) {
+    constructor(wrapper = null, options = {}, changedCallback = null, clickCallback = null) {
         this.#wrapper = wrapper;
         Object.assign(this.#options, options);
         this.#changedCallback = changedCallback;
+        this.#clickCallback = clickCallback;
         this.#bindHandlers();
     }
 
@@ -145,7 +151,7 @@ export default class PanzoomController {
      * @returns {{x:number,y:number}|null} Point or null if coordinates not present.
      */
     #getPointFromEvent(e) {
-        if (e.clientX && e.clientY) {
+        if (Number.isFinite(e?.clientX) && Number.isFinite(e?.clientY)) {
             return {
                 x: e.clientX,
                 y: e.clientY,
@@ -155,6 +161,13 @@ export default class PanzoomController {
         }
     }
 
+    /** Reset transient pointer data after a completed or interrupted gesture. */
+    #resetPointerEvents() {
+        this.#pointerEvents.lastPointerDownPosition = null;
+        this.#pointerEvents.partialCounter = 0;
+        this.#pointerEvents.totalCounter = 0;
+    }
+
     /**
      * Update internal pan/zoom state and emit a custom event with current values.
      * If a changed callback is defined, it is invoked with the updated state object.
@@ -164,6 +177,9 @@ export default class PanzoomController {
      */
     #checkPanzoomState(transform) {
         this.#state = {
+            x: transform.x,
+            y: transform.y,
+            scale: transform.scale,
             moved: transform.x !== 0 || transform.y !== 0,
             scaled: transform.scale !== 1,
             maximized: transform.scale === this.#options.maxScale,
@@ -252,7 +268,6 @@ export default class PanzoomController {
      * @private
      * @param {CustomEvent} e - Panzoom custom event with originalEvent property.
      * @returns {void}
-     * @todo Implement selection/click logic.
      */
     #onPanzoomEnd(e) {
         this.#pointerEvents.partialCounter--;
@@ -260,21 +275,21 @@ export default class PanzoomController {
         if (this.#pointerEvents.partialCounter > 0) {
             return;
         } else if (this.#pointerEvents.totalCounter > 1) {
-            this.#pointerEvents.partialCounter = 0;
-            this.#pointerEvents.totalCounter = 0;
+            this.#resetPointerEvents();
             return;
         }
 
-        this.#pointerEvents.partialCounter = 0;
-        this.#pointerEvents.totalCounter = 0;
-
-        const originalEvent = e.detail.originalEvent;
+        const originalEvent = e?.detail?.originalEvent;
+        if (!originalEvent) {
+            this.#resetPointerEvents();
+            return;
+        }
         const point = this.#getPointFromEvent(originalEvent);
         const distance = this.#getDistanceBetweenPoints(point, this.#pointerEvents.lastPointerDownPosition);
 
         let proceedToPick = true;
 
-        if (!point || distance > this.#interactionOptions.clickThreshold) {
+        if (!point || !this.#pointerEvents.lastPointerDownPosition || distance > this.#interactionOptions.clickThreshold) {
             proceedToPick = false;
         }
 
@@ -282,7 +297,7 @@ export default class PanzoomController {
             proceedToPick = false;
         }
 
-        this.#pointerEvents.lastPointerDownPosition = null;
+        this.#resetPointerEvents();
 
         if (!proceedToPick) {
             return;
@@ -292,7 +307,9 @@ export default class PanzoomController {
             return;
         }
 
-        // Selection/click logic can be implemented here.
+        if (typeof this.#clickCallback === "function") {
+            this.#clickCallback(originalEvent);
+        }
     }
 
     /**
@@ -302,7 +319,7 @@ export default class PanzoomController {
      * @returns {void}
      */
     #onPanzoomStart(e) {
-        const originalEvent = e.detail.originalEvent;
+        const originalEvent = e?.detail?.originalEvent;
         this.#pointerEvents.partialCounter++;
         this.#pointerEvents.totalCounter++;
         this.#pointerEvents.lastPointerDownPosition = this.#getPointFromEvent(originalEvent);
@@ -421,13 +438,15 @@ export default class PanzoomController {
         if (!this.#wrapper) {
             return;
         }
+        this.#disableMouseWheelZoom();
+        this.#resetPointerEvents();
         this.#wrapper.parentElement.removeAttribute("tabindex");
         this.#wrapper.removeEventListener("panzoomstart", this.#handlers.panzoomStart);
         this.#wrapper.removeEventListener("panzoomchange", this.#handlers.panzoomChange);
         this.#wrapper.removeEventListener("panzoomend", this.#handlers.panzoomEnd);
         this.#wrapper.parentElement.removeEventListener("keyup", this.#handlers.keyUp);
-        this.#wrapper.parentElement.removeEventListener("focus", this.#handlers.focus);
-        this.#wrapper.parentElement.removeEventListener("blur", this.#handlers.blur);
+        this.#wrapper.parentElement.removeEventListener("focus", this.#handlers.focus, true);
+        this.#wrapper.parentElement.removeEventListener("blur", this.#handlers.blur, true);
         this.#wrapper.parentElement.removeEventListener("contextmenu", this.#handlers.contextMenu);
     }
 
@@ -523,7 +542,7 @@ export default class PanzoomController {
     /**
      * Returns the current pan/zoom state.
      * @public
-     * @returns {object} The state object: { moved, scaled, maximized, minimized }.
+     * @returns {object} The state object: { x, y, scale, moved, scaled, maximized, minimized }.
      */
     get state() {
         return this.#state;

package/src/pref-viewer-2d.js

@@ -19,20 +19,24 @@ import { PrefViewer2DStyles } from "./styles.js";
  *  - visible: "true" | "false" (controls visibility and event subscription)
  *
  * Public methods
- *  - async load(svgConfig) : Promise<boolean> — accept SVG input/config and prepare for render
+ *  - async load(svgConfig) : Promise<{success: boolean, error: Error|null}> — accept SVG input/config and prepare for render
  *  - show(), hide() — toggle visibility and event subscriptions
  *  - zoomIn(), zoomOut(), zoomCenter(), zoomExtentsAll() — pan/zoom controls
+ *  - applySelectionState(state) — reconcile selectable and selected visual layers
+ *  - appendSvgNode(id, svgId, svg), removeAppendedSvgNodes() — manage host-provided SVG nodes
  * 
- * * Public Properties:
+ * Public Properties:
  *  - isInitialized: Indicates whether the component has completed initialization.
  *  - isLoaded: Indicates whether the SVG content is loaded and ready.
  *  - isVisible: Indicates whether the component is currently visible.
  *
  * Events
- *  - "drawing-loading": emitted before loading starts
- *  - "drawing-loaded": emitted after content and Panzoom are ready
- *  - "drawing-error": emitted on validation/fetch errors (detail.error: Error)
- *  - "drawing-zoom-changed": emitted when pan/zoom state changes (detail: { moved, scaled, maximized, minimized })
+ *  - "pref-viewer-2d-loading": emitted before loading starts. Legacy alias: "drawing-loading"
+ *  - "pref-viewer-2d-loaded": emitted after content and Panzoom are ready. Legacy alias: "drawing-loaded"
+ *  - "pref-viewer-2d-error": emitted on validation/fetch errors (detail.error: Error). Legacy alias: "drawing-error"
+ *  - "pref-viewer-2d-viewport-changed": emitted when pan/zoom state changes
+ *    (detail: { x, y, scale, moved, scaled, maximized, minimized })
+ *  - "pref-viewer-2d-element-click": emitted with `{ ids: string[] }` after semantic hit resolution
  *
  * Implementation notes
  *  - Keeps internal state in private fields (#svg, #panzoom, #panzoomOptions, ...).
@@ -69,10 +73,24 @@ export default class PrefViewer2D extends HTMLElement {
     #wrapper = null; // Panzoom element
     #panzoomController = null; // PanzoomController instance
 
+    #selectionState = {
+        selectableIds: [],
+        selectedItems: [],
+    };
+    #selectionNodes = [];
+    #appendedSvgElements = [];
+
     #handlers = {
         onPanzoomChanged: null,
+        onElementClick: null,
     };
 
+    #SELECTABLE_PREFIX = "_SELECTABLE_";
+    #SELECTED_PREFIX = "_SELECTED_";
+    #SELECTABLE_COLOR = "#FFFF00";
+    #SELECTED_COLOR = "#FF0000";
+    #COLOR_OPACITY = "0.5";
+
     /**
      * Create a new instance of the 2D viewer component.
      * The constructor only calls super(); heavy initialization happens in connectedCallback.
@@ -123,10 +141,15 @@ export default class PrefViewer2D extends HTMLElement {
      * @returns {void}
      */
     connectedCallback() {
-        this.#createDOMElements();
+        if (!this.#wrapper) {
+            this.#createDOMElements();
+        }
         this.#setInitialVisibility();
-        this.#initializePanzoom();
+        if (!this.#panzoomController) {
+            this.#initializePanzoom();
+        }
         this.#isInitialized = true;
+        this.#svg.update = true;
         this.#loadSVG();
     }
 
@@ -140,6 +163,8 @@ export default class PrefViewer2D extends HTMLElement {
         if (this.#panzoomController) {
             this.#panzoomController.disable();
         }
+        this.#isInitialized = false;
+        this.#isLoaded = false;
     }
 
     /**
@@ -175,7 +200,13 @@ export default class PrefViewer2D extends HTMLElement {
      */
     #initializePanzoom() {
         this.#handlers.onPanzoomChanged = this.#onPanzoomChanged.bind(this);
-        this.#panzoomController = new PanzoomController(this.#wrapper, undefined, this.#handlers.onPanzoomChanged);
+        this.#handlers.onElementClick = this.#onElementClick.bind(this);
+        this.#panzoomController = new PanzoomController(
+            this.#wrapper,
+            undefined,
+            this.#handlers.onPanzoomChanged,
+            this.#handlers.onElementClick,
+        );
     }
 
     /**
@@ -205,6 +236,8 @@ export default class PrefViewer2D extends HTMLElement {
             this.#panzoomController.disable();
         }
 
+        this.#clearSelectionLayers();
+        this.#removeAppendedSvgNodes();
         this.#wrapper.innerHTML = this.#svg.value;
 
         // If SVG is empty, do not initialize Panzoom but don't emit an error
@@ -235,7 +268,8 @@ export default class PrefViewer2D extends HTMLElement {
             composed: false, // indicates whether or not the event will propagate across the shadow DOM boundary into the standard DOM
             detail: detail,
         };
-        this.dispatchEvent(new CustomEvent("drawing-error", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-2d-error", customEventOptions));
+        this.dispatchEvent(new CustomEvent("drawing-error", customEventOptions)); // Legacy alias for backward compatibility
         return detail;
     }
 
@@ -250,12 +284,14 @@ export default class PrefViewer2D extends HTMLElement {
             cancelable: true,
             composed: false,
         };
-        this.dispatchEvent(new CustomEvent("drawing-loaded", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-2d-loaded", customEventOptions));
+        this.dispatchEvent(new CustomEvent("drawing-loaded", customEventOptions)); // Legacy alias for backward compatibility
 
         this.removeAttribute("loading");
         this.setAttribute("loaded", "");
 
         this.#isLoaded = true;
+        this.#reconcileSelectionState();
         this.#subscribeToEvents();
     }
 
@@ -270,7 +306,8 @@ export default class PrefViewer2D extends HTMLElement {
             cancelable: true,
             composed: false,
         };
-        this.dispatchEvent(new CustomEvent("drawing-loading", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-2d-loading", customEventOptions));
+        this.dispatchEvent(new CustomEvent("drawing-loading", customEventOptions)); // Legacy alias for backward compatibility
 
         this.removeAttribute("loaded");
         this.setAttribute("loading", "");
@@ -283,12 +320,12 @@ export default class PrefViewer2D extends HTMLElement {
     }
 
     /**
-     * Handles Panzoom state changes by dispatching a "prefviewer2d-zoomchanged" custom event.
+     * Handles Panzoom state changes by dispatching the public "pref-viewer-2d-viewport-changed" event.
      * @private
      * @param {object} state - The current Panzoom state object.
      * @returns {void}
      * @description
-     * The event detail contains the Panzoom state: { moved, scaled, maximized, minimized } to provide
+     * The event detail contains the Panzoom state: { x, y, scale, moved, scaled, maximized, minimized } to provide
      * the UI with the enabled/disabled status of the zoomIn, zoomOut, center, and zoomExtentsAll buttons.
      */
     #onPanzoomChanged(state) {
@@ -298,18 +335,294 @@ export default class PrefViewer2D extends HTMLElement {
             composed: false,
             detail: state,
         };
-        customEventOptions.detail.desde2d = "true";
-        this.dispatchEvent(new CustomEvent("drawing-zoom-changed", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-2d-viewport-changed", customEventOptions));
     }
 
     /**
-     * Subscribe DOM events required by Panzoom and keyboard interactions.
+     * Resolve a classified click to semantic SVG ids and notify the root component.
      * @private
+     * @param {Event} event - Original pointer event supplied by Panzoom.
      * @returns {void}
-                composed: true,
-                detail: state,
-            })
-        );
+     */
+    #onElementClick(event) {
+        const composedTarget = typeof event?.composedPath === "function"
+            ? event.composedPath()[0]
+            : null;
+        const ids = this.#resolveSemanticIds(composedTarget ?? event?.target);
+        if (ids.length === 0) {
+            return;
+        }
+        this.dispatchEvent(new CustomEvent("pref-viewer-2d-element-click", {
+            bubbles: true,
+            cancelable: true,
+            composed: false,
+            detail: { ids },
+        }));
+    }
+
+    /**
+     * Return the group that owns drawable PrefCAD elements.
+     * @private
+     * @returns {SVGElement|null}
+     */
+    #getSvgRoot() {
+        const svg = this.#wrapper?.querySelector("svg");
+        return svg?.firstElementChild ?? svg ?? null;
+    }
+
+    /**
+     * Resolve href values used by SVG `<use>` and paint references.
+     * @private
+     * @param {Element|null} node - SVG node.
+     * @returns {string|null}
+     */
+    #getHrefId(node) {
+        const href = node?.href?.baseVal
+            ?? node?.getAttribute?.("href")
+            ?? node?.getAttribute?.("xlink:href");
+        if (typeof href !== "string" || href.length === 0) {
+            return null;
+        }
+        if (href.startsWith("#")) {
+            return href.substring(1) || null;
+        }
+        const urlMatch = /^Url\(#(.+)\)$/i.exec(href);
+        return urlMatch?.[1] ?? null;
+    }
+
+    /**
+     * Resolve visual clones, direct ids and SVG references to business ids.
+     * @private
+     * @param {EventTarget|null} target - Original event target.
+     * @returns {string[]}
+     */
+    #resolveSemanticIds(target) {
+        if (!(target instanceof Element)) {
+            return [];
+        }
+
+        const visualNode = target.closest("[data-pref-viewer-semantic-id]");
+        let id = visualNode?.getAttribute("data-pref-viewer-semantic-id") ?? target.id ?? null;
+
+        if (!id && target.correspondingUseElement?.id) {
+            id = target.correspondingUseElement.id;
+        }
+        if (!id) {
+            id = this.#getHrefId(target);
+        }
+        if (!id) {
+            const drawingRoot = this.#getSvgRoot();
+            let ancestor = target.parentElement;
+            while (ancestor && ancestor !== drawingRoot) {
+                if (ancestor.id) {
+                    id = ancestor.id;
+                    break;
+                }
+                ancestor = ancestor.parentElement;
+            }
+        }
+        if (!id) {
+            return [];
+        }
+
+        if (id.startsWith(this.#SELECTABLE_PREFIX)) {
+            id = id.substring(this.#SELECTABLE_PREFIX.length);
+        } else if (id.startsWith(this.#SELECTED_PREFIX)) {
+            id = id.substring(this.#SELECTED_PREFIX.length);
+        }
+
+        if (!id.startsWith("ParametricMaterial")) {
+            return [id];
+        }
+
+        const group = this.#findSvgElementsById(id).find((node) => node.localName === "g");
+        const childIds = Array.from(group?.children ?? [])
+            .map((node) => node.id)
+            .filter((childId) => typeof childId === "string" && childId.length > 0);
+        return childIds.length > 0 ? childIds : [id];
+    }
+
+    /**
+     * Find supported drawing elements by exact id without CSS-selector escaping.
+     * @private
+     * @param {string} id - Semantic SVG id.
+     * @returns {Element[]}
+     */
+    #findSvgElementsById(id) {
+        const root = this.#getSvgRoot();
+        if (!root || typeof id !== "string") {
+            return [];
+        }
+        const elements = [root, ...root.querySelectorAll("path, use, g")];
+        return elements.filter((node) => node.id === id && !node.hasAttribute("data-pref-viewer-selection-layer"));
+    }
+
+    /**
+     * Locate the definition referenced by an SVG node.
+     * @private
+     * @param {Element} node - Referencing node.
+     * @returns {Element|null}
+     */
+    #getReferencedNode(node) {
+        const id = this.#getHrefId(node);
+        if (!id) {
+            return null;
+        }
+        const svg = this.#wrapper?.querySelector("svg");
+        return Array.from(svg?.querySelectorAll("[id]") ?? []).find((candidate) => candidate.id === id) ?? null;
+    }
+
+    /**
+     * Update a cloned `<use>` reference while supporting current browser SVG APIs.
+     * @private
+     * @param {Element} node - Cloned SVG node.
+     * @param {string} value - New href.
+     * @returns {void}
+     */
+    #setHref(node, value) {
+        node.setAttribute("href", value);
+        if (node.href?.baseVal !== undefined) {
+            node.href.baseVal = value;
+        }
+    }
+
+    /**
+     * Register and append a visual selection clone.
+     * @private
+     * @param {Element} node - Clone to append.
+     * @param {string} semanticId - Business id represented by the clone.
+     * @param {"selectable"|"selected"|"definition"} layer - Layer type.
+     * @param {Element|null} parent - Optional parent; defaults to drawing root.
+     * @returns {Element|null}
+     */
+    #appendSelectionNode(node, semanticId, layer, parent = null) {
+        const destination = parent ?? this.#getSvgRoot();
+        if (!destination || !node) {
+            return null;
+        }
+        node.setAttribute("data-pref-viewer-selection-layer", layer);
+        node.setAttribute("data-pref-viewer-semantic-id", semanticId);
+        destination.appendChild(node);
+        this.#selectionNodes.push(node);
+        return node;
+    }
+
+    /**
+     * Create the legacy-equivalent red clones for one source node.
+     * @private
+     * @param {Element} source - Source SVG node.
+     * @param {string} semanticId - Highlight id.
+     * @returns {Element[]}
+     */
+    #createSelectedClones(source, semanticId) {
+        const referred = this.#getReferencedNode(source);
+        const referredChildren = Array.from(referred?.childNodes ?? []).filter((node) => node.attributes);
+        const hatchChild = referredChildren.find((node) => node.getAttribute("fill")?.includes("Hatch"));
+        const delimiterChildren = referredChildren.filter((node) => node.getAttribute("fill") === "none" && node.hasAttribute("stroke"));
+
+        if (referred && hatchChild) {
+            const definition = referred.cloneNode(true);
+            const definitionId = `${this.#SELECTED_PREFIX}${this.#getHrefId(source)}`;
+            definition.id = definitionId;
+            const definitionChild = Array.from(definition.children).find((node) => node.hasAttribute("fill"));
+            definitionChild?.setAttribute("fill", this.#SELECTED_COLOR);
+            definitionChild?.setAttribute("fill-opacity", this.#COLOR_OPACITY);
+            this.#appendSelectionNode(definition, semanticId, "definition", referred.parentNode);
+
+            const clone = source.cloneNode(true);
+            this.#setHref(clone, `#${definitionId}`);
+            return [clone];
+        }
+
+        if (referred && delimiterChildren.length > 0) {
+            const definition = referred.cloneNode(true);
+            const definitionId = `${this.#SELECTED_PREFIX}${this.#getHrefId(source)}`;
+            definition.id = definitionId;
+            Array.from(definition.childNodes).forEach((node) => {
+                if (!node.attributes || node.getAttribute("fill") !== "none" || !node.hasAttribute("stroke")) {
+                    return;
+                }
+                node.setAttribute("stroke", this.#SELECTED_COLOR);
+                node.setAttribute("stroke-width", "10");
+            });
+            this.#appendSelectionNode(definition, semanticId, "definition", referred.parentNode);
+
+            const clone = source.cloneNode(true);
+            this.#setHref(clone, `#${definitionId}`);
+            return [clone];
+        }
+
+        const parent = source.parentElement;
+        if (parent?.id?.startsWith("ParametricMaterial")) {
+            const selectedId = `${this.#SELECTED_PREFIX}${semanticId}`;
+            const definition = parent.cloneNode(true);
+            definition.id = selectedId;
+            Array.from(definition.children).forEach((node) => {
+                node.removeAttribute("id");
+                if (node.getAttribute("fill") === "none" && node.hasAttribute("stroke")) {
+                    node.style.fill = this.#SELECTED_COLOR;
+                    node.style.fillOpacity = this.#COLOR_OPACITY;
+                }
+            });
+            this.#appendSelectionNode(definition, semanticId, "definition", parent.parentNode);
+
+            const uses = Array.from(this.#getSvgRoot()?.querySelectorAll("use") ?? [])
+                .filter((node) => this.#getHrefId(node) === parent.id)
+                .map((node) => {
+                    const clone = node.cloneNode(true);
+                    this.#setHref(clone, `#${selectedId}`);
+                    return clone;
+                });
+            if (uses.length > 0) {
+                return uses;
+            }
+        }
+
+        const clone = source.cloneNode(true);
+        clone.style.fill = this.#SELECTED_COLOR;
+        clone.style.fillOpacity = this.#COLOR_OPACITY;
+        return [clone];
+    }
+
+    /** Remove all visual selection clones and cloned definitions. */
+    #clearSelectionLayers() {
+        this.#selectionNodes.forEach((node) => node.parentNode?.removeChild(node));
+        this.#selectionNodes = [];
+    }
+
+    /** Remove all host-provided SVG nodes and clear their registry. */
+    #removeAppendedSvgNodes() {
+        this.#appendedSvgElements.forEach((entry) => entry.svg?.parentNode?.removeChild(entry.svg));
+        this.#appendedSvgElements = [];
+    }
+
+    /** Rebuild visual layers from the latest semantic snapshot. */
+    #reconcileSelectionState() {
+        this.#clearSelectionLayers();
+        if (!this.#isLoaded || !this.#getSvgRoot()) {
+            return;
+        }
+
+        this.#selectionState.selectableIds.forEach((id) => {
+            this.#findSvgElementsById(id).forEach((source) => {
+                const clone = source.cloneNode(true);
+                clone.id = `${this.#SELECTABLE_PREFIX}${id}`;
+                clone.style.fill = this.#SELECTABLE_COLOR;
+                clone.style.fillOpacity = this.#COLOR_OPACITY;
+                this.#appendSelectionNode(clone, id, "selectable");
+            });
+        });
+
+        this.#selectionState.selectedItems.forEach((item) => {
+            item.highlights.forEach((id) => {
+                this.#findSvgElementsById(id).forEach((source) => {
+                    this.#createSelectedClones(source, id).forEach((clone) => {
+                        clone.id = `${this.#SELECTED_PREFIX}${id}`;
+                        this.#appendSelectionNode(clone, id, "selected");
+                    });
+                });
+            });
+        });
     }
 
     /**
@@ -369,6 +682,67 @@ export default class PrefViewer2D extends HTMLElement {
         return { success: success, error: null };
     }
 
+    /**
+     * Apply a complete semantic selection snapshot to the current drawing.
+     * @public
+     * @param {{selectableIds?: string[], selectedItems?: Array<{id: string, highlights?: string[]}>}} state - Selection snapshot.
+     * @returns {void}
+     */
+    applySelectionState(state = {}) {
+        const selectableIds = Array.isArray(state.selectableIds)
+            ? state.selectableIds.filter((id) => typeof id === "string" && id.length > 0)
+            : [];
+        const selectedItems = Array.isArray(state.selectedItems)
+            ? state.selectedItems
+                .map((item) => {
+                    const id = typeof item === "string" ? item : (item?.id ?? item?.Id);
+                    if (typeof id !== "string" || id.length === 0) {
+                        return null;
+                    }
+                    const rawHighlights = typeof item === "string" ? [item] : (item.highlights ?? item.Highlights ?? [id]);
+                    return {
+                        id,
+                        highlights: Array.isArray(rawHighlights)
+                            ? rawHighlights.filter((highlight) => typeof highlight === "string" && highlight.length > 0)
+                            : [],
+                    };
+                })
+                .filter(Boolean)
+            : [];
+        this.#selectionState = { selectableIds, selectedItems };
+        this.#reconcileSelectionState();
+    }
+
+    /**
+     * Add a host-owned SVG node to the interactive drawing.
+     * @public
+     * @param {string} id - Owner id.
+     * @param {string} svgId - Stable selector/id used to prevent duplicates.
+     * @param {SVGElement} svg - Node to append.
+     * @returns {boolean} True when appended.
+     */
+    appendSvgNode(id, svgId, svg) {
+        const root = this.#getSvgRoot();
+        if (!root || !svg || this.#appendedSvgElements.some((entry) => entry.svgId === svgId)) {
+            return false;
+        }
+        root.appendChild(svg);
+        this.#appendedSvgElements.push({ id, svgId, svg });
+        this.#reconcileSelectionState();
+        return true;
+    }
+
+    /**
+     * Remove every node previously added through appendSvgNode.
+     * @public
+     * @returns {void}
+     */
+    removeAppendedSvgNodes() {
+        this.#clearSelectionLayers();
+        this.#removeAppendedSvgNodes();
+        this.#reconcileSelectionState();
+    }
+
     /**
      * Hide the component: set style, attribute and unsubscribe from events.
      * @public