mount-observer 0.1.1 → 0.1.3

package/README.md

@@ -5,6 +5,45 @@
 
 Note that much of what is described below has not yet been polyfilled.
 
+## Implementation Status
+
+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)
+
+### 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
+
+### Advanced Features
+- ✅ **Dynamic imports**: Lazy loading of JavaScript modules
+- ✅ **assignOnMount**: Property assignment when elements mount
+- ✅ **assignOnDismount**: Property assignment when elements dismount
+- ✅ **do callbacks**: Mount/dismount/disconnect/reconnect lifecycle hooks
+- ✅ **map configuration**: Metadata mapping for attribute coordinates
+- ✅ **once option**: Fire attrchange event only once per attribute
+- ✅ **Shared MutationObserver**: Efficient observer sharing across instances
+- ✅ **Code splitting**: Conditional features loaded on-demand
+- ✅ **Memory management**: WeakRef usage for DOM node references
+
+### Not Yet Implemented
+- ❌ Intersection observer integration
+- ❌ Container query support
+- ❌ Shadow DOM traversal utilities
+- ❌ Reconnect event handling
+- ❌ Multiple import types (CSS, JSON, HTML)
+
 # The MountObserver api.
 
 Author:  Bruce B. Anderson (with valuable feedback from @doeixd )
@@ -70,9 +109,9 @@ To specify the equivalent of what the alternative proposal linked to above would
 
 ```JavaScript
 const observer = new MountObserver({
-   select:'my-element',
+   select:'my-element', //not supported by this polyfill
    import: './my-element.js',
-   do: ({localName}, {modules, observer, observeInfo}) => {
+   do: ({localName}, {modules, observer, mountInit, rootNode}) => {
       if(!customElements.get(localName)) {
          customElements.define(localName, modules[0].MyElement);
       }
@@ -83,7 +122,7 @@ const observer = new MountObserver({
 observer.observe(document);
 ```
 
-The do function will *only be called once per matching element* -- i.e. if the element stops matching the "select" criteria, then matches again, the do function won't be called again.  It will be called for all elements when they match within the scope passed in to the observe method.  However, the events discussed below, as well as more structured inline functions also as discussed below, will continue to be called repeatedly.
+The do function will *only be called once per matching element* -- i.e. if the element stops matching the "select" criteria, then matches again, the do function won't be called again.  It will be called for all elements when they match within the scope passed in to the observe method.  However, the events discussed below, will continue to be called repeatedly.
 
 The constructor argument can also be an array of objects that fit the pattern shown above.
 
@@ -100,19 +139,20 @@ 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 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.
 
-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 "on" that is used specifically for (a subset?) of queries supported by the existing "matches" method that elements support.
+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).
 
 So the developer could use:
 
-## Polyfill Supported Scenario I
+## Polyfill Supported Mount Observer
 
 ```JavaScript
 const observer = new MountObserver({
-   import: './my-element.js',
+   //supported by this polyfill
    whereElementMatches:'my-element',
-   do: ({localName}, {modules, observer, observeInfo}) => {
+   import: './my-element.js',
+   do: ({localName}, {modules, observer, mountInit, rootNode}) => {
       if(!customElements.get(localName)) {
          customElements.define(localName, modules[0].MyElement);
       }
@@ -123,9 +163,11 @@ const observer = new MountObserver({
 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 "*"
+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 ("whreElementMatches"), and leaves "select" for such a time as when a selector observer is available in the platform.
+[Implemented as Requirement 1](requirements/Requirement1.md).
 
 ##  The import key
 
@@ -133,12 +175,12 @@ This proposal has been amended to support multiple imports, including of differe
 
 ```JavaScript
 const observer = new MountObserver({
-   select:'my-element',
+   whereElementMatches:'my-element',
    import: [
       ['./my-element-small.css', {type: 'css'}],
       './my-element.js',
    ],
-   do: ({localName}, {modules, observer}) => {
+   do: ({localName}, {modules, observer, mountInit, rootNode}) => {
       if(!customElements.get(localName)) {
          customElements.define(localName, modules[1].MyElement);
       }
@@ -154,7 +196,9 @@ The do function won't be invoked until all the imports have been successfully co
 
 Previously, this proposal called for allowing arrow functions as well, thinking that could be a good interim way to support bundlers, as well as multiple imports.  But the valuable input provided by [doeixd](https://github.com/doeixd) makes me think that that interim support could more effectively be done by the developer in the do methods.
 
-This proposal would also include support for JSON and HTML module imports (really, all types). 
+This proposal would also include support for JSON and HTML module imports (really, all types).
+
+[Implemented as Requirement 1](requirements/Requirement1.md).
 
 ## Preemptive downloading
 
@@ -171,7 +215,7 @@ So for this we add loadingEagerness:
 
 ```JavaScript
 const observer = new MountObserver({
-   select: 'my-element',
+   select: 'my-element', //not supported by this polyfill
    loadingEagerness: 'eager',
    import: './my-element.js',
    do: ({localName}, {modules}) => customElements.define(localName, modules[0].MyElement),
@@ -183,130 +227,368 @@ So what this does is only check for the presence of an element with tag name "my
 > [!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:
+
+```JavaScript
+//module myActions.js
+const  doFunction = function({localName}, {modules, observer, mountInit, rootNode}){
+   if(!customElements.get(localName)) {
+      // Find the first exported class constructor from the module
+      const ElementClass = Object.values(modules[0]).find(exp => 
+         typeof exp === 'function' && exp.prototype && exp.prototype.constructor === exp
+      );
+      if(ElementClass) {
+         customElements.define(localName, ElementClass);
+      }
+   }
+   observer.disconnectedSignal.abort();
+}
+export {doFunction as do}
+
+// observer setup
+
+const observer = new MountObserver({
+   whereElementMatches:'my-element',
+   import: [
+      './my-element.js',
+      ['./my-element-small.css', {type: 'css'}],
+      './myActions.js'
+   ],
+   reference: 2
+});
+observer.observe(document);
+
+```
+
+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.
+
+**Key behaviors:**
+- The `reference` property can be a single number or an array of numbers, each referring to an import index
+- Referenced modules must be JavaScript modules (not CSS, JSON, or HTML imports)
+- If a referenced module exports a `do` function, it will be called after the inline `do` callback (if present)
+- If a referenced module doesn't export a `do` function, it's silently skipped
+- The inline `do` callback runs first, then referenced `do` functions run in the order specified
+
+**Important:** Since `do` is a reserved keyword in JavaScript, you must export it using the syntax:
+```javascript
+const doFunction = function(element, context) { /* ... */ };
+export { doFunction as do };
+```
+
+**Validation:** The `reference` property is validated in the constructor:
+- Throws an error if `import` is not defined
+- Throws an error if any index is out of bounds
+- Throws an error if any index points to a non-JS module (e.g., CSS or JSON import)
+
+Multiple references can also be made.
+
+So for example:
+
+```JavaScript
+
+import: [
+    ['./my-element-small.css', {type: 'css'}],
+    './component.js',
+    './actions1.js',
+    './actions2.js'
+],
+reference: [2, 3]  // Both actions1 and actions2 will have their 'do' called if present
+```
+
+[Implemented as [Requirement11](requirements/Requirement11.md)]
+
+### Referenced whereInstanceOf
+
+Similar to the `do` function, the `whereInstanceOf` 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}) {
+   if(!customElements.get(localName)) {
+      customElements.define(localName, modules[1].MyElement);
+   }
+   observer.disconnectedSignal.abort();
+};
+
+const whereInstanceOf = [HTMLMarqueeElement, SVGElement];
+
+export { doFunction as do, whereInstanceOf };
+
+// my local module
+const observer = new MountObserver({
+   whereElementMatches: 'my-element',
+   import: [
+      ['./my-element-small.css', {type: 'css'}],
+      './my-element.js',
+      './mySettings.js'
+   ],
+   reference: 2
+});
+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
+- **Timing**: 
+  - With lazy loading (default): Inline `whereInstanceOf` 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.
+
+[Implemented as [Requirement12](requirements/Requirement12.md)]
+
 
 
 ## Mount Observer Script Elements (MOSEs)
 
 Following an approach similar to the [speculation api](https://developer.chrome.com/blog/speculation-rules-improvements), we can add a script element anywhere in the DOM:
 
-```html
-<script type="mountobserver" onload="{...}"  onmount="{
-   const {matchingElement} = event;
-   const {localName} = matchingElement;
+```JavaScript
+// myPackage/myDefiner.js
+//my all powerful custom element definer
+const doFunction = function({localNme}, {modules, observer}){
    if(!customElements.get(localName)) {
       customElements.define(localName, modules[1].MyElement);
    }
    observer.disconnectedSignal.abort();
-}">
+}
+export { doFunction as do };
+```
+
+```html
+<script type="mountobserver" >
 {
    "select":"my-element",
    "import": [
       ["./my-element-small.css", {type: "css"}],
       "./my-element.js",
-   ]
+      "myPackage/myDefiner.js
+   ],
+   "reference": 2
 }
 </script>
 ```
 
-The things that make this API work together, namely the "modules", "observer", and "mountedElements" (an array of an array of weak refs to elements that match all the criteria for the i<sup>th</sup> "on" selector) would be accessible as properties of the script element:
+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.
+
+
+## Binding from a distance
+
+It is important to note that "whereElementMatches" is a css query with no restrictions.  So something like:
 
 ```JavaScript
-const {modules, observer, mountedElements, mountInit} = myMountObserver;
+import {EvtRt} from 'mount-observer/EvtRt.js';
+
+class MyHandler extends EvtRt {
+   mount(mountedElement, mountInit, context){
+      mountedElement.textContent = 'hello';
+   }
+   dismount(mountedElement, mountInit){
+      mountedElement.textContent = 'goodbye';
+   }
+}
+
+const observer = new MountObserver({
+   // not supported by polyfill
+   //select: 'div > p + p ~ span[class$="name"]' 
+   // is supported:
+   whereElementMatches: 'div > p + p ~ span[class$="name"]',
+   do: (mountedElement, ctx) => {
+      new MyHandler(mountedElement, ctx);
+   },
+});
+observer.observe(document);
 ```
 
-The "scope" of the observer would be the ShadowRoot containing the script element (or the document outside Shadow if placed outside any shadow DOM, like in the head element).
 
-Once again, arrays of settings could be supported, which, in practice, would greatly increase the ratio between declarative, JSON-parsable instructions that could be performed in low-level c++/rust threads, vs custom JavaScript in the example above.  The events / callbacks would need to provide the index of which set of criteria was just fulfilled.
+... would work.
 
-> [!Note]
-> To support the event handlers above, I believe it would require that CSP solutions factor in both the inner content of the script element as well as all the event handlers via the string concatenation operator.  I actually think such support is quite critical due to lack of support of import.meta.[some reference to the script element] not being available, as it was pre-ES Modules.
+EvtRt is a convenience class provided with the polyfill package, and is considered part of this proposal (see how it is used below  by built in handlers).
 
-## Specific solution for lazy loading custom element definitions
+This allows developers to create "stylesheet" like capabilities.
 
-Since the example we've been dwelling on so far (lazy custom element definition) seems like such a pressing, common requirement, and was in fact the originating impetus for this proposal, we can go a step further and make the example above 100% declarative, thus resulting in a less clunky interplay between JSON and custom script.  This is meant as a way of illustrating how the platform could continue to extend this proposal going forward.
+## Registering reusable handlers with MountObserver.define
 
-The syntax below is just one, "spit-balling" way this could be done, as an example, and would require absorbing final heuristics from other custom element initiatives (such as declarative custom elements) when they get added to the platform.
+To make MountInit configurations more JSON-serializable and encourage code reuse, you can register handler classes with string names and reference them by name:
 
-```html
-<script type="mountobserver">
-{
-   "select":"my-element",
-   "import": [
-      ["./my-element-small.css", {type: "css"}],
-      "./my-element.js",
-   ],
-   "define": {
-      "targetRegistry": "CustomElements",
-      "targetScope": "global",
-      "styleModules": [0],
-      "classDefinition": {
-         "module": 1,
-         "exportSymbol": 'MyElement'
-      }
+```JavaScript
+import {EvtRt} from 'mount-observer/EvtRt.js';
+
+class MyHandler extends EvtRt {
+   mount(mountedElement, mountInit, context){
+      mountedElement.textContent = 'hello';
+   }
+   dismount(mountedElement, mountInit){
+      mountedElement.textContent = 'bye';
    }
 }
-</script>
+
+// Register the handler with a string name
+MountObserver.define('myHandler', MyHandler);
+
+// Reference it by name in the configuration
+const observer = new MountObserver({
+   whereElementMatches: 'div > p + p ~ span[class$="name"]',
+   do: 'myHandler'  // String reference instead of inline function
+});
+observer.observe(document);
 ```
 
+### Benefits of registered handlers
 
-## Shadow Root inheritance
+1. **JSON serialization**: Configurations using string references can be serialized to JSON
+2. **Code reuse**: Define handlers once, use them in multiple observers
+3. **Separation of concerns**: Keep handler logic separate from configuration
 
-Inside a shadow root, we can plop a script element, also with type "mountobserver", optionally giving it the same id as above:
+### Using arrays with mixed types
 
-```html
-#shadowRoot
-<script id=myMountObserver type=mountobserver>
-{
-   "select":"your-element"
+The `do` property can be a string, a function, or an array mixing both:
+
+```JavaScript
+MountObserver.define('logger', LoggerHandler);
+MountObserver.define('validator', ValidatorHandler);
+
+const observer = new MountObserver({
+   whereElementMatches: 'input',
+   do: [
+      'logger',                    // Registered handler
+      (element, ctx) => {          // Inline function
+         element.dataset.processed = 'true';
+      },
+      'validator'                  // Another registered handler
+   ]
+});
+```
+
+Handlers execute in the order specified. If a handler constructor throws an error, execution stops and subsequent handlers won't run.
+
+### Interaction with the reference property
+
+When both `do` (with string/array) and `reference` are specified, the execution order is:
+
+1. Inline `do` functions and registered handlers (from `do` strings), in whatever order they appear
+2. Referenced `do` functions (from `reference` property)
+
+```JavaScript
+MountObserver.define('setup', SetupHandler);
+
+const observer = new MountObserver({
+   whereElementMatches: 'button',
+   import: './button-actions.js',
+   reference: 0,
+   do: ['setup', (el) => { el.dataset.ready = 'true'; }]
+});
+// Execution order: setup handler, inline function, then imported do function
+```
+
+### Handler requirements
+
+Registered handlers must be classes (constructors) that accept `(mountedElement: Element, ctx: MountContext)` as constructor parameters. They can be:
+
+- ES6 classes extending `EvtRt` (recommended)
+- ES6 classes with custom logic
+- ES5-style constructor functions
+
+```JavaScript
+// ES5-style constructor function
+function SimpleHandler(element, ctx) {
+   element.textContent = 'Handled!';
 }
-</script>
+
+MountObserver.define('simple', SimpleHandler);
 ```
 
-If no id is found in the parent ShadowRoot (or in the parent window if the shadow root is at the top level), then this becomes a new set of rules to observe.
+### Error handling
 
-But if a matching id is found, then the values from the parent script element get merged in with the one in the child, with the child settings, including the event handling attributes. 
+**Validation at construction time**: If you reference an unregistered handler name, an error is thrown when creating the MountObserver:
 
-> [!Note]
-> The onload event is critical for a number of reasons, among them:
-> 1. We need a way to inject non JSON serializable settings (described below) when necessary, and 
-> 2. We need a way to override settings in child Shadow DOM's programmatically in some cases.
+```JavaScript
+const observer = new MountObserver({
+   do: 'nonexistent'  // Error: No handler defined for nonexistent
+});
+```
+
+**Duplicate registration**: Attempting to register the same name twice throws an error:
+
+```JavaScript
+MountObserver.define('myHandler', Handler1);
+MountObserver.define('myHandler', Handler2);  // Error: myHandler already in use
+```
 
-We will come back to some important [additional features](#creating-frameworks-that-revolve-around-moses) of using these script elements later, but first we want to cover the highlights of this proposal, in order to give more context as to what kinds of functionality these MOSEs can provide.
 
 
-## Binding from a distance
+### Global registry
+
+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)]
+
+### Built in handlers
+
+This proposal advocates having the platform provide some built in handlers, that extend EvtRt, that is included with this Polyfill.
 
-It is important to note that "select" is a css query with no restrictions.  So something like:
+#### Log to console handler
 
 ```JavaScript
 const observer = new MountObserver({
-   select:'div > p + p ~ span[class$="name"]',
-   do:{
-      mount: (matchingElement) => {
-         //attach some behavior or set some property value or add an event listener, etc.
-         matchingElement.textContent = 'hello';
-      },
-      dismount: (matchingElement) => {
-         matchingElement.textContent = 'bye';
-      }
-   }
-})
+   // not supported by polyfill
+   //select: 'div > p + p ~ span[class$="name"]' 
+   // is supported:
+   whereElementMatches: 'div > p + p ~ span[class$="name"]',
+   do: 'builtIns.logToConsole'
+});
+observer.observe(document);
 ```
 
-... would work.
+This logs to console all the events (mount, dismount, disconnect)
+
+### Lazy custom element handler
+
+```JavaScript
+// MyElement.js
+export default class MyElement extends HTMLElement {
+    connectedCallback() {
+        this.textContent = 'Hello!';
+    }
+}
+
+// main.js
+import { MountObserver } from 'mount-observer';
+
+const observer = new MountObserver({
+    whereElementMatches: 'my-element',
+    import: './MyElement.js',
+    do: 'builtIns.defineCustomElement'
+});
+observer.observe(document);
 
-Note that in this example, "do" no longer points to a function.  When it did (above), we mentioned this would only be called once per element.  **Now it will be called every the conditions flip from not all satisfied to satisfied"**.
+// HTML - elements will be upgraded when discovered
+// by the mount observer
+<my-element></my-element>
 
-This would allow developers to create "stylesheet" like capabilities.
+```
 
-## Applying properties with assignGingerly
+## Applying properties on mount and dismount
 
-For the common use case of setting properties on matching elements, MountObserver provides built-in support for the [assignGingerly](https://github.com/bahrus/assign-gingerly) library. This allows you to declaratively specify properties to apply to elements without writing custom mount callbacks:
+For the common use case of setting properties on matching elements, MountObserver provides built-in support for the [assignGingerly](https://github.com/bahrus/assign-gingerly) library. This allows us to declaratively specify properties to apply to elements during their lifecycle without writing custom mount callbacks:
 
 ```JavaScript
 const observer = new MountObserver({
    whereElementMatches: 'input',
-   assignGingerly: {
+   assignOnMount: {
       disabled: true,
       value: 'Default value',
       title: 'This is a tooltip'
@@ -317,35 +599,100 @@ 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)]
+
+### Assigning properties on dismount
+
+You can also specify properties to apply when elements are removed from the DOM using `assignOnDismount`:
+
+```JavaScript
+const observer = new MountObserver({
+   whereElementMatches: '.status-indicator',
+   assignOnMount: {
+      '?.style?.color': 'green',
+      '?.dataset?.status': 'active'
+   },
+   assignOnDismount: {
+      '?.style?.color': 'red',
+      '?.dataset?.status': 'inactive'
+   }
+});
+observer.observe(document);
+```
+
+This is useful for cleanup operations, visual feedback, or maintaining state on elements that may be temporarily removed from the DOM but still referenced elsewhere in your code.
+
+**Note:** The `assignOnDismount` properties are applied before the element is removed from the mounted elements tracking, so the element still has access to its DOM context.
+
+#### Practical use case: Form validation feedback
+
+A common use case is providing visual feedback for form validation:
+
+```JavaScript
+const observer = new MountObserver({
+   whereElementMatches: 'input.validated',
+   assignOnMount: {
+      '?.style?.borderColor': 'green',
+      '?.style?.backgroundColor': '#f0fff0',
+      '?.setAttribute': ['aria-invalid', 'false']
+   },
+   assignOnDismount: {
+      '?.style?.borderColor': '',
+      '?.style?.backgroundColor': '',
+      '?.removeAttribute': 'aria-invalid'
+   }
+});
+observer.observe(document);
+```
+
+When an input gains the `validated` class, it gets green styling. When the class is removed (dismount), the styling is cleaned up.
+
+#### Remounting behavior
+
+If an element is removed and then re-added to the DOM, the `assignOnMount` properties will be reapplied:
+
+```JavaScript
+const input = document.querySelector('input');
+input.classList.add('validated');  // assignOnMount applied
+input.classList.remove('validated'); // assignOnDismount applied
+input.classList.add('validated');  // assignOnMount applied again
+```
+
+This ensures consistent behavior across the element's lifecycle.
+
 ### Nested properties with dataset
 
-The `assignGingerly` library supports nested property assignment using the `?.` notation. This is particularly useful for setting data attributes:
+The `assignGingerly` library supports nested property assignment using the `?.` notation. This is particularly useful for setting data attributes and style:
 
 ```JavaScript
 const observer = new MountObserver({
    whereElementMatches: 'button',
-   assignGingerly: {
+   assignOnMount: {
       disabled: false,
-      '?.dataset.action': 'submit',
-      '?.dataset.trackingId': '12345'
+      '?.dataset?.action': 'submit',
+      '?.dataset?.trackingId': '12345',
+      '?.style': {
+         color: 'white',
+         height: '25px',
+      }
    }
 });
 observer.observe(document);
 ```
 
-The `?.` prefix tells assignGingerly to create nested properties if they don't exist. In this example, `?.dataset.action` will set the `data-action` attribute on the button elements.
+The `?.` prefix tells assignGingerly to create nested properties if they don't exist. In this example, `?.dataset?.action` will set the `data-action` attribute on the button elements.
 
 ### Combining with imports
 
-You can combine `assignGingerly` with lazy loading to both import resources and set properties:
+You can combine `assignOn*` with lazy loading to both import resources and set properties:
 
 ```JavaScript
 const observer = new MountObserver({
    whereElementMatches: 'my-element',
    import: './my-element.js',
-   assignGingerly: {
+   assignOnMount: {
       theme: 'dark',
-      '?.dataset.initialized': 'true'
+      '?.dataset?.initialized': 'true'
    },
    do: ({localName}, {modules}) => {
       if(!customElements.get(localName)) {
@@ -360,13 +707,386 @@ The `assignGingerly` properties are applied after imports are loaded but before
 
 ### Performance benefits
 
-Using `assignGingerly` provides several benefits:
+Using `assignOn*` provides several benefits:
 
 1. **Lazy loading**: The assign-gingerly library is only loaded when needed (when the `assignGingerly` property is specified)
 2. **Bulk operations**: Properties are applied efficiently to all matching elements
 3. **Declarative**: No need to write custom mount callbacks for simple property assignments
 4. **Consistent**: The same property values are applied uniformly across all matching elements
 
+### Dynamically updating assignGingerly configuration
+
+The `MountObserver` class provides a public `assignGingerly()` method that allows you to merge new updates into the  observer. This is useful for responding to user actions or application state changes:
+
+```JavaScript
+const observer = new MountObserver({
+   whereElementMatches: 'input',
+   assignOnMount: {
+      disabled: true,
+      value: 'Initial value'
+   }
+});
+observer.observe(document);
+
+// Later, update the configuration
+await observer.assignGingerly({
+   title: 'Updated tooltip',
+   placeholder: 'New placeholder'
+});
+```
+
+**Key behaviors:**
+
+1. **Merging**: New properties are merged with existing configuration. In the example above, future elements will receive all properties: `disabled`, `value`, `title`, and `placeholder`.
+
+2. **Applies to existing elements**: The new properties are immediately applied to all currently mounted elements.
+
+3. **Applies to future elements**: Future elements that mount will receive the merged configuration.
+
+4. **Starting without initial config**: You can call the method even if no `assignGingerly` was specified in the constructor:
+
+```JavaScript
+const observer = new MountObserver({
+   whereElementMatches: 'input'
+});
+observer.observe(document);
+
+// Set configuration later
+await observer.assignGingerly({
+   disabled: true,
+   value: 'Set via method'
+});
+```
+
+5. **Clearing configuration**: Pass `undefined` to clear the configuration for future elements (already-mounted elements keep their properties):
+
+```JavaScript
+await observer.assignGingerly(undefined);
+// Future elements will not have properties applied
+// Existing elements retain their current properties
+```
+
+**Method signature:**
+```TypeScript
+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)]
+
+## Emitting events from mounted elements
+
+MountObserver can automatically dispatch custom events from elements when they mount. This is useful for:
+
+1. **Signaling readiness**: Notify parent components or listeners that an element is ready
+2. **Initialization events**: Trigger workflows when elements appear in the DOM
+3. **Decoupled communication**: Allow elements to announce their presence without tight coupling
+
+### Basic event emission
+
+```JavaScript
+const observer = new MountObserver({
+   whereElementMatches: 'button[data-action]',
+   mountedElemEmits: {
+      event: 'Event',
+      args: 'custom-ready'
+   }
+});
+observer.observe(document);
+```
+
+This dispatches a `custom-ready` event from each matching button element when it mounts. Events bubble by default, so you can listen at the document level:
+
+```JavaScript
+document.addEventListener('custom-ready', (e) => {
+   console.log('Button ready:', e.target);
+});
+```
+
+### Event constructors
+
+You can specify any event constructor available in `globalThis`:
+
+```JavaScript
+mountedElemEmits: {
+   event: 'CustomEvent',
+   args: ['element-ready', { detail: { timestamp: Date.now() } }]
+}
+```
+
+Or pass a constructor directly:
+
+```JavaScript
+mountedElemEmits: {
+   event: CustomEvent,
+   args: ['element-ready', { detail: { timestamp: Date.now() } }]
+}
+```
+
+### Magic string substitution
+
+Use magic strings to inject dynamic values into event data:
+
+- `{{mountedElement}}` - The element that just mounted
+- `{{mountInit}}` - The MountInit configuration object
+
+```JavaScript
+const observer = new MountObserver({
+   whereElementMatches: 'button[data-test]',
+   mountedElemEmits: {
+      event: 'CustomEvent',
+      args: ['element-mounted', { 
+         detail: { 
+            element: '{{mountedElement}}',
+            config: '{{mountInit}}'
+         }
+      }]
+   }
+});
+```
+
+Magic strings work at any depth in nested objects and arrays:
+
+```JavaScript
+mountedElemEmits: {
+   event: 'CustomEvent',
+   args: ['data-ready', {
+      detail: {
+         nested: {
+            deep: {
+               element: '{{mountedElement}}'
+            }
+         }
+      }
+   }]
+}
+```
+
+### Multiple events
+
+Emit multiple events in sequence by providing an array:
+
+```JavaScript
+const observer = new MountObserver({
+   whereElementMatches: 'my-component',
+   mountedElemEmits: [
+      { event: 'Event', args: 'component-loading' },
+      { event: 'Event', args: 'component-ready' },
+      { event: 'CustomEvent', args: ['component-initialized', { detail: { version: '1.0' } }] }
+   ]
+});
+```
+
+Events are dispatched in the order specified.
+
+### Event properties with eventProps
+
+Apply additional properties to the event object using `eventProps`:
+
+```JavaScript
+mountedElemEmits: {
+   event: 'CustomEvent',
+   args: ['ready', { detail: {} }],
+   eventProps: {
+      timestamp: Date.now(),  //TODO:  magic string?
+      source: 'mount-observer',
+      element: '{{mountedElement}}'
+   }
+}
+```
+
+Properties are applied using the [assignGingerly](https://github.com/bahrus/assign-gingerly) library, which supports nested property assignment with the `?.` notation.
+
+### Fire once per element
+
+Use `oncePerMountedElement` to ensure an event only fires the first time an element mounts:
+
+```JavaScript
+const observer = new MountObserver({
+   whereElementMatches: 'button[data-once]',
+   mountedElemEmits: {
+      event: 'Event',
+      args: 'initialized',
+      oncePerMountedElement: true
+   }
+});
+```
+
+If the element is removed and re-added to the DOM, the event will not fire again. This is useful for initialization events that should only happen once per element instance.
+
+### Performance considerations
+
+The event emission logic is code-split into a separate module (`emitEvents.js`) that is only loaded when `mountedElemEmits` is configured. This keeps the core MountObserver lean for users who don't need this feature.
+
+### Complete example
+
+```JavaScript
+const observer = new MountObserver({
+   whereElementMatches: 'my-widget',
+   import: './my-widget.js',
+   mountedElemEmits: [
+      {
+         event: 'CustomEvent',
+         args: ['widget-loading', { 
+            detail: { 
+               element: '{{mountedElement}}',
+               timestamp: Date.now()
+            }
+         }],
+         oncePerMountedElement: true
+      },
+      {
+         event: 'Event',
+         args: 'widget-ready'
+      }
+   ],
+   do: ({localName}, {modules}) => {
+      if(!customElements.get(localName)) {
+         customElements.define(localName, modules[0].MyWidget);
+      }
+   }
+});
+
+// Listen for events
+document.addEventListener('widget-loading', (e) => {
+   console.log('Widget loading:', e.detail.element);
+});
+
+document.addEventListener('widget-ready', (e) => {
+   console.log('Widget ready:', e.target);
+});
+
+observer.observe(document);
+```
+
+[Implemented as [Requirement10](requirements/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.
+
+### Basic usage
+
+```JavaScript
+const observer = new MountObserver({
+   whereElementMatches: 'button',
+   do: (mountedElement, {observer}) => {
+      const notifier = observer.getNotifier(mountedElement);
+      
+      notifier.addEventListener('mount', (e) => {
+         console.log('This specific button mounted', e.mountedElement);
+      });
+      
+      notifier.addEventListener('dismount', (e) => {
+         console.log('This specific button dismounted', e.mountedElement, e.reason);
+      });
+      
+      notifier.addEventListener('disconnect', (e) => {
+         console.log('This specific button disconnected', e.mountedElement);
+      });
+   }
+});
+observer.observe(document);
+```
+
+### When mount events fire on notifiers
+
+The notifier follows a specific rule for mount events:
+
+- **First mount**: If `getNotifier()` is called during the `do` callback (when the element is mounting), the mount event does NOT fire on the notifier
+- **Subsequent mounts**: After the element dismounts and mounts again, the mount event WILL fire on the notifier
+
+This prevents duplicate mount notifications when setting up listeners during the initial mount.
+
+```JavaScript
+const observer = new MountObserver({
+   whereElementMatches: '#my-button',
+   do: (element, {observer}) => {
+      const notifier = observer.getNotifier(element);
+      
+      // This listener won't fire for the current mount
+      // (since we're inside the do callback)
+      notifier.addEventListener('mount', () => {
+         console.log('Element re-mounted after being removed');
+      });
+   }
+});
+```
+
+### Creating notifiers before mounting
+
+You can call `getNotifier()` at any time, even before an element mounts:
+
+```JavaScript
+const observer = new MountObserver({
+   whereElementMatches: '#future-button'
+});
+observer.observe(document);
+
+// Get notifier before element exists
+const button = document.createElement('button');
+button.id = 'future-button';
+
+const notifier = observer.getNotifier(button);
+notifier.addEventListener('mount', () => {
+   console.log('Button mounted!'); // This WILL fire
+});
+
+// Add to DOM later
+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:
+
+1. **Progressive enhancement**: Attach/detach behaviors when elements mount/dismount
+2. **Cleanup on disconnect**: Remove event listeners or cancel timers when elements are removed
+3. **Peer element coordination**: React to changes in related elements
+4. **Lifecycle-aware components**: Build components that respond to their own mounting state
+
+### Performance notes
+
+- Notifiers are cached in a WeakMap, so calling `getNotifier()` multiple times for the same element returns the same EventTarget
+- No explicit cleanup is needed - notifiers are garbage collected when their elements are
+- The notifier continues to exist even after the element disconnects, allowing it to receive mount events if the element is re-added
+
+**Method signature:**
+```TypeScript
+getNotifier(element: Element): EventTarget
+```
+
+[Implemented as [Requirement13](requirements/Requirement13.md)]
+
 
 ##  Extra lazy loading
 
@@ -376,7 +1096,7 @@ However, we could make the loading even more lazy by specifying intersection opt
 
 ```JavaScript
 const observer = new MountObserver({
-   select: 'my-element',
+   select: 'my-element', //not supported by polyfill
    whereElementIntersectsWith:{
       rootMargin: "0px",
       threshold: 1.0,
@@ -385,45 +1105,33 @@ const observer = new MountObserver({
 });
 ```
 
-## Media / container queries / instanceOf / custom checks
+## Media / container queries / instanceOf / custom checks [TODO] out of date
 
 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({
-   select: 'div > p + p ~ span[class$="name"]',
+   select: 'div > p + p ~ span[class$="name"]', // not supported by polyfill
    whereMediaMatches: '(max-width: 1250px)',
    whereSizeOfContainerMatches: '(min-width: 700px)',
    whereContainerHas: '[itemprop=isActive][value="true"]',
    whereInstanceOf: [HTMLMarqueeElement], //or ['HTMLMarqueeElement']
    whereLangIn: ['en-GB'],
-   whereConnectiselect:{
+   whereConnectionHas:{
       effectiveTypeIn: ["slow-2g"],
    },
    import: ['./my-element-small.css', {type: 'css'}],
-   do: {
-      confirm: (matchingElement, (e: MountObserverConfirmEvent) => {
-         e.isSatisfied = true;
-         e.preventDefault();
-      }),
-      mount: ({localName}, {modules}) => {
-        ...
-      },
-      dismount: ...,
-      disconnect: ...,
-      move: ...,
-      reconnect: ...,
-      confirm: ...,
-      reconfirm: ...,
-      exit: ...,
-      forget: ...,
-   }
+   do: ...
 });
 ```
 
+[whereInstanceOf implemented as [Requirement5](requirements/Requirement5.md)]
+
+[whereMediaMatches implemented as [Requirement6](requirements/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.  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 "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.
 
 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.
 
@@ -446,7 +1154,7 @@ observer.addEventListener('confirm', e => {
 });
 observer.addEventListener('mount', e => {
   console.log({
-      matchingElement: e.matchingElement, 
+      mountedElement: e.mountedElement, 
       module: e.module
    });
 });
@@ -473,6 +1181,8 @@ observer.addEventListener('forget', e => {
 });
 ```
 
+[mount, dismount, disconnect] events implemented
+
 ## 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.
@@ -506,6 +1216,8 @@ I'm on the fence on that one.   I think the benefits either way to DX are so sma
 
 ## Dismounting
 
+[TODO] This section is out of date
+
 In many cases, it will be critical to inform the developer **why** the element no longer satisfies all the criteria.  For example, we may be using an intersection observer, and when we've scrolled away from view, we can "shut down" until the element is (nearly) scrolled back into view.  We may also be displaying things differently depending on the network speed.  How we should respond when one of the original conditions, but not the other, no longer applies, is of paramount importance.
 
 So the dismount event should provide a "checklist" of all the conditions, and their current value:
@@ -538,6 +1250,8 @@ 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)]
+
 
 ## Support for "donut hole scoping"
 
@@ -550,36 +1264,48 @@ For the polyfill, we need to support it as follows:
 ```html
 <div id=myTest itemscope>
    <span itemprop=name>
+    <div itemscope>
+        <data itemprop=ssn>
+    </div>
 </div>
 ```
 
+We want to find all elements with attribute itemprop outside any itemscope, so the span and not the data element.
+
 ```JavaScript
-const oElement = document.getElementById('myTest');
+const oContainerNode = document.getElementById('myTest');
 const observer = new MountObserver({
-   select:'[itemprop]',
-   outside: '[itemscope]'
-   do: {
-      mount: ({localName}, {modules, observer}) => {
-        ...
-      },
+   whereElementMatches:'[itemprop]',
+   whereOutside: '[itemscope]'
+   do: ({localName}, {modules, observer}) => {
+      ...
    },
    disconnectedSignal: new AbortController().signal
 });
-observer.observe(oElement);
+observer.observe(oContainerNode);
 ```
 
-The check for "outside" is done via script:
+The check for "whereOutside" is done via script:
 
 ```JavaScript
-outsideCheck(oElement: Element, matchCandidate: Element, outside: string){
-   const elementsToExclude = Array.from(oElement.querySelectorAll(outside));
-   for(const elementToExclude of elementsToExclude){
-      if(elementToExclude === matchCandidate || elementToExclude.contains(matchCandidate)) return false;
-   }
-   return true;
+import {whereOutside} from 'mount-observer/whereOutside.js';
+whereOutside(oContainerNode: Node, matchCandidate: Element, outside: string){
+    let current = matchCandidate.parentElement;
+    
+    while (current && current !== oContainerNode) {
+        if (current.matches(outside)) {
+            return false;  // Found an excluding ancestor
+        }
+        current = current.parentElement;
+    }
+    
+    return true;  // No excluding ancestors found
 }
+
 ```
 
+[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.
@@ -632,10 +1358,10 @@ const mo = new MountObserver({
    observedAttrsWhenMounted: ['lang', 'contenteditable']
 });
 
-mo.addEventListener('attrChange', e => {
+mo.addEventListener('attrchange', e => {
    console.log(e);
    // {
-   //    matchingElement,
+   //    mountedElement,
    //    attrChangeInfo:[{
    //       idx: 0,
    //       name: 'lang'
@@ -779,7 +1505,7 @@ MountObserver provides a breakdown of the matching attribute when encountered:
    mo.addEventListener('attrChange', e => {
       console.log(e);
       // {
-      //    matchingElement,
+      //    mountedElement,
       //    attrChangeInfo:[{
       //       idx: 0,
       //       oldValue: null,
@@ -1144,78 +1870,6 @@ Just as it is useful to be able lazy load external imports when needed, it would
 </compose>
 ```
 
-
-## Creating "frameworks" that revolve around MOSEs.
-
-Often, we will want to define a large number of "mount observer script elements (MOSEs)" programmatically, and we need it to be done in a generic way, that can be published and easily referenced.  
-
-This is a problem space that [be-hive](https://github.com/bahrus/be-hive) is grappling with, and is used as an example for this section, to simply make things more concrete.  But we can certainly envision other "frameworks" that could leverage this feature for a variety of purposes, including other families of behaviors/enhancements, or "binding from a distance" syntaxes.  
-
-In particular, *be-hive* supports publishing [enhancements](https://github.com/bahrus/be-enhanced) that take advantage of the DOM filtering ability that the MountObserver provides, that "ties the knot" based on CSS matches in the DOM to behaviors/enhancements that we want to attach directly onto the matching elements.  *be-hive* seeks to take advantage of the inheritable infrastructure that MOSEs provide, but we don't want to burden the developer with having to manually list all these configurations, we want it to happen automatically, only expecting manual intervention when we need some special customizations within a specific ShadowDOM realm.
-
-To support this, we propose these highlights:
-
-1.  Adding a static "synthesize" method to the MountObserver api.  This would provide a kind of passage-way from the imperative api to the declarative one.  
-2.  As the *synthesize* method is called repeatedly from different packages that work within that framework, it creates a cluster of MOSEs wrapped inside the "synthesizing" custom element ("be-hive") that the framework developer authors.  It appends script elements with type="mountobserver" to the custom element instance sitting in the DOM, that dispatches events from the synthesizing custom element it gets appended to, so subscribers in child Shadow DOM's don't need to add a general mutation observer in order to know when parent shadow roots had a MOSE inserted that it needs to act on.  This allows the child Shadow DOM's to inherit (in this case) behaviors/enhancements from the parent Shadow DOM.
-
-So framework developers can develop a bespoke custom element that inherits from the "abstract" class "*Synthesizer*" that is part of this package / proposal, that is used to group families of MountObserver's together. 
-
-Some attributes that the base "Synthesizer" supports are listed below.  They are all related to allowing individual ShadowDOM realms to be able to easily opt in or opt out, depending on the level of control/trust that is exerted by a web component / Shadow Root, as far as the HTML it imports in. 
-
-1.  passthrough.  Allows for the inheritance of behaviors to flow through from above (or from the root document), while not actually activating any of them within the Shadow DOM realm itself.
-2.  exclude.  List of specific MOSE id's to block.  Allows them to flow through to child Shadow Roots.
-3.  include.  List of specific MOSE id's to allow.
-
-What functionality do these "synthesizing" custom elements provide, what value-add proposition do they fulfill over what is built into the MountObserver polyfill / package?
-
-The sky is the limit, but focusing on the first example, be-hive, they are:
-
-1.  Managing, interpreting and parsing the attributes that add semantic enhancement vocabularies onto exiting elements.
-2.  Establishing the "handshake" that imports the enhancement package, instantiates the enhancement, and passes properties that were previously assigned to the pre-enhanced element to the attached enhancement/behavior.
-3.  Providing an inheritable "registry" of reusable scriptlets that can be leveraged in a declarative way.
-
-If one inspects the DOM, one will see grouped (already "parsed") MOSEs, like so:
-
-```html
-<be-hive>
-   <script type=mountobserver id=be-hive.be-searching></script>
-   <script type=mountobserver id=be-hive.be-counted></script>
-</be-hive>
-```
-
-Without the help of the synthesize method / Synthesizer base class, the developer would need to set these up manually, so this lifts a significant burden from the shoulders of people who want to leverage these behaviors/enhancements in a seamless way.  
-
-The developer of each package defines their MOSE "template", and then syndicates it via the synthesize method:
-
-```JavaScript
-MountObserver.synthesize(root: document | shadowRootNode, ctr:  ({new() => Synthesizer}), mose: MOSE)
-```
-
-What this method does is it:
-
-1.  Uses [customElements.getName](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/getName) to get the name of the custom element (say it is 'be-hive') from the provided constructor.
-2.  Searches for a be-hive tag inside the root node (with special logic for the "head" element).  If not found, creates it.
-3.  Places the MOSE inside.
-
-
-Then in our shadowroot, rather than adding a script type=mountobserver for every single mount observer we want to inherit, we could reference the group via simply:
-
-```html
-<be-hive></be-hive>
-```
-
-And we can give each inheriting ShadowRoot a personality of its own by customizing the settings within that shadow scope, by manually adding a MOSE with matching id that overrides the inheriting settings with custom settings:
-
-```html
-<be-hive>
-   <script type=mountobserver id=be-hive.be-searching>
-      {
-         ...my custom settings
-      }
-   </script>
-</be-hive>
-```
-
 ## Creating an Element-To-RefID DOM traversal API
 
 The platform provides some nice help with managing forms, including IDREF dependency support:
@@ -1332,4 +1986,4 @@ To keep the api uniform, we hide this discrepancy by pretending the form element
    // includes both field1 and field2
    
 </script>
-```
+```