mount-observer 0.1.12 → 0.1.14

package/README.md

@@ -3,7 +3,6 @@
 [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/mount-observer?style=for-the-badge)](https://bundlephobia.com/result?p=mount-observer)
 <img src="http://img.badgesize.io/https://cdn.jsdelivr.net/npm/mount-observer?compression=gzip">
 
-Note that much of what is described below has not yet been polyfilled.
 
 ## Implementation Status
 
@@ -11,7 +10,11 @@ The following features have been implemented and tested:
 
 ### Core Functionality
 - ✅ **matching**: CSS selector-based element matching
+- ✅ **whenDefined**: Wait for custom elements to be defined before mounting
 - ✅ **whereInstanceOf**: Constructor-based element filtering (single or array)
+- ✅ **whereLocalNameMatches**: Regular expression-based localName filtering
+- ✅ **shouldMount**: Custom JavaScript check for complex mounting conditions
+- ✅ **Registry matching**: Automatic filtering by customElementRegistry (Chrome 146+)
 - ✅ **withMediaMatching**: Media query-based conditional mounting (string or MediaQueryList)
 - ✅ **whereObservedRootSizeMatches**: Container query-based conditional mounting (observes root element size)
 - ✅ **whereElementIntersectsWith**: Intersection observer-based conditional mounting (observes element visibility)
@@ -29,6 +32,7 @@ The following features have been implemented and tested:
 - ✅ **assignOnDismount**: Property assignment when elements dismount
 - ✅ **stageOnMount**: Reversible property assignment (auto-restores on dismount)
 - ✅ **do callbacks**: Mount/dismount/disconnect/reconnect lifecycle hooks
+- ✅ **with property**: Hierarchical observer composition with sub-observers
 - ✅ **Element mount extension**: element.mount() method for scoped registry observation
 - ✅ **Shared MutationObserver**: Efficient observer sharing across instances
 - ✅ **Code splitting**: Conditional features loaded on-demand
@@ -80,7 +84,9 @@ There is quite a bit of functionality this proposal would open up that is exceed
 
 3. Knowing when an element previously being monitored passes totally "out-of-scope" so that no more hard references to the element remain. This would allow for cleanup of no longer needed weak references without requiring polling.
 
-4. Some CSS selectors, such as the [scope donut hole range](https://css-tricks.com/solved-by-css-donuts-scopes/#aa-donut-scoping-with-scope), aren't supported by oEl.querySelectorAll(...) or oEl.matches(...).
+4. Some CSS selectors, such as the [donut hole scope range](https://css-tricks.com/solved-by-css-donuts-scopes/#aa-donut-scoping-with-scope), aren't supported by oEl.querySelectorAll(...) or oEl.matches(...).
+
+5. Scoped custom element registries form natural "islands" of DOM that have many commonalities with css "donut hole scoping", and which mutation observers aren't really designed around.  The mount-observer is designed to work with scoped custom element registries as first-class citizens. Learn more about [scoped custom element registries](https://developer.chrome.com/blog/scoped-registries). 
 
 
 ###  Most significant use cases
@@ -98,7 +104,7 @@ The extra flexibility this new primitive would provide could be quite useful to
 
 ## Quick Examples of the Most Common Use Cases
 
-Before getting into the weeds, let's demonstrate the two most prominent use cases:
+Before getting into the weeds, let's demonstrate a few of the most prominent use cases:
 
 ### Use Case 1:  Custom Attribute Enhancement
 
@@ -107,7 +113,7 @@ Before getting into the weeds, let's demonstrate the two most prominent use case
     <div log-to-console="clicked on a div">hello</div>
 
     <script type=module>
-        document.body.mount({
+        document.mount({
             matching: '[log-to-console]',
             do: (el) => {
                 el.addEventListener('click', e => {
@@ -166,7 +172,7 @@ element.mount({
 
 ## Enhancing Elements with assign-gingerly
 
-The `builtIns.enhanceMountedElement` handler automatically enhances mounted elements using the [assign-gingerly](https://www.npmjs.com/package/assign-gingerly) enhancement system. This allows you to attach behavior and state to elements without subclassing.
+The `builtIns.enhanceMountedElement` handler automatically enhances mounted elements using the [assign-gingerly](https://www.npmjs.com/package/assign-gingerly) enhancement system. This allows us to attach behavior and state to elements without subclassing.
 
 ```JavaScript
 // MyEnhancement.js
@@ -188,6 +194,8 @@ export default {
     enhKey: 'buttonEnh'
 };
 
+// main.js
+
 document.mount({
     matching: '.enhance-me',
     import: './MyEnhancement.js',
@@ -205,251 +213,1604 @@ console.log(button.enh.buttonEnh.clickCount); // 1
 ```
 
 The handler:
-1. Searches the imported module for an export with a `spawn` property (the enhancement class)
+1. Searches the imported module for an export with a `spawn` property (the enhancement class), starting with default.
 2. Calls `element.enh.get(registryItem, context)` to spawn the enhancement
 3. Stores the enhancement instance on `element.enh[enhKey]` if an `enhKey` is provided
 
-This works with browsers that don't support scoped custom element registries by polyfilling the `customElementRegistry` property on elements.
 
+## Exposing Module Exports from Script Elements
 
-# Thorough Exposition Begins Here
+The `builtIns.scriptExport` handler solves a long-standing limitation: accessing ES module exports from script elements. It also provides a clean way to import JSON and other data formats declaratively.
 
-Okay, let's get into the weeds.  First, we strongly recommend studying the core package that mount-observer extends, [assign-gingerly](https://www.npmjs.com/package/assign-gingerly).
+### Problem 1: ES Module Export Access
 
-## First use case -- lazy loading custom elements without sugar coating
+The browser doesn't expose module exports from `<script type="module">` elements. There's been a [decade-old proposal](https://github.com/whatwg/html/issues/1013) to add this, but it remains unimplemented.
 
-This registers the custom element in the global registry.
+**The Solution:**
 
-```JavaScript
-const observer = new MountObserver({
-   select:'my-element', //not supported by this polyfill
-   import: './my-element.js',
-   do: ({localName}, {modules, observer, MountConfig, rootNode}) => {
-      if(!customElements.get(localName)) {
-         customElements.define(localName, modules[0].MyElement);
-      }
-      observer.disconnectedSignal.abort();
-   }
-   
-}, {disconnectedSignal: new AbortController().signal});
-observer.observe(document);
+```html
+<!-- Use nomodule to prevent browser from loading it separately -->
+<script nomodule src="./config.js" id="myConfig"></script>
+
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    const observer = new MountObserver({
+        do: 'builtIns.scriptExport'
+    });
+    observer.observe(document);
+    
+    // Access the module's exports via element.export
+    const config = document.getElementById('myConfig').export;
+    console.log(config.apiKey);
+    console.log(config.endpoints);
+</script>
 ```
 
-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.
+**Why `nomodule`?**
+- Prevents the browser from loading the module separately
+- Avoids having the module loaded twice in memory
+- The handler imports it once and exposes exports via `element.export`
 
-The constructor argument can also be an array of objects that fit the pattern shown above.
+### Problem 2: Declarative JSON Import
 
-In fact, as we will see, where it makes sense, where we see examples that are strings, we will also allow for arrays of such strings.  For example, the "select" key can point to an array of CSS selectors (and in this case the mount/dismount callbacks would need to provide an index of which one matched).  I only recommend adding this complexity if what I suspect is true -- providing this support can reduce "context switching" between threads / memory spaces (c++ vs JavaScript), and thus improve performance.  If multiple "on" selectors are provided, and multiple ones match, I think it makes sense to indicate the one with the highest specifier that matches.  It would probably be helpful in this case to provide a special event that allows for knowing when the matching selector with the highest specificity changes for mounted elements.
+Importing JSON typically requires `fetch()` or dynamic `import()` with assertions. This handler provides a declarative alternative.
 
-If no imports are specified, it would go straight to do (if any such callbacks are specified), and it will also dispatch events as discussed below.
+**The Solution:**
 
-This only searches for elements matching 'my-element' outside any shadow DOM.
+```html
+<!-- Load JSON data -->
+<script src="./data.json" type="json" id="myData"></script>
 
-But the observe method can accept a node within the document, or a shadowRoot, or a node inside a shadowRoot as well.
+<!-- Also supports full MIME types -->
+<script src="./config.json" type="application/json" id="config"></script>
+<script src="./linked-data.json" type="application/ld+json" id="linkedData"></script>
 
-The "observer" constant above is a class instance that inherits from EventTarget, which means it can be subscribed to by outside interests.
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    const observer = new MountObserver({
+        do: 'builtIns.scriptExport'
+    });
+    observer.observe(document);
+    
+    // Access the JSON data via element.export.default
+    const data = document.getElementById('myData').export.default;
+    console.log(data.items);
+    console.log(data.config);
+</script>
+```
 
-> [!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.
+<details>
+   <summary>Talking points</summary>
 
-In fact, I have encountered statements made by the browser vendors that some queries supported by css can't be evaluated simply by looking at the layout of the HTML, but have to be made after rendering and performing style calculations.  This necessitates having to delay the notification, which would be unacceptable in some circumstances.
+**Why no `nomodule` for JSON?**
+- The browser ignores script elements with non-standard type attributes
+- No risk of double-loading since the browser won't load it at all
+- The handler imports it with the appropriate JSON assertion
+
+**Supported JSON types:**
+- `type="json"` - Simple and clean
+- `type="application/json"` - Standard MIME type
+- `type="application/ld+json"` - JSON-LD linked data
+- Any type containing "json" triggers JSON import assertion
+
+**How it works:**
+1. Matches `script[src]` elements (via static properties)
+2. Skips `type="module"` scripts (browser-handled)
+3. Processes scripts with `nomodule` attribute OR type containing "json"
+4. Resolves the `src` relative to the document
+5. Imports with appropriate assertion (JSON if type contains "json")
+6. Stores the imported module on `element.export`
+7. Dispatches a `resolved` event with the imported module
+
+**Reusing imported modules:**
+
+The handler stores the imported module on the script element's `export` property and dispatches a `resolved` event. This allows other code to access the module without re-importing:
+
+```html
+<script src="./data.json" type="json" id="myData"></script>
+
+<script type="module">
+    const dataScript = document.getElementById('myData');
+    
+    // Listen for the resolved event
+    dataScript.addEventListener('resolved', (e) => {
+        console.log('Data loaded:', e.export);
+        // e.export contains the imported module
+        // For JSON: e.export.default contains the data
+    });
+    
+    // Or access directly after processing
+    // dataScript.export will contain the imported module
+</script>
+```
+
+This is particularly useful when multiple components need to access the same data or configuration without triggering multiple imports.
+
+**Benefits:**
+- Access ES module exports from script elements (finally!)
+- Declarative JSON loading without fetch
+- Prevents double-loading of modules
+- Clean, intuitive syntax
+- Works with relative and absolute URLs
+- No need to specify `matching` or `whereInstanceOf` (handler provides defaults)
+
+**Use cases:**
+- Accessing configuration module exports in HTML
+- Loading JSON data declaratively
+- Progressive enhancement with module loading
+- Declarative dependency management
+- Loading JSON-LD structured data
+
+</details>
+
+## Mount Observer Script Elements (MOSEs)
+
+Inspired by the [speculation rules api](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API) `builtIns.mountObserverScript` handler enables fully declarative mount observer configuration using `<script type="mountobserver">` elements. This provides the ultimate in HTML-first progressive enhancement.
+
+```html
+<!-- Inline JSON configuration -->
+<script type="mountobserver">
+{
+    "matching": "my-fancy-button",
+    "import": "./fancy-button.js",
+    "do": "builtIns.defineCustomElement"
+}
+</script>
+
+<!-- External JSON configuration -->
+<script type="mountobserver" src="./observer-config.json"></script>
+
+<!-- Bootstrap the handler -->
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    // Handler provides matching and whereInstanceOf via static properties
+    const observer = new MountObserver({
+        do: 'builtIns.mountObserverScript'
+    });
+    observer.observe(document);
+</script>
+```
+
+<details>
+<summary>Talking points</summary>
+
+**How it works:**
+1. The handler matches `script[type="mountobserver"]` elements (via static properties)
+2. If the script has a `src` attribute, imports JSON from that URL
+3. Otherwise, parses the script's textContent as JSON
+4. Supports both single config objects and arrays of configs
+5. Stores the parsed config on `scriptElement.export` for reuse
+6. Dispatches a `resolved` event with the parsed config
+7. Calls `scriptElement.mount(config)` for each configuration
+8. The `mount()` method creates a MountObserver for that configuration
+
+**Reusing parsed configurations:**
+
+The handler optimizes performance by storing the parsed configuration on the script element's `export` property and dispatching a `resolved` event. When the same script element is observed again (e.g., after being cloned or moved), the handler reuses the existing `export` instead of re-parsing:
+
+```html
+<script type="mountobserver" id="myConfig">
+{
+    "matching": ".my-element",
+    "do": "builtIns.logToConsole"
+}
+</script>
+
+<script type="module">
+    const configScript = document.getElementById('myConfig');
+    
+    // Listen for the resolved event (fires only once on first parse)
+    configScript.addEventListener('resolved', (e) => {
+        console.log('Config loaded:', e.export);
+        // e.export contains the parsed configuration
+    });
+    
+    // Or access directly after processing
+    // configScript.export will contain the parsed config
+    
+    // If observed again, the handler will reuse configScript.export
+    // without re-parsing or firing the resolved event
+</script>
+```
+
+This is particularly useful when inheriting mount observer configurations across shadow DOM boundaries, as the parsed config can be reused without re-parsing JSON. The `resolved` event fires only once (on first parse), but the handler will still process the configuration on subsequent observations.
+
+**Multiple configs in one script:**
+
+You can define multiple mount observer configurations in a single script element using a JSON array:
+
+```html
+<script type="mountobserver">
+[
+    {
+        "do": "builtIns.hoistTemplate"
+    },
+    {
+        "do": "builtIns.HTMLInclude"
+    },
+    {
+        "matching": "my-button",
+        "import": "./my-button.js",
+        "do": "builtIns.defineCustomElement"
+    }
+]
+</script>
+```
+
+This is equivalent to having three separate `<script type="mountobserver">` elements, but more concise. Each config in the array is processed independently and creates its own MountObserver.
+
+**Benefits:**
+- Zero JavaScript required for observer configuration
+- Configurations are pure JSON (fully serializable)
+- Easy to generate server-side or from build tools
+- Supports both inline and external configurations
+- Leverages the `element.mount()` API for automatic scope management
+- No need to specify `matching` or `whereInstanceOf` for the handler itself
+
+**Use cases:**
+- Server-side rendering with progressive enhancement
+- Build-time generation of observer configurations
+- CMS-driven component loading
+- Declarative micro-frontend architecture
+- Configuration management without JavaScript bundling
+
+**Example with multiple configurations:**
+```html
+<!-- Load custom elements -->
+<script type="mountobserver">
+{
+    "matching": "my-button",
+    "import": "./components/my-button.js",
+    "do": "builtIns.defineCustomElement"
+}
+</script>
+
+<!-- Enhance existing elements -->
+<script type="mountobserver">
+{
+    "matching": ".interactive",
+    "import": "./enhancements/interactive.js",
+    "do": "builtIns.enhanceMountedElement"
+}
+</script>
+
+<!-- Single bootstrap script activates all configurations -->
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    new MountObserver({
+        do: 'builtIns.mountObserverScript'
+    }).observe(document);
+</script>
+```
+
+</details>
+
+## Hoisting Templates for Performance
+
+The `builtIns.hoistTemplate` handler optimizes template usage by moving a template element's content from shadow roots to `document.head`. 
+
+**Why hoist templates?**
+
+Template hoisting is particularly useful when you need to share conditional or repeated templates across multiple custom element instances.
+
+When HTML-first custom elements repeat throughout a page, each instance typically contains its own copy of template content. Moving these templates to a centralized location:
+- Reduces memory usage (one template instead of many copies)
+- Improves cloning performance (single source of truth)
+- Maintains the same API through the `remoteContent` getter
+
+**Basic usage:**
+
+```html
+<my-web-component>
+    #shadow
+        <template id="my-template">
+            <div>My content</div>
+        </template>
+</my-web-component>
+
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    const observer = new MountObserver({
+        do: 'builtIns.hoistTemplate'
+    });
+    observer.observe(document);
+</script>
+```
+
+**What happens:**
+1. The handler finds templates with IDs in shadow roots
+2. Moves the template content to a new template in `<head>`
+3. Updates the original template with `src="#mount-observer-0"` (unique ID)
+4. Defines a `remoteContent` getter that returns the hoisted template's content
+
+**Accessing hoisted content:**
+
+```javascript
+const template = shadowRoot.querySelector('#my-template');
+
+// After hoisting, use remoteContent to access the content
+const content = template.remoteContent;  // Returns DocumentFragment
+const clone = content.cloneNode(true);   // Clone the content
+```
+<details>
+   <summary>Matching criteria
+
+The handler automatically hoists templates that:
+- Have an `id` attribute
+- Don't already have a `src` attribute
+- Are in a shadow root (or disconnected, being cloned)
+- Have content (empty templates are skipped)
+
+**Declarative usage with MOSE:**
+
+```html
+<script type="mountobserver">
+{
+    "do": "builtIns.hoistTemplate"
+}
+</script>
+
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    new MountObserver({
+        do: 'builtIns.mountObserverScript'
+    }).observe(document);
+</script>
+```
+
+[Implemented as HoistingTemplates requirement](requirements/Done/HoistingTemplates.md)
+
+</details>
+
+## Intra-Document HTML Includes with HTMLInclude
+
+The `builtIns.HTMLInclude` handler enables declarative HTML fragment reuse within a document using `<template src="#id">` syntax. Think of it as "constants for HTML" - define content once with an ID, then reference it multiple times throughout your document.
+
+**Why use HTML includes?**
+
+- Reduces duplication of repeated HTML structures
+- Enables template-based content generation
+- Supports partial updates via matching insertions
+- Works across shadow DOM boundaries
+- Supports declarative shadow DOM attachment
+- Caches lookups for performance
+- Detects circular references automatically
+- Can be used to inherit from MOSEs
+
+**Basic usage - Simple cloning:**
+
+```html
+<!-- Define reusable content -->
+<div id="reusable">
+    <p>This content can be reused</p>
+    <button>Click me</button>
+</div>
+
+<!-- Reference it with a template -->
+<template src="#reusable"></template>
+
+<!-- Results in: -->
+<div>
+    <p>This content can be reused</p>
+    <button>Click me</button>
+</div>
+
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    const observer = new MountObserver({
+        do: 'builtIns.HTMLInclude'
+    });
+    observer.observe(document);
+</script>
+```
+
+<details>
+   <summary>More discussion
+
+**What happens:**
+1. The handler finds templates with `src` attributes starting with `#`
+2. Searches for an element with that ID (across shadow boundaries)
+3. Clones the content from the source element
+4. Replaces the template with the cloned content
+5. Removes the `id` attribute from cloned elements to avoid duplicate IDs
+
+**Cloning priority:**
+1. `remoteContent` property (hoisted templates) - highest priority
+2. `content` property (regular templates)
+3. The element itself (any element with an ID)
+
+**Works with hoisted templates:**
+
+```html
+<my-web-component>
+    #shadow
+        <template id="my-template">
+            <div>Hoisted content</div>
+        </template>
+</my-web-component>
+
+<!-- After hoisting, this still works -->
+<template src="#my-template"></template>
+
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    // First hoist templates
+    new MountObserver({
+        do: 'builtIns.hoistTemplate'
+    }).observe(document);
+    
+    // Then use them
+    new MountObserver({
+        do: 'builtIns.HTMLInclude'
+    }).observe(document);
+</script>
+```
+
+</details>
+
+### Shadow DOM Support
+
+The HTMLInclude handler supports declarative shadow DOM attachment using the `shadowrootmodeonload` attribute. This allows you to attach cloned content directly to a parent element's shadow root, similar to the platform's [declarative shadow DOM](https://web.dev/articles/declarative-shadow-dom) feature.
+
+**Basic shadow DOM usage:**
+
+```html
+<!-- Define reusable shadow content -->
+<template id="shadow-content">
+    <style>
+        :host {
+            display: block;
+            padding: 10px;
+        }
+        .shadow-text {
+            color: blue;
+        }
+    </style>
+    <div class="shadow-text">
+        <slot name="greeting"></slot>
+        <slot></slot>
+    </div>
+</template>
+
+<!-- Attach to shadow root -->
+<div class="host-element">
+    <template src="#shadow-content" shadowrootmodeonload="open"></template>
+    <span slot="greeting">Hello</span>
+    <span>World!</span>
+</div>
+
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    new MountObserver({
+        do: 'builtIns.HTMLInclude'
+    }).observe(document);
+</script>
+```
+
+**What happens:**
+1. The handler checks for the `shadowrootmodeonload` attribute (case-insensitive)
+2. If present, it attaches the cloned content to the parent element's shadow root
+3. If the parent doesn't have a shadow root, one is created with the specified mode
+4. If a shadow root already exists, the content is appended to it
+5. The template is removed as usual
+
+**Shadow root modes:**
+- `open` - Shadow root is accessible via `element.shadowRoot`
+- `closed` - Shadow root is not accessible from outside
+
+**Slots work automatically:**
+
+The native browser slot mechanism handles content distribution. Light DOM elements with `slot` attributes are automatically projected into the corresponding `<slot>` elements in the shadow DOM.
+
+**Example - Complex nested structure:**
+
+```html
+<template id="chorus">
+    <template src="#beautiful">
+        <span slot="subjectIs">
+            <slot name="subjectIs1"></slot>
+        </span>
+    </template>
+    <div>No matter what they say</div>
+    <div>Words <slot name="verb1"></slot> bring <slot name="pronoun1"></slot> down</div>
+</template>
+
+<div class="chorus">
+    <template src="#chorus" shadowrootmodeonload="open"></template>
+    <span slot="verb1">can't</span>
+    <span slot="pronoun1">me</span>
+    <span slot="subjectIs1">I am</span>
+</div>
+```
+
+**Nested templates in shadow DOM:**
+
+Templates inside shadow roots are not automatically processed by the parent observer. To process nested templates, you need to observe the shadow root separately:
+
+```javascript
+const host = document.querySelector('.host-element');
+if (host.shadowRoot) {
+    const shadowObserver = new MountObserver({
+        do: 'builtIns.HTMLInclude'
+    });
+    await shadowObserver.observe(host.shadowRoot);
+}
+```
+
+**Error handling:**
+
+- Invalid mode values: Logs warning if mode is not `"open"` or `"closed"`
+- Missing parent: Logs warning if template has no parent element
+- Attachment failures: Logs error if shadow root cannot be attached
+
+### Matching Insertions - Partial Updates
+
+When a template has children, they are used to match elements in the cloned content and selectively update them. This enables partial modifications and "nulling out" content without duplicating the entire structure.
+
+**How it works:**
+1. Template children generate CSS selectors (tag, classes, attributes)
+2. Matching elements in the cloned content are found
+3. Matched elements have their children replaced and attributes updated
+4. The `-i` attribute specifies which attributes to update
+
+**Example - Updating attributes:**
+
+```html
+<!-- Source content -->
+<div itemscope id="love">
+    <data value="false" itemprop="todayIsFriday">It's Thursday</data>
+</div>
+
+<!-- Template with matching insertion -->
+<template src="#love">
+    <data value="true" itemprop="todayIsFriday" -i="value"></data>
+</template>
+
+<!-- Results in: -->
+<div itemscope>
+    <data value="true" itemprop="todayIsFriday">It's Thursday</data>
+</div>
+<!-- The value attribute is updated, but content stays "It's Thursday" -->
+```
+
+**The `-i` attribute:**
+
+The `-i` (insert) attribute is a space-separated list of attribute names to update on matched elements. Attributes listed in `-i` are:
+- Excluded from the CSS selector (allows matching elements with different values)
+- Updated on matched elements with values from the template child
+
+```html
+<template src="#form">
+    <!-- Update both value and placeholder -->
+    <input type="text" name="username" value="new" placeholder="Updated" -i="value placeholder">
+</template>
+```
+
+**Example - Replacing content:**
+
+```html
+<!-- Source -->
+<div id="greeting">
+    <p class="message">Hello</p>
+</div>
+
+<!-- Template replaces content -->
+<template src="#greeting">
+    <p class="message">Goodbye</p>
+</template>
+
+<!-- Results in: -->
+<div>
+    <p class="message">Goodbye</p>
+</div>
+```
+
+**Example - Multiple matching elements:**
+
+```html
+<!-- Source with multiple items -->
+<div id="list">
+    <span class="item">Item 1</span>
+    <span class="item">Item 2</span>
+    <span class="item">Item 3</span>
+</div>
+
+<!-- Update all matching items -->
+<template src="#list">
+    <span class="item">Updated</span>
+</template>
+
+<!-- Results in: -->
+<div>
+    <span class="item">Updated</span>
+    <span class="item">Updated</span>
+    <span class="item">Updated</span>
+</div>
+```
+
+**Example - Nulling out content:**
+
+```html
+<!-- Source -->
+<div id="status">
+    <span data-active="false" class="indicator">Inactive</span>
+</div>
+
+<!-- Update attribute, remove content -->
+<template src="#status">
+    <span data-active="true" class="indicator" -i="data-active"></span>
+</template>
+
+<!-- Results in: -->
+<div>
+    <span data-active="true" class="indicator"></span>
+</div>
+<!-- Content is removed, attribute is updated -->
+```
+
+### Use Case: Inheriting Groups of Mount-Observers
+
+Matching insertions become particularly powerful when combined with Mount Observer Script Elements (MOSEs) for inheriting and customizing groups of mount-observers across shadow DOM boundaries.
+
+**Scenario:** You have a base component with a set of mount-observers defined in its shadow root, and you want to reuse those observers in other components while making targeted modifications.
+
+```html
+<!-- Base component with mount-observers -->
+<template id="base-observers">
+    <script type="mountobserver">
+    {
+        "matching": "button.primary",
+        "import": "./primary-button.js",
+        "do": "builtIns.defineCustomElement"
+    }
+    </script>
+    
+    <script type="mountobserver">
+    {
+        "matching": ".interactive",
+        "import": "./interactive.js",
+        "do": "builtIns.enhanceMountedElement"
+    }
+    </script>
+    
+    <script type="mountobserver">
+    {
+        "matching": "form",
+        "import": "./form-validator.js",
+        "do": "builtIns.enhanceMountedElement"
+    }
+    </script>
+</template>
+
+<!-- Derived component - inherit and customize -->
+<my-derived-component>
+    #shadow
+        <!-- Include base observers -->
+        <template src="#base-observers">
+            <!-- Override the form validator with a different one -->
+            <script type="mountobserver">
+            {
+                "matching": "form",
+                "import": "./custom-form-validator.js",
+                "do": "builtIns.enhanceMountedElement"
+            }
+            </script>
+        </template>
+        
+        <!-- Component content -->
+        <form>...</form>
+        <button class="primary">Submit</button>
+</my-derived-component>
+
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    // Bootstrap HTMLInclude handler
+    new MountObserver({
+        do: 'builtIns.HTMLInclude'
+    }).observe(document);
+    
+    // Bootstrap MOSE handler to activate the observers
+    new MountObserver({
+        do: 'builtIns.mountObserverScript'
+    }).observe(document);
+</script>
+```
+
+**What happens:**
+1. The `<template src="#base-observers">` clones all three MOSE scripts
+2. The matching insertion finds the form validator script (matching by `matching` attribute)
+3. Replaces its content with the custom validator configuration
+4. All three scripts are inserted into the shadow root
+5. The MOSE handler activates all observers in the shadow root's registry scope
+
+**Benefits:**
+- **Composition**: Build complex observer configurations from reusable pieces
+- **Inheritance**: Derive new components with modified observer behavior
+- **Scoped registries**: Each shadow root gets its own set of observers
+- **Declarative**: No JavaScript required for observer inheritance
+- **Maintainable**: Update base observers in one place, changes propagate
+
+**Advanced pattern - Multiple inheritance:**
+
+```html
+<!-- Base UI observers -->
+<template id="ui-observers">
+    <script type="mountobserver">{"matching": "button", ...}</script>
+    <script type="mountobserver">{"matching": "input", ...}</script>
+</template>
+
+<!-- Base data observers -->
+<template id="data-observers">
+    <script type="mountobserver">{"matching": "[itemscope]", ...}</script>
+</template>
+
+<!-- Component combines both -->
+<my-component>
+    #shadow
+        <template src="#ui-observers"></template>
+        <template src="#data-observers"></template>
+        
+        <!-- Add component-specific observers -->
+        <script type="mountobserver">
+        {
+            "matching": ".special",
+            "import": "./special.js",
+            "do": "builtIns.enhanceMountedElement"
+        }
+        </script>
+</my-component>
+```
+
+This pattern enables:
+- **Mixins**: Combine multiple observer groups
+- **Layering**: Stack observers from different concerns (UI, data, behavior)
+- **Customization**: Override specific observers while keeping others
+- **Reusability**: Share observer configurations across components
+
+**Declarative usage with MOSE:**
+
+```html
+<script type="mountobserver">
+{
+    "do": "builtIns.HTMLInclude"
+}
+</script>
+
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    new MountObserver({
+        do: 'builtIns.mountObserverScript'
+    }).observe(document);
+</script>
+```
+
+**Error handling:**
+
+The handler provides helpful error messages:
+- Missing elements: `data-include-error="Element with id='foo' not found"`
+- Circular references: `data-include-error="Circular reference detected: #foo"`
+- Clone failures: `data-include-error="Unable to clone content from #foo"`
+
+**Performance:**
+
+- Uses WeakMap caching for repeated ID lookups
+- Efficient for scenarios like periodic tables with many repeated elements
+- Searches across shadow boundaries using `upShadowSearch` (registry-aware)
+- Respects scoped custom element registry boundaries
+- Cleans up cache entries when elements are garbage collected
+
+**MOSE Export Optimization:**
+
+When cloning live DOM elements (not templates) that contain Mount Observer Script Elements (MOSEs) across shadow DOM boundaries, the HTMLInclude handler automatically copies the parsed `export` property from source scripts to cloned scripts. This optimization avoids re-parsing JSON when the same MOSE configuration is reused in multiple shadow roots.
+
+**How it works:**
+1. Detects when cloning a live element (not a template) from a different root node
+2. Finds all `script[type="mountobserver"]` elements in both source and clone
+3. Matches scripts by their `id` attribute
+4. Copies the `export` property from source to clone (by reference)
+5. If source script hasn't been processed yet, waits for the `resolved` event
+
+**Example:**
+
+```html
+<!-- Source element with MOSE in light DOM -->
+<div id="observer-config">
+    <script type="mountobserver" id="my-config">
+    {
+        "matching": ".interactive",
+        "import": "./interactive.js",
+        "do": "builtIns.enhanceMountedElement"
+    }
+    </script>
+    <div class="interactive">Content</div>
+</div>
+
+<!-- Clone into shadow DOM -->
+<my-component>
+    #shadow
+        <template src="#observer-config"></template>
+</my-component>
+
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    // Process MOSEs in light DOM
+    new MountObserver({
+        do: 'builtIns.mountObserverScript'
+    }).observe(document.body);
+    
+    // Clone into shadow roots
+    new MountObserver({
+        do: 'builtIns.HTMLInclude'
+    }).observe(document);
+</script>
+```
+
+**Benefits:**
+- **Performance**: JSON is parsed only once, not for each clone
+- **Memory efficiency**: Cloned scripts share the same export object
+- **Consistency**: All clones use identical configuration
+- **Automatic**: No manual intervention required
+
+**Requirements:**
+- Source and clone must be in different root nodes (document vs shadow root)
+- MOSE scripts must have `id` attributes for matching
+- Source script must be processed by `builtIns.mountObserverScript` or `builtIns.scriptExport` before cloning
+
+[Implemented as MatchingInsertionsAndDeletionsWithIntraDocumentHTMLIncludes requirement](requirements/Done/MatchingInsertionsAndDeletionsWithIntraDocumentHTMLIncludes.md)
+
+## Automatic ID Generation with genIds
+
+The `builtIns.generateIds` handler automatically generates unique IDs for elements within scoped containers using the [id-generation](https://www.npmjs.com/package/id-generation) package. This is particularly useful for forms, microdata structures, and any scenario where you need unique IDs for accessibility or linking purposes.
+
+**Why use automatic ID generation?**
+
+- Eliminates manual ID management and conflicts
+- Supports scoped ID generation within fieldsets or itemscope containers
+- Automatically updates ID references in attributes (aria-labelledby, for, etc.)
+- Provides shorthand syntax for common patterns
+- Handles deferred attribute activation
+- Removes `disabled` from fieldsets after processing
+
+**Basic usage:**
+
+```html
+<fieldset disabled>
+    <label>
+        LHS: <input data-id={{lhs}}>
+    </label>
+    
+    <label for=rhs>
+        RHS: <input data-id={{rhs}}>
+    </label>
+    
+    <template -id defer-🎚️ 🎚️='on if isEqual, based on #{{lhs}} and #{{rhs}}.'>
+        <div>LHS === RHS</div>
+    </template>
+</fieldset>
+
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    const observer = new MountObserver({
+        do: 'builtIns.generateIds'
+    });
+    observer.observe(document);
+</script>
+```
+
+**What happens:**
+
+1. The handler watches for elements with the `-id` attribute (the trigger)
+2. Finds the nearest scope container (fieldset, [itemscope], or root)
+3. Generates unique IDs for elements with `data-id={{name}}`, `#`, `@`, or `|` attributes
+4. Replaces `#{{name}}` references with generated IDs in attributes
+5. Removes `-id` and `defer-*` attributes after processing
+6. Removes `disabled` from fieldset containers
+
+**Result:**
+
+```html
+<fieldset>
+    <label>
+        LHS: <input id=gid-0 data-id=lhs>
+    </label>
+    
+    <label for=rhs>
+        RHS: <input id=gid-1 data-id=rhs>
+    </label>
+    
+    <template 🎚️='on if isEqual, based on #gid-0 and #gid-1.'>
+        <div>LHS === RHS</div>
+    </template>
+</fieldset>
+```
+
+**Shorthand attributes:**
+
+```html
+<fieldset disabled>
+    <!-- # uses element's tag name -->
+    <my-element #></my-element>  <!-- becomes id=gid-0 data-id=my-element -->
+    
+    <!-- @ uses element's name attribute -->
+    <input @ name="email" type="email">  <!-- becomes id=gid-1 data-id=email -->
+    
+    <!-- | uses element's itemprop attribute -->
+    <span | itemprop="price">$99</span>  <!-- becomes id=gid-2 data-id=price -->
+    
+    <button -id>Generate IDs</button>
+</fieldset>
+```
+
+**Side effects with data-id:**
+
+The `data-id` attribute supports special symbols that trigger side effects:
+
+```html
+<form>
+    <fieldset disabled>
+        <label>
+            LHS: <input data-id="{{@. lhs}}">
+        </label>
+        
+        <label for=rhs>
+            RHS: <span contenteditable data-id="{{|.% rhs}}">
+        </label>
+        
+        <template -id defer-🎚️ 🎚️='on if isEqual, based on #{{lhs}} and #{{rhs}}.'>
+            <div>LHS === RHS</div>
+        </template>
+    </fieldset>
+</form>
+```
+
+**Result:**
+
+```html
+<form>
+    <fieldset>
+        <label>
+            LHS: <input name=lhs class=lhs id=gid-0 data-id=lhs>
+        </label>
+        
+        <label for=rhs>
+            RHS: <span contenteditable itemprop=rhs class=rhs part=rhs id=gid-1 data-id=rhs>
+        </label>
+        
+        <template 🎚️='on if isEqual, based on #gid-0 and #gid-1.'>
+            <div>LHS === RHS</div>
+        </template>
+    </fieldset>
+</form>
+```
+
+**Symbol meanings:**
+
+| Symbol | Attribute         | Meaning                                                                      |
+|--------|-------------------|------------------------------------------------------------------------------|
+| @      | name              | Second letter of name, common in social media for selecting names            |
+| \|     | itemprop          | "Pipe" resembles itemprop, half of dollar sign, looks like an I              |
+| $      | itemscope+itemprop| Combination of S for Scope and Pipe                                          |
+| %      | part              | Starts with p, percent indicates proportion                                  |
+| .      | class             | CSS selector                                                                 |
+
+Multiple symbols can be combined: `data-id="{{@.% myName}}"` adds name, class, and part attributes.
+
+**Deferred attributes:**
+
+Use `defer-*` prefix to prevent attributes from being applied until IDs are generated:
+
+```html
+<fieldset disabled>
+    <!-- These attributes won't work until IDs are generated -->
+    <label defer-for="for: #{{email}}">Email:</label>
+    <input data-id={{email}} type="email">
+    
+    <button -id>Activate Form</button>
+</fieldset>
+```
+
+**Supported reference attributes:**
+
+The handler automatically replaces `#{{name}}` references in these attributes:
+- ARIA: `aria-labelledby`, `aria-describedby`, `aria-controls`, `aria-owns`, `aria-flowto`, `aria-activedescendant`
+- Form: `for`, `form`, `list`
+- Microdata: `itemref`
+- Any `data-*` attribute
+- Any attribute with a `defer-*` prefix
+
+**Declarative usage with MOSE:**
+
+```html
+<script type="mountobserver">
+{
+    "do": "builtIns.generateIds"
+}
+</script>
+
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    new MountObserver({
+        do: 'builtIns.mountObserverScript'
+    }).observe(document);
+</script>
+```
+
+**Scope containers:**
+
+The handler looks for the nearest scope container using `.closest()`:
+- `<fieldset>` elements
+- Elements with `[itemscope]` attribute
+- Falls back to the root node if no scope is found
+
+**Global counter:**
+
+IDs are generated using a global counter (via `Symbol.for`) to ensure uniqueness across multiple module instances. Generated IDs follow the pattern `gid-0`, `gid-1`, `gid-2`, etc.
+
+
+# Thorough Exposition Begins Here
+
+Okay, let's get into the weeds.  First, we strongly recommend studying the core package that mount-observer extends, [assign-gingerly](https://www.npmjs.com/package/assign-gingerly).
+
+## First use case -- lazy loading custom elements without sugar coating
+
+This registers the custom element in the global registry.
+
+```JavaScript
+const observer = new MountObserver({
+   select:'my-element', //not supported by this polyfill
+   import: './my-element.js',
+   do: ({localName}, {modules, observer, MountConfig, rootNode}) => {
+      if(!customElements.get(localName)) {
+         customElements.define(localName, modules[0].MyElement);
+      }
+      observer.disconnectedSignal.abort();
+   }
+   
+}, {disconnectedSignal: new AbortController().signal});
+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, will continue to be called repeatedly.
+
+The constructor argument can also be an array of objects that fit the pattern shown above.
+
+In fact, as we will see, where it makes sense, where we see examples that are strings, we will also allow for arrays of such strings.  For example, the "select" key can point to an array of CSS selectors (and in this case the mount/dismount callbacks would need to provide an index of which one matched).  I only recommend adding this complexity if what I suspect is true -- providing this support can reduce "context switching" between threads / memory spaces (c++ vs JavaScript), and thus improve performance.  If multiple "on" selectors are provided, and multiple ones match, I think it makes sense to indicate the one with the highest specifier that matches.  It would probably be helpful in this case to provide a special event that allows for knowing when the matching selector with the highest specificity changes for mounted elements.
+
+If no imports are specified, it would go straight to do (if any such callbacks are specified), and it will also dispatch events as discussed below.
+
+This only searches for elements matching 'my-element' outside any shadow DOM.
+
+But the observe method can accept a node within the document, or a shadowRoot, or a node inside a shadowRoot as well.
+
+The "observer" constant above is a class instance that inherits from EventTarget, which means it can be subscribed to by outside interests.
+
+> [!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 have to be made after rendering and performing style calculations.  This necessitates having to delay the notification, which would be unacceptable in some circumstances.
+
+If the developer has a simple query in mind that needs no such nuance, I'm thinking it might be helpful to provide an alternative key to "select" that is used specifically for (a subset?) of queries supported by the existing "matches" method that elements support, maybe even after the browser vendors provide a selector-observer (if ever).
+
+So the developer could use:
+
+## Polyfill Supported Mount Observer
+
+```JavaScript
+const observer = new MountObserver({
+   //supported by this polyfill
+   matching:'my-element',
+   import: './my-element.js',
+   do: ({localName}, {modules, observer, MountConfig, rootNode}) => {
+      if(!customElements.get(localName)) {
+         customElements.define(localName, modules[0].MyElement);
+      }
+      observer.disconnectedSignal.abort();
+   }
+   
+}, {disconnectedSignal: new AbortController().signal});
+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 ("matching"), and leaves "select" for such a time as when a selector observer is available in the platform.
+
+[Implemented as Requirement 1](requirements/Done/Requirement1.md).
+
+## The observe() method
+
+The `observe()` method begins observation of elements within the provided node:
+
+```typescript
+async observe(observedNode: Node): Promise<void>
+```
+
+**Parameter: `observedNode`**
+
+The `observedNode` parameter is the node where observation takes place. In order to support the polyfill, a mutation observer is registered on this node to detect when matching elements are added or removed. All matching elements within this node and its descendants will trigger mount callbacks, as long as it belongs to the same scoped custom element registry as the observed node.
+
+**Common usage:**
+```javascript
+const observer = new MountObserver({
+    matching: '.my-element',
+    do: (el) => console.log('Mounted:', el)
+});
+
+// Observe the entire document
+await observer.observe(document);
+
+// Or observe a specific subtree
+const container = document.querySelector('#container');
+await observer.observe(container);
+
+// Or observe within a shadow DOM
+const shadowRoot = element.shadowRoot;
+await observer.observe(shadowRoot);
+```
+
+**Note:** An observer can only observe one node at a time. Calling `observe()` again will throw an error. Call `disconnect()` first to observe a different node.
+
+**Relationship with element.mount():**
+
+When using the `element.mount()` convenience method, it internally determines which node to pass to `observe()` based on the `scope` option:
+- `'self'` - Observes the element itself
+- `'registryRoot'` - Finds and observes the element's registry root
+- `'registry'` - Finds and observes all DOM nodes that have the same custom element registry
+- `'shadow'` - Observes the element's shadow root
+- `'root'` - Observes the element's root node (via `getRootNode()`)
+
+##  The import key
+
+This proposal has been amended to support multiple imports, including of different types:
+
+```JavaScript
+const observer = new MountObserver({
+   matching:'my-element',
+   import: [
+      ['./my-element-small.css', {type: 'css'}],
+      './my-element.js',
+   ],
+   do: ({localName}, {modules, observer, MountConfig, rootNode}) => {
+      ...
+   }
+});
+observer.observe(document);
+```
+
+Once again, the key can accept either a single import, but alternatively it can also support multiple imports (via an array).
+
+The do function won't be invoked until all the imports have been successfully completed and inserted into the modules array.
+
+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).
+
+[Implemented as Requirement 1](requirements/Done/Requirement1.md).
+
+## Preemptive downloading
+
+There are two significant steps to imports, each of which imposes a cost:  
+
+1.  Downloading the resource.
+2.  Loading the resource into memory.
+
+What if we want to *download* the resource ahead of time, but only load into memory when needed?
+
+The link rel=modulepreload option (and maybe the new defer tc39 proposal) provides an already existing platform support for this, but the browser complains when no use of the resource is used within a short time span of page load.  That doesn't really fit the bill for lazy loading custom elements and other resources.
+
+So for this we add loadingEagerness:
+
+```JavaScript
+const observer = new MountObserver({
+   select: 'my-element', //not supported by this polyfill
+   loadingEagerness: 'eager', //partially supported by this polyfill
+   import: './my-element.js',
+   do: ({localName}, {modules}) => customElements.define(localName, modules[0].MyElement),
+});
+```
+
+So what this does is only check for the presence of an element with tag name "my-element", and it starts downloading the resource, even before the element has "mounted" based on other criteria.
+
+The polyfill just loads the module into memory right away.
+
+> [!NOTE]
+> As a result of the google IO 2024 talks, I became aware that there is some similarity between this proposal and the [speculation rules api](https://developer.chrome.com/blog/speculation-rules-improvements).  This motivated the change to the property from "loading" to loadingEagerness above.
+
+## Importing Configuration with configFrom
+
+The `configFrom` property provides a clean way to import MountConfig settings from external modules, enabling better code organization and reusability.
+
+**Key benefit for JSON serialization**: One of the most important advantages of `configFrom` is that it allows us to separate non-JSON-serializable settings (like functions and class constructors) from JSON-serializable settings. This makes it possible to keep our inline MountConfig 100% JSON-serializable while still leveraging the full power of JavaScript in our imported configuration modules when needed.
+
+```JavaScript
+// Inline config - 100% JSON serializable
+const observer = new MountObserver({
+   matching: '.my-element',
+   configFrom: './my-handlers.js'  // Non-serializable code lives here
+});
+
+// my-handlers.js - Contains functions and class references
+export const mountConfig = {
+   whereInstanceOf: HTMLButtonElement,  // Class constructor
+   do: (element, context) => {          // Function
+      element.addEventListener('click', () => console.log('clicked'));
+   }
+};
+```
+
+This separation is crucial for scenarios like Mount Observer Script Elements (MOSEs) where configuration needs to be embedded in HTML as JSON, but we still want to leverage imperative JavaScript code.
+
+### Basic Usage
+
+Create a configuration module that exports a `mountConfig` constant:
+
+```JavaScript
+// my-config.js
+export const mountConfig = {
+   matching: '.my-element',
+   do: (element, context) => {
+      element.textContent = 'Configured!';
+   }
+};
+```
+
+Then reference it in your observer:
+
+```JavaScript
+const observer = new MountObserver({
+   configFrom: './my-config.js'
+});
+observer.observe(document);
+```
+
+### Multiple Configuration Modules
+
+You can import multiple config modules. Later configs override earlier ones (left-to-right merge):
+
+```JavaScript
+const observer = new MountObserver({
+   configFrom: ['./base-config.js', './override-config.js']
+});
+```
+
+### Inline Config Takes Precedence
+
+Inline configuration always overrides imported configuration:
+
+```JavaScript
+const observer = new MountObserver({
+   configFrom: './base-config.js',
+   matching: '.custom-selector'  // Overrides matching from base-config.js
+});
+```
+
+### Merge Semantics
+
+- **Shallow merge**: Uses `Object.assign()` for merging
+- **Merge order**: First configFrom module → second configFrom module → ... → inline config
+- **Arrays are replaced**: If multiple configs define the same array property, the later array completely replaces the earlier one
+- **Inline wins**: Inline configuration always takes final precedence
+
+### Supported Properties
+
+Config modules can export any valid MountConfig property, including:
+- `matching`, `whereInstanceOf`, `withMediaMatching`
+- `whereObservedRootSizeMatches`, `whereElementIntersectsWith`
+- `whereConnectionHas`, `withScopePerimeter`
+- `import`, `do`, `loadingEagerness`
+- `assignOnMount`, `assignOnDismount`, `stageOnMount`
+- `mountedElemEmits`, `customData`, `getPlayByPlay`
+
+### Functions and Class References
+
+Config modules can include non-JSON-serializable values like functions and class constructors:
+
+```JavaScript
+// button-config.js
+export const mountConfig = {
+   matching: 'button',
+   whereInstanceOf: HTMLButtonElement,
+   do: (element, context) => {
+      element.addEventListener('click', () => {
+         console.log('Button clicked!');
+      });
+   }
+};
+```
+
+### Error Handling
+
+**Missing mountConfig export:**
+```JavaScript
+// This will throw an error
+const observer = new MountObserver({
+   configFrom: './module-without-mountConfig.js'
+});
+// Error: Module './module-without-mountConfig.js' does not export 'mountConfig'
+```
+
+**Duplicate modules:**
+```JavaScript
+// This will throw an error
+const observer = new MountObserver({
+   configFrom: ['./config.js', './config.js']
+});
+// Error: Duplicate configFrom module: './config.js'
+```
+
+### Circular Dependency Warning
+
+Be careful to avoid circular dependencies when using `configFrom`. Config modules should only export configuration and avoid importing modules that create MountObserver instances.
+
+**Safe pattern:**
+```JavaScript
+// config.js - Only exports configuration
+export const mountConfig = {
+   matching: '.element',
+   do: (el) => { /* ... */ }
+};
+```
+
+**Avoid:**
+```JavaScript
+// config.js - Creates circular dependency
+import { MountObserver } from 'mount-observer/MountObserver.js';
+// This could cause issues if the importing module also imports MountObserver
+```
+
+## Media / container queries / instanceOf
+
+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({
+   // not supported by polyfill
+   select: 'div > p + p ~ span[class$="name"]', 
+   withMediaMatching: '(max-width: 1250px)',
+   whereObservedRootSizeMatches: '(min-width: 700px)',
+   whereElementIntersectsWith:{
+      rootMargin: "0px",
+      threshold: 1.0,
+   },
+   whereInstanceOf: [HTMLMarqueeElement], //or 'HTMLMarqueeElement'
+   whereLangIn: ['en-GB'], // Cannot be implemented - see https://github.com/whatwg/html/issues/7039
+   whereConnectionHas:{
+      effectiveTypeIn: ["slow-2g"],
+   },
+   import: ['./my-element-small.css', {type: 'css'}],
+   do: function(mountedElement, ctx){
+      console.log({mountedElement, ctx});
+   }
+});
+```
+
+[whereInstanceOf implemented as [Requirement5](requirements/Done/Requirement5.md)]
+[whereObservedRootSizeMatches implemented]
+[whereElementIntersectsWith implemented]
+[whereConnectionHas implemented]
+[whereLocalNameMatches implemented as [RegularExpressionNameMatching](requirements/Done/RegularExpressionNameMatching.md)]
 
-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).
+[withMediaMatching implemented as [Requirement6](requirements/Done/Requirement6.md)]
 
-So the developer could use:
+## Waiting for Custom Element Definitions
 
-## Polyfill Supported Mount Observer
+The `whenDefined` property allows you to wait for custom elements to be defined before mounting elements. This ensures that elements are only processed after their custom element definitions are available, preventing issues with undefined custom elements.
 
-```JavaScript
+```javascript
 const observer = new MountObserver({
-   //supported by this polyfill
-   matching:'my-element',
-   import: './my-element.js',
-   do: ({localName}, {modules, observer, MountConfig, rootNode}) => {
-      if(!customElements.get(localName)) {
-         customElements.define(localName, modules[0].MyElement);
-      }
-      observer.disconnectedSignal.abort();
-   }
-   
-}, {disconnectedSignal: new AbortController().signal});
+    matching: 'my-element',
+    whenDefined: 'my-element',  // Wait for my-element to be defined
+    do: (element) => {
+        console.log('my-element is now defined and mounted');
+    }
+});
 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 ("matching"), and leaves "select" for such a time as when a selector observer is available in the platform.
-
-[Implemented as Requirement 1](requirements/Done/Requirement1.md).
 
+// Later, when the custom element is defined
+customElements.define('my-element', class extends HTMLElement {
+    // ...
+});
+```
 
-##  The import key
+**Waiting for multiple custom elements:**
 
-This proposal has been amended to support multiple imports, including of different types:
+You can specify an array of tag names to wait for all of them to be defined:
 
-```JavaScript
+```javascript
 const observer = new MountObserver({
-   matching:'my-element',
-   import: [
-      ['./my-element-small.css', {type: 'css'}],
-      './my-element.js',
-   ],
-   do: ({localName}, {modules, observer, MountConfig, rootNode}) => {
-      ...
-   }
+    matching: 'my-element, another-element',
+    whenDefined: ['my-element', 'another-element'],  // Wait for both
+    do: (element) => {
+        console.log('Both elements are defined, mounting:', element.localName);
+    }
 });
-observer.observe(document);
 ```
 
-Once again, the key can accept either a single import, but alternatively it can also support multiple imports (via an array).
+**How it works:**
 
-The do function won't be invoked until all the imports have been successfully completed and inserted into the modules array.
+1. The check happens first, before any other `where*` conditions
+2. Uses `customElements.whenDefined()` for each specified tag name
+3. Uses the `customElementRegistry` of the observed root node
+4. Only checks once per observer instance (doesn't re-check on subsequent mounts)
+5. The `observe()` method waits for all definitions before processing elements
 
-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.
+**Common use cases:**
 
-This proposal would also include support for JSON and HTML module imports (really, all types).
+```javascript
+// Lazy load and wait for custom element definition
+const observer = new MountObserver({
+    matching: 'my-button',
+    whenDefined: 'my-button',
+    import: './my-button.js',
+    do: 'builtIns.defineCustomElement'
+});
 
-[Implemented as Requirement 1](requirements/Done/Requirement1.md).
+// Wait for dependencies before enhancing
+const observer = new MountObserver({
+    matching: '.needs-custom-elements',
+    whenDefined: ['base-element', 'helper-element'],
+    do: (element) => {
+        // Safe to interact with custom elements now
+        const base = element.querySelector('base-element');
+        const helper = element.querySelector('helper-element');
+    }
+});
+```
 
-## Preemptive downloading
+**AND condition logic:**
 
-There are two significant steps to imports, each of which imposes a cost:  
+Like all `where*` properties, `whenDefined` forms an AND condition with other filters. However, it's checked first as a prerequisite before evaluating other conditions:
 
-1.  Downloading the resource.
-2.  Loading the resource into memory.
+```javascript
+const observer = new MountObserver({
+    matching: 'my-element',
+    whenDefined: 'my-element',           // Checked FIRST
+    whereInstanceOf: HTMLElement,        // Then checked
+    whereLocalNameMatches: /^my-/,       // Then checked
+    do: (element) => { /* ... */ }
+});
+```
 
-What if we want to *download* the resource ahead of time, but only load into memory when needed?
+[whenDefined implemented as [SupportForWhenDefined](requirements/SupportForWhenDefined.md)]
 
-The link rel=modulepreload option (and maybe the new defer tc39 proposal) provides an already existing platform support for this, but the browser complains when no use of the resource is used within a short time span of page load.  That doesn't really fit the bill for lazy loading custom elements and other resources.
+## LocalName Pattern Matching
 
-So for this we add loadingEagerness:
+The `whereLocalNameMatches` property allows filtering elements by their `localName` using regular expressions. This is useful when you need to match elements based on naming patterns rather than CSS selectors.
 
-```JavaScript
+```javascript
 const observer = new MountObserver({
-   select: 'my-element', //not supported by this polyfill
-   loadingEagerness: 'eager', //partially supported by this polyfill
-   import: './my-element.js',
-   do: ({localName}, {modules}) => customElements.define(localName, modules[0].MyElement),
+    matching: '*',  // Match all elements
+    whereLocalNameMatches: /^my-/,  // Only mount elements starting with 'my-'
+    do: (element) => {
+        console.log('Mounted:', element.localName);
+    }
 });
+observer.observe(document);
 ```
 
-So what this does is only check for the presence of an element with tag name "my-element", and it starts downloading the resource, even before the element has "mounted" based on other criteria.
+**String patterns are automatically converted to RegExp:**
 
-The polyfill just loads the module into memory right away.
+```javascript
+// These are equivalent
+whereLocalNameMatches: 'button|input'
+whereLocalNameMatches: /button|input/
+```
 
-> [!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.
+**Common use cases:**
 
-## Separating JS imperative code from JSON serializable config
+```javascript
+// Match custom elements with a specific prefix
+whereLocalNameMatches: /^app-/
 
+// Match elements ending with a suffix
+whereLocalNameMatches: /-widget$/
 
-In order to support pure 100% declarative syntax in the passed in MountConfig argument, we need to be able to import the do function.  This is done as follows:
+// Match multiple element types
+whereLocalNameMatches: /^(button|input|select)$/
 
-```JavaScript
-//module myActions.js
-const  doFunction = function({localName}, {modules, observer, MountConfig, rootNode}){
-   if(!customElements.get(localName)) {
-      // Find the first exported class constructor from the module
-      const ElementClass = Object.values(modules[0]).find(exp => 
-         typeof exp === 'function' && exp.prototype && exp.prototype.constructor === exp
-      );
-      if(ElementClass) {
-         customElements.define(localName, ElementClass);
-      }
-   }
-   observer.disconnectedSignal.abort();
-}
-export {doFunction as do}
+// Match elements containing a pattern
+whereLocalNameMatches: /dialog/
+```
+
+**AND condition logic:**
 
-// observer setup
+Like all `where*` properties, `whereLocalNameMatches` forms an AND condition with other filters:
 
+```javascript
 const observer = new MountObserver({
-   matching:'my-element',
-   import: [
-      './my-element.js',
-      ['./my-element-small.css', {type: 'css'}],
-      './myActions.js'
-   ],
-   reference: 2
+    matching: '[data-enhanced]',           // Must have data-enhanced attribute
+    whereLocalNameMatches: /^custom-/,     // AND localName starts with 'custom-'
+    whereInstanceOf: HTMLElement,          // AND is an HTMLElement instance
+    do: (element) => { /* ... */ }
 });
-observer.observe(document);
-
 ```
 
-Here "2" refers to the imported module index ('./myActions.js' in this case).
+This will only mount elements that satisfy ALL three conditions.
 
-### How the reference property works
+## Custom JavaScript Checks with shouldMount
 
-The `reference` property allows us to call `do` functions from imported modules, enabling 100% JSON-serializable configuration. This is useful when you want to separate imperative code from declarative configuration.
+The `shouldMount` property provides a final JavaScript-based check that runs after all declarative `where*` conditions have passed. This is useful for complex logic that can't be expressed declaratively.
 
-**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
+It's useful to be able to provide this check outside of the do method for separation of concerns reasons, and also because the do function only gets called once, and having this extra check allows us to combine all the checks together in a consistent way.
 
-**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 };
+const observer = new MountObserver({
+    matching: '.protected-feature',
+    shouldMount: (el, ctx) => {
+        // Check user permission
+        const requiredRole = el.dataset.requiredRole;
+        return currentUser.hasRole(requiredRole);
+    },
+    do: (el) => {
+        // Only called if shouldMount returned true
+        enhanceProtectedFeature(el);
+    }
+});
 ```
 
-**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:
+**Behavior:**
+- `shouldMount` is called after ALL `where*` conditions pass
+- If it returns `true`, the element mounts (do callback + mount event)
+- If it returns `false`, the element does NOT mount (no do callback, no mount event)
+- If it throws an error, it's treated as `false` and the error is logged
+- The element can be re-evaluated if removed and re-added to the DOM
 
-```JavaScript
+**Use Cases:**
 
-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
+Authorization checks:
+```javascript
+shouldMount: (el) => currentUser.hasPermission(el.dataset.permission)
 ```
 
-[Implemented as [Requirement11](requirements/Done/Requirement11.md)]
-
-## Media / container queries / instanceOf / custom checks [TODO] out of date
+Feature flags:
+```javascript
+shouldMount: (el) => featureFlags.isEnabled(el.dataset.feature)
+```
 
-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?):
+Data validation:
+```javascript
+shouldMount: (el) => {
+    return el.dataset.apiKey && 
+           el.dataset.apiEndpoint && 
+           el.dataset.apiKey.length > 0;
+}
+```
 
-```JavaScript
-const observer = new MountObserver({
-   select: 'div > p + p ~ span[class$="name"]', // not supported by polyfill
-   withMediaMatching: '(max-width: 1250px)',
-   whereObservedRootSizeMatches: '(min-width: 700px)',
-   whereElementIntersectsWith:{
-      rootMargin: "0px",
-      threshold: 1.0,
-   },
-   whereInstanceOf: [HTMLMarqueeElement], //or 'HTMLMarqueeElement'
-   whereLangIn: ['en-GB'], // Cannot be implemented - see https://github.com/whatwg/html/issues/7039
-   whereConnectionHas:{
-      effectiveTypeIn: ["slow-2g"],
-   },
-   import: ['./my-element-small.css', {type: 'css'}],
-   do: ...
-});
+Complex conditional logic:
+```javascript
+shouldMount: (el, ctx) => {
+    const parent = el.closest('[data-context]');
+    if (!parent) return false;
+    
+    const isActive = parent.dataset.context === 'active';
+    const widgetType = el.dataset.widgetType;
+    const enabledWidgets = parent.dataset.enabledWidgets?.split(',') || [];
+    
+    return isActive && enabledWidgets.includes(widgetType);
+}
 ```
 
-[whereInstanceOf implemented as [Requirement5](requirements/Done/Requirement5.md)]
-[whereObservedRootSizeMatches implemented]
-[whereElementIntersectsWith implemented]
-[whereConnectionHas implemented]
+**Note:** For event-driven mounting (waiting for user clicks, etc.), use the `do` callback with event listeners rather than `shouldMount`. The `shouldMount` callback is for checking conditions, not waiting for events.
 
-[withMediaMatching implemented as [Requirement6](requirements/Done/Requirement6.md)]
+[Implemented as SupportForShouldMount requirement](requirements/Done/SupportForShouldMount.md)
 
 ## InstanceOf checks in detail
 
-Carving out the special "whereInstanceOf" check is provided based on the assumption that there's a performance benefit from doing so. If not, the developer could just add that check inside the "confirm" callback logic (discussed later).  For built-in elements, we can alternatively provide the string name, as indicated in the comment above, which certainly makes it JSON serializable, thus making it easy as pie to include in the MOSE JSON payload.  I don't think there would be any ambiguity in doing so, which means I believe that answers the mystery in my mind whether it could be part of the low-level checklist that could be done within the c++/rust code / thread.
+Carving out the special "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 "shouldMount" 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.
 
@@ -462,52 +1823,69 @@ However, where this support for "whereInstanceOf" would be *most* helpful is whe
 
 -->
 
-### Referenced whereInstanceOf
+## Custom Element Registry Matching
 
-Similar to the `do` function, the `whereInstanceOf` check can also be moved to imported modules for 100% JSON-serializable configuration:
+MountObserver automatically respects scoped custom element registry boundaries. When observing a root node, only elements that share the same `customElementRegistry` as the root node will be mounted by default. This is an implicit AND condition that applies to all observations.
+
+Learn more about [scoped custom element registries in Chrome's blog post](https://developer.chrome.com/blog/scoped-registries).
+
+**How it works:**
 
 ```javascript
-// module mySettings.js
-const doFunction = function({localName}, {modules, observer, MountConfig, rootNode}) {
-   if(!customElements.get(localName)) {
-      customElements.define(localName, modules[1].MyElement);
-   }
-   observer.disconnectedSignal.abort();
-};
+// Observe document - only mounts elements in the global registry
+const observer1 = new MountObserver({
+    matching: '.my-element',
+    do: (el) => { /* ... */ }
+});
+observer1.observe(document);
+
+// Observe shadow root - only mounts elements in that shadow root's registry
+const shadowRoot = host.attachShadow({ mode: 'open' });
+const observer2 = new MountObserver({
+    matching: '.my-element',
+    do: (el) => { /* ... */ }
+});
+observer2.observe(shadowRoot);
+```
+
+**Registry matching logic:**
+
+The implementation is straightforward - it compares the `customElementRegistry` property of the root node with the `customElementRegistry` property of each candidate element:
+
+```javascript
+const registriesMatch = rootNode.customElementRegistry === element.customElementRegistry;
+```
 
-const whereInstanceOf = [HTMLMarqueeElement, SVGElement];
+**Default behavior** (same registry):
+- Elements with matching registries → mount ✓
+- Elements with different registries → don't mount ✓
 
-export { doFunction as do, whereInstanceOf };
+**Inverted behavior** with `whereDifferentCustomElementRegistry: true`:
+- Elements with matching registries → don't mount ✓
+- Elements with different registries → mount ✓
 
-// my local module
+**Use case for inverted matching:**
+```javascript
+// Mount elements from OTHER registries (cross-registry observation)
 const observer = new MountObserver({
-   matching: 'my-element',
-   import: [
-      ['./my-element-small.css', {type: 'css'}],
-      './my-element.js',
-      './mySettings.js'
-   ],
-   reference: 2
+    matching: '.external-component',
+    whereDifferentCustomElementRegistry: true,
+    do: (el) => { /* Handle elements from different registries */ }
 });
-observer.observe(document);
+observer.observe(shadowRoot);
 ```
 
-**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
+**Behavior across browser versions:**
+- **Pre-Chrome 146**: Both `customElementRegistry` properties are `undefined`, so `undefined === undefined` is `true` and elements match (backward compatible)
+- **Chrome 146+ with scoped registries**: Elements are filtered by registry reference equality
 
-This optimization ensures that with lazy loading, elements that don't match the inline `whereInstanceOf` won't trigger unnecessary imports.
+This ensures that when we observe a shadow root with a scoped registry, we won't accidentally mount elements from the parent document or other shadow roots with different registries (unless explicitly requested with `whereDifferentCustomElementRegistry: true`). The registry check happens automatically before any other `where*` conditions are evaluated.
 
-[Implemented as [Requirement12](requirements/Done/Requirement12.md)]
+[Implemented as [ExcludeMatchingElementsWhereCustomElementRegistriesDon'tMatch](requirements/ExcludeMatchingElementsWhereCustomElementRegistriesDon'tMatch.md)]
 
 ## Element Mount Extension
 
-For even more convenience, you can use the `element.mount()` method to observe elements within their scoped custom element registry context. This is particularly useful with scoped custom element registries (Chrome 146+, latest WebKit/Safari).
+For even more convenience, we can use the `element.mount()` method to observe elements within their scoped custom element registry context. This is particularly useful with [scoped custom element registries](https://developer.chrome.com/blog/scoped-registries) (Chrome 146+, latest WebKit/Safari).
 
 ```JavaScript
 import 'mount-observer/ElementMountExtension.js';
@@ -532,7 +1910,7 @@ Scope options (via `options.scope`):
 - `'self'`: Observes only this element
 - `'root'`: Observes the root node (document or shadow root)
 - `'shadow'`: Observes the element's shadowRoot (throws error if none exists)
-- `Element`: Observes a custom element you specify
+- `Element`: Observes a custom element we specify
 
 This is especially useful for web components that want to observe their own shadow DOM or scoped registry:
 
@@ -564,17 +1942,186 @@ class MyComponent extends HTMLElement {
 }
 ```
 
-Browser support: Works in all browsers, but scoped registry features require Chrome 146+ or latest WebKit/Safari.
+Browser support: Works in all browsers, but [scoped registry features](https://developer.chrome.com/blog/scoped-registries) require Chrome 146+ or latest WebKit/Safari.
 
 [Implemented as CustomElementRegistryMounting requirement](requirements/Done/CustomElementRegistryMounting.md).
- 
 
+### Global Propagation with `mountGlobally()`
+
+The `mountGlobally()` method extends `mount()` to automatically propagate mount observers across [custom element registry](https://developer.chrome.com/blog/scoped-registries) boundaries and shadow DOM scopes. This is useful for bootstrapping core handlers that should work everywhere, regardless of scoped registries.  It should be used sparingly, as a last resort, probably limited to things that should arguably be built into the platform.
+
+```JavaScript
+import 'mount-observer/ElementMountExtension.js';
+
+// Mount globally - propagates to all child registries and shadow roots
+await document.mountGlobally({
+    matching: '.target',
+    do: (el) => {
+        el.setAttribute('data-mounted', 'true');
+    }
+});
+```
+
+The `mountGlobally()` method:
+- Mounts the config in the current registry first (using `mount()`)
+- Creates two propagators that automatically mount in:
+  - Elements with different custom element registries (`whereDifferentCustomElementRegistry: true`)
+  - Shadow roots within the same registry (custom elements with shadow DOM)
+- Waits for custom elements to be defined before mounting (ensures shadow roots exist)
+- Recursively propagates through nested shadow roots
+
+This enables "viral" propagation of mount observers, perfect for bootstrapping core handlers like `builtIns.mountObserverScript`:
+
+```JavaScript
+// Bootstrap mount observer script support globally
+await document.mountGlobally({
+    do: 'builtIns.mountObserverScript'
+});
+
+// Now MOSE scripts work everywhere, even in scoped registries
+```
+
+Both `Element.prototype.mountGlobally()` and `ShadowRoot.prototype.mountGlobally()` are available.
+
+[Implemented as goViral requirement](requirements/Done/goViral.md).
+
+## Hierarchical Observer Composition with the `with` Property
+
+The `with` property enables hierarchical composition of MountObservers, allowing a parent observer to declaratively create and manage multiple sub-observers that observe the same root node. This provides a clean way to organize complex observation scenarios and coordinate multiple observers.
+
+### Basic Usage
+
+```JavaScript
+const observer = new MountObserver({
+    matching: '.container',
+    with: {
+        // Sub-observer for custom elements
+        registry: {
+            matching: 'my-element',
+            import: './my-element.js',
+            do: 'builtIns.defineCustomElement'
+        },
+        // Sub-observer for styles
+        styles: {
+            matching: '.styled',
+            import: './styles.css'
+        }
+    }
+});
+
+await observer.observe(document);
+```
+
+### How It Works
+
+1. **Automatic Creation**: When the parent observer's `observe()` method is called, it automatically creates sub-observers for each entry in the `with` property.
+
+2. **Same Root Node**: All sub-observers observe the same root node as the parent.
+
+3. **Independent Configuration**: Each sub-observer operates independently with its own configuration. Sub-observers do NOT inherit properties from the parent.
+
+4. **Automatic Lifecycle**: Sub-observers are automatically disconnected when the parent disconnects.
+
+5. **Unlimited Nesting**: Sub-observers can have their own `with` property for unlimited nesting depth.
+
+### Accessing Sub-Observers in Handlers
+
+Sub-observers are accessible in mount handlers via the `context.withObservers` property:
+
+```JavaScript
+const observer = new MountObserver({
+    matching: '.parent',
+    with: {
+        registry: { matching: 'custom-element' },
+        styles: { matching: '.styled' }
+    },
+    do: (el, ctx) => {
+        // Access sub-observers with type safety
+        const registryObserver = ctx.withObservers?.registry;
+        const stylesObserver = ctx.withObservers?.styles;
+        
+        if (registryObserver) {
+            console.log('Registry observer:', registryObserver);
+            console.log('Mounted elements:', registryObserver.mountedElements);
+        }
+    }
+});
+```
+
+### Nested Sub-Observers
+
+Sub-observers can have their own sub-observers, creating a tree structure:
+
+```JavaScript
+const observer = new MountObserver({
+    matching: '.root',
+    with: {
+        level1: {
+            matching: '.level1',
+            with: {
+                level2: {
+                    matching: '.level2',
+                    do: (el) => console.log('Level 2 mounted:', el)
+                }
+            }
+        }
+    }
+});
+```
+
+### Use Case: Cross-Scope Registry Management
+
+A practical use case is managing custom elements across different scoped registries:
+
+```JavaScript
+const observer = new MountObserver({
+    matching: 'div[shadowroot]',
+    with: {
+        // Observe elements in the main registry
+        mainRegistry: {
+            matching: 'my-element',
+            whereDifferentCustomElementRegistry: false,
+            do: 'builtIns.defineCustomElement'
+        },
+        // Observe elements in shadow DOM registries
+        shadowRegistry: {
+            matching: 'shadow-element',
+            whereDifferentCustomElementRegistry: true,
+            do: 'builtIns.defineScopedCustomElement'
+        }
+    }
+});
+```
+
+### Type Safety
 
+When using TypeScript, the keys in the `with` property are inferred and provide autocomplete:
 
+```TypeScript
+const observer = new MountObserver({
+    matching: '.parent',
+    with: {
+        registry: { matching: 'my-element' },
+        styles: { import: './styles.css' }
+    },
+    do: (el, ctx) => {
+        ctx.withObservers?.registry  // ✓ TypeScript knows this exists
+        ctx.withObservers?.unknown   // ✗ TypeScript error
+    }
+});
+```
 
+### Key Benefits
 
+1. **Declarative Composition**: Define complex observer hierarchies in a single configuration
+2. **Automatic Lifecycle**: Sub-observers are created and cleaned up automatically
+3. **Independent Operation**: Each sub-observer has its own configuration and state
+4. **Type Safety**: Full TypeScript support with key inference
+5. **Unlimited Nesting**: Create arbitrarily deep observer hierarchies
 
+### Known Limitations
 
+- **Circular References**: The library does not detect or prevent circular references in `with` configurations. Avoid configurations where observer A's `with` references observer B, and B's `with` references A, as this will cause a stack overflow.
 
 ## Mount Observer Script Elements (MOSEs)
 
@@ -582,14 +2129,15 @@ Following an approach similar to the [speculation api](https://developer.chrome.
 
 ```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);
+// My all powerful custom element definer
+export const mountConfig = {
+   do: function({localName}, {modules, observer}) {
+      if(!customElements.get(localName)) {
+         customElements.define(localName, modules[1].MyElement);
+      }
+      observer.disconnectedSignal.abort();
    }
-   observer.disconnectedSignal.abort();
-}
-export { doFunction as do };
+};
 ```
 
 ```html
@@ -597,18 +2145,14 @@ export { doFunction as do };
 {
    "select":"my-element",
    "import": [
-      ["./my-element-small.css", {type: "css"}],
-      "./my-element.js",
-      "myPackage/myDefiner.js
+      ["./my-element-small.css", {"type": "css"}],
+      "./my-element.js"
    ],
-   "reference": 2
+   "configFrom": "myPackage/myDefiner.js"
 }
 </script>
 ```
 
-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, including support for inheritance across containing scoped custom element registries.
-
-But I think it's important to think about this way of making the mount observer declarative, as it provides one significant reason why we place so much emphasis on making sure that the mount observer settings (MountConfig) is as JSON serializable as possible.
 
 
 ## Binding from a distance
@@ -648,7 +2192,7 @@ This allows developers to create "stylesheet" like capabilities.
 
 ## Registering reusable handlers with MountObserver.define
 
-To make MountConfig configurations more JSON-serializable and encourage code reuse, you can register handler classes with string names and reference them by name:
+To make MountConfig configurations more JSON-serializable and encourage code reuse, we can register handler classes with string names and reference them by name:
 
 ```JavaScript
 import {EvtRt} from 'mount-observer/EvtRt.js';
@@ -701,25 +2245,6 @@ const observer = new MountObserver({
 
 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({
-   matching: '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:
@@ -758,13 +2283,13 @@ MountObserver.define('myHandler', Handler2);  // Error: myHandler already in use
 
 ### 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.
+The handler registry is global and shared across all MountObserver instances, similar to the global custom elements registry. Once a handler is registered, it can be used by any MountObserver instance in your application.
 
 [Implemented as [Requirement14](requirements/Done/Requirement14.md)]
 
 ### Handler defaults with static properties
 
-Registered handler classes can specify default MountConfig properties using static class properties. When you reference a handler by name, its static properties are automatically merged with your inline configuration, with inline config always taking precedence:
+Registered handler classes can specify default MountConfig properties using static class properties. When we reference a handler by name, its static properties are automatically merged with your inline configuration, with inline config always taking precedence:
 
 ```JavaScript
 import {EvtRt} from 'mount-observer/EvtRt.js';
@@ -869,7 +2394,7 @@ export default class MyElement extends HTMLElement {
 }
 
 // main.js
-import { MountObserver } from 'mount-observer';
+import { MountObserver } from 'mount-observer/MountObserver.js';
 
 const observer = new MountObserver({
     matching: 'my-element',
@@ -1019,7 +2544,7 @@ Using `assignOn*` provides several benefits:
 
 ### 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:
+The `MountObserver` class provides a public `assignGingerly()` method that allows us to merge new updates into the  observer. This is useful for responding to user actions or application state changes:
 
 ```JavaScript
 const observer = new MountObserver({
@@ -1046,7 +2571,7 @@ await observer.assignGingerly({
 
 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:
+4. **Starting without initial config**: We can call the method even if no `assignGingerly` was specified in the constructor:
 
 ```JavaScript
 const observer = new MountObserver({
@@ -1080,7 +2605,7 @@ The method is async because the assign-gingerly library is loaded dynamically wh
 
 ## Reversible property assignment with stageOnMount
 
-While `assignOnMount` and `assignOnDismount` provide permanent property assignments, sometimes you need temporary changes that automatically reverse when elements dismount. The `stageOnMount` property provides this capability using the `assignTentatively` function from assign-gingerly:
+While `assignOnMount` and `assignOnDismount` provide permanent property assignments, sometimes we need temporary changes that automatically reverse when elements dismount. The `stageOnMount` property provides this capability using the `assignTentatively` function from assign-gingerly:
 
 ```JavaScript
 const observer = new MountObserver({
@@ -1104,7 +2629,7 @@ When a matching button mounts, these properties are applied. When it dismounts (
 2. **Applies the new properties** when elements mount
 3. **Automatically reverses** to original values when elements dismount
 
-This is different from `assignOnMount`/`assignOnDismount`, where you must explicitly specify both the mount and dismount values.
+This is different from `assignOnMount`/`assignOnDismount`, where we must explicitly specify both the mount and dismount values.
 
 ### When to use stageOnMount vs assignOnMount
 
@@ -1228,7 +2753,7 @@ const observer = new MountObserver({
 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:
+This dispatches a `custom-ready` event from each matching button element when it mounts. Events bubble by default, so we can listen at the document level:
 
 ```JavaScript
 document.addEventListener('custom-ready', (e) => {
@@ -1396,7 +2921,7 @@ observer.observe(document);
 
 ## Element-specific lifecycle notifications with getNotifier
 
-While the MountObserver dispatches lifecycle events (mount, dismount, disconnect) at the observer level, sometimes you need to listen for events specific to a single element. The `getNotifier()` method returns an EventTarget that dispatches filtered events for only that element.
+While the MountObserver dispatches lifecycle events (mount, dismount, disconnect) at the observer level, sometimes we 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
 
@@ -1494,7 +3019,7 @@ getNotifier(element: Element): EventTarget
 [Implemented as [Requirement13](requirements/Done/Requirement13.md)]
 
 
-##  Extra lazy loading
+<!-- ##  Extra lazy loading
 
 By default, the matches would be reported as soon as an element matching the criterion is found or added into the DOM, inside the node specified by rootNode.
 
@@ -1509,7 +3034,7 @@ const observer = new MountObserver({
    },
    import: './my-element.js'
 });
-```
+``` -->
 
  
 
@@ -1518,7 +3043,8 @@ const observer = new MountObserver({
 Subscribing can be done via:
 
 ```JavaScript
-observer.addEventListener('confirm', e => {
+//[TODO] not implemented yet
+observer.addEventListener('shouldMount', e => {
   e.isSatisfied = true; //or false to prevent the mount event below
 });
 observer.addEventListener('mount', e => {
@@ -1533,18 +3059,23 @@ observer.addEventListener('dismount', e => {
 observer.addEventListener('disconnect', e => {
   ...
 });
+//[TODO]
 observer.addEventListener('move', e => {
   ...
 });
+//[TODO]
 observer.addEventListener('reconnect', e => {
   ...
 });
+//[TODO]
 observer.addEventListener('reconfirm', e => {
   ...
 });
+//[TODO]
 observer.addEventListener('exit', e => {
   ...
 });
+//[TODO]
 observer.addEventListener('forget', e => {
   ...
 });