mount-observer 0.1.4 → 0.1.5

package/README.md

@@ -10,19 +10,13 @@ Note that much of what is described below has not yet been polyfilled.
 The following features have been implemented and tested:
 
 ### Core Functionality
-- ✅ **whereElementMatches**: CSS selector-based element matching
-- ✅ **whereAttr**: Complex attribute-based matching with:
-  - Built-in vs custom element distinction
-  - Attribute prefix variations (data-, enh-, data-enh-)
-  - Hierarchical attribute branches with customizable delimiters
-  - Coordinate system for attribute mapping
-- ✅ **whereInstanceOf**: Constructor-based element filtering (single or array)
-- ✅ **whereMediaMatches**: Media query-based conditional mounting (string or MediaQueryList)
-- ✅ **whereOutside**: Donut hole scoping (exclude elements inside matching ancestors)
+- ✅ **matching**: CSS selector-based element matching
+- ✅ **withInstance**: Constructor-based element filtering (single or array)
+- ✅ **withMediaMatching**: Media query-based conditional mounting (string or MediaQueryList)
+- ✅ **withScopePerimeter**: Donut hole scoping (exclude elements inside matching ancestors)
 
 ### Lifecycle & Events
 - ✅ **mount/dismount/disconnect events**: Element lifecycle tracking
-- ✅ **attrchange event**: Attribute change notifications with batching
 - ✅ **mediamatch/mediaunmatch events**: Media query state change notifications (with `getPlayByPlay` option)
 - ✅ **load event**: Import completion notification
 
@@ -30,9 +24,11 @@ The following features have been implemented and tested:
 - ✅ **Dynamic imports**: Lazy loading of JavaScript modules
 - ✅ **assignOnMount**: Property assignment when elements mount
 - ✅ **assignOnDismount**: Property assignment when elements dismount
+- ✅ **stageOnMount**: Reversible property assignment (auto-restores on dismount)
+- ✅ **spawn**: Automatic enhancement spawning via assign-gingerly integration
 - ✅ **do callbacks**: Mount/dismount/disconnect/reconnect lifecycle hooks
-- ✅ **map configuration**: Metadata mapping for attribute coordinates
-- ✅ **once option**: Fire attrchange event only once per attribute
+- ✅ **Array argument shorthand**: Pass EnhancementConfig[] directly to constructor
+- ✅ **Element mount extension**: element.mount() method for scoped registry observation
 - ✅ **Shared MutationObserver**: Efficient observer sharing across instances
 - ✅ **Code splitting**: Conditional features loaded on-demand
 - ✅ **Memory management**: WeakRef usage for DOM node references
@@ -44,21 +40,21 @@ The following features have been implemented and tested:
 - ❌ Reconnect event handling
 - ❌ Multiple import types (CSS, JSON, HTML)
 
-# The MountObserver api.
+# The MountObserver API
 
-Author:  Bruce B. Anderson (with valuable feedback from @doeixd )
+Author: Bruce B. Anderson (with valuable feedback from @doeixd)
 
-Issues / pr's / polyfill:  [mount-observer](https://github.com/bahrus/mount-observer)
+Issues / PRs / polyfill: [mount-observer](https://github.com/bahrus/mount-observer)
 
 Last Update: Aug 7, 2025
 
 ## 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 mounting a "campaign" of some sort, like importing a resource, and/or progressively enhancing an element, and/or "binding from a distance".
+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 basically maps common filtering conditions in the DOM to mounting a "campaign" of some sort, like importing a resource, and/or progressively enhancing an element, and/or "binding from a distance".
 
 ["Binding from a distance"](https://github.com/WICG/webcomponents/issues/1035#issuecomment-1806393525) 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, to the HTML as it streams in.  Libraries that take this approach include [Corset](https://corset.dev/) and [trans-render](https://github.com/bahrus/trans-render), [selector-observer](https://github.com/josh/selector-observer), [pure](http://web.archive.org/web/20160313152905/https://beebole.com/pure/), [weld](https://github.com/tmpvar/weld), [bess](https://github.com/bkardell/bess).  The concept has been promoted by a [number](https://bkardell.com/blog/CSSLike.html) [of](https://www.w3.org/TR/NOTE-AS)  [prominent](https://www.xanthir.com/blog/b4K_0) voices in the community. 
 
-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, including, potentially, [a selector observer](https://github.com/whatwg/dom/issues/1285), which may be a similar duplicate to [the match-media counterpart proposal](https://github.com/whatwg/dom/issues/1225).
+The underlying theme is that this API is meant to make it easy for developers to do the right thing by encouraging lazy loading and smaller footprints. It rolls up most of the other observer APIs into one, including, potentially, [a selector observer](https://github.com/whatwg/dom/issues/1285), which may be a similar duplicate to [the match-media counterpart proposal](https://github.com/whatwg/dom/issues/1225).
 
 ### Finite Element Analysis
 
@@ -77,41 +73,112 @@ ES module based web components may or may not be the best fit for these applicat
 A significant pain point has to do with downloading all the third-party web components and/or (progressive) enhancements that these macro components / compositions require, and loading them into memory only when needed.
 
 
-### Does this api make the impossible possible?
+### 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:  
+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, and requires carefully constructed "negating" queries if needing to know when the css selector is no longer matching.
+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, and requires carefully constructed "negating" queries if needing to know when the CSS selector is no longer matching.
 
-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.  
+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 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 while 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.
+3. Knowing when an element previously being monitored 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.
 
-4.  Some css selectors, such as the [scope donut hole range](https://css-tricks.com/solved-by-css-donuts-scopes/#aa-donut-scoping-with-scope) aren't supported by oEl.querySelectorAll(...) or oEl.matches(...).
+4. Some CSS selectors, such as the [scope donut hole range](https://css-tricks.com/solved-by-css-donuts-scopes/#aa-donut-scoping-with-scope), aren't supported by oEl.querySelectorAll(...) or oEl.matches(...).
 
-###  Most significant use cases.
+###  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:
+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 set property values of elements in bulk as the HTML streams in.  For example, say a web page is streaming in HTML with thousands of input elements (say a long tax form).  We want to have some indication in the head tag of the HTML (for example) to make all the input elements read only as they stream through the page. With css, we could do similar things, for example set the background to red of all input elements. Why can't we do something similar with setting properties like readOnly, disabled, etc?  With this api, giving developers the "keys" to css filtering, so they can "mount a campaign" to apply common settings on them all feels like something that almost every web developer has mentally screamed to themselves "why can't I do that?", doesn't it? 
-    3.  Supporting "progressive enhancement" more effectively.
-2.  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.  This is done by passing into the API substantial number of conditions, which can all be evaluated at a lower level, before the api needs to surface up to the developer "found one!".
-3.  As discussed earlier, 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?  
+1. Give developers 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 set property values of elements in bulk as the HTML streams in. For example, say a web page is streaming in HTML with thousands of input elements (say a long tax form). We want to have some indication in the head tag of the HTML (for example) to make all the input elements read-only as they stream through the page. With CSS, we could do similar things, for example set the background to red of all input elements. Why can't we do something similar with setting properties like readOnly, disabled, etc? With this API, giving developers the "keys" to CSS filtering so they can "mount a campaign" to apply common settings on them all feels like something that almost every web developer has mentally screamed to themselves "why can't I do that?", doesn't it?
+    3. Supporting "progressive enhancement" more effectively.
+2. Potentially allow the platform to do more work in low-level (C/C++/Rust?) code without as much context switching into the JavaScript memory space, which may reduce CPU cycles as well. This is done by passing a substantial number of conditions into the API, which can all be evaluated at a lower level before the API needs to surface up to the developer "found one!".
+3. As discussed earlier, 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 an 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
+## Quick Examples of the Most Common Use Cases
+
+Before getting into the weeds, let's demonstrate the two most prominent use cases:
+
+### Use Case 1:  Custom Attribute Enhancement
+
+```html
+<body>
+    <div log-to-console="clicked on a div">hello</div>
+
+    <script type=module>
+        import 'mount-observer/ElementMountExtension.js';
+        document.body.mount([{
+            withAttrs:{base: 'log-to-console'},
+            spawn: function(el){
+                el.addEventListener('click', e => {
+                  console.log(e.target.getAttribute('log-to-console'));
+                });
+            },
+        }])
+    </script>
+</body>
+```
+
+See [this extending package](https://github.com/bahrus/mount-observer-script-element) that provides for a more declarative approach.
+
+### Use Case 2: Lazy Global Custom Element Definition
 
-To specify the equivalent of what the alternative proposal linked to above would do, we can do the following:
+To specify the equivalent of what the [alternative proposal linked to above would do](https://github.com/WICG/webcomponents/issues/782), we can do the following:
+
+```JavaScript
+// MyElement.js
+export default class MyElement extends HTMLElement {
+    connectedCallback() {
+        this.textContent = 'Hello!';
+    }
+}
+
+// main.js
+import 'mount-observer/ElementMountExtension.js';
+
+document.mount({
+    matching: 'my-element',
+    import: './MyElement.js',
+    do: 'builtIns.defineCustomElement'
+});
+
+// HTML - elements will be upgraded when discovered
+// by the mount observer
+<my-element></my-element>
+
+```
+
+This registers custom elements with the global customElements registry.
+
+### Scoped
+
+To register the class in the same custom element registry as the element which calls the "mount" method (element in this case), use "builtIns.defineScopedCustomElement":
+
+```JavaScript
+element.mount({
+    matching: 'my-element',
+    import: './MyElement.js',
+    do: 'builtIns.defineScopedCustomElement'
+});
+```
+
+
+# Thorough Exposition Begins Here
+
+Okay, let's get into the weeds.  First, we strongly recommend studying the core package that mount-observer extends, [assign-gingerly](https://www.npmjs.com/package/assign-gingerly).
+
+## First use case -- lazy loading custom elements without sugar coating
+
+This registers the custom element in the global registry.
 
 ```JavaScript
 const observer = new MountObserver({
    select:'my-element', //not supported by this polyfill
    import: './my-element.js',
-   do: ({localName}, {modules, observer, mountInit, rootNode}) => {
+   do: ({localName}, {modules, observer, MountConfig, rootNode}) => {
       if(!customElements.get(localName)) {
          customElements.define(localName, modules[0].MyElement);
       }
@@ -139,7 +206,7 @@ The "observer" constant above is a class instance that inherits from EventTarget
 > [!Note]
 > Reading through the historical links tied to the selector-observer proposal this proposal helped spawn, I may have painted an overly optimistic picture of [what the platform is capable of](https://github.com/whatwg/dom/issues/398).  It does leave me a little puzzled why this isn't an issue when it comes to styling, and also if some of the advances that were utilized to support :has could be applied to this problem space, so that maybe the arguments raised there have weakened.  Even if the concerns raised are as relevant today, I think considering the use cases this proposal envisions, that the objections could be overcome, for the following reasons: 1.  For scenarios where lazy loading is the primary objective, "bunching" multiple DOM mutations together and only reevaluating when things are quite idle is perfectly reasonable.  Also, for binding from a distance, most of the mutations that need responding to quickly will be when the *state of the host* changes, so DOM mutations play a somewhat muted role in that regard. Again, bunching multiple DOM mutations together, even if adds a bit of a delay, also seems reasonable.  I also think the platform could add an "analysis" step to look at the query and categorize it as "simple" queries vs complex.  Selector queries that are driven by the characteristics of the element itself (localName, attributes, etc) could be handled in a more expedited fashion.  Those that the platform does expect to require more babysitting could be monitored for less vigilantly.  Maybe in the latter case, a console.warning could be emitted during initialization.  The other use case, for lazy loading custom elements and custom enhancements based on attributes, I think most of the time this would fit the "simple" scenario, so again there wouldn't be much of an issue.
 
-In fact, I have encountered statements made by the browser vendors that some queries supported by css can't be evaluated simply by looking at the layout of the HTML, but has to be made after rendering and performing style calculations.  This necessitates having to delay the notification, which would be unacceptable in some circumstances.
+In fact, I have encountered statements made by the browser vendors that some queries supported by css can't be evaluated simply by looking at the layout of the HTML, but have to be made after rendering and performing style calculations.  This necessitates having to delay the notification, which would be unacceptable in some circumstances.
 
 If the developer has a simple query in mind that needs no such nuance, I'm thinking it might be helpful to provide an alternative key to "select" that is used specifically for (a subset?) of queries supported by the existing "matches" method that elements support, maybe even after the browser vendors provide a selector-observer (if ever).
 
@@ -150,9 +217,9 @@ So the developer could use:
 ```JavaScript
 const observer = new MountObserver({
    //supported by this polyfill
-   whereElementMatches:'my-element',
+   matching:'my-element',
    import: './my-element.js',
-   do: ({localName}, {modules, observer, mountInit, rootNode}) => {
+   do: ({localName}, {modules, observer, MountConfig, rootNode}) => {
       if(!customElements.get(localName)) {
          customElements.define(localName, modules[0].MyElement);
       }
@@ -165,9 +232,10 @@ observer.observe(document);
 
 and could perhaps expect faster binding as a result of the more limited supported expressions.  Since "select" is not specified, it is assumed to be "*".
 
-This polyfill in fact only supports this latter option ("whereElementMatches"), and leaves "select" for such a time as when a selector observer is available in the platform.
+This polyfill in fact only supports this latter option ("matching"), and leaves "select" for such a time as when a selector observer is available in the platform.
+
+[Implemented as Requirement 1](requirements/Done/Requirement1.md).
 
-[Implemented as Requirement 1](requirements/Requirement1.md).
 
 ##  The import key
 
@@ -175,16 +243,13 @@ This proposal has been amended to support multiple imports, including of differe
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches:'my-element',
+   matching:'my-element',
    import: [
       ['./my-element-small.css', {type: 'css'}],
       './my-element.js',
    ],
-   do: ({localName}, {modules, observer, mountInit, rootNode}) => {
-      if(!customElements.get(localName)) {
-         customElements.define(localName, modules[1].MyElement);
-      }
-      observer.disconnectedSignal.abort();
+   do: ({localName}, {modules, observer, MountConfig, rootNode}) => {
+      ...
    }
 });
 observer.observe(document);
@@ -198,7 +263,7 @@ Previously, this proposal called for allowing arrow functions as well, thinking
 
 This proposal would also include support for JSON and HTML module imports (really, all types).
 
-[Implemented as Requirement 1](requirements/Requirement1.md).
+[Implemented as Requirement 1](requirements/Done/Requirement1.md).
 
 ## Preemptive downloading
 
@@ -209,14 +274,14 @@ There are two significant steps to imports, each of which imposes a cost:
 
 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.
+The link rel=modulepreload option (and maybe the new defer tc39 proposal) 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 loadingEagerness:
 
 ```JavaScript
 const observer = new MountObserver({
    select: 'my-element', //not supported by this polyfill
-   loadingEagerness: 'eager',
+   loadingEagerness: 'eager', //partially supported by this polyfill
    import: './my-element.js',
    do: ({localName}, {modules}) => customElements.define(localName, modules[0].MyElement),
 });
@@ -224,18 +289,19 @@ const observer = new MountObserver({
 
 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.
 
+The polyfill just loads the module into memory right away.
+
 > [!NOTE]
 > As a result of the google IO 2024 talks, I became aware that there is some similarity between this proposal and the [speculation rules api](https://developer.chrome.com/blog/speculation-rules-improvements).  This motivated the change to the property from "loading" to loadingEagerness above.
 
 ## Separating JS imperative code from JSON serializable config
 
 
-
-In order to support pure 100% declarative syntax in the passed in mountInit argument, we need to be able to import the do function.  This is done as follows:
+In order to support pure 100% declarative syntax in the passed in MountConfig argument, we need to be able to import the do function.  This is done as follows:
 
 ```JavaScript
 //module myActions.js
-const  doFunction = function({localName}, {modules, observer, mountInit, rootNode}){
+const  doFunction = function({localName}, {modules, observer, MountConfig, rootNode}){
    if(!customElements.get(localName)) {
       // Find the first exported class constructor from the module
       const ElementClass = Object.values(modules[0]).find(exp => 
@@ -252,7 +318,7 @@ export {doFunction as do}
 // observer setup
 
 const observer = new MountObserver({
-   whereElementMatches:'my-element',
+   matching:'my-element',
    import: [
       './my-element.js',
       ['./my-element-small.css', {type: 'css'}],
@@ -268,7 +334,7 @@ Here "2" refers to the imported module index ('./myActions.js' in this case).
 
 ### How the reference property works
 
-The `reference` property allows you to call `do` functions from imported modules, enabling 100% JSON-serializable configuration. This is useful when you want to separate imperative code from declarative configuration.
+The `reference` property allows us to call `do` functions from imported modules, enabling 100% JSON-serializable configuration. This is useful when you want to separate imperative code from declarative configuration.
 
 **Key behaviors:**
 - The `reference` property can be a single number or an array of numbers, each referring to an import index
@@ -303,28 +369,28 @@ import: [
 reference: [2, 3]  // Both actions1 and actions2 will have their 'do' called if present
 ```
 
-[Implemented as [Requirement11](requirements/Requirement11.md)]
+[Implemented as [Requirement11](requirements/Done/Requirement11.md)]
 
-### Referenced whereInstanceOf
+### Referenced withInstance
 
-Similar to the `do` function, the `whereInstanceOf` check can also be moved to imported modules for 100% JSON-serializable configuration:
+Similar to the `do` function, the `withInstance` check can also be moved to imported modules for 100% JSON-serializable configuration:
 
 ```javascript
 // module mySettings.js
-const doFunction = function({localName}, {modules, observer, mountInit, rootNode}) {
+const doFunction = function({localName}, {modules, observer, MountConfig, rootNode}) {
    if(!customElements.get(localName)) {
       customElements.define(localName, modules[1].MyElement);
    }
    observer.disconnectedSignal.abort();
 };
 
-const whereInstanceOf = [HTMLMarqueeElement, SVGElement];
+const withInstance = [HTMLMarqueeElement, SVGElement];
 
-export { doFunction as do, whereInstanceOf };
+export { doFunction as do, withInstance };
 
 // my local module
 const observer = new MountObserver({
-   whereElementMatches: 'my-element',
+   matching: 'my-element',
    import: [
       ['./my-element-small.css', {type: 'css'}],
       './my-element.js',
@@ -336,17 +402,144 @@ observer.observe(document);
 ```
 
 **Behavior:**
-- **Combining checks**: If both inline `whereInstanceOf` and referenced `whereInstanceOf` exist, they are AND'd together (element must match both)
-- **Multiple references**: If multiple referenced modules export `whereInstanceOf`, the element must match ALL of them (AND logic)
-- **Validation**: Referenced `whereInstanceOf` is validated after imports load. Throws an error if not a Constructor or array of Constructors
-- **Optional export**: If a referenced module doesn't export `whereInstanceOf`, it's silently ignored
+- **Combining checks**: If both inline `withInstance` and referenced `withInstance` exist, they are AND'd together (element must match both)
+- **Multiple references**: If multiple referenced modules export `withInstance`, the element must match ALL of them (AND logic)
+- **Validation**: Referenced `withInstance` is validated after imports load. Throws an error if not a Constructor or array of Constructors
+- **Optional export**: If a referenced module doesn't export `withInstance`, it's silently ignored
 - **Timing**: 
-  - With lazy loading (default): Inline `whereInstanceOf` is checked first (before imports), then referenced checks happen after imports load
+  - With lazy loading (default): Inline `withInstance` is checked first (before imports), then referenced checks happen after imports load
   - With `loadingEagerness: 'eager'`: Both inline and referenced checks happen together after imports are loaded
 
-This optimization ensures that with lazy loading, elements that don't match the inline `whereInstanceOf` won't trigger unnecessary imports.
+This optimization ensures that with lazy loading, elements that don't match the inline `withInstance` won't trigger unnecessary imports.
+
+[Implemented as [Requirement12](requirements/Done/Requirement12.md)]
+
+## Simplified API: Array Argument Shorthand
+
+For simple use cases where you just want to enhance elements based on attributes without needing the full `MountConfig` object, you can pass an array of [EnhancementConfig` objects](https://github.com/bahrus/assign-gingerly) directly to the constructor:
+
+```JavaScript
+import { MountObserver } from 'mount-observer';
+
+// Instead of wrapping in MountConfig:
+// const observer = new MountObserver({
+//     enhancementConfig: [config1, config2]
+// });
+
+// You can use the shorthand:
+const observer = new MountObserver([
+    {
+        spawn: Enhancement1,
+        enhKey: 'enh1',
+        withAttrs: {
+            base: 'data-',
+            action: '${base}action'
+        }
+    },
+    {
+        spawn: Enhancement2,
+        enhKey: 'enh2',
+        withAttrs: {
+            base: 'data-',
+            theme: '${base}theme'
+        }
+    }
+]);
+
+await observer.observe(document.body);
+```
+
+When you pass an array directly:
+- The array is automatically converted to `{ matching: '*', enhancementConfig: [...] }`
+- All elements are considered (matching: '*'), with filtering done by `withAttrs` in each config
+- This is perfect for attribute-based progressive enhancement scenarios
+- You can still use all `EnhancementConfig` features like `spawn`, `withAttrs`, `canSpawn`, etc.
+
+This "lite" API makes it easier to do the right thing by reducing boilerplate for common enhancement patterns.
+
+[Implemented as ArrayArgument requirement](requirements/Done/ArrayArgument.md).
+
+## Element Mount Extension
+
+For even more convenience, you can use the `element.mount()` method to observe elements within their scoped custom element registry context. This is particularly useful with scoped custom element registries (Chrome 146+, latest WebKit/Safari).
+
+```JavaScript
+import 'mount-observer/ElementMountExtension.js';
+
+// Mount with MountConfig
+await document.body.mount({
+    matching: 'button',
+    do: (element) => {
+        element.classList.add('enhanced');
+    }
+});
+
+// Or use the array shorthand directly
+await document.body.mount([
+    {
+        spawn: ButtonEnhancement,
+        enhKey: 'btn-enh',
+        withAttrs: {
+            base: 'data-',
+            action: '${base}action'
+        }
+    }
+]);
+```
+
+The `mount()` method:
+- Automatically finds the highest scoped container with the same `customElementRegistry` as the element (default behavior)
+- Creates a `MountObserver` with the provided config
+- Observes the determined scope
+- Returns the element for chaining (as a Promise)
+- Accepts both `MountConfig` objects and `EnhancementConfig[]` arrays
+
+Scope options (via `options.scope`):
+- `'registry'` (default): Observes the root registry container (highest element with same customElementRegistry)
+- `'self'`: Observes only this element
+- `'root'`: Observes the root node (document or shadow root)
+- `'shadow'`: Observes the element's shadowRoot (throws error if none exists)
+- `Element`: Observes a custom element you specify
+
+This is especially useful for web components that want to observe their own shadow DOM or scoped registry:
+
+```JavaScript
+class MyComponent extends HTMLElement {
+    async connectedCallback() {
+        const shadow = this.attachShadow({ mode: 'open', registry: new CustomElementRegistry() });
+        shadow.innerHTML = `<button data-action="click">Click me</button>`;
+        
+        // Default: Observe within this component's scoped registry
+        await shadow.mount([{
+            spawn: ButtonHandler,
+            enhKey: 'handler',
+            withAttrs: { action: 'data-action' }
+        }]);
+        
+        // Or observe just the shadow root itself
+        await this.mount([{
+            spawn: ShadowHandler,
+            enhKey: 'shadow'
+        }], { scope: 'shadow' });
+        
+        // Or observe the entire document
+        await this.mount({
+            matching: '.global-button',
+            do: (el) => console.log('Global button found')
+        }, { scope: 'root' });
+    }
+}
+```
+
+Browser support: Works in all browsers, but scoped registry features require Chrome 146+ or latest WebKit/Safari.
+
+[Implemented as CustomElementRegistryMounting requirement](requirements/Done/CustomElementRegistryMounting.md).
+ 
+
+
+
+
 
-[Implemented as [Requirement12](requirements/Requirement12.md)]
 
 
 
@@ -382,21 +575,21 @@ export { doFunction as do };
 
 To keep this proposal / polyfill of reasonable size, mount observer script elements has its own [repo / sub-proposal](https://github.com/bahrus/mount-observer-script-element).  There's much more to it, but it is awaiting implementation of scoped custom element registry before finalizing the requirements and (re)-implementing.
 
-But I think it's important to think about this way of making the mount observer declarative, as it provides one significant reason why we place so much emphasis on making sure that the mount observer settings (mountInit) is as JSON serializable as possible.
+But I think it's important to think about this way of making the mount observer declarative, as it provides one significant reason why we place so much emphasis on making sure that the mount observer settings (MountConfig) is as JSON serializable as possible.
 
 
 ## Binding from a distance
 
-It is important to note that "whereElementMatches" is a css query with no restrictions.  So something like:
+It is important to note that "matching" (and especially the non polyfillable "select") is a css query with no restrictions.  So something like:
 
 ```JavaScript
 import {EvtRt} from 'mount-observer/EvtRt.js';
 
 class MyHandler extends EvtRt {
-   mount(mountedElement, mountInit, context){
+   mount(mountedElement, MountConfig, context){
       mountedElement.textContent = 'hello';
    }
-   dismount(mountedElement, mountInit){
+   dismount(mountedElement, MountConfig){
       mountedElement.textContent = 'goodbye';
    }
 }
@@ -404,8 +597,8 @@ class MyHandler extends EvtRt {
 const observer = new MountObserver({
    // not supported by polyfill
    //select: 'div > p + p ~ span[class$="name"]' 
-   // is supported:
-   whereElementMatches: 'div > p + p ~ span[class$="name"]',
+   // is supported by polyfill, and even after select is also supported:
+   matching: 'div > p + p ~ span[class$="name"]',
    do: (mountedElement, ctx) => {
       new MyHandler(mountedElement, ctx);
    },
@@ -422,16 +615,16 @@ This allows developers to create "stylesheet" like capabilities.
 
 ## Registering reusable handlers with MountObserver.define
 
-To make MountInit configurations more JSON-serializable and encourage code reuse, you can register handler classes with string names and reference them by name:
+To make MountConfig configurations more JSON-serializable and encourage code reuse, you can register handler classes with string names and reference them by name:
 
 ```JavaScript
 import {EvtRt} from 'mount-observer/EvtRt.js';
 
 class MyHandler extends EvtRt {
-   mount(mountedElement, mountInit, context){
+   mount(mountedElement, MountConfig, context){
       mountedElement.textContent = 'hello';
    }
-   dismount(mountedElement, mountInit){
+   dismount(mountedElement, MountConfig){
       mountedElement.textContent = 'bye';
    }
 }
@@ -441,7 +634,7 @@ MountObserver.define('myHandler', MyHandler);
 
 // Reference it by name in the configuration
 const observer = new MountObserver({
-   whereElementMatches: 'div > p + p ~ span[class$="name"]',
+   matching: 'div > p + p ~ span[class$="name"]',
    do: 'myHandler'  // String reference instead of inline function
 });
 observer.observe(document);
@@ -462,7 +655,7 @@ MountObserver.define('logger', LoggerHandler);
 MountObserver.define('validator', ValidatorHandler);
 
 const observer = new MountObserver({
-   whereElementMatches: 'input',
+   matching: 'input',
    do: [
       'logger',                    // Registered handler
       (element, ctx) => {          // Inline function
@@ -486,7 +679,7 @@ When both `do` (with string/array) and `reference` are specified, the execution
 MountObserver.define('setup', SetupHandler);
 
 const observer = new MountObserver({
-   whereElementMatches: 'button',
+   matching: 'button',
    import: './button-actions.js',
    reference: 0,
    do: ['setup', (el) => { el.dataset.ready = 'true'; }]
@@ -534,7 +727,7 @@ MountObserver.define('myHandler', Handler2);  // Error: myHandler already in use
 
 The handler registry is global and shared across all MountObserver instances, similar to the custom elements registry. Once a handler is registered, it can be used by any MountObserver instance in your application.
 
-[Implemented as [Requirement14](requirements/Requirement14.md)]
+[Implemented as [Requirement14](requirements/Done/Requirement14.md)]
 
 ### Built in handlers
 
@@ -547,7 +740,7 @@ const observer = new MountObserver({
    // not supported by polyfill
    //select: 'div > p + p ~ span[class$="name"]' 
    // is supported:
-   whereElementMatches: 'div > p + p ~ span[class$="name"]',
+   matching: 'div > p + p ~ span[class$="name"]',
    do: 'builtIns.logToConsole'
 });
 observer.observe(document);
@@ -569,7 +762,7 @@ export default class MyElement extends HTMLElement {
 import { MountObserver } from 'mount-observer';
 
 const observer = new MountObserver({
-    whereElementMatches: 'my-element',
+    matching: 'my-element',
     import: './MyElement.js',
     do: 'builtIns.defineCustomElement'
 });
@@ -587,7 +780,7 @@ For the common use case of setting properties on matching elements, MountObserve
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: 'input',
+   matching: 'input',
    assignOnMount: {
       disabled: true,
       value: 'Default value',
@@ -599,7 +792,7 @@ observer.observe(document);
 
 This will automatically apply the specified properties to all matching input elements, both existing ones and those added dynamically.
 
-[Implemented as [Requirement2](requirements/Requirement2.md) and [Requirement16](requirements/Requirement16.md)]
+[Implemented as [Requirement2](requirements/Done/Requirement2.md) and [Requirement16](requirements/Done/Requirement16.md)]
 
 ### Assigning properties on dismount
 
@@ -607,7 +800,7 @@ You can also specify properties to apply when elements are removed from the DOM
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: '.status-indicator',
+   matching: '.status-indicator',
    assignOnMount: {
       '?.style?.color': 'green',
       '?.dataset?.status': 'active'
@@ -630,7 +823,7 @@ A common use case is providing visual feedback for form validation:
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: 'input.validated',
+   matching: 'input.validated',
    assignOnMount: {
       '?.style?.borderColor': 'green',
       '?.style?.backgroundColor': '#f0fff0',
@@ -666,7 +859,7 @@ The `assignGingerly` library supports nested property assignment using the `?.`
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: 'button',
+   matching: 'button',
    assignOnMount: {
       disabled: false,
       '?.dataset?.action': 'submit',
@@ -688,7 +881,7 @@ You can combine `assignOn*` with lazy loading to both import resources and set p
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: 'my-element',
+   matching: 'my-element',
    import: './my-element.js',
    assignOnMount: {
       theme: 'dark',
@@ -720,7 +913,7 @@ The `MountObserver` class provides a public `assignGingerly()` method that allow
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: 'input',
+   matching: 'input',
    assignOnMount: {
       disabled: true,
       value: 'Initial value'
@@ -747,7 +940,7 @@ await observer.assignGingerly({
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: 'input'
+   matching: 'input'
 });
 observer.observe(document);
 
@@ -773,7 +966,361 @@ async assignGingerly(config: Record<string, any> | undefined): Promise<void>
 
 The method is async because the assign-gingerly library is loaded dynamically when needed.
 
-[Implemented as [Requirement9](requirements/Requirement9.md)]
+[Implemented as [Requirement9](requirements/Done/Requirement9.md)]
+
+## Reversible property assignment with stageOnMount
+
+While `assignOnMount` and `assignOnDismount` provide permanent property assignments, sometimes you need temporary changes that automatically reverse when elements dismount. The `stageOnMount` property provides this capability using the `assignTentatively` function from assign-gingerly:
+
+```JavaScript
+const observer = new MountObserver({
+   matching: 'button.async-action',
+   stageOnMount: {
+      disabled: true,
+      title: 'Processing...',
+      '?.dataset?.loading': 'true'
+   }
+});
+observer.observe(document);
+```
+
+When a matching button mounts, these properties are applied. When it dismounts (e.g., loses the `async-action` class), the original values are automatically restored.
+
+### How it works
+
+`stageOnMount` uses `assignTentatively` under the hood, which:
+
+1. **Captures original values** before making changes
+2. **Applies the new properties** when elements mount
+3. **Automatically reverses** to original values when elements dismount
+
+This is different from `assignOnMount`/`assignOnDismount`, where you must explicitly specify both the mount and dismount values.
+
+### When to use stageOnMount vs assignOnMount
+
+**Use `stageOnMount` when:**
+- You want temporary state changes that should automatically reverse
+- The original values matter and should be restored
+- You're toggling states (disabled/enabled, hidden/visible)
+- Setting temporary ARIA states or loading indicators
+
+**Use `assignOnMount`/`assignOnDismount` when:**
+- You need different values on mount vs dismount (not just reversal)
+- You want permanent enhancements that shouldn't be reversed
+- You need explicit control over both mount and dismount behavior
+- The dismount value is not simply "restore original"
+
+### Comparison example
+
+```JavaScript
+// With assignOnMount/assignOnDismount - explicit control
+const observer1 = new MountObserver({
+   matching: 'input.validated',
+   assignOnMount: {
+      '?.style?.borderColor': 'green'
+   },
+   assignOnDismount: {
+      '?.style?.borderColor': 'red'  // Different value, not restoration
+   }
+});
+
+// With stageOnMount - automatic reversal
+const observer2 = new MountObserver({
+   matching: 'button.loading',
+   stageOnMount: {
+      disabled: true,  // Automatically restores original disabled state on dismount
+      '?.dataset?.loading': 'true'  // Automatically removes on dismount
+   }
+});
+```
+
+### Combining with assignOnMount
+
+You can use both `assignOnMount` and `stageOnMount` together. The order of operations is:
+
+1. **On mount**: `assignOnMount` applied first, then `stageOnMount`
+2. **On dismount**: `stageOnMount` reversed first, then `assignOnDismount` applied
+
+```JavaScript
+const observer = new MountObserver({
+   matching: 'form',
+   assignOnMount: {
+      noValidate: true  // Permanent enhancement
+   },
+   stageOnMount: {
+      '?.dataset?.submitting': 'true'  // Temporary state
+   }
+});
+```
+
+### Nested properties
+
+Like `assignOnMount`, `stageOnMount` supports nested property paths:
+
+```JavaScript
+const observer = new MountObserver({
+   matching: '.modal',
+   stageOnMount: {
+      '?.style?.display': 'block',
+      '?.style?.opacity': '1',
+      '?.dataset?.visible': 'true',
+      '?.setAttribute': ['aria-hidden', 'false']
+   }
+});
+```
+
+### Re-mounting behavior
+
+If an element dismounts and then re-mounts, `stageOnMount` will:
+
+1. Capture the current values (which may have changed since last mount)
+2. Apply the staged properties again
+3. Store new reversal information for the next dismount
+
+```JavaScript
+const button = document.querySelector('button');
+button.disabled = false;  // Original state
+
+button.classList.add('loading');  // Mount: disabled becomes true
+button.classList.remove('loading');  // Dismount: disabled restored to false
+
+button.disabled = true;  // Manually changed
+button.classList.add('loading');  // Re-mount: disabled becomes true (staged value)
+button.classList.remove('loading');  // Dismount: disabled restored to true (the value before re-mount)
+```
+
+### Performance and memory
+
+- The assign-gingerly library is only loaded when `stageOnMount` is specified
+- Reversal objects are stored in a WeakMap, allowing garbage collection when elements are removed
+- Each element's reversal data is cleaned up when it dismounts
+
+[Implemented as [Requirement13](requirements/Done/Requirement13.md)]
+
+## Spawning enhancements with assign-gingerly integration
+
+MountObserver integrates with the [assign-gingerly](https://github.com/bahrus/assign-gingerly) enhancement system to automatically spawn enhancement instances when elements mount. This provides a powerful way to attach behaviors and functionality to elements using the enhancement registry pattern.
+
+### What is spawn?
+
+In the assign-gingerly enhancement system, `spawn` is a class constructor (not a boolean) that defines what enhancement instance to create. The `enhancementConfig` object is a registry item that gets registered with the element's enhancement registry.
+
+### Basic spawn usage
+
+```JavaScript
+// Define an enhancement class
+class ButtonEnhancement {
+   constructor(element, ctx, initVals) {
+      this.element = element;
+      this.onClick = this.onClick.bind(this);
+      element.addEventListener('click', this.onClick);
+   }
+   
+   onClick(e) {
+      console.log('Button clicked!', this.element);
+   }
+}
+
+const observer = new MountObserver({
+   matching: 'button[data-enhance]',
+   enhancementConfig: {
+      spawn: ButtonEnhancement,  // The class constructor
+      enhKey: 'buttonEnh'
+   }
+});
+observer.observe(document);
+```
+
+When an element mounts, if `enhancementConfig.spawn` is defined, MountObserver will:
+1. Import the assign-gingerly object extension module
+2. Call `element.enh.get(enhancementConfig, mountContext)` to spawn the enhancement
+3. Pass the mount context as the second parameter, making it available to the enhancement constructor
+
+### How spawn works
+
+The spawn feature leverages the `element.enh` property from assign-gingerly, which provides access to the enhancement registry. The `enhancementConfig` is a registry item with this structure:
+
+```TypeScript
+interface IBaseRegistryItem<T> {
+   spawn: {new(element?: Element, ctx?: SpawnContext<T>, initVals?: Partial<T>): T};
+   symlinks?: {[key: symbol]: keyof T};
+   enhKey?: string;
+   withAttrs?: AttrPatterns<T>;
+   canSpawn?: (obj: any, ctx?: SpawnContext<T>) => boolean;
+}
+```
+
+When you call `element.enh.get(enhancementConfig, mountContext)`:
+- If an enhancement matching the config already exists for this element, it returns the existing instance
+- If no enhancement exists, it creates a new one by calling `new enhancementConfig.spawn(element, ctx, initVals)`
+- The enhancement is registered in the element's custom element registry's enhancement registry
+- The mount context is passed to the enhancement constructor via `ctx.mountCtx`
+
+### Spawn happens once per element
+
+The spawn operation only occurs the first time an element mounts. If the element is removed and re-added to the DOM:
+- The spawn code won't run again (element already in `#processedDoForElement`)
+- The existing enhancement instance persists with the element
+- This ensures enhancements are singletons per element instance
+
+### Mount context in enhancements
+
+The mount context passed to spawned enhancements includes:
+
+```TypeScript
+interface MountContext {
+   modules: any[];        // Imported modules (if import was specified)
+   observer: MountObserver;  // The MountObserver instance
+   rootNode: Node;        // The observed root node
+   MountConfig: MountConfig; // The full configuration object
+}
+```
+
+This allows enhancements to access imported dependencies, communicate with the observer, and understand their mounting context.
+
+### Combining spawn with other features
+
+Spawn works seamlessly with other MountObserver features:
+
+```JavaScript
+class WidgetEnhancement {
+   constructor(element, ctx, initVals) {
+      this.element = element;
+      this.modules = ctx.mountCtx?.modules || [];
+      console.log('Widget enhanced with', this.modules);
+   }
+   
+   theme = 'light';
+   mode = 'default';
+}
+
+const observer = new MountObserver({
+   matching: 'my-widget',
+   import: './widget-helpers.js',
+   assignOnMount: {
+      dataset: { initialized: 'true' }
+   },
+   stageOnMount: {
+      disabled: true  // Temporarily disable during setup
+   },
+   enhancementConfig: {
+      spawn: WidgetEnhancement,
+      enhKey: 'widget',
+      withAttrs: {
+         base: 'data-config',
+         theme: '${base}-theme',
+         mode: '${base}-mode'
+      }
+   },
+   do: (element, ctx) => {
+      console.log('Additional setup after spawn');
+   }
+});
+```
+
+**Execution order on mount:**
+1. `assignOnMount` properties applied
+2. `stageOnMount` properties applied
+3. **Spawn enhancement** (if configured)
+4. `do` callbacks executed
+5. Mount event dispatched
+
+### Attribute-based enhancement spawning
+
+When combined with `withAttrs`, spawn only occurs for elements that have the specified attributes:
+
+```JavaScript
+class ActionEnhancement {
+   constructor(element, ctx, initVals) {
+      this.element = element;
+      this.onClick = this.onClick.bind(this);
+      element.addEventListener('click', this.onClick);
+   }
+   
+   onClick(e) {
+      const action = this.element.dataset.action;
+      console.log(`Action: ${action}`);
+   }
+}
+
+const observer = new MountObserver({
+   matching: 'button',
+   enhancementConfig: {
+      spawn: ActionEnhancement,
+      enhKey: 'action',
+      withAttrs: {
+         base: 'data-action'
+      }
+   }
+});
+```
+
+Only buttons with a `data-action` attribute (or `enh-data-action` for custom elements) will have the enhancement spawned.
+
+### Guard conditions with canSpawn
+
+The `canSpawn` property in `enhancementConfig` provides conditional spawning:
+
+```JavaScript
+class InputEnhancement {
+   constructor(element, ctx, initVals) {
+      this.element = element;
+      this.onInput = this.onInput.bind(this);
+      element.addEventListener('input', this.onInput);
+   }
+   
+   onInput(e) {
+      console.log('Input changed:', e.target.value);
+   }
+   
+   static canSpawn(element) {
+      // Only spawn for inputs that aren't readonly
+      return !element.readOnly;
+   }
+}
+
+const observer = new MountObserver({
+   matching: 'input',
+   enhancementConfig: {
+      spawn: InputEnhancement,
+      enhKey: 'inputEnh'
+   }
+});
+```
+
+If `canSpawn` returns `false`, the enhancement won't be spawned for that element.
+
+### Browser compatibility
+
+The spawn feature requires:
+- `Element.prototype.customElementRegistry` (Chrome 146+)
+- `customElementRegistry.enhancementRegistry` (Chrome 146+)
+
+For older browsers, you'll need to polyfill these features or the spawn functionality won't work. The test suite includes a polyfill example:
+
+```JavaScript
+// Polyfill for browsers without customElementRegistry
+if (!Element.prototype.hasOwnProperty('customElementRegistry')) {
+   Object.defineProperty(Element.prototype, 'customElementRegistry', {
+      get() {
+         if (!this._customElementRegistry) {
+            this._customElementRegistry = {
+               enhancementRegistry: new BaseRegistry()
+            };
+         }
+         return this._customElementRegistry;
+      }
+   });
+}
+```
+
+### Performance considerations
+
+- The assign-gingerly object extension module is only loaded when `spawn` is configured
+- Enhancements are created once per element (singleton pattern)
+- The enhancement registry uses weak references to allow garbage collection
+
+[Implemented as [SpawnOnMount](requirements/Done/SpawnOnMount.md)]
 
 ## Emitting events from mounted elements
 
@@ -787,7 +1334,7 @@ MountObserver can automatically dispatch custom events from elements when they m
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: 'button[data-action]',
+   matching: 'button[data-action]',
    mountedElemEmits: {
       event: 'Event',
       args: 'custom-ready'
@@ -829,17 +1376,17 @@ mountedElemEmits: {
 Use magic strings to inject dynamic values into event data:
 
 - `{{mountedElement}}` - The element that just mounted
-- `{{mountInit}}` - The MountInit configuration object
+- `{{MountConfig}}` - The MountConfig configuration object
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: 'button[data-test]',
+   matching: 'button[data-test]',
    mountedElemEmits: {
       event: 'CustomEvent',
       args: ['element-mounted', { 
          detail: { 
             element: '{{mountedElement}}',
-            config: '{{mountInit}}'
+            config: '{{MountConfig}}'
          }
       }]
    }
@@ -869,7 +1416,7 @@ Emit multiple events in sequence by providing an array:
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: 'my-component',
+   matching: 'my-component',
    mountedElemEmits: [
       { event: 'Event', args: 'component-loading' },
       { event: 'Event', args: 'component-ready' },
@@ -904,7 +1451,7 @@ Use `oncePerMountedElement` to ensure an event only fires the first time an elem
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: 'button[data-once]',
+   matching: 'button[data-once]',
    mountedElemEmits: {
       event: 'Event',
       args: 'initialized',
@@ -923,7 +1470,7 @@ The event emission logic is code-split into a separate module (`emitEvents.js`)
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: 'my-widget',
+   matching: 'my-widget',
    import: './my-widget.js',
    mountedElemEmits: [
       {
@@ -960,17 +1507,17 @@ document.addEventListener('widget-ready', (e) => {
 observer.observe(document);
 ```
 
-[Implemented as [Requirement10](requirements/Requirement10.md)]
+[Implemented as [Requirement10](requirements/Done/Requirement10.md)]
 
 ## Element-specific lifecycle notifications with getNotifier
 
-While the MountObserver dispatches lifecycle events (mount, dismount, disconnect, attrchange) at the observer level, sometimes you need to listen for events specific to a single element. The `getNotifier()` method returns an EventTarget that dispatches filtered events for only that element.
+While the MountObserver dispatches lifecycle events (mount, dismount, disconnect) at the observer level, sometimes you need to listen for events specific to a single element. The `getNotifier()` method returns an EventTarget that dispatches filtered events for only that element.
 
 ### Basic usage
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: 'button',
+   matching: 'button',
    do: (mountedElement, {observer}) => {
       const notifier = observer.getNotifier(mountedElement);
       
@@ -1001,7 +1548,7 @@ This prevents duplicate mount notifications when setting up listeners during the
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: '#my-button',
+   matching: '#my-button',
    do: (element, {observer}) => {
       const notifier = observer.getNotifier(element);
       
@@ -1020,7 +1567,7 @@ You can call `getNotifier()` at any time, even before an element mounts:
 
 ```JavaScript
 const observer = new MountObserver({
-   whereElementMatches: '#future-button'
+   matching: '#future-button'
 });
 observer.observe(document);
 
@@ -1039,32 +1586,6 @@ document.body.appendChild(button);
 
 When the notifier is created before the element mounts, the mount event fires normally.
 
-### Filtered attrchange events
-
-For `attrchange` events, the notifier receives a filtered version containing only changes for that specific element:
-
-```JavaScript
-const observer = new MountObserver({
-   whereElementMatches: 'input',
-   whereAttr: {
-      hasBuiltInRootIn: ['data'],
-      hasCERootIn: ['data'],
-      hasBase: 'value',
-      hasBranchIn: ['']
-   },
-   do: (element, {observer}) => {
-      const notifier = observer.getNotifier(element);
-      
-      notifier.addEventListener('attrchange', (e) => {
-         // e.changes only contains changes for this specific input
-         console.log('Attribute changed on this input:', e.changes);
-      });
-   }
-});
-```
-
-Even if multiple elements have attribute changes in the same mutation batch, each notifier only receives the changes relevant to its element.
-
 ### Use cases
 
 Element-specific notifiers are useful for:
@@ -1085,7 +1606,7 @@ Element-specific notifiers are useful for:
 getNotifier(element: Element): EventTarget
 ```
 
-[Implemented as [Requirement13](requirements/Requirement13.md)]
+[Implemented as [Requirement13](requirements/Done/Requirement13.md)]
 
 
 ##  Extra lazy loading
@@ -1112,10 +1633,10 @@ Unlike traditional CSS @import, CSS Modules don't support specifying different i
 ```JavaScript
 const observer = new MountObserver({
    select: 'div > p + p ~ span[class$="name"]', // not supported by polyfill
-   whereMediaMatches: '(max-width: 1250px)',
+   withMediaMatching: '(max-width: 1250px)',
    whereSizeOfContainerMatches: '(min-width: 700px)',
    whereContainerHas: '[itemprop=isActive][value="true"]',
-   whereInstanceOf: [HTMLMarqueeElement], //or ['HTMLMarqueeElement']
+   withInstance: [HTMLMarqueeElement], //or ['HTMLMarqueeElement']
    whereLangIn: ['en-GB'],
    whereConnectionHas:{
       effectiveTypeIn: ["slow-2g"],
@@ -1125,17 +1646,17 @@ const observer = new MountObserver({
 });
 ```
 
-[whereInstanceOf implemented as [Requirement5](requirements/Requirement5.md)]
+[withInstance implemented as [Requirement5](requirements/Done/Requirement5.md)]
 
-[whereMediaMatches implemented as [Requirement6](requirements/Requirement6.md)]
+[withMediaMatching implemented as [Requirement6](requirements/Done/Requirement6.md)]
 
 ## InstanceOf checks in detail
 
-Carving out the special "whereInstanceOf" check is provided based on the assumption that there's a performance benefit from doing so. If not, the developer could just add that check inside the "confirm" callback logic (discussed later).  For built-in elements, we can alternatively provide the string name, as indicated in the comment above, which certainly makes it JSON serializable, thus making it easy as pie to include in the MOSE JSON payload.  I don't think there would be any ambiguity in doing so, which means I believe that answers the mystery in my mind whether it could be part of the low-level checklist that could be done within the c++/rust code / thread.
+Carving out the special "withInstance" check is provided based on the assumption that there's a performance benefit from doing so. If not, the developer could just add that check inside the "confirm" callback logic (discussed later).  For built-in elements, we can alternatively provide the string name, as indicated in the comment above, which certainly makes it JSON serializable, thus making it easy as pie to include in the MOSE JSON payload.  I don't think there would be any ambiguity in doing so, which means I believe that answers the mystery in my mind whether it could be part of the low-level checklist that could be done within the c++/rust code / thread.
 
 The picture becomes murkier for custom elements.  The best solution in that case seems to be to utilize customElements.getName(...) as a basis for the match, but at first glance, that could  preclude being able to use base classes which a family of custom elements subclass, if that superclass isn't itself a custom element.  I suppose the solution to this conundrum, when warranted, is simply to burden the developer with defining a custom element for the superclass, and thus assigning it a name, applicable within ShadowDOM scopes as needed, even though it isn't actually necessarily used for any live custom elements. This would require already having imported the base class, only benefitting from lazy loading the code needed for each sub class, which might not always be all that high as a percentage, compared to the base class.
 
-However, where this support for "whereInstanceOf" would be *most* helpful is when it comes to [*custom enhancements*](https://github.com/WICG/webcomponents/issues/1000) that only wish to lazily layer some heavy lifting functionality on top of certain families of already loaded and upgraded custom elements (possibly in addition to some (specified) built in elements).  Here, the lazy loading of the *entire custom **enhancement***, based on the presence in the DOM of a member of the family of custom elements, would, if my calculations are correct, result in providing a significant benefit. 
+However, where this support for "withInstance" would be *most* helpful is when it comes to [*custom enhancements*](https://github.com/WICG/webcomponents/issues/1000) that only wish to lazily layer some heavy lifting functionality on top of certain families of already loaded and upgraded custom elements (possibly in addition to some (specified) built in elements).  Here, the lazy loading of the *entire custom **enhancement***, based on the presence in the DOM of a member of the family of custom elements, would, if my calculations are correct, result in providing a significant benefit. 
  
 
 <!--
@@ -1250,7 +1771,7 @@ So I believe the prudent thing to do is wait for all the conditions to be satisf
 
 The alternative to providing this feature, which I'm leaning towards, is to just ask the developer to create "specialized" mountObserver construction arguments, that turn on and off precisely when the developer needs to know.
 
-[Implemented with [Requirement6](requirements/Requirement6.md)]
+[Implemented with [Requirement6](requirements/Done/Requirement6.md)]
 
 
 ## Support for "donut hole scoping"
@@ -1275,8 +1796,8 @@ We want to find all elements with attribute itemprop outside any itemscope, so t
 ```JavaScript
 const oContainerNode = document.getElementById('myTest');
 const observer = new MountObserver({
-   whereElementMatches:'[itemprop]',
-   whereOutside: '[itemscope]'
+   matching:'[itemprop]',
+   withScopePerimeter: '[itemscope]'
    do: ({localName}, {modules, observer}) => {
       ...
    },
@@ -1285,11 +1806,11 @@ const observer = new MountObserver({
 observer.observe(oContainerNode);
 ```
 
-The check for "whereOutside" is done via script:
+The check for "withScopePerimeter" is done via script:
 
 ```JavaScript
-import {whereOutside} from 'mount-observer/whereOutside.js';
-whereOutside(oContainerNode: Node, matchCandidate: Element, outside: string){
+import {withScopePerimeter} from 'mount-observer/withScopePerimeter.js';
+withScopePerimeter(oContainerNode: Node, matchCandidate: Element, outside: string){
     let current = matchCandidate.parentElement;
     
     while (current && current !== oContainerNode) {
@@ -1304,308 +1825,7 @@ whereOutside(oContainerNode: Node, matchCandidate: Element, outside: string){
 
 ```
 
-[Implemented as [Requirement7](requirements/Requirement7.md)]
-
-## A tribute to attributes
-
-Attributes of DOM elements are tricky.  They've been around since the get-go of the Web, and they've survived multiple eras of web development, where different philosophies have prevailed, so prepare yourself for some esoteric discussions in what follows.
-
-The MountObserver API provides explicit support for monitoring attributes.  There are two primary reasons for why it is important to provide this as part of the API:
-
-Being that for both custom elements, as well as (hopefully) [custom enhancements](https://github.com/WICG/webcomponents/issues/1000) we need to carefully work with sets of "owned" [observed](https://github.com/WICG/webcomponents/issues/1045) attributes, and in some cases we may need to manage combinations of prefixes and suffixes for better name-spacing management, creating the most effective css query becomes challenging.
-
-We want to be alerted by the discovery of elements adorned by these attributes, but then continue to be alerted to changes of their values, and we can't enumerate which values we are interested in, so we must subscribe to all values as they change.
-
-## Attributes of attributes
-
-I think it is useful to divide [attributes](https://jakearchibald.com/2024/attributes-vs-properties/) that we would want to observe into two categories:
-
-1.  Invariably named, prefix-less, "top-level" attributes that serve as the "source of truth" for key features of the DOM element itself.  We will refer to these attributes as "Source of Truth" attributes.  Please don't read too much into the name.  Whether the platform or custom element author developer chooses to make properties reflect to attributes, or attributes reflect to the properties, or some hybrid of some sort, is immaterial here.
-
-By invariably named, I mean the name will be the same in all Shadow DOM realms.
-
-Examples are many built-in global attributes, like lang, or contenteditable, or more specialized examples such as "content" for the meta tag.  It could also include attributes of third party custom elements we want to enhance in a cross-cutting way.
-
-I think in the vast majority of cases, setting the property values corresponding to these attributes results in directly reflecting those property values to the attributes (and vice versa).  There are exceptions, especially for non-string attributes like the checked property of the input element / type=checkbox, and JSON based attributes for custom elements.
-
-Usually, there are no events we can subscribe to in order to know when the property changes. Hijacking the property setter in order to observe changes may not always work or feel very resilient. So monitoring the attribute value associated with the property is often the most effective way of observing when the property/attribute state for these elements change.  And some attributes (like the microdata attributes such as itemprop) don't even have properties that they pair with! 
-  
-
-2.  In contrast, there are scenarios where we want to support somewhat fluid, renamable attributes within different Shadow DOM realms, which add behavior/enhancement capabilities on top of built-in or third party custom elements.  We'll refer to these attributes as "Enhancement Attributes."
-
-We want our api to be able to distinguish between these two, and to be able to combine both types in one mount observer instance's set of observed attributes.
-
-> [!NOTE]
-> The most important reason for pointing out this distinction is this:  "Source of Truth" attributes will only be *observed*, and will **not** trigger mount/unmount states unless they are part of the "on" selector string. And unlike all the other "where" conditions this proposal supports, the where clauses for the "Enhancement Attributes" are "one-way" -- they trigger a "mount" event / callback, followed by the ability to observe the stream of changes (including removal of those attributes), but they never trigger a "dismount". 
-
-### Counterpoint
-
-Does it make sense to even support "Source of Truth" attributes in a "MountObserver" api, if they have no impact on mounted state?  
-
-We think it does, because some Enhancement Attributes will need to work in conjunction with Source of Truth attributes, in order to provide the observer a coherent picture of the full state of the element.
-
-This realization (hopefully correct) struck me while trying to implement a [userland implementation](https://github.com/bahrus/be-intl) of [this proposal](https://github.com/whatwg/html/issues/9294). 
-
-
-### Source of Truth Attributes
-
-Let's focus on the first scenario.  It doesn't make sense to use the word "where" for these, because we don't want these attributes to affect our mount/dismount state
-
-```JavaScript
-import {MountObserver} from 'mount-observer/MountObserver.js';
-const mo = new MountObserver({
-   select: '*',
-   observedAttrsWhenMounted: ['lang', 'contenteditable']
-});
-
-mo.addEventListener('attrchange', e => {
-   console.log(e);
-   // {
-   //    mountedElement,
-   //    attrChangeInfo:[{
-   //       idx: 0,
-   //       name: 'lang'
-   //       isSOfTAttr: true,
-   //       oldValue: null,
-   //       newValue: 'en-GB',
-   //    }]
-   // }
-});
-```
-
-### Help with parsing?
-
-This proposal is likely to evolve going forward, attempting to synthesize [separate ideas](https://github.com/WICG/webcomponents/issues/1045) for declaratively specifying how to interpret the attributes, parsing them so that they may be merged into properties of a class instance. 
-
-But for now, such support is not part of this proposal (though we can see a glimpse of what that support might look like below).
-
-### Custom Enhancements in userland
-
-[This proposal, support for (progressive) enhancement of built-in or third-party custom elements, could take quite a while to see the light of day, if ever](https://github.com/WICG/webcomponents/issues/1000).
-
-In the meantime, we want to provide the most help for providing for custom enhancements in userland, and for any other kind of (progressive) enhancement based on (server-rendered) attributes going forward.
-
-Suppose we have a (progressive) enhancement that we want to apply based on the presence of 1 or more attributes.
-
-To make this discussion concrete, let's suppose the "canonical" names of those attributes are:
-
-```html
-<div id=div>
-   <section 
-      my-enhancement=greetings 
-      my-enhancement-first-aspect=hello 
-      my-enhancement-second-aspect=goodbye
-      my-enhancement-first-aspect-wow-this-is-deep
-      my-enhancement-first-aspect-have-you-considered-using-json-for-this=just-saying
-   ></section>
-</div>
-```
-
-Now suppose we are worried about namespace clashes, plus we want to serve environments where HTML5 compliance is a must.
-
-So we also want to recognize additional attributes that should map to these canonical attributes:
-
-We want to also support:
-
-```html
-<div id=div>
-   <section class=hello 
-      data-my-enhancement=greetings 
-      data-my-enhancement-first-aspect=hello 
-      data-my-enhancement-second-aspect=goodbye
-      data-my-enhancement-first-aspect-wow-this-is-deep
-      data-my-enhancement-first-aspect-have-you-considered-using-json-for-this=just-saying
-   ></section>
-</div>
-```
-
-Based on the current unspoken rules, no one will raise an eyebrow with these attributes, because the platform has indicated it will generally avoid dashes in attributes (with an exception or two that will only happen in a blue moon, like aria-*).
-
-But now when we consider applying this enhancement to third party custom elements, we have a new risk.  What's to prevent the custom element from having an attribute named my-enhancement?
-
-So let's say we want to insist that on custom elements, we must have the data- prefix?
-
-And we want to support an alternative, more semantic sounding prefix to data, say enh-*, endorsed by [this proposal](https://github.com/WICG/webcomponents/issues/1000).
-
-Here's what the api **doesn't** provide (as originally proposed):
-
-#### The carpal syndrome syntax
-
-Using the same expression structure as above, we would end up with this avalanche of settings:
-
-```JavaScript
-import {MountObserver} from '../MountObserver.js';
-const mo = new MountObserver({
-   select: '*',
-   whereAttr:{
-      isIn: [
-         'data-my-enhancement',
-         'data-my-enhancement-first-aspect', 
-         'data-my-enhancement-second-aspect',
-         'enh-my-enhancement',
-         'enh-my-enhancement-first-aspect', 
-         'enh-my-enhancement-second-aspect',
-         //...some ten more combinations not listed
-         {
-            name: 'my-enhancement',
-            builtIn: true
-         },
-         {
-            name: 'my-enhancement-first-aspect',
-            builtIn: true
-         },
-         {
-            name: 'my-enhancement-second-aspect',
-            builtIn: true
-         },
-         ...
-      ]
-      
-   }
-});
-```
-
-#### The DRY Way
-
-This seems like a much better approach, and is supported by this proposal:
-
-```JavaScript
-import {MountObserver} from '../MountObserver.js';
-const mo = new MountObserver({
-   whereAttr:{
-      hasRootIn: ['data', 'enh', 'data-enh'],
-      hasBase: 'my-enhancement',
-      hasBranchIn: ['first-aspect', 'second-aspect', ''],
-      hasLeafIn: {
-         'first-aspect': ['wow-this-is-deep', 'have-you-considered-using-json-for-this'],
-      }
-   }
-});
-```
-
-MountObserver provides a breakdown of the matching attribute when encountered:
-
-```html
-<div id=div>
-   <section class=hello my-enhancement-first-aspect-wow-this-is-deep="hello"></section>
-</div>
-<script type=module>
-   import {MountObserver} from '../MountObserver.js';
-   const mo = new MountObserver({
-      select: '*',
-      whereAttr:{
-         hasRootIn: ['data', 'enh', 'data-enh'],
-         hasBase: 'my-enhancement',
-         hasBranchIn: ['first-aspect', 'second-aspect', ''],
-         hasLeafIn: {
-            'first-aspect': ['wow-this-is-deep', 'have-you-considered-using-json-for-this'],
-         }
-      }
-   });
-   mo.addEventListener('attrChange', e => {
-      console.log(e);
-      // {
-      //    mountedElement,
-      //    attrChangeInfo:[{
-      //       idx: 0,
-      //       oldValue: null,
-      //       newValue: 'good-bye',
-      //       parts:{
-      //          name: 'data-my-enhancement-first-aspect-wow-this-is-deep'
-      //          root: 'data',
-      //          base: 'my-enhancement',
-      //          branch: 'first-aspect',
-      //          leaf: 'wow-this-is-deep',
-      //       }
-      //    }]
-      // }
-   });
-   mo.observe(div);
-   setTimeout(() => {
-      const myCustomElement = document.querySelector('my-custom-element');
-      myCustomElement.setAttribute('data-my-enhancement-first-aspect-wow-this-is-deep', 'good-bye');
-   }, 1000);
-</script>
-```
-
-Some libraries prefer to use the colon (:) rather than a dash to separate these levels of settings:
-
-Possibly some libraries may prefer to mix it up a bit:
-
-
-```html
-<div id=div>
-   <section class=hello 
-      data-my-enhancement=greetings 
-      data-my-enhancement:first-aspect=hello 
-      data-my-enhancement:second-aspect=goodbye
-      data-my-enhancement:first-aspect--wow-this-is-deep
-      data-my-enhancement:first-aspect--have-you-considered-using-json-for-this=just-saying
-   ></section>
-</div>
-```
-
-An example of this in the real world can be found with [HTMX](https://htmx.org/docs/#hx-on):
-
-```html
-<button hx-post="/example"
-        hx-select:htmx:config-request="event.detail.parameters.example = 'Hello Scripting!'">
-    Post Me!
-</button>
-```
-
-To support such syntax, specify the delimiters thusly:
-
-```JavaScript
-const mo = new MountObserver({
-   select: '*',
-   whereAttr:{
-      hasRootIn: ['data', 'enh', 'data-enh'],
-      hasBase: ['-', 'my-enhancement'],
-      hasBranchIn: [':', ['first-aspect', 'second-aspect', '']],
-      hasLeafIn: {
-         'first-aspect': ['--', ['wow-this-is-deep', 'have-you-considered-using-json-for-this']],
-      }
-   }
-});
-```
-
-## Supporting userland security protections
-
-As we saw with the HTMX example above, element enhancement libraries that (progressively) enhance server rendered HTML are finding it necessary to support inline event handling.  Since the platform has provided no support for hashing built-in event handlers, there's no real advantage for these libraries to utilize the built-in event handlers, so might as well create bespoke event handlers, which unfortunately might not be detected by browser security mechanisms. Perhaps some of these libraries only enable that functionality after confirming no such CSP rules are in place, or provide console warnings, who knows?  This reminds me of the plausible (but probably not universally held) belief that illegalizing relatively safe recreational drugs like hashish or beer pushes the illegal market to gravitate towards drugs/beverages which have more "bang for the buck", which are considerably less safe, leading to the conclusion that the "health and safety" laws end up causing more harm than good.
-
-I am personally pursuing a [userland implementation of CSP tailored for attributes](https://github.com/bahrus/be-hashing-out).  What I'm finding necessary to support this is a way to quickly determine *the full list of* attributes a particular enhancement is monitoring for.
-
-Thus the mountObserver does provide that information to the consumer as well:
-
-```JavaScript
-const mo = new MountObserver({
-   select: '*',
-   whereAttr:{
-      hasRootIn: ['data', 'enh', 'data-enh'],
-      hasBase: ['-', 'my-enhancement'],
-      hasBranchIn: [':', ['first-aspect', 'second-aspect', '']],
-      hasLeafIn: {
-         'first-aspect': ['--', ['wow-this-is-deep', 'have-you-considered-using-json-for-this']],
-      }
-   }
-});
-const observedAttributes = await mo.observedAttrs();
-```
-
-## Resolving ambiguity
-
-Because we want the multiple root values (enh-*, data-enh-*, *) to be treated as equivalent, from a developer point of view, we have a possible ambiguity -- what if more than one root is present for the same base, branch and leaf?  Which value prevails over the others?
-
-Tentative rules:
-
-1.  Roots must differ in length.
-2.  If one value is null (attribute not present) and the other a string, the one with the string value prevails.
-3.  If two or more equivalent attributes have string values, the one with the longer root prevails.
-
-The thinking here is that longer roots indicate higher "specificity", so it is safer to use that one.
-
-
+[Implemented as [Requirement7](requirements/Done/Requirement7.md)]
 
 ## Intra document html imports
 
@@ -1839,7 +2059,7 @@ Just as it is useful to be able lazy load external imports when needed, it would
    <template mount='{
       "select": ":not([defer-loading])",
       "loadingEagerness": "eager",
-      "whereMediaMatches": "(min-width: 700px)",
+      "withMediaMatching": "(min-width: 700px)",
       "whereLangIn": ["en-GB"],
    }'>
       <div>I don't know why you say <slot name=slot2></slot> I say <slot name=slot1></slot></div>
@@ -1848,7 +2068,7 @@ Just as it is useful to be able lazy load external imports when needed, it would
    <template mount='{
       "select": ":not([defer-loading])",
       "loadingEagerness": "lazy",
-      "whereMediaMatches": "(max-width: 700px)",
+      "withMediaMatching": "(max-width: 700px)",
       "whereLangIn": ["fr"],
    }'>
       <div>Je ne sais pas pourquoi tu dis  <slot name=slot2></slot> je dis  <slot name=slot1></slot></div>