mount-observer 0.1.2 → 0.1.3

package/README.md

@@ -28,7 +28,8 @@ The following features have been implemented and tested:
 
 ### Advanced Features
 - ✅ **Dynamic imports**: Lazy loading of JavaScript modules
-- ✅ **assignGingerly**: Property assignment on mount
+- ✅ **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
@@ -108,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);
       }
@@ -121,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.
 
@@ -138,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 "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 every provide a selector-observer (if ever).
+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({
+   //supported by this polyfill
    whereElementMatches:'my-element',
    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);
       }
@@ -163,7 +165,7 @@ 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 ("whreElementMatches"), 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 ("whereElementMatches"), and leaves "select" for such a time as when a selector observer is available in the platform.
 
 [Implemented as Requirement 1](requirements/Requirement1.md).
 
@@ -173,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);
       }
@@ -213,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),
@@ -225,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:
 
-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.
+```JavaScript
+MountObserver.define('myHandler', Handler1);
+MountObserver.define('myHandler', Handler2);  // Error: myHandler already in use
+```
 
 
-## Binding from a distance
 
-It is important to note that "select" is a css query with no restrictions.  So something like:
+### 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.
+
+#### 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)
 
-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"**.
+### Lazy custom element handler
 
-This would allow developers to create "stylesheet" like capabilities.
+```JavaScript
+// MyElement.js
+export default class MyElement extends HTMLElement {
+    connectedCallback() {
+        this.textContent = 'Hello!';
+    }
+}
 
-## Applying properties with assignGingerly
+// main.js
+import { MountObserver } from 'mount-observer';
 
-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 without writing custom mount callbacks:
+const observer = new MountObserver({
+    whereElementMatches: 'my-element',
+    import: './MyElement.js',
+    do: 'builtIns.defineCustomElement'
+});
+observer.observe(document);
+
+// HTML - elements will be upgraded when discovered
+// by the mount observer
+<my-element></my-element>
+
+```
+
+## 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 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'
@@ -359,7 +599,66 @@ 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)]
+[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
 
@@ -368,7 +667,7 @@ The `assignGingerly` library supports nested property assignment using the `?.`
 ```JavaScript
 const observer = new MountObserver({
    whereElementMatches: 'button',
-   assignGingerly: {
+   assignOnMount: {
       disabled: false,
       '?.dataset?.action': 'submit',
       '?.dataset?.trackingId': '12345',
@@ -385,13 +684,13 @@ The `?.` prefix tells assignGingerly to create nested properties if they don't e
 
 ### 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'
    },
@@ -408,7 +707,7 @@ 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
@@ -422,7 +721,7 @@ The `MountObserver` class provides a public `assignGingerly()` method that allow
 ```JavaScript
 const observer = new MountObserver({
    whereElementMatches: 'input',
-   assignGingerly: {
+   assignOnMount: {
       disabled: true,
       value: 'Initial value'
    }
@@ -590,7 +889,7 @@ mountedElemEmits: {
    event: 'CustomEvent',
    args: ['ready', { detail: {} }],
    eventProps: {
-      timestamp: Date.now(),
+      timestamp: Date.now(),  //TODO:  magic string?
       source: 'mount-observer',
       element: '{{mountedElement}}'
    }
@@ -663,6 +962,131 @@ 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
 
@@ -681,13 +1105,13 @@ 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"]',
@@ -697,23 +1121,7 @@ const observer = new MountObserver({
       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: ...
 });
 ```
 
@@ -746,7 +1154,7 @@ observer.addEventListener('confirm', e => {
 });
 observer.addEventListener('mount', e => {
   console.log({
-      matchingElement: e.matchingElement, 
+      mountedElement: e.mountedElement, 
       module: e.module
    });
 });
@@ -869,10 +1277,8 @@ const oContainerNode = document.getElementById('myTest');
 const observer = new MountObserver({
    whereElementMatches:'[itemprop]',
    whereOutside: '[itemscope]'
-   do: {
-      mount: ({localName}, {modules, observer}) => {
-        ...
-      },
+   do: ({localName}, {modules, observer}) => {
+      ...
    },
    disconnectedSignal: new AbortController().signal
 });
@@ -952,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'
@@ -1099,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,
@@ -1464,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:
@@ -1652,4 +1986,4 @@ To keep the api uniform, we hide this discrepancy by pretending the form element
    // includes both field1 and field2
    
 </script>
-```
+```