mount-observer 0.0.0 → 0.0.2

package/.github/workflows/CI.yml

@@ -0,0 +1,18 @@
+name: Playwright Tests
+on: [push]
+jobs:
+  test:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-node@v2
+      with:
+        node-version: '16.x'
+    - name: Install dependencies
+      run: npm ci
+    - name: Install Playwright
+      run: npx playwright install --with-deps
+    - name: Run Playwright tests
+      run: npm run test
+      

package/MountObserver.js

@@ -0,0 +1,269 @@
+import { RootMutObs } from './RootMutObs.js';
+const mutationObserverLookup = new WeakMap();
+export class MountObserver extends EventTarget {
+    #mountInit;
+    #rootMutObs;
+    #abortController;
+    #mounted;
+    #mountedList;
+    #disconnected;
+    //#unmounted: WeakSet<Element>;
+    #isComplex;
+    constructor(init) {
+        super();
+        const { match, whereElementIntersectsWith, whereMediaMatches } = init;
+        this.#isComplex = match !== undefined && (match.includes(' ') || match.includes(':'));
+        if (whereElementIntersectsWith || whereMediaMatches)
+            throw 'NI'; //not implemented
+        this.#mountInit = init;
+        this.#abortController = new AbortController();
+        this.#mounted = new WeakSet();
+        this.#disconnected = new WeakSet();
+        //this.#unmounted = new WeakSet();
+    }
+    #calculatedSelector;
+    get #selector() {
+        if (this.#calculatedSelector !== undefined)
+            return this.#calculatedSelector;
+        const { match, attribMatches } = this.#mountInit;
+        const base = match || '*';
+        if (attribMatches === undefined)
+            return base;
+        const matches = [];
+        attribMatches.forEach(x => {
+            const { names } = x;
+            names.forEach(y => {
+                matches.push(`${base}[${y}]`);
+            });
+        });
+        this.#calculatedSelector = matches.join(',');
+        return this.#calculatedSelector;
+    }
+    async observe(within) {
+        const nodeToMonitor = this.#isComplex ? (within instanceof ShadowRoot ? within : within.getRootNode()) : within;
+        if (!mutationObserverLookup.has(nodeToMonitor)) {
+            mutationObserverLookup.set(nodeToMonitor, new RootMutObs(nodeToMonitor));
+        }
+        const rootMutObs = mutationObserverLookup.get(within);
+        const { attribMatches } = this.#mountInit;
+        rootMutObs.addEventListener('mutation-event', (e) => {
+            //TODO:  disconnected
+            if (this.#isComplex) {
+                this.#inspectWithin(within);
+                return;
+            }
+            const { mutationRecords } = e;
+            const elsToInspect = [];
+            //const elsToDisconnect: Array<Element> = [];
+            const doDisconnect = this.#mountInit.do?.onDisconnect;
+            for (const mutationRecord of mutationRecords) {
+                const { addedNodes, type, removedNodes } = mutationRecord;
+                console.log(mutationRecord);
+                const addedElements = Array.from(addedNodes).filter(x => x instanceof Element);
+                addedElements.forEach(x => elsToInspect.push(x));
+                if (type === 'attributes') {
+                    const { target, attributeName, oldValue } = mutationRecord;
+                    if (target instanceof Element && attributeName !== null && attribMatches !== undefined && this.#mounted.has(target)) {
+                        let idx = 0;
+                        for (const attrMatch of attribMatches) {
+                            const { names } = attrMatch;
+                            if (names.includes(attributeName)) {
+                                const newValue = target.getAttribute(attributeName);
+                                // let parsedNewValue = undefined;
+                                // switch(type){
+                                //     case 'boolean':
+                                //         parsedNewValue = newValue === 'true' ? true : newValue === 'false' ? false : null;
+                                //         break;
+                                //     case 'date':
+                                //         parsedNewValue = newValue === null ? null : new Date(newValue);
+                                //         break;
+                                //     case ''
+                                // }
+                                const attrChangeInfo = {
+                                    name: attributeName,
+                                    oldValue,
+                                    newValue,
+                                    idx
+                                };
+                                this.dispatchEvent(new AttrChangeEvent(target, attrChangeInfo));
+                            }
+                            idx++;
+                        }
+                    }
+                    elsToInspect.push(target);
+                }
+                const deletedElements = Array.from(removedNodes).filter(x => x instanceof Element);
+                for (const deletedElement of deletedElements) {
+                    // if(!this.#mounted.has(deletedElement)) continue;
+                    // this.#mounted.delete(deletedElement);
+                    // this.#mountedList = this.#mountedList?.filter(x => x.deref() !== deletedElement);
+                    this.#disconnected.add(deletedElement);
+                    if (doDisconnect !== undefined) {
+                        doDisconnect(deletedElement, this);
+                    }
+                    this.dispatchEvent(new DisconnectEvent(deletedElement));
+                }
+            }
+            this.#filterAndMount(elsToInspect, true);
+        }, { signal: this.#abortController.signal });
+        await this.#inspectWithin(within);
+    }
+    #confirmInstanceOf(el, whereInstanceOf) {
+        for (const test of whereInstanceOf) {
+            if (el instanceof test)
+                return true;
+        }
+        return false;
+    }
+    async #mount(matching) {
+        //first unmount non matching
+        const alreadyMounted = this.#filterAndDismount();
+        const onMount = this.#mountInit.do?.onMount;
+        const { import: imp, attribMatches } = this.#mountInit;
+        for (const match of matching) {
+            if (alreadyMounted.has(match))
+                continue;
+            this.#mounted.add(match);
+            if (imp !== undefined) {
+                switch (typeof imp) {
+                    case 'string':
+                        this.module = await import(imp);
+                        break;
+                    case 'object':
+                        if (Array.isArray(imp)) {
+                            this.module = await import(imp[0], imp[1]);
+                        }
+                        break;
+                    case 'function':
+                        this.module = await imp(match, this, 'Import');
+                        break;
+                }
+            }
+            if (onMount !== undefined)
+                onMount(match, this, 'PostImport');
+            this.dispatchEvent(new MountEvent(match));
+            if (attribMatches !== undefined) {
+                let idx = 0;
+                for (const attribMatch of attribMatches) {
+                    let newValue = null;
+                    const { names } = attribMatch;
+                    let nonNullName = names[0];
+                    for (const name of names) {
+                        const attrVal = match.getAttribute(name);
+                        if (attrVal !== null)
+                            nonNullName = name;
+                        newValue = newValue || attrVal;
+                    }
+                    const attribInfo = {
+                        oldValue: null,
+                        newValue,
+                        idx,
+                        name: nonNullName
+                    };
+                    this.dispatchEvent(new AttrChangeEvent(match, attribInfo));
+                    idx++;
+                }
+            }
+            this.#mountedList?.push(new WeakRef(match));
+            //if(this.#unmounted.has(match)) this.#unmounted.delete(match);
+        }
+    }
+    async #dismount(unmatching) {
+        const onDismount = this.#mountInit.do?.onDismount;
+        for (const unmatch of unmatching) {
+            if (onDismount !== undefined) {
+                onDismount(unmatch, this);
+            }
+            this.dispatchEvent(new DismountEvent(unmatch));
+        }
+    }
+    #filterAndDismount() {
+        const returnSet = new Set();
+        if (this.#mountedList !== undefined) {
+            const previouslyMounted = this.#mountedList.map(x => x.deref());
+            const { whereSatisfies, whereInstanceOf } = this.#mountInit;
+            const match = this.#selector;
+            const elsToUnMount = previouslyMounted.filter(x => {
+                if (x === undefined)
+                    return false;
+                if (!x.matches(match))
+                    return true;
+                if (whereSatisfies !== undefined) {
+                    if (!whereSatisfies(x, this, 'Inspecting'))
+                        return true;
+                }
+                returnSet.add(x);
+                return false;
+            });
+            this.#dismount(elsToUnMount);
+        }
+        this.#mountedList = Array.from(returnSet).map(x => new WeakRef(x));
+        return returnSet;
+    }
+    async #filterAndMount(els, checkMatch) {
+        const { whereSatisfies, whereInstanceOf } = this.#mountInit;
+        const match = this.#selector;
+        const elsToMount = els.filter(x => {
+            if (checkMatch) {
+                if (!x.matches(match))
+                    return false;
+            }
+            if (whereSatisfies !== undefined) {
+                if (!whereSatisfies(x, this, 'Inspecting'))
+                    return false;
+            }
+            if (whereInstanceOf !== undefined) {
+                if (!this.#confirmInstanceOf(x, whereInstanceOf))
+                    return false;
+            }
+            return true;
+        });
+        this.#mount(elsToMount);
+    }
+    async #inspectWithin(within) {
+        const els = Array.from(within.querySelectorAll(this.#selector));
+        this.#filterAndMount(els, false);
+    }
+    unobserve() {
+        throw 'NI';
+    }
+}
+// https://github.com/webcomponents-cg/community-protocols/issues/12#issuecomment-872415080
+/**
+ * The `mutation-event` event represents something that happened.
+ * We can document it here.
+ */
+export class MountEvent extends Event {
+    mountedElement;
+    static eventName = 'mount';
+    constructor(mountedElement) {
+        super(MountEvent.eventName);
+        this.mountedElement = mountedElement;
+    }
+}
+export class DismountEvent extends Event {
+    dismountedElement;
+    static eventName = 'dismount';
+    constructor(dismountedElement) {
+        super(DismountEvent.eventName);
+        this.dismountedElement = dismountedElement;
+    }
+}
+export class DisconnectEvent extends Event {
+    disconnectedElement;
+    static eventName = 'disconnect';
+    constructor(disconnectedElement) {
+        super(DisconnectEvent.eventName);
+        this.disconnectedElement = disconnectedElement;
+    }
+}
+export class AttrChangeEvent extends Event {
+    mountedElement;
+    attrChangeInfo;
+    static eventName = 'attr-change';
+    constructor(mountedElement, attrChangeInfo) {
+        super(AttrChangeEvent.eventName);
+        this.mountedElement = mountedElement;
+        this.attrChangeInfo = attrChangeInfo;
+    }
+}

package/MountObserver.ts

@@ -0,0 +1,277 @@
+import {MountInit, MountContext, AddMutationEventListener, 
+    MutationEvent, dismountEventName, mountEventName, IMountEvent, IDismountEvent,
+    disconnectedEventName, IDisconnectEvent, IAttrChangeEvent, attrChangeEventName, AttrChangeInfo
+} from './types';
+import {RootMutObs} from './RootMutObs.js';
+
+
+const mutationObserverLookup = new WeakMap<Node, RootMutObs>();
+export class MountObserver extends EventTarget implements MountContext{
+    
+    #mountInit: MountInit;
+    #rootMutObs: RootMutObs | undefined;
+    #abortController: AbortController;
+    #mounted: WeakSet<Element>;
+    #mountedList: Array<WeakRef<Element>> | undefined;
+    #disconnected: WeakSet<Element>;
+    //#unmounted: WeakSet<Element>;
+    #isComplex: boolean;
+
+    constructor(init: MountInit){
+        super();
+        const {match, whereElementIntersectsWith, whereMediaMatches} = init;
+        this.#isComplex = match !== undefined && (match.includes(' ') || match.includes(':'));
+        if(whereElementIntersectsWith || whereMediaMatches) throw 'NI'; //not implemented
+        this.#mountInit = init;
+        this.#abortController = new AbortController();
+        this.#mounted = new WeakSet();
+        this.#disconnected = new WeakSet();
+        //this.#unmounted = new WeakSet();
+    }
+
+    #calculatedSelector: string | undefined;
+    get #selector(){
+        if(this.#calculatedSelector !== undefined) return this.#calculatedSelector;
+        const {match, attribMatches} = this.#mountInit;
+        const base = match || '*';
+        if(attribMatches === undefined) return base;
+        const matches: Array<string> = [];
+        attribMatches.forEach(x => {
+            const {names} = x;
+            names.forEach(y => {
+                matches.push(`${base}[${y}]`)
+            });
+        });
+        this.#calculatedSelector = matches.join(',');
+        return this.#calculatedSelector;
+    }
+
+    async observe(within: Node){
+        const nodeToMonitor = this.#isComplex ? (within instanceof ShadowRoot ? within : within.getRootNode()) : within; 
+        if(!mutationObserverLookup.has(nodeToMonitor)){
+            mutationObserverLookup.set(nodeToMonitor, new RootMutObs(nodeToMonitor));
+        }
+        const rootMutObs = mutationObserverLookup.get(within)!;
+        const {attribMatches} = this.#mountInit;
+        (rootMutObs as any as AddMutationEventListener).addEventListener('mutation-event', (e: MutationEvent) => {
+            //TODO:  disconnected
+            if(this.#isComplex){
+                this.#inspectWithin(within);
+                return;
+            }
+            const {mutationRecords} = e;
+            const elsToInspect: Array<Element> = [];
+            //const elsToDisconnect: Array<Element> = [];
+            const doDisconnect = this.#mountInit.do?.onDisconnect;
+            for(const mutationRecord of mutationRecords){
+                const {addedNodes, type, removedNodes} = mutationRecord;
+                console.log(mutationRecord);
+                const addedElements = Array.from(addedNodes).filter(x => x instanceof Element) as Array<Element>;
+                addedElements.forEach(x => elsToInspect.push(x));
+                if(type === 'attributes'){
+                    const {target, attributeName, oldValue} = mutationRecord;
+                    if(target instanceof Element && attributeName !== null &&  attribMatches !== undefined && this.#mounted.has(target)){
+                        let idx = 0;
+                        for(const attrMatch of attribMatches){
+                            const {names} = attrMatch;
+                            if(names.includes(attributeName)){
+                                const newValue = target.getAttribute(attributeName);
+                                // let parsedNewValue = undefined;
+                                // switch(type){
+                                //     case 'boolean':
+                                //         parsedNewValue = newValue === 'true' ? true : newValue === 'false' ? false : null;
+                                //         break;
+                                //     case 'date':
+                                //         parsedNewValue = newValue === null ? null : new Date(newValue);
+                                //         break;
+                                //     case ''
+
+                                // }
+                                const attrChangeInfo: AttrChangeInfo = {
+                                    name: attributeName,
+                                    oldValue,
+                                    newValue,
+                                    idx
+                                };
+                                this.dispatchEvent(new AttrChangeEvent(target, attrChangeInfo));
+                            }
+                            idx++;
+                        }
+                    }
+                    elsToInspect.push(target as Element);
+                }
+                const deletedElements = Array.from(removedNodes).filter(x => x instanceof Element) as Array<Element>;
+                for(const deletedElement of deletedElements){
+                    // if(!this.#mounted.has(deletedElement)) continue;
+                    // this.#mounted.delete(deletedElement);
+                    // this.#mountedList = this.#mountedList?.filter(x => x.deref() !== deletedElement);
+                    this.#disconnected.add(deletedElement);
+                    if(doDisconnect !== undefined){
+                        doDisconnect(deletedElement, this);
+                    }
+                    this.dispatchEvent(new DisconnectEvent(deletedElement));
+                }
+
+            }
+            this.#filterAndMount(elsToInspect, true);
+        }, {signal: this.#abortController.signal});
+        await this.#inspectWithin(within);
+    }
+
+    #confirmInstanceOf(el: Element, whereInstanceOf: Array<typeof Node>){
+        for(const test of whereInstanceOf){
+            if(el instanceof test) return true;
+        }
+        return false;
+    }
+
+    async #mount(matching: Array<Element>){
+        //first unmount non matching
+        const alreadyMounted = this.#filterAndDismount();
+        const onMount = this.#mountInit.do?.onMount; 
+        const {import: imp, attribMatches} = this.#mountInit;
+        for(const match of matching){
+            if(alreadyMounted.has(match)) continue;
+            this.#mounted.add(match);
+            if(imp !== undefined){
+                switch(typeof imp){
+                    case 'string':
+                        this.module =  await import(imp);
+                        break;
+                    case 'object':
+                        if(Array.isArray(imp)){
+                            this.module = await import(imp[0], imp[1]);
+                        }
+                        break;
+                    case 'function':
+                        this.module = await imp(match, this, 'Import');
+                        break;
+                }
+            }
+            if(onMount !== undefined) onMount(match, this, 'PostImport');
+            this.dispatchEvent(new MountEvent(match));
+            if(attribMatches !== undefined){
+                let idx = 0;
+                for(const attribMatch of attribMatches){
+                    let newValue = null;
+                    const {names} = attribMatch;
+                    let nonNullName = names[0];
+                    for(const name of names){
+                        const attrVal = match.getAttribute(name);
+                        if(attrVal !== null) nonNullName = name;
+                        newValue = newValue || attrVal;
+                    }
+                    const attribInfo: AttrChangeInfo = {
+                        oldValue: null,
+                        newValue,
+                        idx,
+                        name: nonNullName
+                    };
+                    this.dispatchEvent(new AttrChangeEvent(match, attribInfo));
+                    idx++;
+                }
+            }
+            this.#mountedList?.push(new WeakRef(match));
+            //if(this.#unmounted.has(match)) this.#unmounted.delete(match);
+        }
+    }
+
+    async #dismount(unmatching: Array<Element>){
+        const onDismount = this.#mountInit.do?.onDismount
+        for(const unmatch of unmatching){
+            if(onDismount !== undefined){
+                onDismount(unmatch, this);
+            }
+            this.dispatchEvent(new DismountEvent(unmatch));
+        }
+    }
+
+    #filterAndDismount(): Set<Element>{
+        const returnSet = new Set<Element>();
+        if(this.#mountedList !== undefined){
+            const previouslyMounted = this.#mountedList.map(x => x.deref());
+            const {whereSatisfies, whereInstanceOf} = this.#mountInit;
+            const match = this.#selector;
+            const elsToUnMount = previouslyMounted.filter(x => {
+                if(x === undefined) return false;
+                if(!x.matches(match)) return true;
+                if(whereSatisfies !== undefined){
+                    if(!whereSatisfies(x, this, 'Inspecting')) return true;
+                }
+                returnSet.add(x);
+                return false;
+            }) as Array<Element>;
+            this.#dismount(elsToUnMount);
+        }
+        this.#mountedList = Array.from(returnSet).map(x => new WeakRef(x));
+        return returnSet;
+    }
+
+    async #filterAndMount(els: Array<Element>, checkMatch: boolean){
+        const {whereSatisfies, whereInstanceOf} = this.#mountInit;
+        const match = this.#selector;
+        const elsToMount = els.filter(x => {
+            if(checkMatch){
+                if(!x.matches(match)) return false;
+            }
+            if(whereSatisfies !== undefined){
+                if(!whereSatisfies(x, this, 'Inspecting')) return false;
+            }
+            if(whereInstanceOf !== undefined){
+                if(!this.#confirmInstanceOf(x, whereInstanceOf)) return false;
+            }
+            return true;
+        });
+        this.#mount(elsToMount);
+    }
+
+    async #inspectWithin(within: Node){
+        const els = Array.from((within as Element).querySelectorAll(this.#selector));
+        this.#filterAndMount(els, false);
+    }
+
+    unobserve(){
+        throw 'NI';
+    }
+
+}
+
+export interface MountObserver extends MountContext{}
+
+// https://github.com/webcomponents-cg/community-protocols/issues/12#issuecomment-872415080
+/**
+ * The `mutation-event` event represents something that happened.
+ * We can document it here.
+ */
+export class MountEvent extends Event implements IMountEvent {
+    static eventName: mountEventName = 'mount';
+  
+    constructor(public mountedElement: Element) {
+      super(MountEvent.eventName);
+      
+    }
+}
+
+export class DismountEvent extends Event implements IDismountEvent{
+    static eventName: dismountEventName = 'dismount';
+
+    constructor(public dismountedElement: Element){
+        super(DismountEvent.eventName)
+    }
+}
+
+export class DisconnectEvent extends Event implements IDisconnectEvent{
+    static eventName: disconnectedEventName = 'disconnect';
+
+    constructor(public disconnectedElement: Element){
+        super(DisconnectEvent.eventName);
+    }
+}
+
+export class AttrChangeEvent extends Event implements IAttrChangeEvent{
+    static eventName: attrChangeEventName = 'attr-change';
+    constructor(public mountedElement: Element, public attrChangeInfo: AttrChangeInfo){
+        super(AttrChangeEvent.eventName);
+    }
+}
+

package/README.md

@@ -1 +1,212 @@
-# mount-observer
+# The MountObserver api.
+
+Author:  Bruce B. Anderson
+
+Issues / pr's / polyfill:  [mount-observer](https://github.com/bahrus/mount-observer)
+
+Last Update: 2023-11-18
+
+## Benefits of this API
+
+What follows is a far more ambitious alternative to the [lazy custom element proposal](https://github.com/w3c/webcomponents/issues/782).  The goals of the MountObserver api are more encompassing, and less focused on registering custom elements.  In fact, this proposal addresses numerous use cases in one api.  It is basically mapping common filtering conditions in the DOM, to common actions, like importing a resource, or progressively enhancing an element, or "binding from a distance".
+
+"Binding from a distance" refers to empowering the developer to essentially manage their own "stylesheets" -- but rather than for purposes of styling, using these rules to attach behaviors, set property values, etc.
+
+The underlying theme is this api is meant to make it easy for the developer to do the right thing, by encouraging lazy loading and smaller footprints. It rolls up most all the other observer api's into one.
+
+### Does this api make the impossible possible?
+
+There is quite a bit of functionality this proposal would open up, that is exceedingly difficult to polyfill reliably:  
+
+1.  It is unclear how to use mutation observers to observe changes to [custom state](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet).  The closest thing might be a solution like [this](https://davidwalsh.name/detect-node-insertion), but that falls short for elements that aren't visible, or during template instantiation.
+
+2.  For simple css matches, like "my-element", or "[name='hello']" it is enough to use a mutation observer, and only observe the elements within the specified DOM region (more on that below).  But as CSS has evolved, it is quite easy to think of numerous css selectors that would require us to expand our mutation observer to need to scan the entire Shadow DOM realm, or the entire DOM tree outside any Shadow DOM, for any and all mutations (including attribute changes), and re-evaluate every single element within the specified DOM region for new matches or old matches that no longer match.  Things like child selectors, :has, and so on. All this is done, miraculously, by the browser in a performant way.  Reproducing this in userland using JavaScript alone, matching the same performance seems impossible.
+
+3.  Knowing when an element, previously being monitored for, passes totally "out-of-scope", so that no more hard references to the element remain.  This would allow for cleanup of no longer needed weak references without requiring polling.
+
+###  Most significant use cases.
+
+The amount of code necessary to accomplish these common tasks designed to improve the user experience is significant.  Building it into the platform would potentially:
+
+1.  Give the developer a strong signal to do the right thing, by 
+    1.  Making lazy loading of resource dependencies easy, to the benefit of users with expensive networks.
+    2.  Supporting "binding from a distance" that can allow SSR to provide common, shared data using the "DRY" philosophy, similar to how CSS can reduce the amount of repetitive styling instructions found inline within the HTML Markup.
+    3.  Supporting "progressive enhancement."
+2.  Allow numerous components / libraries to leverage this common functionality, which could potentially significantly reduce bandwidth.
+3.  Potentially by allowing the platform to do more work in the low-level (c/c++/rust?) code, without as much context switching into the JavaScript memory space, which may reduce cpu cycles as well.
+4.  To do the job right, polyfills really need to reexamine **all** the elements within the observed node for matches **anytime any element within the Shadow Root so much as sneezes (has attribute modified, changes custom state, etc)**, due to modern selectors such as the :has selector.  Surely, the platform has found ways to do this more efficiently?  
+
+The extra flexibility this new primitive would provide could be quite useful to things other than lazy loading of custom elements, such as implementing [custom enhancements](https://github.com/WICG/webcomponents/issues/1000) as well as [binding from a distance](https://github.com/WICG/webcomponents/issues/1035#issuecomment-1806393525) in userland.
+
+## First use case -- lazy loading custom elements
+
+To specify the equivalent of what the alternative proposal linked to above would do, we can do the following:
+
+```JavaScript
+const observer = new MountObserver({
+   match:'my-element',
+   import: './my-element.js',
+   do: {
+      onMount: ({localName}, {module}) => {
+        if(!customElements.get(localName)) {
+            customElements.define(localName, module.default);
+        }
+      }
+   }
+});
+observer.observe(document);
+```
+
+If no import is specified, it would go straight to do.* (if any such callbacks are specified), and it will also dispatch events as discussed below.
+
+This only searches for elements matching 'my-element' outside any shadow DOM.
+
+But the observe method can accept a shadowRoot, or a node inside a shadowRoot as well.
+
+The import can also be a function:
+
+```JavaScript
+const observer = new MountObserver({
+   match: 'my-element',
+   import: async (matchingElement, {module}) => await import('./my-element.js');
+});
+observer.observe(myRootNode);
+```
+
+which would work better with current bundlers, I suspect.  Also, we can do interesting things like merge multiple imports into one "module".  But should this API built into the platform, such functions wouldn't be necessary, as bundlers could start to recognize strings that are passed to the MountObserver's constructor.
+
+This proposal would also include support for CSS, JSON, HTML module imports.  
+
+"match" is a css query, and could include multiple matches using the comma separator, i.e. no limitation on CSS expressions.
+
+The "observer" constant above is a class instance that inherits from EventTarget, which means it can be subscribed to by outside interests.
+
+<!-- As matches are found (for example, right away if matching elements are immediately found), the imports object would maintain a read-only array of weak references, along with the imported module:
+
+```TypeScript
+interface MountContext {
+    weakReferences:  readonly WeakRef<Element>[];
+    module: any;
+}
+```
+
+This allows code that comes into being after the matching elements were found, to "get caught up" on all the matches. -->
+
+
+##  Extra lazy loading
+
+By default, the matches would be reported as soon as an element matching the criterion is found or added into the DOM, inside the node specified by rootNode.
+
+However, we could make the loading even more lazy by specifying intersection options:
+
+```JavaScript
+const observer = new MountObserver({
+   match: 'my-element',
+   whereElementIntersectsWith:{
+      rootMargin: "0px",
+      threshold: 1.0,
+   },
+   import: './my-element.js'
+});
+```
+
+## Media / container queries / instanceOf / custom checks
+
+Unlike traditional CSS @import, CSS Modules don't support specifying different imports based on media queries.  That can be another condition we can attach (and why not throw in container queries, based on the rootNode?):
+
+```JavaScript
+const observer = new MountObserver({
+   match: 'my-element',
+   whereMediaMatches: '(max-width: 1250px)',
+   whereSizeOfContainerMatches: '(min-width: 700px)',
+   whereInstanceOf: [HTMLMarqueeElement],
+   whereSatisfies: async (matchingElement, context) => true,
+   import: ['./my-element-small.css', {type: 'css'}],
+   do: {
+      onMount: ({localName}, {module}) => {
+        ...
+      },
+      onDismount: ...,
+      onDisconnect: ...,
+      onReconnect: ...,
+      onReconfirm: ...
+      onOutOfScope: ...,
+   }
+})
+```
+
+## Subscribing
+
+Subscribing can be done via:
+
+```JavaScript
+observer.addEventListener('mount', e => {
+  console.log({
+      matchingElement: e.matchingElement, 
+      module: e.module
+   });
+});
+
+observer.addEventListener('dismount', e => {
+  ...
+});
+
+observer.addEventListener('reconnect', e => {
+  ...
+});
+observer.addEventListener('disconnect', e => {
+  ...
+});
+observer.addEventListener('reconfirm', e => {
+  ...
+});
+observer.addEventListener('out-of-scope', e => {
+  ...
+});
+```
+
+## Explanation of all states / events
+
+Normally, an element stays in its place in the DOM tree, but the conditions that the MountObserver instance is monitoring for can change for the element, based on modifications to the attributes of the element itself, or its custom state, or to other peer elements within the shadowRoot, if any, or window resizing, etc.  As the element meets or doesn't meet all the conditions, the mountObserver will first call the corresponding mount/dismount callback, and then dispatch event "mount" or "dismount" according to whether the criteria are all met or not.
+
+The moment a MountObserver instance's "observe" method is called (passing in a root node), it will inspect every element within its subtree (not counting ShadowRoots), and then call the "mount" callback, and dispatch event "mount" for those elements that match the criteria.  It will *not* dispatch "dismount" for elements that don't.
+
+If an element that is in "mounted" state according to a MountObserver instance is moved from one parent DOM element to another:
+
+1)  "disconnect" event is dispatched from the MountObserver instance the moment the element is disconnected from the DOM fragment.
+2)  If/when the element is added somewhere else in the DOM tree, the mountObserver instance will dispatch event "reconnect", regardless of where. [Note:  can't polyfill this very easily]
+3)  If the element is added outside the rootNode being observed, the mountObserver instance will dispatch event "outside-root-node", and the MountObserver instance will relinquish any further responsibility for this element.  Ideally this would also be dispatched when the platform garbage collects the element as well after all hard references are relinquished.
+4)  If the new place it was added remains within the original rootNode and remains either dismounted or mounted, the MountObserver instance dispatches event "reconfirmed".
+5)  If the element no longer satisfies the criteria of the MountObserver instance, the MountObserver instance will dispatch event "dismount".  The same is done in reverse for moved elements that started out in a "dismounted" state. 
+
+## Special support for attributes
+
+Extra support is provided for monitoring attributes.
+
+## Preemptive downloading
+
+There are two significant steps to imports, each of which imposes a cost:  
+
+1.  Downloading the resource.
+2.  Loading the resource into memory.
+
+What if we want to download the resource ahead of time, but only load into memory when needed?
+
+The link rel=modulepreload option provides an already existing platform support for this, but the browser complains when no use of the resource is used within a short time span of page load.  That doesn't really fit the bill for lazy loading custom elements and other resources.
+
+So for this we add option:
+
+```JavaScript
+const observer = new MountObserver({
+   match: 'my-element',
+   loading: 'eager',
+   import: './my-element.js',
+   do:{
+      onMount: (matchingElement, {module}) => customElements.define(module.MyElement)
+   }
+})
+```
+
+So what this does is only check for the presence of an element with tag name "my-element", and it starts downloading the resource, even before the element has "mounted" based on other criteria.
+
+

package/RootMutObs.js

@@ -0,0 +1,29 @@
+export class RootMutObs extends EventTarget {
+    constructor(rootNode) {
+        super();
+        this.#mutationObserver = new MutationObserver(mutationRecords => {
+            this.dispatchEvent(new MutationEvent(mutationRecords));
+        });
+        this.#mutationObserver.observe(rootNode, {
+            subtree: true,
+            childList: true,
+            attributes: true,
+            attributeOldValue: true,
+        });
+    }
+    #mutationObserver;
+}
+// https://github.com/webcomponents-cg/community-protocols/issues/12#issuecomment-872415080
+/**
+ * The `mutation-event` event represents something that happened.
+ * We can document it here.
+ */
+export class MutationEvent extends Event {
+    mutationRecords;
+    static eventName = 'mutation-event';
+    constructor(mutationRecords) {
+        // Since these are hard-coded, dispatchers can't get them wrong
+        super(MutationEvent.eventName);
+        this.mutationRecords = mutationRecords;
+    }
+}

package/RootMutObs.ts

@@ -0,0 +1,37 @@
+import {mutationEventName, AddMutationEventListener} from './types';
+
+export class RootMutObs extends EventTarget{
+    constructor(rootNode: Node ){
+        super();
+        this.#mutationObserver = new MutationObserver(mutationRecords => {
+            this.dispatchEvent(new MutationEvent(mutationRecords))
+        })
+        this.#mutationObserver.observe(rootNode, {
+            subtree: true,
+            childList: true,
+            attributes: true,
+            attributeOldValue: true,
+        });
+    }
+    #mutationObserver: MutationObserver;
+}
+
+
+
+// https://github.com/webcomponents-cg/community-protocols/issues/12#issuecomment-872415080
+
+/**
+ * The `mutation-event` event represents something that happened.
+ * We can document it here.
+ */
+export class MutationEvent extends Event implements MutationEvent {
+    static eventName: mutationEventName = 'mutation-event';
+  
+    constructor(public mutationRecords: Array<MutationRecord>) {
+      // Since these are hard-coded, dispatchers can't get them wrong
+      super(MutationEvent.eventName);
+    }
+}
+
+
+

package/demo/test1.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Document</title>
+</head>
+<body>
+    <div id=div>
+        <span id=span></span>
+    </div>
+    <script type=module>
+        import {MountObserver} from '../MountObserver.js';
+        const mo = new MountObserver({
+            match: '#span',
+            do:{
+                onMount: (el, ctx) => {
+                    console.log({el, ctx});
+                }
+            }
+        });
+        mo.addEventListener('mount', e => {
+            console.log(e);
+        });
+        mo.observe(div);
+    </script>
+</body>
+</html>

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "mount-observer",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "description": "",
-  "main": "index.js",
+  "main": "MountObserver.js",
+  "module": "MountObserver.js",
+  "devDependencies": {
+    "@playwright/test": "1.39.0",
+    "may-it-serve": "0.0.6"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "serve": "node node_modules/may-it-serve",
+    "test": "playwright test",
+    "safari": "npx playwright wk http://localhost:3030",
+    "update": "ncu -u && npm install"
   },
   "author": "",
   "license": "MIT"

package/playwright.config.ts

@@ -0,0 +1,29 @@
+// playwright.config.ts
+import { PlaywrightTestConfig, devices } from '@playwright/test';
+const config: PlaywrightTestConfig = {
+  webServer: {
+    command: 'npm run serve',
+    url: 'http://localhost:3030/',
+    timeout: 120 * 1000,
+    reuseExistingServer: !process.env.CI,
+  },
+  use: {
+    baseURL: 'http://localhost:3030/',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    //firefox lacks support for import assertions
+    // {
+    //   name: 'firefox',
+    //   use: { ...devices['Desktop Firefox'] },
+    // },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+  ],
+};
+export default config;

package/tests/test1.html

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Document</title>
+</head>
+<body>
+    <div id=div>
+        <span id=span></span>
+    </div>
+    <div id=target></div>
+    <script type=module>
+        import {MountObserver} from '../MountObserver.js';
+        const mo = new MountObserver({
+            match: '#span',
+            do:{
+                onMount: (el, ctx) => {
+                    console.log({el, ctx});
+                    target.setAttribute('mark', 'good');
+                }
+            }
+        });
+        mo.addEventListener('mount', e => {
+            console.log(e);
+        });
+        mo.observe(div);
+    </script>
+</body>
+</html>

package/tests/test1.spec.mjs

@@ -0,0 +1,8 @@
+import { test, expect } from '@playwright/test';
+test('test1', async ({ page }) => {
+    await page.goto('./tests/test1.html');
+    // wait for 1 second
+    await page.waitForTimeout(1000);
+    const editor = page.locator('#target');
+    await expect(editor).toHaveAttribute('mark', 'good');
+});

package/tests/test2.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Document</title>
+</head>
+<body>
+    <div id=div>
+    </div>
+    <div id=target></div>
+    <script type=module>
+        import {MountObserver} from '../MountObserver.js';
+        const mo = new MountObserver({
+            match: '#span',
+            do:{
+                onMount: (el, ctx) => {
+                    console.log({el, ctx});
+                    target.setAttribute('mark', 'good');
+                }
+            }
+        });
+        mo.addEventListener('mount', e => {
+            console.log(e);
+        });
+        mo.observe(div);
+        setTimeout(() => {
+            const span = document.createElement('span');
+            span.id = 'span';
+            div.appendChild(span);
+        }, 500);
+    </script>
+</body>
+</html>

package/tests/test2.spec.mjs

@@ -0,0 +1,8 @@
+import { test, expect } from '@playwright/test';
+test('test1', async ({ page }) => {
+    await page.goto('./tests/test2.html');
+    // wait for 1 second
+    await page.waitForTimeout(1000);
+    const editor = page.locator('#target');
+    await expect(editor).toHaveAttribute('mark', 'good');
+});

package/tests/test3.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Document</title>
+</head>
+<body>
+    <div id=div>
+            <span></span>
+    </div>
+    <div id=target></div>
+    <script type=module>
+        import {MountObserver} from '../MountObserver.js';
+        const mo = new MountObserver({
+            match: '#span',
+            do:{
+                onMount: (el, ctx) => {
+                    console.log({el, ctx});
+                    target.setAttribute('mark', 'good');
+                }
+            }
+        });
+        mo.addEventListener('mount', e => {
+            console.log(e);
+        });
+        mo.observe(div);
+        setTimeout(() => {
+            const span = div.querySelector('span');
+            span.id = 'span';
+        }, 500);
+    </script>
+</body>
+</html>

package/tests/test3.spec.mjs

@@ -0,0 +1,8 @@
+import { test, expect } from '@playwright/test';
+test('test1', async ({ page }) => {
+    await page.goto('./tests/test3.html');
+    // wait for 1 second
+    await page.waitForTimeout(1000);
+    const editor = page.locator('#target');
+    await expect(editor).toHaveAttribute('mark', 'good');
+});

package/tests/test4.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Document</title>
+</head>
+<body>
+    <div id=div>
+        <span id=span></span>
+    </div>
+    <div id=target></div>
+    <script type=module>
+        import {MountObserver} from '../MountObserver.js';
+        const mo = new MountObserver({
+            match: '#span',
+            do:{
+                onMount: (el, ctx) => {
+                    console.log({el, ctx});
+                    
+                }
+            }
+        });
+        mo.addEventListener('mount', e => {
+            console.log(e);
+            target.setAttribute('mark', 'good');
+        });
+        mo.observe(div);
+    </script>
+</body>
+</html>

package/tests/test4.spec.mjs

@@ -0,0 +1,8 @@
+import { test, expect } from '@playwright/test';
+test('test1', async ({ page }) => {
+    await page.goto('./tests/test4.html');
+    // wait for 1 second
+    await page.waitForTimeout(1000);
+    const editor = page.locator('#target');
+    await expect(editor).toHaveAttribute('mark', 'good');
+});

package/tests/test5.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Document</title>
+</head>
+<body>
+    <div id=div>
+        <span id=span></span>
+    </div>
+    <div id=target></div>
+    <script type=module>
+        import {MountObserver} from '../MountObserver.js';
+        const mo = new MountObserver({
+            match: '#span',
+            do:{
+                onDisconnect: (el, ctx) => {
+                    console.log({el, ctx});
+                    
+                }
+            }
+        });
+        mo.addEventListener('disconnect', e => {
+            console.log(e);
+            target.setAttribute('mark', 'good');
+        });
+        mo.observe(div);
+        setTimeout(() => {
+            span.remove();
+        }, 1000);
+    </script>
+</body>
+</html>

package/tests/test5.spec.mjs

@@ -0,0 +1,8 @@
+import { test, expect } from '@playwright/test';
+test('test1', async ({ page }) => {
+    await page.goto('./tests/test5.html');
+    // wait for 1 second
+    await page.waitForTimeout(1000);
+    const editor = page.locator('#target');
+    await expect(editor).toHaveAttribute('mark', 'good');
+});

package/tests/test6.html

@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Document</title>
+</head>
+<body>
+    <div id=div>
+        <span id=span></span>
+    </div>
+    <div id=target></div>
+    <script type=module>
+        import {MountObserver} from '../MountObserver.js';
+        const mo = new MountObserver({
+            match: '#span',
+            attribMatches:[
+                {
+                    names: ['test-1']
+                }
+            ],
+            do:{
+                onDisconnect: (el, ctx) => {
+                    console.log({el, ctx});
+                    
+                }
+            }
+        });
+        mo.addEventListener('attr-change', e => {
+            console.log(e);
+            target.setAttribute('mark', 'good');
+        });
+        mo.observe(div);
+        setTimeout(() => {
+            span.setAttribute('test-1', 'hello')
+        }, 1000);
+    </script>
+</body>
+</html>

package/tests/test6.spec.mjs

@@ -0,0 +1,8 @@
+import { test, expect } from '@playwright/test';
+test('test1', async ({ page }) => {
+    await page.goto('./tests/test6.html');
+    // wait for 1 second
+    await page.waitForTimeout(1000);
+    const editor = page.locator('#target');
+    await expect(editor).toHaveAttribute('mark', 'good');
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"sourceMap": false,
+		"experimentalDecorators": false,
+		"newLine": "LF",
+		"strict": true,
+	},
+	"files": [
+		"MountObserver.ts",
+	],
+	"exclude":[
+		"node_modules"
+	]
+
+}

package/types.d.ts

@@ -0,0 +1,110 @@
+export interface MountInit{
+    readonly match?: CSSMatch,
+    readonly attribMatches?: Array<AttribMatch>,  
+    readonly whereElementIntersectsWith?: IntersectionObserverInit,
+    readonly whereMediaMatches?: MediaQuery,
+    readonly whereInstanceOf?: Array<typeof Node>, //[TODO] What's the best way to type this?,
+    readonly whereSatisfies?: PipelineProcessor<boolean>,
+    readonly import?: ImportString | [ImportString, ImportAssertions] | PipelineProcessor,
+    readonly do?: {
+        readonly onMount: PipelineProcessor,
+        readonly onDismount: PipelineProcessor,
+        readonly onDisconnect: PipelineProcessor,
+        readonly onReconfirmed: PipelineProcessor,
+        readonly onOutsideRootNode: PipelineProcessor,
+    }
+    
+}
+type CSSMatch = string;
+type ImportString = string;
+type MediaQuery = string;
+
+export interface AttribMatch{
+    names: string[],
+    //for boolean, support true/false/mixed
+    // type?: 'number' | 'string' | 'date' | 'json-object' | 'boolean',
+    // valConverter?: (s: string) => any,
+    // validator?: (v: any) => boolean;
+}
+
+export interface MountContext {
+    // readonly mountInit: MountInit,
+    // readonly mountedRefs:  WeakRef<Element>[],
+    // readonly dismountedRefs: WeakRef<Element>[],
+    observe(within: Node): void;
+    unobserve(): void;
+    module?: any;
+} 
+
+type PipelineStage = 'Inspecting' | 'PreImport' | 'PostImport' | 'Import'
+export type PipelineProcessor<ReturnType = void> = (matchingElement: Element, ctx: MountContext, stage?: PipelineStage) => Promise<ReturnType>;
+
+//#region mutation event
+export type mutationEventName = 'mutation-event';
+export interface MutationEvent{
+    mutationRecords: Array<MutationRecord>
+}
+export type mutationEventHandler = (e: MutationEvent) => void;
+
+export interface AddMutationEventListener {
+    addEventListener(eventName: mutationEventName, handler: mutationEventHandler, options?: AddEventListenerOptions): void;
+}
+//#endregion
+
+interface AttrChangeInfo{
+    name: string,
+    oldValue: string | null,
+    newValue: string | null,
+    idx: number,
+    //parsedNewValue?: any,
+}
+
+//#region mount event
+export type mountEventName = 'mount';
+export interface IMountEvent{
+    mountedElement: Element,
+}
+export type mountEventHandler = (e: IMountEvent) => void;
+
+export interface AddMountEventListener {
+    addEventListener(eventName: mountEventName, handler: mountEventHandler, options?: AddEventListenerOptions): void;
+}
+//#endregion
+
+//#region dismount event
+export type dismountEventName = 'dismount';
+export interface IDismountEvent {
+    dismountedElement: Element
+}
+
+export type dismountEventHandler = (e: IDismountEvent) => void;
+
+export interface AddDismountEventListener {
+    addEventListener(eventName: dismountEventName, handler: dismountEventHandler, options?: AddEventListenerOptions): void;
+}
+//#endregion
+
+//#region disconnected event
+export type disconnectedEventName = 'disconnect';
+export interface IDisconnectEvent {
+    disconnectedElement: Element
+}
+
+export type disconnectedEventHandler = (e: IDisconnectEvent) => void;
+
+export interface AddDisconnectEventListener {
+    addEventListener(eventName: disconnectedEventName, handler: disconnectedEventHandler, options?: AddEventListenerOptions): void;
+}
+//endregion
+
+//#region attribute change event
+export type attrChangeEventName = 'attr-change';
+export interface IAttrChangeEvent extends IMountEvent {
+    attrChangeInfo: AttrChangeInfo,
+}
+export type attrChangeEventHander = (e: IAttrChangeEvent) => void;
+export interface AddAttrChangeEventistener{
+    addEventListener(eventName: attrChangeEventName, handler: attrChangeEventHander, options?: AddEventListenerOptions): void;
+}
+//#endregion
+