mount-observer 0.1.0 → 0.1.1

package/Events.js

@@ -1,44 +1,78 @@
-// Event classes for MountObserver
-import { mountEventName, dismountEventName, disconnectEventName, loadEventName, attrchangeEventName } from './constants.js';
+// Event name constants
+export const loadEventName = 'load';
+export const mountEventName = 'mount';
+export const dismountEventName = 'dismount';
+export const disconnectEventName = 'disconnect';
+export const attrchangeEventName = 'attrchange';
+export const mediamatchEventName = 'mediamatch';
+export const mediaunmatchEventName = 'mediaunmatch';
 export class MountEvent extends Event {
     matchingElement;
     modules;
+    mountInit;
     static eventName = mountEventName;
-    constructor(matchingElement, modules) {
+    constructor(matchingElement, modules, mountInit) {
         super(MountEvent.eventName);
         this.matchingElement = matchingElement;
         this.modules = modules;
+        this.mountInit = mountInit;
     }
 }
 export class DismountEvent extends Event {
     matchingElement;
+    reason;
+    mountInit;
     static eventName = dismountEventName;
-    constructor(matchingElement) {
+    constructor(matchingElement, reason, mountInit) {
         super(DismountEvent.eventName);
         this.matchingElement = matchingElement;
+        this.reason = reason;
+        this.mountInit = mountInit;
     }
 }
 export class DisconnectEvent extends Event {
     matchingElement;
+    mountInit;
     static eventName = disconnectEventName;
-    constructor(matchingElement) {
+    constructor(matchingElement, mountInit) {
         super(DisconnectEvent.eventName);
         this.matchingElement = matchingElement;
+        this.mountInit = mountInit;
     }
 }
 export class LoadEvent extends Event {
     modules;
+    mountInit;
     static eventName = loadEventName;
-    constructor(modules) {
+    constructor(modules, mountInit) {
         super(LoadEvent.eventName);
         this.modules = modules;
+        this.mountInit = mountInit;
     }
 }
 export class AttrChangeEvent extends Event {
     changes;
+    mountInit;
     static eventName = attrchangeEventName;
-    constructor(changes) {
+    constructor(changes, mountInit) {
         super(AttrChangeEvent.eventName);
         this.changes = changes;
+        this.mountInit = mountInit;
+    }
+}
+export class MediaMatchEvent extends Event {
+    mountInit;
+    static eventName = mediamatchEventName;
+    constructor(mountInit) {
+        super(MediaMatchEvent.eventName);
+        this.mountInit = mountInit;
+    }
+}
+export class MediaUnmatchEvent extends Event {
+    mountInit;
+    static eventName = mediaunmatchEventName;
+    constructor(mountInit) {
+        super(MediaUnmatchEvent.eventName);
+        this.mountInit = mountInit;
     }
 }

package/Events.ts

@@ -1,17 +1,19 @@
 // Event classes for MountObserver
-import {
-    mountEventName,
-    dismountEventName,
-    disconnectEventName,
-    loadEventName,
-    attrchangeEventName
-} from './constants.js';
-import type { IMountEvent, IDismountEvent, IAttrChangeEvent, AttrChange } from './types.js';
+import type { IMountEvent, IDismountEvent, IAttrChangeEvent, AttrChange, MountInit, DismountReason } from './types.js';
+
+// Event name constants
+export const loadEventName = 'load';
+export const mountEventName = 'mount';
+export const dismountEventName = 'dismount';
+export const disconnectEventName = 'disconnect';
+export const attrchangeEventName = 'attrchange';
+export const mediamatchEventName = 'mediamatch';
+export const mediaunmatchEventName = 'mediaunmatch';
 
 export class MountEvent extends Event implements IMountEvent {
     static eventName: typeof mountEventName = mountEventName;
     
-    constructor(public matchingElement: Element, public modules: any[]) {
+    constructor(public matchingElement: Element, public modules: any[], public mountInit: MountInit) {
         super(MountEvent.eventName);
     }
 }
@@ -19,7 +21,7 @@ export class MountEvent extends Event implements IMountEvent {
 export class DismountEvent extends Event implements IDismountEvent {
     static eventName: typeof dismountEventName = dismountEventName;
     
-    constructor(public matchingElement: Element) {
+    constructor(public matchingElement: Element, public reason: DismountReason, public mountInit: MountInit) {
         super(DismountEvent.eventName);
     }
 }
@@ -27,7 +29,7 @@ export class DismountEvent extends Event implements IDismountEvent {
 export class DisconnectEvent extends Event {
     static eventName: typeof disconnectEventName = disconnectEventName;
     
-    constructor(public matchingElement: Element) {
+    constructor(public matchingElement: Element, public mountInit: MountInit) {
         super(DisconnectEvent.eventName);
     }
 }
@@ -35,7 +37,7 @@ export class DisconnectEvent extends Event {
 export class LoadEvent extends Event {
     static eventName: typeof loadEventName = loadEventName;
     
-    constructor(public modules: any[]) {
+    constructor(public modules: any[], public mountInit: MountInit) {
         super(LoadEvent.eventName);
     }
 }
@@ -43,7 +45,23 @@ export class LoadEvent extends Event {
 export class AttrChangeEvent extends Event implements IAttrChangeEvent {
     static eventName: typeof attrchangeEventName = attrchangeEventName;
     
-    constructor(public changes: AttrChange[]) {
+    constructor(public changes: AttrChange[], public mountInit: MountInit) {
         super(AttrChangeEvent.eventName);
     }
 }
+
+export class MediaMatchEvent extends Event {
+    static eventName: typeof mediamatchEventName = mediamatchEventName;
+    
+    constructor(public mountInit: MountInit) {
+        super(MediaMatchEvent.eventName);
+    }
+}
+
+export class MediaUnmatchEvent extends Event {
+    static eventName: typeof mediaunmatchEventName = mediaunmatchEventName;
+    
+    constructor(public mountInit: MountInit) {
+        super(MediaUnmatchEvent.eventName);
+    }
+}

package/MountObserver.js

@@ -1,4 +1,5 @@
 import { MountEvent, DismountEvent, DisconnectEvent, LoadEvent, AttrChangeEvent } from './Events.js';
+import { registerSharedObserver, unregisterSharedObserver } from './SharedMutationObserver.js';
 export class MountObserver extends EventTarget {
     #init;
     #options;
@@ -6,12 +7,15 @@ export class MountObserver extends EventTarget {
     #modules = [];
     #mountedElements = new WeakSet();
     #processedElements = new WeakSet();
-    #mutationObserver;
+    #mutationCallback;
     #rootNode;
     #importsLoaded = false;
     #elementAttrStates = new WeakMap();
+    #elementOnceAttrs = new WeakMap();
     #matchesWhereAttrFn = null;
     #buildAttrCoordinateMapFn = null;
+    #mediaQueryCleanup;
+    #mediaMatches = true;
     constructor(init, options = {}) {
         super();
         this.#init = init;
@@ -41,6 +45,15 @@ export class MountObserver extends EventTarget {
             this.#buildAttrCoordinateMapFn = buildAttrCoordinateMap;
         }
     }
+    async #setupMediaQuery() {
+        if (!this.#rootNode) {
+            throw new Error('Cannot setup media query before observe() is called');
+        }
+        const { setupMediaQuery } = await import('./mediaQuery.js');
+        const result = setupMediaQuery(this.#init, this.#rootNode, this.#mountedElements, this.#modules, this, (node) => this.#processNode(node));
+        this.#mediaMatches = result.mediaMatches;
+        this.#mediaQueryCleanup = result.cleanup;
+    }
     get disconnectedSignal() {
         return this.#abortController.signal;
     }
@@ -49,14 +62,24 @@ export class MountObserver extends EventTarget {
             throw new Error('Already observing');
         }
         this.#rootNode = new WeakRef(rootNode);
+        // Set up media query if specified (needs rootNode to be set first)
+        if (this.#init.whereMediaMatches) {
+            await this.#setupMediaQuery();
+        }
         // Wait for whereAttr utilities to load if needed
         if (this.#init.whereAttr && !this.#matchesWhereAttrFn) {
             await this.#preloadWhereAttrUtilities();
         }
-        // Process existing elements
-        this.#processNode(rootNode);
-        // Set up mutation observer
-        this.#mutationObserver = new MutationObserver((mutations) => {
+        // Process existing elements only if media matches
+        if (this.#mediaMatches) {
+            this.#processNode(rootNode);
+        }
+        // Create mutation callback
+        this.#mutationCallback = (mutations) => {
+            // Skip processing if media doesn't match
+            if (!this.#mediaMatches) {
+                return;
+            }
             const attrChanges = [];
             for (const mutation of mutations) {
                 if (mutation.type === 'childList') {
@@ -82,9 +105,9 @@ export class MountObserver extends EventTarget {
             }
             // Batch and dispatch attribute changes
             if (attrChanges.length > 0) {
-                this.dispatchEvent(new AttrChangeEvent(attrChanges));
+                this.dispatchEvent(new AttrChangeEvent(attrChanges, this.#init));
             }
-        });
+        };
         const observerConfig = {
             childList: true,
             subtree: true
@@ -94,12 +117,20 @@ export class MountObserver extends EventTarget {
             observerConfig.attributes = true;
             observerConfig.attributeOldValue = true;
         }
-        this.#mutationObserver.observe(rootNode, observerConfig);
+        // Register with shared mutation observer
+        registerSharedObserver(rootNode, this.#mutationCallback, observerConfig);
     }
     disconnect() {
-        if (this.#mutationObserver) {
-            this.#mutationObserver.disconnect();
-            this.#mutationObserver = undefined;
+        const rootNode = this.#rootNode?.deref();
+        // Unregister from shared mutation observer
+        if (rootNode && this.#mutationCallback) {
+            unregisterSharedObserver(rootNode, this.#mutationCallback);
+            this.#mutationCallback = undefined;
+        }
+        // Remove media query listener
+        if (this.#mediaQueryCleanup) {
+            this.#mediaQueryCleanup();
+            this.#mediaQueryCleanup = undefined;
         }
         this.#abortController.abort();
         this.#rootNode = undefined;
@@ -112,7 +143,7 @@ export class MountObserver extends EventTarget {
         const { loadImports } = await import('./loadImports.js');
         this.#modules = await loadImports(this.#init.import);
         this.#importsLoaded = true;
-        this.dispatchEvent(new LoadEvent(this.#modules));
+        this.dispatchEvent(new LoadEvent(this.#modules, this.#init));
     }
     #processNode(node) {
         // If it's an element node, check if it matches
@@ -125,38 +156,45 @@ export class MountObserver extends EventTarget {
         // Process children
         if (node.nodeType === Node.ELEMENT_NODE || node.nodeType === Node.DOCUMENT_NODE) {
             const root = node;
-            // If whereAttr is specified, we need to check all elements
-            // since we can't use querySelectorAll for complex attribute matching
-            if (this.#init.whereAttr) {
-                // Get all elements matching the CSS selector first
-                root.querySelectorAll(this.#init.whereElementMatches).forEach(child => {
-                    if (this.#matchesSelector(child)) {
-                        this.#handleMatch(child);
-                    }
-                });
-            }
-            else {
-                // Optimize: use querySelectorAll directly when no whereAttr
-                root.querySelectorAll(this.#init.whereElementMatches).forEach(child => {
+            // Get all elements matching the CSS selector first
+            root.querySelectorAll(this.#init.whereElementMatches).forEach(child => {
+                if (this.#matchesSelector(child)) {
                     this.#handleMatch(child);
-                });
-            }
+                }
+            });
         }
     }
     #matchesSelector(element) {
+        //TODO:  reduce redundncy with this.#init?
         // Check whereElementMatches condition
         const matchesElement = element.matches(this.#init.whereElementMatches);
-        // If whereAttr is not specified, only check whereElementMatches
-        if (!this.#init.whereAttr) {
-            return matchesElement;
-        }
-        // Use cached function (should be loaded by now from constructor)
-        if (!this.#matchesWhereAttrFn) {
-            console.warn('whereAttr utilities not loaded yet');
+        if (!matchesElement) {
             return false;
         }
-        // Both conditions must be true (AND logic)
-        return matchesElement && this.#matchesWhereAttrFn(element, this.#init.whereAttr);
+        // Check whereAttr condition if specified
+        if (this.#init.whereAttr) {
+            // Use cached function (should be loaded by now from constructor)
+            if (!this.#matchesWhereAttrFn) {
+                console.warn('whereAttr utilities not loaded yet');
+                return false;
+            }
+            if (!this.#matchesWhereAttrFn(element, this.#init.whereAttr)) {
+                return false;
+            }
+        }
+        // Check whereInstanceOf condition if specified
+        if (this.#init.whereInstanceOf) {
+            const constructors = Array.isArray(this.#init.whereInstanceOf)
+                ? this.#init.whereInstanceOf
+                : [this.#init.whereInstanceOf];
+            // Element must be an instance of at least one constructor (OR logic for array)
+            const matchesInstanceOf = constructors.some(constructor => element instanceof constructor);
+            if (!matchesInstanceOf) {
+                return false;
+            }
+        }
+        // All conditions passed
+        return true;
     }
     async #handleMatch(element) {
         if (this.#processedElements.has(element)) {
@@ -195,12 +233,12 @@ export class MountObserver extends EventTarget {
             }
         }
         // Dispatch mount event
-        this.dispatchEvent(new MountEvent(element, this.#modules));
+        this.dispatchEvent(new MountEvent(element, this.#modules, this.#init));
         // Check for initial attribute changes if whereAttr is configured
         if (this.#init.whereAttr) {
             const changes = this.#checkAttrChanges(element);
             if (changes.length > 0) {
-                this.dispatchEvent(new AttrChangeEvent(changes));
+                this.dispatchEvent(new AttrChangeEvent(changes, this.#init));
             }
         }
     }
@@ -226,12 +264,30 @@ export class MountObserver extends EventTarget {
             if (currentValue !== null) {
                 currentAttrs.add(attrName);
             }
+            // Check if this attribute has "once: true" in its map entry
+            const mapEntry = this.#init.map?.[coordinate] || null;
+            const isOnce = mapEntry?.once === true;
+            // If "once" is true, check if we've already seen this attribute
+            if (isOnce) {
+                let onceAttrs = this.#elementOnceAttrs.get(element);
+                if (!onceAttrs) {
+                    onceAttrs = new Set();
+                    this.#elementOnceAttrs.set(element, onceAttrs);
+                }
+                // If we've already seen this attribute, skip it
+                if (onceAttrs.has(attrName)) {
+                    continue;
+                }
+                // Mark this attribute as seen if it currently has a value
+                if (currentValue !== null) {
+                    onceAttrs.add(attrName);
+                }
+            }
             // Include if: currently has value OR previously had value but now removed
             if (currentValue !== null || (previousValue !== undefined && currentValue === null)) {
                 // Check if value changed
                 if (currentValue !== previousValue) {
                     const attrNode = currentValue !== null ? element.getAttributeNode(attrName) : null;
-                    const mapEntry = this.#init.map?.[coordinate] || null;
                     changes.push({
                         value: currentValue,
                         attrNode,
@@ -274,7 +330,7 @@ export class MountObserver extends EventTarget {
             this.#init.do.dismount(element, context);
         }
         // Dispatch dismount event
-        this.dispatchEvent(new DismountEvent(element));
+        this.dispatchEvent(new DismountEvent(element, 'where-element-matches-failed', this.#init));
         // Check if element is being moved within the same root
         // If it's truly disconnected, dispatch disconnect event
         setTimeout(() => {
@@ -282,7 +338,7 @@ export class MountObserver extends EventTarget {
                 if (this.#init.do && typeof this.#init.do !== 'function' && this.#init.do.disconnect) {
                     this.#init.do.disconnect(element, context);
                 }
-                this.dispatchEvent(new DisconnectEvent(element));
+                this.dispatchEvent(new DisconnectEvent(element, this.#init));
             }
         }, 0);
     }

package/MountObserver.ts

@@ -10,8 +10,15 @@ import {
     DismountEvent,
     DisconnectEvent,
     LoadEvent,
-    AttrChangeEvent
+    AttrChangeEvent,
+    MediaMatchEvent,
+    MediaUnmatchEvent
 } from './Events.js';
+import {
+    registerSharedObserver,
+    unregisterSharedObserver,
+    type MutationCallback
+} from './SharedMutationObserver.js';
 
 export class MountObserver extends EventTarget implements IMountObserver {
     #init: MountInit;
@@ -20,12 +27,15 @@ export class MountObserver extends EventTarget implements IMountObserver {
     #modules: any[] = [];
     #mountedElements = new WeakSet<Element>();
     #processedElements = new WeakSet<Element>();
-    #mutationObserver: MutationObserver | undefined;
+    #mutationCallback: MutationCallback | undefined;
     #rootNode: WeakRef<Node> | undefined;
     #importsLoaded = false;
     #elementAttrStates = new WeakMap<Element, Map<string, string | null>>();
+    #elementOnceAttrs = new WeakMap<Element, Set<string>>();
     #matchesWhereAttrFn: ((element: Element, whereAttr: any) => boolean) | null = null;
     #buildAttrCoordinateMapFn: ((whereAttr: any, isCustomElement: boolean) => any) | null = null;
+    #mediaQueryCleanup?: () => void;
+    #mediaMatches: boolean = true;
 
     constructor(init: MountInit, options: MountObserverOptions = {}) {
         super();
@@ -60,6 +70,25 @@ export class MountObserver extends EventTarget implements IMountObserver {
             this.#buildAttrCoordinateMapFn = buildAttrCoordinateMap;
         }
     }
+    
+    async #setupMediaQuery(): Promise<void> {
+        if (!this.#rootNode) {
+            throw new Error('Cannot setup media query before observe() is called');
+        }
+        
+        const { setupMediaQuery } = await import('./mediaQuery.js');
+        const result = setupMediaQuery(
+            this.#init,
+            this.#rootNode,
+            this.#mountedElements,
+            this.#modules,
+            this,
+            (node) => this.#processNode(node)
+        );
+        
+        this.#mediaMatches = result.mediaMatches;
+        this.#mediaQueryCleanup = result.cleanup;
+    }
 
     get disconnectedSignal(): AbortSignal {
         return this.#abortController.signal;
@@ -72,16 +101,28 @@ export class MountObserver extends EventTarget implements IMountObserver {
 
         this.#rootNode = new WeakRef(rootNode);
 
+        // Set up media query if specified (needs rootNode to be set first)
+        if (this.#init.whereMediaMatches) {
+            await this.#setupMediaQuery();
+        }
+
         // Wait for whereAttr utilities to load if needed
         if (this.#init.whereAttr && !this.#matchesWhereAttrFn) {
             await this.#preloadWhereAttrUtilities();
         }
         
-        // Process existing elements
-        this.#processNode(rootNode);
+        // Process existing elements only if media matches
+        if (this.#mediaMatches) {
+            this.#processNode(rootNode);
+        }
 
-        // Set up mutation observer
-        this.#mutationObserver = new MutationObserver((mutations) => {
+        // Create mutation callback
+        this.#mutationCallback = (mutations) => {
+            // Skip processing if media doesn't match
+            if (!this.#mediaMatches) {
+                return;
+            }
+            
             const attrChanges: AttrChange[] = [];
             
             for (const mutation of mutations) {
@@ -108,9 +149,9 @@ export class MountObserver extends EventTarget implements IMountObserver {
             
             // Batch and dispatch attribute changes
             if (attrChanges.length > 0) {
-                this.dispatchEvent(new AttrChangeEvent(attrChanges));
+                this.dispatchEvent(new AttrChangeEvent(attrChanges, this.#init));
             }
-        });
+        };
 
         const observerConfig: MutationObserverInit = {
             childList: true,
@@ -123,14 +164,25 @@ export class MountObserver extends EventTarget implements IMountObserver {
             observerConfig.attributeOldValue = true;
         }
 
-        this.#mutationObserver.observe(rootNode, observerConfig);
+        // Register with shared mutation observer
+        registerSharedObserver(rootNode, this.#mutationCallback, observerConfig);
     }
 
     disconnect(): void {
-        if (this.#mutationObserver) {
-            this.#mutationObserver.disconnect();
-            this.#mutationObserver = undefined;
+        const rootNode = this.#rootNode?.deref();
+        
+        // Unregister from shared mutation observer
+        if (rootNode && this.#mutationCallback) {
+            unregisterSharedObserver(rootNode, this.#mutationCallback);
+            this.#mutationCallback = undefined;
         }
+        
+        // Remove media query listener
+        if (this.#mediaQueryCleanup) {
+            this.#mediaQueryCleanup();
+            this.#mediaQueryCleanup = undefined;
+        }
+        
         this.#abortController.abort();
         this.#rootNode = undefined;
     }
@@ -145,7 +197,7 @@ export class MountObserver extends EventTarget implements IMountObserver {
         this.#modules = await loadImports(this.#init.import);
         this.#importsLoaded = true;
 
-        this.dispatchEvent(new LoadEvent(this.#modules));
+        this.dispatchEvent(new LoadEvent(this.#modules, this.#init));
     }
 
     #processNode(node: Node): void {
@@ -162,41 +214,52 @@ export class MountObserver extends EventTarget implements IMountObserver {
         if (node.nodeType === Node.ELEMENT_NODE || node.nodeType === Node.DOCUMENT_NODE) {
             const root = node as Element | Document;
             
-            // If whereAttr is specified, we need to check all elements
-            // since we can't use querySelectorAll for complex attribute matching
-            if (this.#init.whereAttr) {
-                // Get all elements matching the CSS selector first
-                root.querySelectorAll(this.#init.whereElementMatches).forEach(child => {
-                    if (this.#matchesSelector(child)) {
-                        this.#handleMatch(child);
-                    }
-                });
-            } else {
-                // Optimize: use querySelectorAll directly when no whereAttr
-                root.querySelectorAll(this.#init.whereElementMatches).forEach(child => {
+            // Get all elements matching the CSS selector first
+            root.querySelectorAll(this.#init.whereElementMatches).forEach(child => {
+                if (this.#matchesSelector(child)) {
                     this.#handleMatch(child);
-                });
-            }
+                }
+            });
         }
     }
 
     #matchesSelector(element: Element): boolean {
+        //TODO:  reduce redundncy with this.#init?
         // Check whereElementMatches condition
         const matchesElement = element.matches(this.#init.whereElementMatches);
+        if (!matchesElement) {
+            return false;
+        }
         
-        // If whereAttr is not specified, only check whereElementMatches
-        if (!this.#init.whereAttr) {
-            return matchesElement;
+        // Check whereAttr condition if specified
+        if (this.#init.whereAttr) {
+            // Use cached function (should be loaded by now from constructor)
+            if (!this.#matchesWhereAttrFn) {
+                console.warn('whereAttr utilities not loaded yet');
+                return false;
+            }
+            
+            if (!this.#matchesWhereAttrFn(element, this.#init.whereAttr)) {
+                return false;
+            }
         }
         
-        // Use cached function (should be loaded by now from constructor)
-        if (!this.#matchesWhereAttrFn) {
-            console.warn('whereAttr utilities not loaded yet');
-            return false;
+        // Check whereInstanceOf condition if specified
+        if (this.#init.whereInstanceOf) {
+            const constructors = Array.isArray(this.#init.whereInstanceOf) 
+                ? this.#init.whereInstanceOf 
+                : [this.#init.whereInstanceOf];
+            
+            // Element must be an instance of at least one constructor (OR logic for array)
+            const matchesInstanceOf = constructors.some(constructor => element instanceof constructor);
+            
+            if (!matchesInstanceOf) {
+                return false;
+            }
         }
         
-        // Both conditions must be true (AND logic)
-        return matchesElement && this.#matchesWhereAttrFn(element, this.#init.whereAttr);
+        // All conditions passed
+        return true;
     }
 
     async #handleMatch(element: Element): Promise<void> {
@@ -242,13 +305,13 @@ export class MountObserver extends EventTarget implements IMountObserver {
         }
 
         // Dispatch mount event
-        this.dispatchEvent(new MountEvent(element, this.#modules));
+        this.dispatchEvent(new MountEvent(element, this.#modules, this.#init));
         
         // Check for initial attribute changes if whereAttr is configured
         if (this.#init.whereAttr) {
             const changes = this.#checkAttrChanges(element);
             if (changes.length > 0) {
-                this.dispatchEvent(new AttrChangeEvent(changes));
+                this.dispatchEvent(new AttrChangeEvent(changes, this.#init));
             }
         }
     }
@@ -281,12 +344,34 @@ export class MountObserver extends EventTarget implements IMountObserver {
                 currentAttrs.add(attrName);
             }
             
+            // Check if this attribute has "once: true" in its map entry
+            const mapEntry = this.#init.map?.[coordinate] || null;
+            const isOnce = mapEntry?.once === true;
+            
+            // If "once" is true, check if we've already seen this attribute
+            if (isOnce) {
+                let onceAttrs = this.#elementOnceAttrs.get(element);
+                if (!onceAttrs) {
+                    onceAttrs = new Set<string>();
+                    this.#elementOnceAttrs.set(element, onceAttrs);
+                }
+                
+                // If we've already seen this attribute, skip it
+                if (onceAttrs.has(attrName)) {
+                    continue;
+                }
+                
+                // Mark this attribute as seen if it currently has a value
+                if (currentValue !== null) {
+                    onceAttrs.add(attrName);
+                }
+            }
+            
             // Include if: currently has value OR previously had value but now removed
             if (currentValue !== null || (previousValue !== undefined && currentValue === null)) {
                 // Check if value changed
                 if (currentValue !== previousValue) {
                     const attrNode = currentValue !== null ? element.getAttributeNode(attrName) : null;
-                    const mapEntry = this.#init.map?.[coordinate] || null;
                     
                     changes.push({
                         value: currentValue,
@@ -337,7 +422,7 @@ export class MountObserver extends EventTarget implements IMountObserver {
         }
 
         // Dispatch dismount event
-        this.dispatchEvent(new DismountEvent(element));
+        this.dispatchEvent(new DismountEvent(element, 'where-element-matches-failed', this.#init));
 
         // Check if element is being moved within the same root
         // If it's truly disconnected, dispatch disconnect event
@@ -347,7 +432,7 @@ export class MountObserver extends EventTarget implements IMountObserver {
                     this.#init.do.disconnect(element, context);
                 }
 
-                this.dispatchEvent(new DisconnectEvent(element));
+                this.dispatchEvent(new DisconnectEvent(element, this.#init));
             }
         }, 0);
     }

package/SharedMutationObserver.js

@@ -0,0 +1,70 @@
+/**
+ * Manages shared MutationObserver instances for multiple MountObserver instances
+ * observing the same root node. This reduces overhead when multiple observers
+ * are watching the same DOM fragment.
+ */
+/**
+ * Global registry of shared observers, keyed by root node
+ */
+const sharedObservers = new WeakMap();
+/**
+ * Registers a callback with the shared MutationObserver for the given root node.
+ * Creates a new shared observer if one doesn't exist for this root.
+ */
+export function registerSharedObserver(rootNode, callback, config) {
+    let sharedData = sharedObservers.get(rootNode);
+    if (!sharedData) {
+        // Create new shared observer for this root node
+        const observer = new MutationObserver((mutations) => {
+            // Distribute mutations to all registered callbacks
+            const callbacks = sharedData.callbacks;
+            for (const cb of callbacks) {
+                cb(mutations);
+            }
+        });
+        observer.observe(rootNode, config);
+        sharedData = {
+            observer,
+            callbacks: new Set(),
+            config
+        };
+        sharedObservers.set(rootNode, sharedData);
+    }
+    else {
+        // Verify config matches (for safety)
+        // In practice, all MountObservers should use the same config
+        if (!configsMatch(sharedData.config, config)) {
+            console.warn('MutationObserver config mismatch detected. Using existing config.');
+        }
+    }
+    // Register the callback
+    sharedData.callbacks.add(callback);
+}
+/**
+ * Unregisters a callback from the shared MutationObserver.
+ * If this was the last callback, disconnects and removes the shared observer.
+ */
+export function unregisterSharedObserver(rootNode, callback) {
+    const sharedData = sharedObservers.get(rootNode);
+    if (!sharedData) {
+        return;
+    }
+    // Remove the callback
+    sharedData.callbacks.delete(callback);
+    // If no more callbacks, disconnect and cleanup
+    if (sharedData.callbacks.size === 0) {
+        sharedData.observer.disconnect();
+        sharedObservers.delete(rootNode);
+    }
+}
+/**
+ * Checks if two MutationObserverInit configs are equivalent
+ */
+function configsMatch(a, b) {
+    return a.childList === b.childList &&
+        a.subtree === b.subtree &&
+        a.attributes === b.attributes &&
+        a.attributeOldValue === b.attributeOldValue &&
+        a.characterData === b.characterData &&
+        a.characterDataOldValue === b.characterDataOldValue;
+}

package/SharedMutationObserver.ts

@@ -0,0 +1,96 @@
+/**
+ * Manages shared MutationObserver instances for multiple MountObserver instances
+ * observing the same root node. This reduces overhead when multiple observers
+ * are watching the same DOM fragment.
+ */
+
+export type MutationCallback = (mutations: MutationRecord[]) => void;
+
+interface SharedObserverData {
+    observer: MutationObserver;
+    callbacks: Set<MutationCallback>;
+    config: MutationObserverInit;
+}
+
+/**
+ * Global registry of shared observers, keyed by root node
+ */
+const sharedObservers = new WeakMap<Node, SharedObserverData>();
+
+/**
+ * Registers a callback with the shared MutationObserver for the given root node.
+ * Creates a new shared observer if one doesn't exist for this root.
+ */
+export function registerSharedObserver(
+    rootNode: Node,
+    callback: MutationCallback,
+    config: MutationObserverInit
+): void {
+    let sharedData = sharedObservers.get(rootNode);
+    
+    if (!sharedData) {
+        // Create new shared observer for this root node
+        const observer = new MutationObserver((mutations) => {
+            // Distribute mutations to all registered callbacks
+            const callbacks = sharedData!.callbacks;
+            for (const cb of callbacks) {
+                cb(mutations);
+            }
+        });
+        
+        observer.observe(rootNode, config);
+        
+        sharedData = {
+            observer,
+            callbacks: new Set(),
+            config
+        };
+        
+        sharedObservers.set(rootNode, sharedData);
+    } else {
+        // Verify config matches (for safety)
+        // In practice, all MountObservers should use the same config
+        if (!configsMatch(sharedData.config, config)) {
+            console.warn('MutationObserver config mismatch detected. Using existing config.');
+        }
+    }
+    
+    // Register the callback
+    sharedData.callbacks.add(callback);
+}
+
+/**
+ * Unregisters a callback from the shared MutationObserver.
+ * If this was the last callback, disconnects and removes the shared observer.
+ */
+export function unregisterSharedObserver(
+    rootNode: Node,
+    callback: MutationCallback
+): void {
+    const sharedData = sharedObservers.get(rootNode);
+    
+    if (!sharedData) {
+        return;
+    }
+    
+    // Remove the callback
+    sharedData.callbacks.delete(callback);
+    
+    // If no more callbacks, disconnect and cleanup
+    if (sharedData.callbacks.size === 0) {
+        sharedData.observer.disconnect();
+        sharedObservers.delete(rootNode);
+    }
+}
+
+/**
+ * Checks if two MutationObserverInit configs are equivalent
+ */
+function configsMatch(a: MutationObserverInit, b: MutationObserverInit): boolean {
+    return a.childList === b.childList &&
+           a.subtree === b.subtree &&
+           a.attributes === b.attributes &&
+           a.attributeOldValue === b.attributeOldValue &&
+           a.characterData === b.characterData &&
+           a.characterDataOldValue === b.characterDataOldValue;
+}

package/index.ts

@@ -15,5 +15,8 @@ export {
     mountEventName,
     dismountEventName,
     disconnectEventName,
-    loadEventName
-} from './constants.js';
+    loadEventName,
+    attrchangeEventName,
+    mediamatchEventName,
+    mediaunmatchEventName
+} from './Events.js';

package/mediaQuery.js

@@ -0,0 +1,86 @@
+import { MediaMatchEvent, MediaUnmatchEvent, DismountEvent } from './Events.js';
+export function setupMediaQuery(init, rootNodeRef, mountedElements, modules, observer, processNode) {
+    const { whereMediaMatches } = init;
+    // Create or use MediaQueryList
+    let mediaQueryList;
+    if (typeof whereMediaMatches === 'string') {
+        mediaQueryList = window.matchMedia(whereMediaMatches);
+    }
+    else {
+        mediaQueryList = whereMediaMatches;
+    }
+    // Track current state
+    let mediaMatches = mediaQueryList.matches;
+    // Set up change listener
+    const mediaChangeHandler = (e) => {
+        const previousMatches = mediaMatches;
+        mediaMatches = e.matches;
+        if (e.matches && !previousMatches) {
+            // Media query now matches - wake up and process elements
+            handleMediaMatch();
+        }
+        else if (!e.matches && previousMatches) {
+            // Media query no longer matches - dismount all elements
+            handleMediaUnmatch();
+        }
+    };
+    function handleMediaMatch() {
+        // Dispatch mediamatch event if requested
+        if (init.getPlayByPlay) {
+            observer.dispatchEvent(new MediaMatchEvent(init));
+        }
+        // Process all elements in the observed node
+        const rootNode = rootNodeRef.deref();
+        if (rootNode) {
+            processNode(rootNode);
+        }
+    }
+    function handleMediaUnmatch() {
+        // Dispatch mediaunmatch event if requested
+        if (init.getPlayByPlay) {
+            observer.dispatchEvent(new MediaUnmatchEvent(init));
+        }
+        // Dismount all currently mounted elements
+        const rootNode = rootNodeRef.deref();
+        if (!rootNode) {
+            return;
+        }
+        const context = {
+            modules,
+            observer: observer,
+            observeInfo: {
+                rootNode
+            }
+        };
+        // Get all mounted elements (we need to iterate through the DOM to find them)
+        const mountedElementsList = [];
+        const collectMountedElements = (node) => {
+            if (node.nodeType === Node.ELEMENT_NODE) {
+                const element = node;
+                if (mountedElements.has(element)) {
+                    mountedElementsList.push(element);
+                }
+            }
+            node.childNodes.forEach(child => collectMountedElements(child));
+        };
+        collectMountedElements(rootNode);
+        // Dismount each element
+        for (const element of mountedElementsList) {
+            mountedElements.delete(element);
+            // Call dismount callback
+            if (init.do && typeof init.do !== 'function' && init.do.dismount) {
+                init.do.dismount(element, context);
+            }
+            // Dispatch dismount event with reason
+            observer.dispatchEvent(new DismountEvent(element, 'media-query-failed', init));
+        }
+    }
+    mediaQueryList.addEventListener('change', mediaChangeHandler);
+    return {
+        mediaQueryList,
+        mediaMatches,
+        cleanup: () => {
+            mediaQueryList.removeEventListener('change', mediaChangeHandler);
+        }
+    };
+}

package/mediaQuery.ts

@@ -0,0 +1,113 @@
+// Media query handling for MountObserver
+import type { MountInit, MountContext } from './types.js';
+import { MediaMatchEvent, MediaUnmatchEvent, DismountEvent } from './Events.js';
+
+export function setupMediaQuery(
+    init: MountInit,
+    rootNodeRef: WeakRef<Node>,
+    mountedElements: WeakSet<Element>,
+    modules: any[],
+    observer: EventTarget,
+    processNode: (node: Node) => void
+): {
+    mediaQueryList: MediaQueryList;
+    mediaMatches: boolean;
+    cleanup: () => void;
+} {
+    const { whereMediaMatches } = init;
+    
+    // Create or use MediaQueryList
+    let mediaQueryList: MediaQueryList;
+    if (typeof whereMediaMatches === 'string') {
+        mediaQueryList = window.matchMedia(whereMediaMatches);
+    } else {
+        mediaQueryList = whereMediaMatches!;
+    }
+    
+    // Track current state
+    let mediaMatches = mediaQueryList.matches;
+    
+    // Set up change listener
+    const mediaChangeHandler = (e: MediaQueryListEvent) => {
+        const previousMatches = mediaMatches;
+        mediaMatches = e.matches;
+        
+        if (e.matches && !previousMatches) {
+            // Media query now matches - wake up and process elements
+            handleMediaMatch();
+        } else if (!e.matches && previousMatches) {
+            // Media query no longer matches - dismount all elements
+            handleMediaUnmatch();
+        }
+    };
+    
+    function handleMediaMatch(): void {
+        // Dispatch mediamatch event if requested
+        if (init.getPlayByPlay) {
+            observer.dispatchEvent(new MediaMatchEvent(init));
+        }
+        
+        // Process all elements in the observed node
+        const rootNode = rootNodeRef.deref();
+        if (rootNode) {
+            processNode(rootNode);
+        }
+    }
+    
+    function handleMediaUnmatch(): void {
+        // Dispatch mediaunmatch event if requested
+        if (init.getPlayByPlay) {
+            observer.dispatchEvent(new MediaUnmatchEvent(init));
+        }
+        
+        // Dismount all currently mounted elements
+        const rootNode = rootNodeRef.deref();
+        if (!rootNode) {
+            return;
+        }
+        
+        const context: MountContext = {
+            modules,
+            observer: observer as any,
+            observeInfo: {
+                rootNode
+            }
+        };
+        
+        // Get all mounted elements (we need to iterate through the DOM to find them)
+        const mountedElementsList: Element[] = [];
+        const collectMountedElements = (node: Node) => {
+            if (node.nodeType === Node.ELEMENT_NODE) {
+                const element = node as Element;
+                if (mountedElements.has(element)) {
+                    mountedElementsList.push(element);
+                }
+            }
+            node.childNodes.forEach(child => collectMountedElements(child));
+        };
+        collectMountedElements(rootNode);
+        
+        // Dismount each element
+        for (const element of mountedElementsList) {
+            mountedElements.delete(element);
+            
+            // Call dismount callback
+            if (init.do && typeof init.do !== 'function' && init.do.dismount) {
+                init.do.dismount(element, context);
+            }
+            
+            // Dispatch dismount event with reason
+            observer.dispatchEvent(new DismountEvent(element, 'media-query-failed', init));
+        }
+    }
+    
+    mediaQueryList.addEventListener('change', mediaChangeHandler);
+    
+    return {
+        mediaQueryList,
+        mediaMatches,
+        cleanup: () => {
+            mediaQueryList.removeEventListener('change', mediaChangeHandler);
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mount-observer",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Observe and act on css matches.",
   "main": "MountObserver.js",
   "module": "MountObserver.js",
@@ -13,22 +13,25 @@
   },
   "exports": {
     ".": {
+      "default": "./index.js",
+      "types": "./index.ts"
+    },
+    "./MountObserver.js": {
       "default": "./MountObserver.js",
       "types": "./MountObserver.ts"
     }
-
   },
   "files": [
     "*.js",
     "*.ts"
   ],
-  "types": "./ts-refs/mount-observer/types.d.ts",
+  "types": "./types.d.ts",
   "scripts": {
     "serve": "node ./node_modules/spa-ssi/serve.js",
     "test": "playwright test",
     "safari": "npx playwright wk http://localhost:8000",
     "update": "ncu -u && npm install"
   },
-  "author": "",
+  "author": "Bruce B. Anderson <anderson.bruce.b@gmail.com>",
   "license": "MIT"
 }

package/types.d.ts

@@ -1,13 +1,22 @@
 // Core types for MountObserver v2 - Polyfill Supported Scenario I
 
+export type Constructor = new (...args: any[]) => any;
+
+export type DismountReason = 
+    | 'media-query-failed'
+    | 'where-element-matches-failed';
+
 export interface MountInit {
     whereElementMatches: string;
     whereAttr?: WhereAttr;
+    whereInstanceOf?: Constructor | Constructor[];
+    whereMediaMatches?: string | MediaQueryList;
     import?: string | ImportSpec | Array<string | ImportSpec>;
     do?: DoCallback | DoCallbacks;
     loadingEagerness?: 'eager' | 'lazy';
     assignGingerly?: Record<string, any>;
     map?: MapConfig;
+    getPlayByPlay?: boolean;
 }
 
 export interface MapConfig {
@@ -17,6 +26,11 @@ export interface MapConfig {
 export interface MapEntry {
     instanceOf?: string;
     mapsTo?: string;
+    /**
+     * Only notify the presence of this attribute
+     * the first time it is seen
+     */
+    once?: boolean;
     [key: string]: any;
 }
 
@@ -66,14 +80,18 @@ export interface IMountObserver extends EventTarget {
 export interface IMountEvent extends Event {
     matchingElement: Element;
     modules: any[];
+    mountInit: MountInit;
 }
 
 export interface IDismountEvent extends Event {
     matchingElement: Element;
+    reason: DismountReason;
+    mountInit: MountInit;
 }
 
 export interface IAttrChangeEvent extends Event {
     changes: AttrChange[];
+    mountInit: MountInit;
 }
 
 export interface AttrChange {

package/constants.js

@@ -1,6 +0,0 @@
-// Constants for MountObserver
-export const loadEventName = 'load';
-export const mountEventName = 'mount';
-export const dismountEventName = 'dismount';
-export const disconnectEventName = 'disconnect';
-export const attrchangeEventName = 'attrchange';

package/constants.ts

@@ -1,7 +0,0 @@
-// Constants for MountObserver
-
-export const loadEventName = 'load';
-export const mountEventName = 'mount';
-export const dismountEventName = 'dismount';
-export const disconnectEventName = 'disconnect';
-export const attrchangeEventName = 'attrchange';