@customviews-js/customviews 1.1.11 → 1.3.0

package/dist/custom-views.core.cjs.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.
  */
@@ -156,7 +156,9 @@ class URLStateManager {
         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 {
@@ -170,6 +172,10 @@ class URLStateManager {
             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;
@@ -191,7 +197,9 @@ class URLStateManager {
         }
     }
     /**
-     * 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 {
@@ -230,6 +238,10 @@ class URLStateManager {
                     }
                 }
             }
+            // Reconstruct Focus
+            if (Array.isArray(compact.f)) {
+                state.focus = compact.f;
+            }
             return state;
         }
         catch (error) {
@@ -414,9 +426,15 @@ function getPinIcon(isPinned = false) {
     </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';
@@ -432,11 +450,9 @@ class TabManager {
         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
@@ -541,10 +557,18 @@ class TabManager {
     /**
      * 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
@@ -748,8 +772,7 @@ class TabManager {
     /**
      * 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)
@@ -812,7 +835,7 @@ class TabManager {
      */
     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)) {
@@ -824,9 +847,8 @@ class TabManager {
     /**
      * 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)
@@ -976,33 +998,31 @@ function renderAssetInto(el, assetId, assetsManager) {
     }
 }
 
-// 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';
             }
         });
     }
@@ -1038,6 +1058,21 @@ class ToggleManager {
             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
@@ -1361,11 +1396,1200 @@ function injectCoreStyles() {
     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;
@@ -1378,6 +2602,73 @@ class CustomViewsCore {
         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;
@@ -1413,7 +2704,7 @@ class CustomViewsCore {
             });
         }
         const computedState = {
-            toggles: [...(this.config.allToggles || [])],
+            toggles: this.config.toggles?.map(t => t.id) || [],
             tabs
         };
         return computedState;
@@ -1452,8 +2743,28 @@ class CustomViewsCore {
     // 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);
@@ -1469,23 +2780,53 @@ class CustomViewsCore {
             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
@@ -1539,23 +2880,34 @@ class CustomViewsCore {
             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
@@ -1696,10 +3048,11 @@ function prependBaseUrl(path, baseUrl) {
 }
 
 /**
- * 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() {
@@ -1707,7 +3060,8 @@ class CVTab extends HTMLElement {
     }
 }
 /**
- * <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() {
@@ -1723,7 +3077,7 @@ class CVTabgroup extends HTMLElement {
     }
 }
 /**
- * <cv-toggle> element - represents a toggleable content block
+ * `<cv-toggle>`: A custom element for creating a toggleable content block.
  */
 class CVToggle extends HTMLElement {
     connectedCallback() {
@@ -1731,8 +3085,8 @@ class CVToggle extends HTMLElement {
     }
 }
 /**
- * <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() {
@@ -1740,8 +3094,7 @@ class CVTabHeader extends HTMLElement {
     }
 }
 /**
- * <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() {
@@ -1749,7 +3102,7 @@ class CVTabBody extends HTMLElement {
     }
 }
 /**
- * Register custom elements
+ * Registers all CustomViews custom elements with the CustomElementRegistry.
  */
 function registerCustomElements() {
     // Only register if not already defined
@@ -1807,7 +3160,7 @@ class CustomViews {
         else {
             console.error("No config provided, using minimal default config");
             // Create a minimal default config
-            config = { allToggles: [], defaultState: {} };
+            config = { toggles: [], defaultState: {} };
         }
         const coreOptions = {
             assetsManager,
@@ -2064,6 +3417,10 @@ const WIDGET_STYLES = `
   animation: fadeIn 0.2s ease;
 }
 
+.cv-widget-modal-overlay.cv-hidden {
+  display: none;
+}
+
 @keyframes fadeIn {
   from { opacity: 0; }
   to { opacity: 1; }
@@ -2920,8 +4277,11 @@ class CustomViewsWidget {
     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;
@@ -2939,12 +4299,41 @@ class CustomViewsWidget {
             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
@@ -2977,9 +4366,9 @@ class CustomViewsWidget {
             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() {
@@ -2992,49 +4381,71 @@ class CustomViewsWidget {
      * 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">
@@ -3069,7 +4480,7 @@ class CustomViewsWidget {
         </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">
@@ -3085,7 +4496,7 @@ class CustomViewsWidget {
         <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">
@@ -3115,65 +4526,80 @@ class CustomViewsWidget {
             <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();
@@ -3181,17 +4607,14 @@ class CustomViewsWidget {
             });
         });
         // 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,
@@ -3202,84 +4625,56 @@ class CustomViewsWidget {
             });
         });
         // 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) {
@@ -3287,7 +4682,7 @@ class CustomViewsWidget {
             }
         });
         // 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;
@@ -3315,25 +4710,25 @@ class CustomViewsWidget {
      * 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]) {
@@ -3348,8 +4743,8 @@ class CustomViewsWidget {
             }
             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
@@ -3360,33 +4755,22 @@ class CustomViewsWidget {
             }
         }
     }
-    /**
-     * 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');
         }
     }
     /**
@@ -3394,12 +4778,14 @@ class CustomViewsWidget {
      */
     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">
@@ -3423,33 +4809,32 @@ class CustomViewsWidget {
         </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);
@@ -3519,7 +4904,7 @@ function initializeFromScript() {
                     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 }
                     };
                 }
@@ -3557,7 +4942,7 @@ function initializeFromScript() {
                     core,
                     ...configFile.widget
                 });
-                widget.render();
+                widget.renderModalIcon();
                 // Store widget instance
                 window.customViewsInstance.widget = widget;
                 console.log('[CustomViews] Widget initialized and rendered');