@customviews-js/customviews 1.1.11 → 1.3.0

package/dist/custom-views.js

@@ -1,5 +1,5 @@
 /*!
- * @customviews-js/customviews v1.1.11
+ * @customviews-js/customviews v1.3.0
  * (c) 2025 Chan Ger Teck
  * Released under the MIT License.
  */
@@ -160,7 +160,9 @@
             return url.toString();
         }
         /**
-         * Encode state into URL-safe string (Toggles and Tabs only currently)
+         * Encode state into URL-safe string
+         *
+         * (Covers Toggles, Tabs and Focus currently)
          */
         static encodeState(state) {
             try {
@@ -174,6 +176,10 @@
                 if (state.tabs && Object.keys(state.tabs).length > 0) {
                     compact.g = Object.entries(state.tabs);
                 }
+                // Add focus if present
+                if (state.focus && state.focus.length > 0) {
+                    compact.f = state.focus;
+                }
                 // Convert to JSON and encode
                 const json = JSON.stringify(compact);
                 let encoded;
@@ -195,7 +201,9 @@
             }
         }
         /**
-         * Decode custom state from URL parameter (Toggles and Tabs only currently)
+         * Decode custom state from URL parameter
+         *
+         * (Covers Toggles, Tabs and Focus currently)
          */
         static decodeState(encoded) {
             try {
@@ -234,6 +242,10 @@
                         }
                     }
                 }
+                // Reconstruct Focus
+                if (Array.isArray(compact.f)) {
+                    state.focus = compact.f;
+                }
                 return state;
             }
             catch (error) {
@@ -418,9 +430,15 @@
     </svg>
   `.trim();
     }
+    function getShareIcon() {
+        return `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+            <path fill="currentColor" d="M18 8h-2a1 1 0 0 0 0 2h2v8H6v-8h2a1 1 0 0 0 0-2H6a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-8a2 2 0 0 0-2-2z"/>
+            <path fill="currentColor" d="M11 6.41V12a1 1 0 0 0 2 0V6.41l1.29 1.3a1 1 0 0 0 1.42 0a1 1 0 0 0 0-1.42l-3-3a1 1 0 0 0-1.42 0l-3 3a1 1 0 1 0 1.42 1.42L11 6.41z"/>
+          </svg>`;
+    }
 
     // Constants for selectors
-    const TABGROUP_SELECTOR = 'cv-tabgroup';
+    const TABGROUP_SELECTOR$1 = 'cv-tabgroup';
     const TAB_SELECTOR = 'cv-tab';
     const NAV_AUTO_SELECTOR = 'cv-tabgroup[nav="auto"], cv-tabgroup:not([nav])';
     const NAV_CONTAINER_CLASS = 'cv-tabs-nav';
@@ -436,11 +454,9 @@
             return trimmedIds;
         }
         /**
-         * Apply tab selections to all tab groups in the DOM
+         * Apply tab selections to a given list of tab group elements
          */
-        static applyTabSelections(rootEl, tabs, cfgGroups) {
-            // Find all cv-tabgroup elements
-            const tabGroups = rootEl.querySelectorAll(TABGROUP_SELECTOR);
+        static applyTabSelections(tabGroups, tabs, cfgGroups) {
             tabGroups.forEach((groupEl) => {
                 const groupId = groupEl.getAttribute('id');
                 // Determine the active tab for this group
@@ -545,10 +561,18 @@
         /**
          * Build navigation for tab groups (one-time setup)
          */
-        static buildNavs(rootEl, cfgGroups, onTabClick, onTabDoubleClick) {
-            // Find all cv-tabgroup elements with nav="auto" or no nav attribute
-            const tabGroups = rootEl.querySelectorAll(NAV_AUTO_SELECTOR);
+        static buildNavs(tabGroups, cfgGroups, onTabClick, onTabDoubleClick) {
+            const rootEl = document.body; // Needed for NAV_HIDE_ROOT_CLASS check
             tabGroups.forEach((groupEl) => {
+                // Prevent re-initialization
+                if (groupEl.hasAttribute('data-cv-initialized')) {
+                    return;
+                }
+                groupEl.setAttribute('data-cv-initialized', 'true');
+                // Filter to only build for groups with nav="auto" or no nav attribute
+                if (!groupEl.matches(NAV_AUTO_SELECTOR)) {
+                    return;
+                }
                 const groupId = groupEl.getAttribute('id') || null;
                 // Note: groupId can be null for standalone tabgroups
                 // These won't sync with other groups or persist state
@@ -752,8 +776,7 @@
         /**
          * Update active states for all tab groups based on current state
          */
-        static updateAllNavActiveStates(rootEl, tabs, cfgGroups) {
-            const tabGroups = rootEl.querySelectorAll(TABGROUP_SELECTOR);
+        static updateAllNavActiveStates(tabGroups, tabs, cfgGroups) {
             tabGroups.forEach((groupEl) => {
                 const groupId = groupEl.getAttribute('id');
                 if (!groupId)
@@ -816,7 +839,7 @@
          */
         static getTabgroupsWithId(rootEl, sourceGroupId, tabId) {
             const syncedGroupEls = [];
-            const allGroupEls = Array.from(rootEl.querySelectorAll(`${TABGROUP_SELECTOR}[id="${sourceGroupId}"]`));
+            const allGroupEls = Array.from(rootEl.querySelectorAll(`${TABGROUP_SELECTOR$1}[id="${sourceGroupId}"]`));
             allGroupEls.forEach((targetGroupEl) => {
                 // Only sync if target group actually contains this tab
                 if (this.groupHasTab(targetGroupEl, tabId)) {
@@ -828,9 +851,8 @@
         /**
          * Update pin icon visibility for all tab groups based on current state.
          * Shows pin icon for tabs that are in the persisted state (i.e., have been double-clicked).
-         */
-        static updatePinIcons(rootEl, tabs) {
-            const tabGroups = rootEl.querySelectorAll(TABGROUP_SELECTOR);
+          */
+        static updatePinIcons(tabGroups, tabs) {
             tabGroups.forEach((groupEl) => {
                 const groupId = groupEl.getAttribute('id');
                 if (!groupId)
@@ -980,33 +1002,31 @@
         }
     }
 
-    // Constants for selectors
-    const TOGGLE_DATA_SELECTOR = "[data-cv-toggle], [data-customviews-toggle]";
-    const TOGGLE_ELEMENT_SELECTOR = "cv-toggle";
-    const TOGGLE_SELECTOR = `${TOGGLE_DATA_SELECTOR}, ${TOGGLE_ELEMENT_SELECTOR}`;
     /**
      * ToggleManager handles discovery, visibility, and asset rendering for toggle elements
      */
     class ToggleManager {
         /**
-         * Apply toggle visibility to all toggle elements in the DOM
+         * Apply toggle visibility to a given list of toggle elements
          */
-        static applyToggles(rootEl, activeToggles) {
-            rootEl.querySelectorAll(TOGGLE_SELECTOR).forEach(el => {
+        static applyToggles(elements, activeToggles) {
+            elements.forEach(el => {
                 const categories = this.getToggleCategories(el);
                 const shouldShow = categories.some(cat => activeToggles.includes(cat));
                 this.applyToggleVisibility(el, shouldShow);
             });
         }
         /**
-         * Render assets into toggle elements that are currently visible
+         * Render assets into a given list of toggle elements that are currently visible
          */
-        static renderAssets(rootEl, activeToggles, assetsManager) {
-            rootEl.querySelectorAll(TOGGLE_SELECTOR).forEach(el => {
+        static renderAssets(elements, activeToggles, assetsManager) {
+            elements.forEach(el => {
                 const categories = this.getToggleCategories(el);
                 const toggleId = this.getToggleId(el);
-                if (toggleId && categories.some(cat => activeToggles.includes(cat))) {
+                const isRendered = el.dataset.cvRendered === 'true';
+                if (toggleId && !isRendered && categories.some(cat => activeToggles.includes(cat))) {
                     renderAssetInto(el, toggleId, assetsManager);
+                    el.dataset.cvRendered = 'true';
                 }
             });
         }
@@ -1042,6 +1062,21 @@
                 el.classList.remove('cv-visible');
             }
         }
+        /**
+         * Scans a given DOM subtree for toggle elements and initializes them.
+         * This includes applying visibility and rendering assets.
+         */
+        static initializeToggles(root, activeToggles, assetsManager) {
+            const elements = [];
+            if (root.matches('[data-cv-toggle], [data-customviews-toggle], cv-toggle')) {
+                elements.push(root);
+            }
+            root.querySelectorAll('[data-cv-toggle], [data-customviews-toggle], cv-toggle').forEach(el => elements.push(el));
+            if (elements.length === 0)
+                return;
+            this.applyToggles(elements, activeToggles);
+            this.renderAssets(elements, activeToggles, assetsManager);
+        }
     }
 
     // src/utils/scroll-manager.ts
@@ -1365,11 +1400,1200 @@ ${TAB_STYLES}
         document.head.appendChild(style);
     }
 
+    const TOAST_STYLE_ID = 'cv-toast-styles';
+    const TOAST_CLASS = 'cv-toast-notification';
+    const TOAST_STYLES = `
+  .cv-toast-notification {
+    position: fixed;
+    top: 20px;
+    left: 50%;
+    transform: translateX(-50%);
+    background-color: #323232;
+    color: white;
+    padding: 12px 24px;
+    border-radius: 4px;
+    z-index: 100000;
+    box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+    opacity: 0;
+    transition: opacity 0.3s ease;
+    pointer-events: none; /* Let clicks pass through if needed, though usually it blocks */
+    font-family: system-ui, -apple-system, sans-serif;
+    font-size: 14px;
+  }
+`;
+
+    /**
+     * Manages toast notifications for the application.
+     */
+    class ToastManager {
+        static isStyleInjected = false;
+        static toastEl = null;
+        static navTimeout = null;
+        static fadeTimeout = null;
+        static show(message, duration = 2500) {
+            this.injectStyles();
+            // specific reuse logic
+            if (!this.toastEl) {
+                this.toastEl = document.createElement('div');
+                this.toastEl.className = TOAST_CLASS;
+                document.body.appendChild(this.toastEl);
+            }
+            // Reset state
+            this.toastEl.textContent = message;
+            this.toastEl.style.opacity = '0';
+            this.toastEl.style.display = 'block';
+            // Clear any pending dismissal
+            if (this.navTimeout)
+                clearTimeout(this.navTimeout);
+            if (this.fadeTimeout)
+                clearTimeout(this.fadeTimeout);
+            // Trigger reflow & fade in
+            requestAnimationFrame(() => {
+                if (this.toastEl)
+                    this.toastEl.style.opacity = '1';
+            });
+            // Schedule fade out
+            this.navTimeout = setTimeout(() => {
+                if (this.toastEl)
+                    this.toastEl.style.opacity = '0';
+                this.fadeTimeout = setTimeout(() => {
+                    if (this.toastEl)
+                        this.toastEl.style.display = 'none';
+                }, 300);
+            }, duration);
+        }
+        static injectStyles() {
+            if (this.isStyleInjected)
+                return;
+            if (document.getElementById(TOAST_STYLE_ID)) {
+                this.isStyleInjected = true;
+                return;
+            }
+            const style = document.createElement('style');
+            style.id = TOAST_STYLE_ID;
+            style.innerHTML = TOAST_STYLES;
+            document.head.appendChild(style);
+            this.isStyleInjected = true;
+        }
+    }
+
+    /**
+     * Engine for generating and resolving robust anchors.
+     *
+     * It implements a simple anchor generation and resolution algorithm that uses a combination of
+     * structural, contextual, and content-based hints to generate a unique anchor for a given DOM element.
+     *
+     * The anchor is generated by first creating an AnchorDescriptor for the element, which contains
+     * information about the element's tag, index, parent ID, and text content. This descriptor is then
+     * serialized into a URL-safe string using a minification algorithm.
+     *
+     * The anchor is then resolved by searching for the element in the DOM using the serialized string.
+     *
+     */
+    class AnchorEngine {
+        /**
+         * Generates a simple hash code for a string.
+         *
+         * It takes each character's Unicode code point and uses it to update the hash value.
+         */
+        static hashCode(str) {
+            let hash = 0;
+            if (str.length === 0)
+                return hash;
+            for (let i = 0; i < str.length; i++) {
+                const char = str.charCodeAt(i);
+                hash = ((hash << 5) - hash) + char;
+                hash = hash & hash; // Convert to 32bit integer
+            }
+            return hash;
+        }
+        /**
+         * Normalizes text content by removing excessive whitespace.
+         *
+         * It trims leading and trailing whitespace and replaces multiple spaces with a single space.
+         */
+        static normalizeText(text) {
+            return text.trim().replace(/\s+/g, ' ');
+        }
+        /**
+         * Creates an AnchorDescriptor for a given DOM element.
+         */
+        static createDescriptor(el) {
+            const tag = el.tagName;
+            const textContent = el.textContent || "";
+            const normalizedText = this.normalizeText(textContent);
+            // Find nearest parent with an ID
+            let parentId;
+            let parent = el.parentElement;
+            while (parent) {
+                if (parent.id) {
+                    parentId = parent.id;
+                    break;
+                }
+                parent = parent.parentElement;
+            }
+            // Calculate index relative to the container (either the found parent or document.body)
+            const container = parent || document.body;
+            const siblings = Array.from(container.querySelectorAll(tag));
+            // Index is the position of the element in the list of siblings, where siblings are those of the same tag.
+            const index = siblings.indexOf(el);
+            const descriptor = {
+                tag,
+                index: index !== -1 ? index : 0,
+                textSnippet: normalizedText.substring(0, 32),
+                textHash: this.hashCode(normalizedText)
+            };
+            if (parentId) {
+                descriptor.parentId = parentId;
+            }
+            return descriptor;
+        }
+        /**
+         * Serializes a list of AnchorDescriptors into a URL-safe string.
+         */
+        static serialize(descriptors) {
+            // Minify keys for compactness
+            const minified = descriptors.map(d => ({
+                t: d.tag,
+                i: d.index,
+                p: d.parentId,
+                s: d.textSnippet,
+                h: d.textHash
+            }));
+            const json = JSON.stringify(minified);
+            // Base64 encode
+            return btoa(encodeURIComponent(json));
+        }
+        /**
+         * Deserializes a URL-safe string back into a list of AnchorDescriptors.
+         */
+        static deserialize(encoded) {
+            try {
+                const json = decodeURIComponent(atob(encoded));
+                const minified = JSON.parse(json);
+                return minified.map((m) => ({
+                    tag: m.t,
+                    index: m.i,
+                    parentId: m.p,
+                    textSnippet: m.s,
+                    textHash: m.h
+                }));
+            }
+            catch (e) {
+                console.error("Failed to deserialize anchor:", e);
+                return [];
+            }
+        }
+        /**
+         * Finds the best DOM element match for a descriptor.
+         */
+        static resolve(root, descriptor) {
+            // 1. Scope
+            let scope = root;
+            if (descriptor.parentId) {
+                const foundParent = root.querySelector(`#${descriptor.parentId}`);
+                if (foundParent instanceof HTMLElement) {
+                    scope = foundParent;
+                }
+                else {
+                    // Fallback: if parent ID not found, search global root - document.body
+                    const globalParent = document.getElementById(descriptor.parentId);
+                    if (globalParent) {
+                        scope = globalParent;
+                    }
+                }
+            }
+            // 2. Candidate Search
+            const candidates = Array.from(scope.querySelectorAll(descriptor.tag));
+            // 3. Scoring
+            let bestMatch = null;
+            let highestScore = 0;
+            candidates.forEach((candidate) => {
+                let score = 0;
+                const text = this.normalizeText(candidate.textContent || "");
+                // Exact Text Match (Hash check is faster proxy for full string compare, but let's check hash first)
+                if (this.hashCode(text) === descriptor.textHash) {
+                    score += 50;
+                }
+                else if (text.startsWith(descriptor.textSnippet)) {
+                    // Fuzzy Text Match (Snippet) - +30 score
+                    score += 30;
+                }
+                // Structural Match (Index)
+                // We need to re-calculate index of this candidate to compare with descriptor.index
+                // The descriptor.index is relative to the *found* parentId container.
+                // So we must compare index within the scope we are searching.
+                const siblings = Array.from(scope.querySelectorAll(descriptor.tag));
+                const index = siblings.indexOf(candidate);
+                if (index === descriptor.index) {
+                    score += 10;
+                }
+                if (score > highestScore) {
+                    highestScore = score;
+                    bestMatch = candidate;
+                }
+            });
+            // 4. Winner
+            if (highestScore > 30) {
+                return bestMatch;
+            }
+            return null;
+        }
+    }
+
+    const SHARE_MODE_STYLE_ID = 'cv-share-mode-styles';
+    const FLOATING_ACTION_BAR_ID = 'cv-floating-action-bar';
+    const HOVER_HELPER_ID = 'cv-hover-helper';
+    const HIGHLIGHT_TARGET_CLASS = 'cv-highlight-target';
+    const SELECTED_CLASS = 'cv-share-selected';
+    /**
+     * CSS styles to be injected during Share Mode.
+     */
+    const SHARE_MODE_STYLES = `
+  body.cv-share-mode {
+    cursor: default;
+  }
+
+  /* Highlight outlines */
+  .${HIGHLIGHT_TARGET_CLASS} {
+    outline: 2px dashed #0078D4 !important;
+    outline-offset: 2px;
+    cursor: crosshair;
+  }
+
+  .${SELECTED_CLASS} {
+    outline: 3px solid #005a9e !important;
+    outline-offset: 2px;
+    background-color: rgba(0, 120, 212, 0.05);
+  }
+
+  /* Floating Action Bar */
+  #${FLOATING_ACTION_BAR_ID} {
+    position: fixed;
+    bottom: 20px;
+    left: 50%;
+    transform: translateX(-50%);
+    background-color: #2c2c2c;
+    color: #f1f1f1;
+    border-radius: 8px;
+    padding: 12px 20px;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
+    display: flex;
+    align-items: center;
+    gap: 16px;
+    z-index: 99999;
+    font-family: system-ui, -apple-system, sans-serif;
+    font-size: 14px;
+    border: 1px solid #4a4a4a;
+  }
+
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button {
+    background-color: #0078D4;
+    color: white;
+    border: none;
+    padding: 8px 14px;
+    border-radius: 5px;
+    cursor: pointer;
+    font-weight: 500;
+    transition: background-color 0.2s;
+  }
+  
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button:hover {
+    background-color: #005a9e;
+  }
+
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.clear {
+    background-color: #5a5a5a;
+  }
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.clear:hover {
+    background-color: #4a4a4a;
+  }
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.clear:hover {
+    background-color: #4a4a4a;
+  }
+
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.preview {
+    background-color: #106ebe;
+  }
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.preview:hover {
+    background-color: #005a9e;
+  }
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.exit {
+    background-color: #d13438;
+  }
+  #${FLOATING_ACTION_BAR_ID} .cv-action-button.exit:hover {
+    background-color: #a42628;
+  }
+
+  /* Hover Helper (Smart Label & Level Up) */
+  #${HOVER_HELPER_ID} {
+    position: fixed;
+    z-index: 99999;
+    background-color: #333;
+    color: white;
+    padding: 4px 8px;
+    border-radius: 4px;
+    font-size: 12px;
+    font-family: monospace;
+    display: none;
+    pointer-events: auto; /* Allow clicking buttons inside */
+    align-items: center;
+    gap: 8px;
+    box-shadow: 0 2px 5px rgba(0,0,0,0.2);
+  }
+
+  #${HOVER_HELPER_ID} button {
+    background: #555;
+    border: none;
+    color: white;
+    border-radius: 3px;
+    cursor: pointer;
+    padding: 2px 6px;
+    font-size: 14px;
+    line-height: 1;
+  }
+  #${HOVER_HELPER_ID} button:hover {
+    background: #777;
+  }
+
+`;
+
+    const CV_CUSTOM_ELEMENTS = 'cv-tabgroup, cv-toggle';
+    const SHAREABLE_SELECTOR = 'div, p, blockquote, pre, li, h1, h2, h3, h4, h5, h6, [data-share], ' + CV_CUSTOM_ELEMENTS;
+    /**
+     * Manages the "Share Mode" for creating custom focus links.
+     * Implementing Robust Granular Sharing with "Innermost Wins" and "Level Up" UI.
+     */
+    class ShareManager {
+        isActive = false;
+        selectedElements = new Set();
+        floatingBarEl = null;
+        helperEl = null;
+        currentHoverTarget = null;
+        excludedTags;
+        excludedIds;
+        boundHandleHover;
+        boundHandleClick;
+        boundHandleKeydown;
+        constructor(options) {
+            this.excludedTags = new Set(options.excludedTags.map(t => t.toUpperCase()));
+            this.excludedIds = new Set(options.excludedIds);
+            this.boundHandleHover = this.handleHover.bind(this);
+            this.boundHandleClick = this.handleClick.bind(this);
+            this.boundHandleKeydown = this.handleKeydown.bind(this);
+        }
+        listeners = [];
+        addStateChangeListener(listener) {
+            this.listeners.push(listener);
+        }
+        removeStateChangeListener(listener) {
+            this.listeners = this.listeners.filter(l => l !== listener);
+        }
+        notifyListeners() {
+            this.listeners.forEach(listener => listener(this.isActive));
+        }
+        toggleShareMode() {
+            this.isActive = !this.isActive;
+            if (this.isActive) {
+                this.activate();
+            }
+            else {
+                this.cleanup();
+            }
+            this.notifyListeners();
+        }
+        /**
+         * Activates the share mode.
+         * Injects styles, creates floating bar, and helper element.
+         * Adds event listeners for hover and click.
+         */
+        activate() {
+            this.injectStyles();
+            this.createFloatingBar();
+            this.helperEl = this.createHelperPopover();
+            // Event Listeners
+            document.addEventListener('mouseover', this.boundHandleHover, true);
+            document.addEventListener('click', this.boundHandleClick, true);
+            document.addEventListener('keydown', this.boundHandleKeydown, true);
+        }
+        injectStyles() {
+            const styleElement = document.createElement('style');
+            styleElement.id = SHARE_MODE_STYLE_ID;
+            styleElement.innerHTML = SHARE_MODE_STYLES;
+            document.head.appendChild(styleElement);
+        }
+        /**
+         * Creates the hover helper element that shows up when hovering over a shareable element.
+         */
+        createHelperPopover() {
+            const div = document.createElement('div');
+            div.id = HOVER_HELPER_ID;
+            div.innerHTML = `
+      <span id="cv-helper-tag">TAG</span>
+      <button id="cv-helper-select-btn" title="Select This Element">✓</button>
+      <button id="cv-helper-up-btn" title="Select Parent">↰</button>
+    `;
+            document.body.appendChild(div);
+            // Select parent button
+            div.querySelector('#cv-helper-up-btn')?.addEventListener('click', (e) => {
+                e.preventDefault();
+                e.stopPropagation();
+                this.handleSelectParent();
+            });
+            // Select element button
+            div.querySelector('#cv-helper-select-btn')?.addEventListener('click', (e) => {
+                e.preventDefault();
+                e.stopPropagation();
+                if (this.currentHoverTarget) {
+                    this.toggleSelection(this.currentHoverTarget);
+                }
+            });
+            return div;
+        }
+        /**
+         * Handles mouse hover events.
+         *
+         * This function is called when the user hovers over an element.
+         * It checks if the element is shareable and highlights it.
+         * If a parent element is already selected, it highlights the parent instead,
+         * allowing the helper to remain visible for the selected parent.
+         *
+         * @param e The mouse event triggered by the hover.
+         */
+        handleHover(e) {
+            if (!this.isActive)
+                return;
+            // Check if we are hovering over the helper itself
+            if (this.helperEl && this.helperEl.contains(e.target)) {
+                return;
+            }
+            const target = e.target;
+            // Exclude by Tag or ID
+            const upperTag = target.tagName.toUpperCase();
+            if (this.excludedTags.has(upperTag) || (target.id && this.excludedIds.has(target.id))) {
+                return;
+            }
+            // Check closest excluded (for nested elements in excluded regions)
+            let ancestor = target.parentElement;
+            while (ancestor) {
+                if (this.excludedTags.has(ancestor.tagName.toUpperCase()) || (ancestor.id && this.excludedIds.has(ancestor.id))) {
+                    return;
+                }
+                ancestor = ancestor.parentElement;
+            }
+            // Find closest shareable parent element
+            const shareablePart = target.closest(SHAREABLE_SELECTOR);
+            if (!shareablePart) {
+                this.clearHover();
+                return;
+            }
+            // Cast to HTMLElement
+            const finalTarget = shareablePart;
+            // Check if any ancestor is already selected. If so, do NOT highlight this child.
+            // Instead, highlight (or keep highlighted) the SELECTED PARENT so the user can see the helper for it.
+            let parent = finalTarget.parentElement;
+            let selectedAncestor = null;
+            // Loop outwards until we find a selected parent or reach the top
+            while (parent) {
+                if (this.selectedElements.has(parent)) {
+                    selectedAncestor = parent;
+                    break;
+                }
+                parent = parent.parentElement;
+            }
+            if (selectedAncestor) {
+                // If we are hovering deep inside a selected block, show the helper for that block
+                this.setNewHoverTarget(selectedAncestor);
+                return;
+            }
+            // stop bubbling to parent
+            // when element found for highlight
+            e.stopPropagation();
+            // If we are already on this target, do nothing (and keep it selected/highlighted)
+            if (this.currentHoverTarget === finalTarget)
+                return;
+            // Highlight
+            this.setNewHoverTarget(finalTarget);
+        }
+        setNewHoverTarget(target) {
+            if (this.currentHoverTarget) {
+                this.currentHoverTarget.classList.remove(HIGHLIGHT_TARGET_CLASS);
+            }
+            this.currentHoverTarget = target;
+            this.currentHoverTarget.classList.add(HIGHLIGHT_TARGET_CLASS);
+            this.positionHelper(target);
+        }
+        positionHelper(target) {
+            if (!this.helperEl)
+                return;
+            const rect = target.getBoundingClientRect();
+            const tagLabel = this.helperEl.querySelector('#cv-helper-tag');
+            const upBtn = this.helperEl.querySelector('#cv-helper-up-btn');
+            if (tagLabel)
+                tagLabel.textContent = target.tagName;
+            // Position at top-right of the element
+            // Prevent going off-screen
+            let top = rect.top - 20;
+            if (top < 0)
+                top = rect.top + 10; // Flip down if too close to top
+            let left = rect.right - 80;
+            if (left < 0)
+                left = 10;
+            this.helperEl.style.display = 'flex';
+            this.helperEl.style.top = `${top}px`;
+            this.helperEl.style.left = `${left}px`;
+            // Update Select Button State (Tick or Cross)
+            const selectBtn = this.helperEl.querySelector('#cv-helper-select-btn');
+            if (selectBtn) {
+                if (this.selectedElements.has(target)) {
+                    selectBtn.textContent = '✕';
+                    selectBtn.title = 'Deselect This Element';
+                    selectBtn.style.backgroundColor = '#d13438'; // Reddish
+                }
+                else {
+                    selectBtn.textContent = '✓';
+                    selectBtn.title = 'Select This Element';
+                    selectBtn.style.backgroundColor = ''; // Reset
+                }
+            }
+            // Ancestry Check
+            const parent = target.parentElement;
+            const parentIsShareable = parent && parent.matches(SHAREABLE_SELECTOR);
+            if (parentIsShareable) {
+                upBtn.style.display = 'inline-block';
+            }
+            else {
+                upBtn.style.display = 'none';
+            }
+        }
+        handleSelectParent() {
+            if (this.currentHoverTarget && this.currentHoverTarget.parentElement) {
+                const parent = this.currentHoverTarget.parentElement;
+                if (parent.matches(SHAREABLE_SELECTOR)) {
+                    this.setNewHoverTarget(parent);
+                }
+            }
+        }
+        handleClick(e) {
+            if (!this.isActive)
+                return;
+            // If clicking helper
+            if (this.helperEl && this.helperEl.contains(e.target))
+                return;
+            // If clicking floating bar
+            if (this.floatingBarEl && this.floatingBarEl.contains(e.target))
+                return;
+            e.preventDefault();
+            e.stopPropagation();
+            if (this.currentHoverTarget) {
+                this.toggleSelection(this.currentHoverTarget);
+            }
+        }
+        handleKeydown(e) {
+            if (!this.isActive)
+                return;
+            if (e.key === 'Escape') {
+                e.preventDefault();
+                e.stopPropagation();
+                this.toggleShareMode();
+            }
+        }
+        /**
+         * Toggles the selection state of a given HTML element.
+         * Implements selection logic:
+         * - If an ancestor of the element is already selected, the click is ignored.
+         * - If the element being selected is a parent of already selected elements, those children are deselected.
+         * @param el The HTMLElement to toggle selection for.
+         */
+        toggleSelection(el) {
+            if (this.selectedElements.has(el)) {
+                this.selectedElements.delete(el);
+                el.classList.remove(SELECTED_CLASS);
+            }
+            else {
+                // Selection Logic
+                // Scenario A: Selecting a Parent -> Remove children selected while selecting parent
+                // Scenario B: Selecting a Child -> Ignore if ancestor selected (or handle)
+                // B. Check if any ancestor is already selected, return if any (Scenario B)
+                let parent = el.parentElement;
+                while (parent) {
+                    if (this.selectedElements.has(parent)) {
+                        // Ancestor is selected. Ignore click.
+                        return;
+                    }
+                    parent = parent.parentElement;
+                }
+                // A. Check if any children are selected (Scenario A)
+                // We must iterate over currently selected elements
+                const toRemove = [];
+                this.selectedElements.forEach(selected => {
+                    if (el.contains(selected) && el !== selected) {
+                        toRemove.push(selected);
+                    }
+                });
+                toRemove.forEach(child => {
+                    this.selectedElements.delete(child);
+                    child.classList.remove(SELECTED_CLASS);
+                });
+                // Add new selection
+                this.selectedElements.add(el);
+                el.classList.add(SELECTED_CLASS);
+            }
+            this.updateFloatingBarCount();
+        }
+        createFloatingBar() {
+            const bar = document.createElement('div');
+            bar.id = FLOATING_ACTION_BAR_ID;
+            bar.innerHTML = `
+      <span id="cv-selected-count">0 items selected</span>
+      <button class="cv-action-button clear">Clear All</button>
+      <button class="cv-action-button preview">Preview</button>
+      <button class="cv-action-button generate">Generate Link</button>
+      <button class="cv-action-button exit">Exit</button>
+    `;
+            document.body.appendChild(bar);
+            this.floatingBarEl = bar;
+            bar.querySelector('.clear')?.addEventListener('click', () => this.clearAll());
+            bar.querySelector('.preview')?.addEventListener('click', () => this.previewLink());
+            bar.querySelector('.generate')?.addEventListener('click', () => this.generateLink());
+            bar.querySelector('.exit')?.addEventListener('click', () => this.toggleShareMode());
+        }
+        updateFloatingBarCount() {
+            if (this.floatingBarEl) {
+                const countElement = this.floatingBarEl.querySelector('#cv-selected-count');
+                if (countElement) {
+                    const count = this.selectedElements.size;
+                    countElement.textContent = `${count} item${count === 1 ? '' : 's'} selected`;
+                }
+            }
+        }
+        clearAll() {
+            this.selectedElements.forEach(el => el.classList.remove('cv-share-selected'));
+            this.selectedElements.clear();
+            this.updateFloatingBarCount();
+        }
+        getShareUrl() {
+            if (this.selectedElements.size === 0) {
+                return null;
+            }
+            const descriptors = Array.from(this.selectedElements).map(el => AnchorEngine.createDescriptor(el));
+            const serialized = AnchorEngine.serialize(descriptors);
+            const url = new URL(window.location.href);
+            url.searchParams.set('cv-focus', serialized);
+            return url;
+        }
+        async generateLink() {
+            const url = this.getShareUrl();
+            if (!url) {
+                ToastManager.show('Please select at least one item.');
+                return;
+            }
+            try {
+                await navigator.clipboard.writeText(url.toString());
+                ToastManager.show('Link copied to clipboard!');
+            }
+            catch (e) {
+                console.error('Clipboard failed', e);
+                ToastManager.show('Failed to copy link.');
+            }
+        }
+        previewLink() {
+            const url = this.getShareUrl();
+            if (!url) {
+                ToastManager.show('Please select at least one item.');
+                return;
+            }
+            window.open(url.toString(), '_blank');
+        }
+        clearHover() {
+            if (this.currentHoverTarget) {
+                this.currentHoverTarget.classList.remove(HIGHLIGHT_TARGET_CLASS);
+                this.currentHoverTarget = null;
+            }
+            if (this.helperEl) {
+                this.helperEl.style.display = 'none';
+            }
+        }
+        cleanup() {
+            document.body.classList.remove('cv-share-mode');
+            this.clearAll();
+            const style = document.getElementById(SHARE_MODE_STYLE_ID);
+            if (style)
+                document.head.removeChild(style);
+            if (this.floatingBarEl) {
+                document.body.removeChild(this.floatingBarEl);
+                this.floatingBarEl = null;
+            }
+            if (this.helperEl) {
+                document.body.removeChild(this.helperEl);
+                this.helperEl = null;
+            }
+            if (this.currentHoverTarget) {
+                this.currentHoverTarget.classList.remove(HIGHLIGHT_TARGET_CLASS);
+                this.currentHoverTarget = null;
+            }
+            document.removeEventListener('mouseover', this.boundHandleHover, true);
+            document.removeEventListener('click', this.boundHandleClick, true);
+            document.removeEventListener('keydown', this.boundHandleKeydown, true);
+            this.isActive = false;
+        }
+    }
+
+    const SHARE_BUTTON_ID = 'cv-share-button';
+    const SHARE_BUTTON_STYLES = `
+  #${SHARE_BUTTON_ID} {
+    position: fixed;
+    bottom: 20px;
+    right: 100px;
+    width: 50px;
+    height: 50px;
+    border-radius: 50%;
+    background-color: #007bff; /* Primary Blue */
+    color: white;
+    border: none;
+    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1), 0 1px 3px rgba(0, 0, 0, 0.08); /* Drop shadow */
+    z-index: 9998; /* Below modals (9999) but above content */
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: opacity 0.3s ease, transform 0.3s ease, background-color 0.2s;
+    opacity: 1;
+    transform: scale(1);
+    padding: 0;
+    margin: 0;
+  }
+
+  #${SHARE_BUTTON_ID}:hover {
+    background-color: #0056b3; /* Darker blue on hover */
+    transform: scale(1.05);
+  }
+
+  #${SHARE_BUTTON_ID}:active {
+    transform: scale(0.95);
+  }
+
+  #${SHARE_BUTTON_ID}.cv-hidden {
+    opacity: 0;
+    pointer-events: none;
+    transform: scale(0.8);
+  }
+
+  @media print {
+    #${SHARE_BUTTON_ID} {
+      display: none !important;
+    }
+  }
+
+  #${SHARE_BUTTON_ID} svg {
+    width: 24px;
+    height: 24px;
+    fill: currentColor;
+  }
+`;
+
+    class ShareButton {
+        shareManager;
+        button = null;
+        boundHandleClick;
+        constructor(shareManager) {
+            this.shareManager = shareManager;
+            this.boundHandleClick = () => this.shareManager.toggleShareMode();
+        }
+        init() {
+            if (this.button)
+                return;
+            this.injectStyles();
+            this.button = this.createButton();
+            document.body.appendChild(this.button);
+            // Subscribe to share manager state changes
+            this.shareManager.addStateChangeListener((isActive) => {
+                this.setShareModeActive(isActive);
+            });
+        }
+        destroy() {
+            if (this.button) {
+                this.button.remove();
+                this.button = null;
+            }
+        }
+        createButton() {
+            const btn = document.createElement('button');
+            btn.id = SHARE_BUTTON_ID;
+            btn.setAttribute('aria-label', 'Share specific sections');
+            btn.title = 'Select sections to share';
+            // Using the link icon from utils, ensuring it's white via CSS currentColor
+            btn.innerHTML = getShareIcon();
+            btn.addEventListener('click', this.boundHandleClick);
+            return btn;
+        }
+        injectStyles() {
+            if (!document.getElementById('cv-share-button-styles')) {
+                const style = document.createElement('style');
+                style.id = 'cv-share-button-styles';
+                style.textContent = SHARE_BUTTON_STYLES;
+                document.head.appendChild(style);
+            }
+        }
+        setShareModeActive(isActive) {
+            if (!this.button)
+                return;
+            if (isActive) {
+                this.button.classList.add('cv-hidden');
+            }
+            else {
+                this.button.classList.remove('cv-hidden');
+            }
+        }
+    }
+
+    const FOCUS_MODE_STYLE_ID = 'cv-focus-mode-styles';
+    const BODY_FOCUS_CLASS = 'cv-focus-mode';
+    const HIDDEN_CLASS = 'cv-focus-hidden';
+    const FOCUSED_CLASS = 'cv-focused-element';
+    const DIVIDER_CLASS = 'cv-context-divider';
+    const EXIT_BANNER_ID = 'cv-exit-focus-banner';
+    const styles = `
+  body.${BODY_FOCUS_CLASS} {
+     /* e.g. potentially hide scrollbars or adjust layout */
+  }
+
+  .${HIDDEN_CLASS} {
+    display: none !important;
+  }
+
+  .${FOCUSED_CLASS} {
+    /* No visual style for focused elements, just logic class for now. Can add borders for debugging*/
+  }
+
+  .${DIVIDER_CLASS} {
+    padding: 12px;
+    margin: 16px 0;
+    background-color: #f8f8f8;
+    border-top: 1px dashed #ccc;
+    border-bottom: 1px dashed #ccc;
+    color: #555;
+    text-align: center;
+    cursor: pointer;
+    font-family: system-ui, sans-serif;
+    font-size: 13px;
+    transition: background-color 0.2s;
+  }
+  .${DIVIDER_CLASS}:hover {
+    background-color: #e8e8e8;
+    color: #333;
+  }
+
+  #${EXIT_BANNER_ID} {
+    position: sticky;
+    top: 0;
+    left: 0;
+    right: 0;
+    background-color: #0078D4;
+    color: white;
+    padding: 10px 20px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 16px;
+    z-index: 100000;
+    font-family: system-ui, sans-serif;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+  }
+
+  #${EXIT_BANNER_ID} button {
+    background: white;
+    color: #0078D4;
+    border: none;
+    padding: 4px 12px;
+    border-radius: 4px;
+    cursor: pointer;
+    font-weight: 600;
+  }
+  #${EXIT_BANNER_ID} button:hover {
+    background: #f0f0f0;
+  }
+`;
+    const FOCUS_MODE_STYLES = styles;
+
+    /**
+     * Manages the "Focus Mode" (Presentation View).
+     * Parses the URL for robust anchors, resolves them, hides irrelevant content, and inserts context dividers.
+     */
+    const FOCUS_PARAM = 'cv-focus';
+    class FocusManager {
+        rootEl;
+        hiddenElements = new Set();
+        dividers = [];
+        exitBanner = null;
+        excludedTags;
+        excludedIds;
+        constructor(rootEl, options) {
+            this.rootEl = rootEl;
+            this.excludedTags = new Set(options.excludedTags.map(t => t.toUpperCase()));
+            this.excludedIds = new Set(options.excludedIds);
+        }
+        /**
+         * Initializes the Focus Manager. Checks URL for focus parameter.
+         */
+        init() {
+            this.handleUrlChange();
+        }
+        handleUrlChange() {
+            const urlParams = new URLSearchParams(window.location.search);
+            const encodedDescriptors = urlParams.get(FOCUS_PARAM);
+            if (encodedDescriptors) {
+                this.applyFocusMode(encodedDescriptors);
+            }
+            else {
+                // encoding missing, ensure we exit focus mode if active
+                if (document.body.classList.contains(BODY_FOCUS_CLASS)) {
+                    this.exitFocusMode();
+                }
+            }
+        }
+        /**
+         * Applies Focus Mode based on encoded descriptors.
+         */
+        applyFocusMode(encodedDescriptors) {
+            const descriptors = AnchorEngine.deserialize(encodedDescriptors);
+            if (!descriptors || descriptors.length === 0)
+                return;
+            // Resolve anchors to DOM elements
+            const targets = [];
+            descriptors.forEach(desc => {
+                const el = AnchorEngine.resolve(this.rootEl, desc);
+                if (el) {
+                    targets.push(el);
+                }
+            });
+            if (targets.length === 0) {
+                ToastManager.show("Some shared sections could not be found.");
+                return;
+            }
+            if (targets.length < descriptors.length) {
+                ToastManager.show("Some shared sections could not be found.");
+            }
+            this.injectStyles();
+            document.body.classList.add(BODY_FOCUS_CLASS);
+            this.renderFocusedView(targets);
+            this.showExitBanner();
+        }
+        injectStyles() {
+            if (document.getElementById(FOCUS_MODE_STYLE_ID))
+                return;
+            const style = document.createElement('style');
+            style.id = FOCUS_MODE_STYLE_ID;
+            style.textContent = FOCUS_MODE_STYLES;
+            document.head.appendChild(style);
+        }
+        /**
+         * Hides irrelevant content and adds dividers.
+         */
+        renderFocusedView(targets) {
+            // 1. Mark targets
+            targets.forEach(t => t.classList.add(FOCUSED_CLASS));
+            // 2. We need to hide siblings of targets (and their ancestors up to root generally, 
+            // but "siblings between focused zones" suggests we are mostly looking at a flat list or specific nesting).
+            //
+            // "All sibling elements between the focused zones are collapsed and hidden."
+            // "If a user selects a parent element, all of its child elements must be visible."
+            //
+            // Algorithm:
+            // Walk up from each target to finding the common container? 
+            // Or just assume targets are somewhat related.
+            //
+            // Let's implement a robust "Hide Siblings" approach.
+            // For every target, we ensure it is visible.
+            // We look at its siblings. If a sibling is NOT a target AND NOT an ancestor of a target, we hide it.
+            // We need to identify all "Keep Visible" elements (targets + ancestors)
+            const keepVisible = new Set();
+            targets.forEach(t => {
+                let curr = t;
+                while (curr && curr !== document.body && curr !== document.documentElement) {
+                    keepVisible.add(curr);
+                    curr = curr.parentElement;
+                }
+            });
+            // Now iterate through siblings of "Keep Visible" elements?
+            // Actually, we can just walk the tree or iterate siblings of targets/ancestors?
+            //
+            // Improved Algorithm: 
+            // 1. Collect all direct siblings of every element in keepVisible set.
+            // 2. If a sibling is NOT in keepVisible, hide it.
+            // To avoid processing the entire DOM, we start from targets and walk up.
+            keepVisible.forEach(el => {
+                if (el === document.body)
+                    return; // Don't hide siblings of body (scripts etc) unless we are sure.
+                // Actually usually we want to hide siblings of the content container.
+                const parent = el.parentElement;
+                if (!parent)
+                    return;
+                // FIX: "Parent Dominance"
+                // If the parent itself is a target (or we otherwise decided its whole content is meaningful),
+                // then we should NOT hide anything inside it.
+                // We check if 'parent' is one of the explicitly resolved targets.
+                // We can check if it has the FOCUSED_CLASS class, since we added it in step 1.
+                if (parent.classList.contains(FOCUSED_CLASS)) {
+                    return;
+                }
+                // Using children because we want element nodes
+                Array.from(parent.children).forEach(child => {
+                    if (child instanceof HTMLElement && !keepVisible.has(child)) {
+                        this.hideElement(child);
+                    }
+                });
+            });
+            // 3. Insert Dividers
+            // We process each container that has hidden elements
+            const processedContainers = new Set();
+            keepVisible.forEach(el => {
+                const parent = el.parentElement;
+                if (parent && !processedContainers.has(parent)) {
+                    this.insertDividersForContainer(parent);
+                    processedContainers.add(parent);
+                }
+            });
+        }
+        hideElement(el) {
+            if (this.hiddenElements.has(el))
+                return; // Already hidden
+            // Exclude by Tag
+            if (this.excludedTags.has(el.tagName.toUpperCase()))
+                return;
+            // Exclude by ID (if strictly matching)
+            if (el.id && this.excludedIds.has(el.id))
+                return;
+            // Also don't hide things that are aria-hidden
+            if (el.getAttribute('aria-hidden') === 'true')
+                return;
+            // Exclude Toast Notification
+            if (el.classList.contains(TOAST_CLASS))
+                return;
+            // We check if it is already hidden (e.g. by previous focus mode run? No, isActive check handles that)
+            // Just mark it.
+            el.classList.add(HIDDEN_CLASS);
+            this.hiddenElements.add(el);
+        }
+        insertDividersForContainer(container) {
+            const children = Array.from(container.children);
+            let hiddenCount = 0;
+            let hiddenGroupStart = null;
+            children.forEach((child) => {
+                if (child.classList.contains(HIDDEN_CLASS)) {
+                    if (hiddenCount === 0)
+                        hiddenGroupStart = child;
+                    hiddenCount++;
+                }
+                else {
+                    // Found a visible element. Was there a hidden group before this?
+                    if (hiddenCount > 0 && hiddenGroupStart) {
+                        this.createDivider(container, hiddenGroupStart, hiddenCount);
+                        hiddenCount = 0;
+                        hiddenGroupStart = null;
+                    }
+                }
+            });
+            // Trailing hidden group
+            if (hiddenCount > 0 && hiddenGroupStart) {
+                this.createDivider(container, hiddenGroupStart, hiddenCount);
+            }
+        }
+        createDivider(container, insertBeforeEl, count) {
+            const divider = document.createElement('div');
+            divider.className = DIVIDER_CLASS;
+            divider.textContent = `... ${count} section${count > 1 ? 's' : ''} hidden (Click to expand) ...`;
+            divider.onclick = () => this.expandContext(insertBeforeEl, count, divider);
+            container.insertBefore(divider, insertBeforeEl);
+            this.dividers.push(divider);
+        }
+        expandContext(firstHidden, count, divider) {
+            // Divider is inserted BEFORE firstHidden.
+            // So firstHidden is the first element to reveal.
+            let curr = firstHidden;
+            let expanded = 0;
+            while (curr && expanded < count) {
+                if (curr instanceof HTMLElement && curr.classList.contains(HIDDEN_CLASS)) {
+                    curr.classList.remove(HIDDEN_CLASS);
+                    this.hiddenElements.delete(curr);
+                }
+                curr = curr.nextElementSibling;
+                // Note: If nested dividers or other elements exist, they shouldn't count?
+                // "Children" iteration in insertDividers covered direct children.
+                // sibling iteration also covers direct children.
+                // We assume contiguous hidden siblings.
+                expanded++;
+            }
+            divider.remove();
+            const idx = this.dividers.indexOf(divider);
+            if (idx > -1)
+                this.dividers.splice(idx, 1);
+            // If no more hidden elements, remove the banner
+            if (this.hiddenElements.size === 0) {
+                this.removeExitBanner();
+            }
+        }
+        removeExitBanner() {
+            if (this.exitBanner) {
+                this.exitBanner.remove();
+                this.exitBanner = null;
+            }
+        }
+        /**
+         * Override of renderFocusedView with robust logic
+         */
+        // (We use the class method `renderFocusedView` and internal helpers)
+        showExitBanner() {
+            if (document.getElementById(EXIT_BANNER_ID))
+                return;
+            const banner = document.createElement('div');
+            banner.id = EXIT_BANNER_ID;
+            banner.innerHTML = `
+        <span>You are viewing a focused selection.</span>
+        <button id="cv-exit-focus-btn">Show Full Page</button>
+      `;
+            document.body.prepend(banner); // Top of body
+            banner.querySelector('button')?.addEventListener('click', () => this.exitFocusMode());
+            this.exitBanner = banner;
+        }
+        exitFocusMode() {
+            document.body.classList.remove(BODY_FOCUS_CLASS);
+            // Show all hidden elements
+            this.hiddenElements.forEach(el => el.classList.remove(HIDDEN_CLASS));
+            this.hiddenElements.clear();
+            // Remove dividers
+            this.dividers.forEach(d => d.remove());
+            this.dividers = [];
+            // Remove styling from targets
+            const targets = document.querySelectorAll(`.${FOCUSED_CLASS}`);
+            targets.forEach(t => t.classList.remove(FOCUSED_CLASS));
+            // Remove banner
+            this.removeExitBanner();
+            // Update URL
+            const url = new URL(window.location.href);
+            url.searchParams.delete(FOCUS_PARAM);
+            window.history.pushState({}, '', url.toString());
+        }
+    }
+
+    const DEFAULT_EXCLUDED_TAGS = ['HEADER', 'NAV', 'FOOTER', 'SCRIPT', 'STYLE'];
+    const DEFAULT_EXCLUDED_IDS = ['cv-floating-action-bar', 'cv-hover-helper', 'cv-toast-notification'];
+
+    const TOGGLE_SELECTOR = "[data-cv-toggle], [data-customviews-toggle], cv-toggle";
+    const TABGROUP_SELECTOR = 'cv-tabgroup';
     class CustomViewsCore {
         rootEl;
         assetsManager;
         persistenceManager;
         visibilityManager;
+        observer = null;
+        shareManager;
+        shareButton;
+        focusManager;
+        componentRegistry = {
+            toggles: new Set(),
+            tabGroups: new Set(),
+        };
         config;
         stateChangeListeners = [];
         showUrlEnabled;
@@ -1382,6 +2606,73 @@ ${TAB_STYLES}
             this.visibilityManager = new VisibilityManager();
             this.showUrlEnabled = opt.showUrl ?? false;
             this.lastAppliedState = this.cloneState(this.getComputedDefaultState());
+            // Resolve Exclusions
+            const excludedTags = [...DEFAULT_EXCLUDED_TAGS, ...(this.config.shareExclusions?.tags || [])];
+            const excludedIds = [...DEFAULT_EXCLUDED_IDS, ...(this.config.shareExclusions?.ids || [])];
+            const commonOptions = { excludedTags, excludedIds };
+            this.shareManager = new ShareManager(commonOptions);
+            this.shareButton = new ShareButton(this.shareManager);
+            this.focusManager = new FocusManager(this.rootEl, commonOptions);
+        }
+        getShareManager() {
+            return this.shareManager;
+        }
+        /**
+         * Toggles the share mode on or off.
+         */
+        toggleShareMode() {
+            this.shareManager.toggleShareMode();
+        }
+        /**
+         * Scan the given element for toggles and tab groups, register them
+         * Returns true if new components were found
+         */
+        scan(element) {
+            let newComponentsFound = false;
+            // Scan for toggles
+            const toggles = Array.from(element.querySelectorAll(TOGGLE_SELECTOR));
+            if (element.matches(TOGGLE_SELECTOR)) {
+                toggles.unshift(element);
+            }
+            toggles.forEach((toggle) => {
+                if (!this.componentRegistry.toggles.has(toggle)) {
+                    this.componentRegistry.toggles.add(toggle);
+                    newComponentsFound = true;
+                }
+            });
+            // Scan for tab groups
+            const tabGroups = Array.from(element.querySelectorAll(TABGROUP_SELECTOR));
+            if (element.matches(TABGROUP_SELECTOR)) {
+                tabGroups.unshift(element);
+            }
+            tabGroups.forEach((tabGroup) => {
+                if (!this.componentRegistry.tabGroups.has(tabGroup)) {
+                    this.componentRegistry.tabGroups.add(tabGroup);
+                    newComponentsFound = true;
+                }
+            });
+            return newComponentsFound;
+        }
+        /**
+         * Unscan the given element for toggles and tab groups, de-register them from registry
+         */
+        unscan(element) {
+            // Unscan for toggles
+            const toggles = Array.from(element.querySelectorAll(TOGGLE_SELECTOR));
+            if (element.matches(TOGGLE_SELECTOR)) {
+                toggles.unshift(element);
+            }
+            toggles.forEach((toggle) => {
+                this.componentRegistry.toggles.delete(toggle);
+            });
+            // Unscan for tab groups
+            const tabGroups = Array.from(element.querySelectorAll(TABGROUP_SELECTOR));
+            if (element.matches(TABGROUP_SELECTOR)) {
+                tabGroups.unshift(element);
+            }
+            tabGroups.forEach((tabGroup) => {
+                this.componentRegistry.tabGroups.delete(tabGroup);
+            });
         }
         getConfig() {
             return this.config;
@@ -1417,7 +2708,7 @@ ${TAB_STYLES}
                 });
             }
             const computedState = {
-                toggles: [...(this.config.allToggles || [])],
+                toggles: this.config.toggles?.map(t => t.id) || [],
                 tabs
             };
             return computedState;
@@ -1456,8 +2747,28 @@ ${TAB_STYLES}
         // Inject styles, setup listeners and call rendering logic
         async init() {
             injectCoreStyles();
-            // Build navigation once (with click and double-click handlers)
-            TabManager.buildNavs(this.rootEl, this.config.tabGroups, 
+            this.scan(this.rootEl);
+            // Initialize all components found on initial scan
+            this.initializeNewComponents();
+            // Apply stored nav visibility preference on page load
+            const navPref = this.persistenceManager.getPersistedTabNavVisibility();
+            if (navPref !== null) {
+                TabManager.setNavsVisibility(this.rootEl, navPref);
+            }
+            // For session history, clicks on back/forward button
+            window.addEventListener("popstate", () => {
+                this.loadAndCallApplyState();
+                this.focusManager.handleUrlChange();
+            });
+            this.loadAndCallApplyState();
+            this.focusManager.init();
+            this.shareButton.init();
+            this.initObserver();
+        }
+        initializeNewComponents() {
+            // Build navigation for any newly added tab groups.
+            // The `data-cv-initialized` attribute in `buildNavs` prevents re-initialization.
+            TabManager.buildNavs(Array.from(this.componentRegistry.tabGroups), this.config.tabGroups, 
             // Single click: update clicked group only (local, no persistence)
             (groupId, tabId, groupEl) => {
                 this.setActiveTab(groupId, tabId, groupEl);
@@ -1473,23 +2784,53 @@ ${TAB_STYLES}
                 const currentToggles = this.getCurrentActiveToggles();
                 const newState = {
                     toggles: currentToggles,
-                    tabs: currentTabs
+                    tabs: currentTabs,
                 };
                 // 2. Apply state with scroll anchor information
                 this.applyState(newState, {
                     scrollAnchor: { element: anchorElement, top: initialTop }
                 });
             });
-            // Apply stored nav visibility preference on page load
-            const navPref = this.persistenceManager.getPersistedTabNavVisibility();
-            if (navPref !== null) {
-                TabManager.setNavsVisibility(this.rootEl, navPref);
-            }
-            // For session history, clicks on back/forward button
-            window.addEventListener("popstate", () => {
-                this.loadAndCallApplyState();
+            // Future components (e.g., toggles, widgets) can be initialized here
+        }
+        initObserver() {
+            this.observer = new MutationObserver((mutations) => {
+                let newComponentsFound = false;
+                for (const mutation of mutations) {
+                    if (mutation.type === 'childList') {
+                        mutation.addedNodes.forEach((node) => {
+                            if (node instanceof Element) {
+                                // Scan the new node for components and add them to the registry
+                                if (this.scan(node)) {
+                                    newComponentsFound = true;
+                                }
+                            }
+                        });
+                        mutation.removedNodes.forEach((node) => {
+                            if (node instanceof Element) {
+                                // Unscan the removed node to cleanup the registry
+                                this.unscan(node);
+                            }
+                        });
+                    }
+                }
+                if (newComponentsFound) {
+                    // Initialize navs for new components.
+                    this.initializeNewComponents();
+                    // Re-apply the last known state. renderState will handle disconnecting
+                    // the observer to prevent infinite loops.
+                    if (this.lastAppliedState) {
+                        this.renderState(this.lastAppliedState);
+                    }
+                }
             });
-            this.loadAndCallApplyState();
+            // Observe only the root element to avoid performance issues on large pages.
+            if (this.rootEl) {
+                this.observer.observe(this.rootEl, {
+                    childList: true,
+                    subtree: true,
+                });
+            }
         }
         // Priority: URL state > persisted state > config default > computed default
         // Also filters using the visibility manager to persist selection
@@ -1543,23 +2884,34 @@ ${TAB_STYLES}
                 ScrollManager.handleScrollAnchor(options.scrollAnchor);
             }
         }
-        /** Render all toggles for the current state */
+        /**
+         * Renders state on components in ComponentRegistry
+         * Applies the given state.
+         * Disconnects the mutation observer during rendering to prevent loops
+         **/
         renderState(state) {
+            this.observer?.disconnect();
             this.lastAppliedState = this.cloneState(state);
             const toggles = state?.toggles || [];
             const finalToggles = this.visibilityManager.filterVisibleToggles(toggles);
+            const toggleElements = Array.from(this.componentRegistry.toggles);
+            const tabGroupElements = Array.from(this.componentRegistry.tabGroups);
             // Apply toggle visibility
-            ToggleManager.applyToggles(this.rootEl, finalToggles);
+            ToggleManager.applyToggles(toggleElements, finalToggles);
             // Render assets into toggles
-            ToggleManager.renderAssets(this.rootEl, finalToggles, this.assetsManager);
+            ToggleManager.renderAssets(toggleElements, finalToggles, this.assetsManager);
             // Apply tab selections
-            TabManager.applyTabSelections(this.rootEl, state.tabs || {}, this.config.tabGroups);
+            TabManager.applyTabSelections(tabGroupElements, state.tabs || {}, this.config.tabGroups);
             // Update nav active states (without rebuilding)
-            TabManager.updateAllNavActiveStates(this.rootEl, state.tabs || {}, this.config.tabGroups);
+            TabManager.updateAllNavActiveStates(tabGroupElements, state.tabs || {}, this.config.tabGroups);
             // Update pin icons to show which tabs are persisted
-            TabManager.updatePinIcons(this.rootEl, state.tabs || {});
+            TabManager.updatePinIcons(tabGroupElements, state.tabs || {});
             // Notify state change listeners (like widgets)
             this.notifyStateChangeListeners();
+            this.observer?.observe(document.body, {
+                childList: true,
+                subtree: true,
+            });
         }
         /**
          * Reset to default state
@@ -1700,10 +3052,11 @@ ${TAB_STYLES}
     }
 
     /**
-     * Custom Elements for Tab Groups and Tabs
+     * Defines the custom elements used by CustomViews.
      */
     /**
-     * <cv-tab> element - represents a single tab panel
+     * `<cv-tab>`: A custom element representing a single tab panel within a tab group.
+     * Its content is displayed when the corresponding tab is active.
      */
     class CVTab extends HTMLElement {
         connectedCallback() {
@@ -1711,7 +3064,8 @@ ${TAB_STYLES}
         }
     }
     /**
-     * <cv-tabgroup> element - represents a group of tabs
+     * `<cv-tabgroup>`: A custom element that encapsulates a set of tabs (`<cv-tab>`).
+     * It manages the tab navigation and content visibility for the group.
      */
     class CVTabgroup extends HTMLElement {
         connectedCallback() {
@@ -1727,7 +3081,7 @@ ${TAB_STYLES}
         }
     }
     /**
-     * <cv-toggle> element - represents a toggleable content block
+     * `<cv-toggle>`: A custom element for creating a toggleable content block.
      */
     class CVToggle extends HTMLElement {
         connectedCallback() {
@@ -1735,8 +3089,8 @@ ${TAB_STYLES}
         }
     }
     /**
-     * <cv-tab-header> element - represents tab header with rich HTML formatting
-     * Content is extracted and used in the navigation link
+     * `<cv-tab-header>`: A semantic container for a tab's header content.
+     * The content of this element is used to create the navigation link for the tab.
      */
     class CVTabHeader extends HTMLElement {
         connectedCallback() {
@@ -1744,8 +3098,7 @@ ${TAB_STYLES}
         }
     }
     /**
-     * <cv-tab-body> element - represents tab body content
-     * Semantic container for tab panel content
+     * `<cv-tab-body>`: A semantic container for the main content of a tab panel.
      */
     class CVTabBody extends HTMLElement {
         connectedCallback() {
@@ -1753,7 +3106,7 @@ ${TAB_STYLES}
         }
     }
     /**
-     * Register custom elements
+     * Registers all CustomViews custom elements with the CustomElementRegistry.
      */
     function registerCustomElements() {
         // Only register if not already defined
@@ -1811,7 +3164,7 @@ ${TAB_STYLES}
             else {
                 console.error("No config provided, using minimal default config");
                 // Create a minimal default config
-                config = { allToggles: [], defaultState: {} };
+                config = { toggles: [], defaultState: {} };
             }
             const coreOptions = {
                 assetsManager,
@@ -2068,6 +3421,10 @@ ${TAB_STYLES}
   animation: fadeIn 0.2s ease;
 }
 
+.cv-widget-modal-overlay.cv-hidden {
+  display: none;
+}
+
 @keyframes fadeIn {
   from { opacity: 0; }
   to { opacity: 1; }
@@ -2924,8 +4281,11 @@ ${TAB_STYLES}
         container;
         widgetIcon = null;
         options;
+        _hasVisibleConfig = false;
+        pageToggleIds = new Set();
+        pageTabIds = new Set();
         // Modal state
-        modal = null;
+        stateModal = null;
         constructor(options) {
             this.core = options.core;
             this.container = options.container || document.body;
@@ -2943,12 +4303,41 @@ ${TAB_STYLES}
                 welcomeMessage: options.welcomeMessage || 'This site is powered by Custom Views. Use the widget on the side (⚙) to customize your experience. Your preferences will be saved and can be shared via URL.<br><br>Learn more at <a href="https://github.com/customviews-js/customviews" target="_blank">customviews GitHub</a>.',
                 showTabGroups: options.showTabGroups ?? true
             };
-            // No external state manager to initialize
+            // Determine if there are any configurations to show
+            const config = this.core.getConfig();
+            const allToggles = config?.toggles || [];
+            const visibleToggles = allToggles.filter(toggle => {
+                if (toggle.isLocal) {
+                    return !!document.querySelector(`[data-cv-toggle="${toggle.id}"], [data-cv-toggle-group-id="${toggle.id}"]`);
+                }
+                return true;
+            });
+            const allTabGroups = this.core.getTabGroups() || [];
+            const visibleTabGroups = allTabGroups.filter(group => {
+                if (group.isLocal) {
+                    return !!document.querySelector(`cv-tabgroup[id="${group.id}"]`);
+                }
+                return true;
+            });
+            if (visibleToggles.length > 0 || (this.options.showTabGroups && visibleTabGroups.length > 0)) {
+                this._hasVisibleConfig = true;
+            }
+            // Scan for page-declared local components and cache them
+            // Do this on initialization to avoid querying DOM repeatedly
+            const pageTogglesAttr = document.querySelector('[data-cv-page-local-toggles]')?.getAttribute('data-cv-page-local-toggles') || '';
+            this.pageToggleIds = new Set(pageTogglesAttr.split(',').map(id => id.trim()).filter(id => id));
+            const pageTabsAttr = document.querySelector('[data-cv-page-local-tabs]')?.getAttribute('data-cv-page-local-tabs') || '';
+            this.pageTabIds = new Set(pageTabsAttr.split(',').map(id => id.trim()).filter(id => id));
         }
         /**
-         * Render the widget
+         * Render the widget modal icon
+         *
+         * Does not render if there are no visible toggles or tab groups.
          */
-        render() {
+        renderModalIcon() {
+            if (!this._hasVisibleConfig) {
+                return;
+            }
             this.widgetIcon = this.createWidgetIcon();
             this.attachEventListeners();
             // Always append to body since it's a floating icon
@@ -2981,9 +4370,9 @@ ${TAB_STYLES}
                 this.widgetIcon = null;
             }
             // Clean up modal
-            if (this.modal) {
-                this.modal.remove();
-                this.modal = null;
+            if (this.stateModal) {
+                this.stateModal.remove();
+                this.stateModal = null;
             }
         }
         attachEventListeners() {
@@ -2996,49 +4385,71 @@ ${TAB_STYLES}
          * Close the modal
          */
         closeModal() {
-            if (this.modal) {
-                this.modal.remove();
-                this.modal = null;
+            if (this.stateModal) {
+                this.stateModal.classList.add('cv-hidden');
             }
         }
         /**
          * Open the custom state creator
          */
         openStateModal() {
-            // Get toggles from current configuration and open the modal regardless of count
-            const config = this.core.getConfig();
-            const toggles = config?.allToggles || [];
-            this.createCustomStateModal(toggles);
+            if (!this.stateModal) {
+                this._createStateModal();
+            }
+            this._updateStateModalContent();
+            this.stateModal.classList.remove('cv-hidden');
         }
         /**
-         * Create the custom state creator modal
+         * Create the custom state creator modal shell and attach listeners
          */
-        createCustomStateModal(toggles) {
-            // Close existing modal
-            this.closeModal();
-            this.modal = document.createElement('div');
-            this.modal.className = 'cv-widget-modal-overlay';
+        _createStateModal() {
+            this.stateModal = document.createElement('div');
+            this.stateModal.className = 'cv-widget-modal-overlay cv-hidden';
             this.applyThemeToModal();
-            const toggleControlsHtml = toggles.map(toggle => `
+            document.body.appendChild(this.stateModal);
+            this._attachStateModalFrameEventListeners();
+        }
+        /**
+         * Update the content of the state modal
+         */
+        _updateStateModalContent() {
+            if (!this.stateModal)
+                return;
+            const pageToggleIds = this.pageToggleIds;
+            const pageTabIds = this.pageTabIds;
+            // Get toggles from current configuration
+            const config = this.core.getConfig();
+            const allToggles = config?.toggles || [];
+            // Filter toggles to only include global and visible/declared local toggles
+            const visibleToggles = allToggles.filter(toggle => {
+                if (toggle.isLocal) {
+                    return pageToggleIds.has(toggle.id) || !!document.querySelector(`[data-cv-toggle="${toggle.id}"], [data-cv-toggle-group-id="${toggle.id}"]`);
+                }
+                return true; // Keep global toggles
+            });
+            const toggleControlsHtml = visibleToggles.map(toggle => `
       <div class="cv-toggle-card">
         <div class="cv-toggle-content">
           <div>
-            <p class="cv-toggle-title">${this.formatToggleName(toggle)}</p>
+            <p class="cv-toggle-title">${toggle.label || toggle.id}</p>
           </div>
           <label class="cv-toggle-label">
-            <input class="cv-toggle-input" type="checkbox" data-toggle="${toggle}"/>
+            <input class="cv-toggle-input" type="checkbox" data-toggle="${toggle.id}"/>
             <span class="cv-toggle-slider"></span>
           </label>
         </div>
       </div>
     `).join('');
-            // Todo: Re-add description if needed (Line 168, add label field to toggles if needed change structure)
-            // <p class="cv-toggle-description">Show or hide the ${this.formatToggleName(toggle).toLowerCase()} area </p>
             // Get tab groups
-            const tabGroups = this.core.getTabGroups();
+            const allTabGroups = this.core.getTabGroups() || [];
+            const tabGroups = allTabGroups.filter(group => {
+                if (group.isLocal) {
+                    return pageTabIds.has(group.id) || !!document.querySelector(`cv-tabgroup[id="${group.id}"]`);
+                }
+                return true; // Keep global tab groups
+            });
             let tabGroupControlsHTML = '';
             if (this.options.showTabGroups && tabGroups && tabGroups.length > 0) {
-                // Determine initial nav visibility state
                 const initialNavsVisible = TabManager.areNavsVisible(document.body);
                 tabGroupControlsHTML = `
         <div class="cv-tabgroup-card cv-tabgroup-header">
@@ -3073,7 +4484,7 @@ ${TAB_STYLES}
         </div>
       `;
             }
-            this.modal.innerHTML = `
+            this.stateModal.innerHTML = `
       <div class="cv-widget-modal cv-custom-state-modal">
         <header class="cv-modal-header">
           <div class="cv-modal-header-content">
@@ -3089,7 +4500,7 @@ ${TAB_STYLES}
         <main class="cv-modal-main">
           ${this.options.description ? `<p class="cv-modal-description">${this.options.description}</p>` : ''}
           
-          ${toggles.length ? `
+          ${visibleToggles.length ? `
           <div class="cv-content-section">
             <div class="cv-section-heading">Toggles</div>
             <div class="cv-toggles-container">
@@ -3119,65 +4530,80 @@ ${TAB_STYLES}
             <span>Copy Shareable URL</span>
             <span class="cv-share-btn-icon">${getCopyIcon()}</span>
           </button>
+
         </footer>
       </div>
     `;
-            document.body.appendChild(this.modal);
-            this.attachStateModalEventListeners();
-            // Load current state into form if we're already in a custom state
+            this._attachStateModalContentEventListeners();
             this.loadCurrentStateIntoForm();
         }
         /**
-         * Attach event listeners for custom state creator
+         * Attach event listeners for the modal frame (delegated events)
          */
-        attachStateModalEventListeners() {
-            if (!this.modal)
+        _attachStateModalFrameEventListeners() {
+            if (!this.stateModal)
                 return;
-            // Close button
-            const closeBtn = this.modal.querySelector('.cv-modal-close');
-            if (closeBtn) {
-                closeBtn.addEventListener('click', () => {
+            // Delegated click events
+            this.stateModal.addEventListener('click', (e) => {
+                const target = e.target;
+                // Close button
+                if (target.closest('.cv-modal-close')) {
                     this.closeModal();
-                });
-            }
-            // Copy URL button
-            const copyUrlBtn = this.modal.querySelector('.cv-share-btn');
-            if (copyUrlBtn) {
-                copyUrlBtn.addEventListener('click', () => {
+                    return;
+                }
+                // Copy URL button
+                if (target.closest('.cv-share-btn')) {
                     this.copyShareableURL();
-                    // Visual feedback: change icon to tick for 3 seconds
-                    const iconContainer = copyUrlBtn.querySelector('.cv-share-btn-icon');
+                    const copyUrlBtn = target.closest('.cv-share-btn');
+                    const iconContainer = copyUrlBtn?.querySelector('.cv-share-btn-icon');
                     if (iconContainer) {
                         const originalIcon = iconContainer.innerHTML;
                         iconContainer.innerHTML = getTickIcon();
-                        // Revert after 3 seconds
                         setTimeout(() => {
                             iconContainer.innerHTML = originalIcon;
                         }, 3000);
                     }
-                });
-            }
-            // Reset to default button
-            const resetBtn = this.modal.querySelector('.cv-reset-btn');
-            if (resetBtn) {
-                resetBtn.addEventListener('click', () => {
-                    // Add spinning animation to icon
-                    const resetIcon = resetBtn.querySelector('.cv-reset-btn-icon');
+                    return;
+                }
+                // Reset to default button
+                if (target.closest('.cv-reset-btn')) {
+                    const resetBtn = target.closest('.cv-reset-btn');
+                    const resetIcon = resetBtn?.querySelector('.cv-reset-btn-icon');
                     if (resetIcon) {
                         resetIcon.classList.add('cv-spinning');
                     }
                     this.core.resetToDefault();
                     this.loadCurrentStateIntoForm();
-                    // Remove spinning animation after it completes
                     setTimeout(() => {
                         if (resetIcon) {
                             resetIcon.classList.remove('cv-spinning');
                         }
-                    }, 600); // 600ms matches the animation duration
-                });
-            }
+                    }, 600);
+                    return;
+                }
+                // Overlay click to close
+                if (e.target === this.stateModal) {
+                    this.closeModal();
+                }
+            });
+            // Escape key to close
+            const handleEscape = (e) => {
+                if (e.key === 'Escape') {
+                    this.closeModal();
+                }
+            };
+            // We can't remove this listener easily if it's anonymous, so we attach it to the document
+            // and it will stay for the lifetime of the widget. This is acceptable.
+            document.addEventListener('keydown', handleEscape);
+        }
+        /**
+         * Attach event listeners for custom state creator's dynamic content
+         */
+        _attachStateModalContentEventListeners() {
+            if (!this.stateModal)
+                return;
             // Listen to toggle switches
-            const toggleInputs = this.modal.querySelectorAll('.cv-toggle-input');
+            const toggleInputs = this.stateModal.querySelectorAll('.cv-toggle-input');
             toggleInputs.forEach(toggleInput => {
                 toggleInput.addEventListener('change', () => {
                     const state = this.getCurrentCustomStateFromModal();
@@ -3185,17 +4611,14 @@ ${TAB_STYLES}
                 });
             });
             // Listen to tab group selects
-            const tabGroupSelects = this.modal.querySelectorAll('.cv-tabgroup-select');
+            const tabGroupSelects = this.stateModal.querySelectorAll('.cv-tabgroup-select');
             tabGroupSelects.forEach(select => {
                 select.addEventListener('change', () => {
                     const groupId = select.dataset.groupId;
                     const tabId = select.value;
                     if (groupId && tabId) {
-                        // Get current state and update the tab for this group, then apply globally
-                        // This triggers sync behavior and persistence
                         const currentTabs = this.core.getCurrentActiveTabs();
                         currentTabs[groupId] = tabId;
-                        // Apply state globally for persistence and sync
                         const currentToggles = this.core.getCurrentActiveToggles();
                         const newState = {
                             toggles: currentToggles,
@@ -3206,84 +4629,56 @@ ${TAB_STYLES}
                 });
             });
             // Listener for show/hide tab navs
-            const tabNavToggle = this.modal.querySelector('.cv-nav-pref-input');
-            const navIcon = this.modal?.querySelector('#cv-nav-icon');
-            const navHeaderCard = this.modal?.querySelector('.cv-tabgroup-card.cv-tabgroup-header');
+            const tabNavToggle = this.stateModal.querySelector('.cv-nav-pref-input');
+            const navIcon = this.stateModal?.querySelector('#cv-nav-icon');
+            const navHeaderCard = this.stateModal?.querySelector('.cv-tabgroup-card.cv-tabgroup-header');
             if (tabNavToggle && navIcon && navHeaderCard) {
-                // Helper to update icon based on state
                 const updateIcon = (isVisible, isHovering = false) => {
                     if (isHovering) {
-                        // On hover, show the transition icon
                         navIcon.innerHTML = getNavDashed();
                     }
                     else {
-                        // Normal state, show the status icon (on if visible, off if hidden)
                         navIcon.innerHTML = isVisible ? getNavHeadingOnIcon() : getNavHeadingOffIcon();
                     }
                 };
-                // Add hover listeners to entire header card
-                navHeaderCard.addEventListener('mouseenter', () => {
-                    updateIcon(tabNavToggle.checked, true);
-                });
-                navHeaderCard.addEventListener('mouseleave', () => {
-                    updateIcon(tabNavToggle.checked, false);
-                });
-                // Add change listener
+                navHeaderCard.addEventListener('mouseenter', () => updateIcon(tabNavToggle.checked, true));
+                navHeaderCard.addEventListener('mouseleave', () => updateIcon(tabNavToggle.checked, false));
                 tabNavToggle.addEventListener('change', () => {
                     const visible = tabNavToggle.checked;
-                    // Update the icon based on new state (not hovering)
                     updateIcon(visible, false);
-                    // Persist preference via core
                     this.core.persistTabNavVisibility(visible);
-                    // Apply to DOM using TabManager via core
                     try {
-                        const rootEl = document.body;
-                        TabManager.setNavsVisibility(rootEl, visible);
+                        TabManager.setNavsVisibility(document.body, visible);
                     }
                     catch (e) {
-                        // ignore errors
                         console.error('Failed to set tab nav visibility:', e);
                     }
                 });
             }
-            // Overlay click to close
-            this.modal.addEventListener('click', (e) => {
-                if (e.target === this.modal) {
-                    this.closeModal();
-                }
-            });
-            // Escape key to close
-            const handleEscape = (e) => {
-                if (e.key === 'Escape') {
-                    this.closeModal();
-                    document.removeEventListener('keydown', handleEscape);
-                }
-            };
-            document.addEventListener('keydown', handleEscape);
         }
         /**
          * Apply theme class to the modal overlay based on options
          */
         applyThemeToModal() {
-            if (!this.modal)
+            if (!this.stateModal)
                 return;
             if (this.options.theme === 'dark') {
-                this.modal.classList.add('cv-widget-theme-dark');
+                this.stateModal.classList.add('cv-widget-theme-dark');
             }
             else {
-                this.modal.classList.remove('cv-widget-theme-dark');
+                this.stateModal.classList.remove('cv-widget-theme-dark');
             }
         }
         /**
          * Get current state from form values
          */
         getCurrentCustomStateFromModal() {
-            if (!this.modal) {
+            if (!this.stateModal) {
                 return {};
             }
             // Collect toggle values
             const toggles = [];
-            const toggleInputs = this.modal.querySelectorAll('.cv-toggle-input');
+            const toggleInputs = this.stateModal.querySelectorAll('.cv-toggle-input');
             toggleInputs.forEach(toggleInput => {
                 const toggle = toggleInput.dataset.toggle;
                 if (toggle && toggleInput.checked) {
@@ -3291,7 +4686,7 @@ ${TAB_STYLES}
                 }
             });
             // Collect tab selections
-            const tabGroupSelects = this.modal.querySelectorAll('.cv-tabgroup-select');
+            const tabGroupSelects = this.stateModal.querySelectorAll('.cv-tabgroup-select');
             const tabs = {};
             tabGroupSelects.forEach(select => {
                 const groupId = select.dataset.groupId;
@@ -3319,25 +4714,25 @@ ${TAB_STYLES}
          * Load current state into form based on currently active toggles
          */
         loadCurrentStateIntoForm() {
-            if (!this.modal)
+            if (!this.stateModal)
                 return;
             // Get currently active toggles (from custom state or default configuration)
             const activeToggles = this.core.getCurrentActiveToggles();
             // First, uncheck all toggle inputs
-            const allToggleInputs = this.modal.querySelectorAll('.cv-toggle-input');
+            const allToggleInputs = this.stateModal.querySelectorAll('.cv-toggle-input');
             allToggleInputs.forEach(toggleInput => {
                 toggleInput.checked = false;
             });
             // Then check the ones that should be active
             activeToggles.forEach(toggle => {
-                const toggleInput = this.modal?.querySelector(`[data-toggle="${toggle}"]`);
+                const toggleInput = this.stateModal?.querySelector(`[data-toggle="${toggle}"]`);
                 if (toggleInput) {
                     toggleInput.checked = true;
                 }
             });
             // Load tab group selections
             const activeTabs = this.core.getCurrentActiveTabs();
-            const tabGroupSelects = this.modal.querySelectorAll('.cv-tabgroup-select');
+            const tabGroupSelects = this.stateModal.querySelectorAll('.cv-tabgroup-select');
             tabGroupSelects.forEach(select => {
                 const groupId = select.dataset.groupId;
                 if (groupId && activeTabs[groupId]) {
@@ -3352,8 +4747,8 @@ ${TAB_STYLES}
                 }
                 return TabManager.areNavsVisible(document.body);
             })();
-            const tabNavToggle = this.modal.querySelector('.cv-nav-pref-input');
-            const navIcon = this.modal?.querySelector('#cv-nav-icon');
+            const tabNavToggle = this.stateModal.querySelector('.cv-nav-pref-input');
+            const navIcon = this.stateModal?.querySelector('#cv-nav-icon');
             if (tabNavToggle) {
                 tabNavToggle.checked = navPref;
                 // Ensure UI matches actual visibility
@@ -3364,33 +4759,22 @@ ${TAB_STYLES}
                 }
             }
         }
-        /**
-         * Format toggle name for display
-         */
-        formatToggleName(toggle) {
-            return toggle.charAt(0).toUpperCase() + toggle.slice(1);
-        }
         /**
          * Check if this is the first visit and show welcome modal
          */
         showWelcomeModalIfFirstVisit() {
+            if (!this._hasVisibleConfig)
+                return;
             const STORAGE_KEY = 'cv-welcome-shown';
             // Check if welcome has been shown before
             const hasSeenWelcome = localStorage.getItem(STORAGE_KEY);
             if (!hasSeenWelcome) {
-                // Check if this page has any custom views elements
-                const hasCustomViewElements = document.querySelector('cv-tabgroup') !== null ||
-                    document.querySelector('cv-tab') !== null ||
-                    document.querySelector('cv-toggle') !== null ||
-                    document.querySelector('[data-cv-toggle]') !== null;
-                if (hasCustomViewElements) {
-                    // Show welcome modal after a short delay to let the page settle
-                    setTimeout(() => {
-                        this.createWelcomeModal();
-                    }, 500);
-                    // Mark as shown
-                    localStorage.setItem(STORAGE_KEY, 'true');
-                }
+                // Show welcome modal after a short delay to let the page settle
+                setTimeout(() => {
+                    this.createWelcomeModal();
+                }, 500);
+                // Mark as shown
+                localStorage.setItem(STORAGE_KEY, 'true');
             }
         }
         /**
@@ -3398,12 +4782,14 @@ ${TAB_STYLES}
          */
         createWelcomeModal() {
             // Don't show if there's already a modal open
-            if (this.modal)
+            if (this.stateModal && !this.stateModal.classList.contains('cv-hidden'))
                 return;
-            this.modal = document.createElement('div');
-            this.modal.className = 'cv-widget-modal-overlay cv-welcome-modal-overlay';
-            this.applyThemeToModal();
-            this.modal.innerHTML = `
+            const welcomeModal = document.createElement('div');
+            welcomeModal.className = 'cv-widget-modal-overlay cv-welcome-modal-overlay';
+            if (this.options.theme === 'dark') {
+                welcomeModal.classList.add('cv-widget-theme-dark');
+            }
+            welcomeModal.innerHTML = `
       <div class="cv-widget-modal cv-welcome-modal">
         <header class="cv-modal-header">
           <div class="cv-modal-header-content">
@@ -3427,33 +4813,32 @@ ${TAB_STYLES}
         </div>
       </div>
     `;
-            document.body.appendChild(this.modal);
-            this.attachWelcomeModalEventListeners();
+            document.body.appendChild(welcomeModal);
+            this.attachWelcomeModalEventListeners(welcomeModal);
         }
         /**
          * Attach event listeners for welcome modal
          */
-        attachWelcomeModalEventListeners() {
-            if (!this.modal)
-                return;
+        attachWelcomeModalEventListeners(welcomeModal) {
+            const closeModal = () => {
+                welcomeModal.remove();
+                document.removeEventListener('keydown', handleEscape);
+            };
             // Got it button
-            const gotItBtn = this.modal.querySelector('.cv-welcome-got-it');
+            const gotItBtn = welcomeModal.querySelector('.cv-welcome-got-it');
             if (gotItBtn) {
-                gotItBtn.addEventListener('click', () => {
-                    this.closeModal();
-                });
+                gotItBtn.addEventListener('click', closeModal);
             }
             // Overlay click to close
-            this.modal.addEventListener('click', (e) => {
-                if (e.target === this.modal) {
-                    this.closeModal();
+            welcomeModal.addEventListener('click', (e) => {
+                if (e.target === welcomeModal) {
+                    closeModal();
                 }
             });
             // Escape key to close
             const handleEscape = (e) => {
                 if (e.key === 'Escape') {
-                    this.closeModal();
-                    document.removeEventListener('keydown', handleEscape);
+                    closeModal();
                 }
             };
             document.addEventListener('keydown', handleEscape);
@@ -3523,7 +4908,7 @@ ${TAB_STYLES}
                         console.warn(`[CustomViews] Config file not found at ${fullConfigPath}. Using defaults.`);
                         // Provide minimal default config structure
                         configFile = {
-                            config: { allToggles: [], defaultState: {} },
+                            config: { toggles: [], defaultState: {} },
                             widget: { enabled: true }
                         };
                     }
@@ -3561,7 +4946,7 @@ ${TAB_STYLES}
                         core,
                         ...configFile.widget
                     });
-                    widget.render();
+                    widget.renderModalIcon();
                     // Store widget instance
                     window.customViewsInstance.widget = widget;
                     console.log('[CustomViews] Widget initialized and rendered');