mount-observer 0.1.12 → 0.1.13

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
 
@@ -12,6 +11,9 @@ The following features have been implemented and tested:
 ### Core Functionality
 - ✅ **matching**: CSS selector-based element matching
 - ✅ **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 +31,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 +83,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. 
 
 
 ###  Most significant use cases
@@ -107,7 +112,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 +171,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,28 +193,818 @@ export default {
     enhKey: 'buttonEnh'
 };
 
+// main.js
+
 document.mount({
     matching: '.enhance-me',
     import: './MyEnhancement.js',
     do: 'builtIns.enhanceMountedElement'
 });
 
-// HTML
-<button class="enhance-me">Click me</button>
+// HTML
+<button class="enhance-me">Click me</button>
+
+// Access the enhancement
+const button = document.querySelector('.enhance-me');
+console.log(button.enh.buttonEnh.clickCount); // 0
+button.click();
+console.log(button.enh.buttonEnh.clickCount); // 1
+```
+
+The handler:
+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
+
+
+## Loading ES Modules from Script Elements
+
+The `builtIns.scriptNoModule` handler enables declarative module loading using `<script nomodule>` elements. This provides a way to import ES modules and JSON data directly from HTML without writing JavaScript.
+
+```html
+<!-- Load a JavaScript module -->
+<script nomodule src="./config.js" id="myConfig"></script>
+
+<!-- Load JSON data with import assertion -->
+<script nomodule src="./data.json" with-type="json" id="myData"></script>
+
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    // Handler provides matching and whereInstanceOf via static properties
+    const observer = new MountObserver({
+        do: 'builtIns.scriptNoModule'
+    });
+    observer.observe(document);
+    
+    // Access the imported modules
+    const config = document.getElementById('myConfig').export;
+    const data = document.getElementById('myData').export.default;
+    
+    console.log(config.mountConfig); // Access exported values
+    console.log(data); // Access JSON data
+</script>
+```
+
+**How it works:**
+1. The handler matches `script[nomodule][src]` elements (via static properties)
+2. Reads the `src` attribute and resolves it relative to the document
+3. Checks for optional `with-type` attribute for import assertions (e.g., `"json"`)
+4. Dynamically imports the module: `import(src, { with: { type: withType } })`
+5. Stores the imported module on `element.export`
+
+**Benefits:**
+- Declarative module loading directly in HTML
+- Supports JSON imports with `with-type="json"` attribute
+- No need to specify `matching` or `whereInstanceOf` (handler provides defaults)
+- Modules are accessible via `scriptElement.export`
+- Works with relative and absolute URLs
+
+**Use cases:**
+- Loading configuration files declaratively
+- Importing JSON data without fetch
+- Progressive enhancement with module loading
+- Declarative dependency management in HTML
+
+## Mount Observer Script Elements (MOSEs)
+
+The `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>
+```
+
+**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. Calls `scriptElement.mount(config)` with the parsed configuration
+5. The `mount()` method creates a MountObserver for that configuration
+
+**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>
+```
+
+## Hoisting Templates for Performance
+
+The `builtIns.hoistTemplate` handler optimizes template usage by moving a template element's content from shadow roots to `document.head`. This is particularly useful when templates with IDs are repeated across multiple custom elements.
+
+**Why hoist templates?**
+
+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>
+```
+
+**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>
+```
+
+### 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`
+- Cleans up cache entries when elements are garbage collected
+
+[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
+
+**Basic usage:**
+
+```html
+<fieldset disabled>
+    <label defer-for="for: #{{username}}">Username:</label>
+    <input data-id="username" type="text">
+    
+    <label defer-for="for: #{{password}}">Password:</label>
+    <input data-id="password" type="password">
+    
+    <button -id>Generate IDs</button>
+</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`, `#`, `@`, 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
+
+**Shorthand attributes:**
+
+```html
+<fieldset>
+    <!-- # uses element's tag name -->
+    <input # type="text">  <!-- becomes data-id="input" -->
+    
+    <!-- @ uses element's name attribute -->
+    <input @ name="email" type="email">  <!-- becomes data-id="email" -->
+    
+    <!-- | uses element's itemprop attribute -->
+    <span | itemprop="price">$99</span>  <!-- becomes 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
+<fieldset>
+    <!-- @ sets name attribute -->
+    <input data-id="@ username" type="text">
+    <!-- Result: id="gid-0" name="username" data-id="username" -->
+    
+    <!-- | sets itemprop attribute -->
+    <span data-id="| price">$99</span>
+    <!-- Result: id="gid-1" itemprop="price" data-id="price" -->
+    
+    <!-- $ sets itemscope and itemprop -->
+    <div data-id="$ product">...</div>
+    <!-- Result: id="gid-2" itemscope itemprop="product" data-id="product" -->
+    
+    <!-- . adds to class attribute -->
+    <div data-id=". highlight">Content</div>
+    <!-- Result: id="gid-3" class="highlight" data-id="highlight" -->
+    
+    <!-- % adds to part attribute -->
+    <div data-id="% header">Header</div>
+    <!-- Result: id="gid-4" part="header" data-id="header" -->
+    
+    <button -id>Generate IDs</button>
+</fieldset>
+```
+
+**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" defer-aria-describedby="aria-describedby: #{{emailHelp}}">
+    <span data-id="emailHelp">Enter your email address</span>
+    
+    <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:**
 
-// Access the enhancement
-const button = document.querySelector('.enhance-me');
-console.log(button.enh.buttonEnh.clickCount); // 0
-button.click();
-console.log(button.enh.buttonEnh.clickCount); // 1
-```
+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
 
-The handler:
-1. Searches the imported module for an export with a `spawn` property (the enhancement class)
-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
+**Global counter:**
 
-This works with browsers that don't support scoped custom element registries by polyfilling the `customElementRegistry` property on elements.
+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
@@ -282,6 +1077,47 @@ This polyfill in fact only supports this latter option ("matching"), and leaves
 
 [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
 
@@ -340,90 +1176,156 @@ The polyfill just loads the module into memory right away.
 > [!NOTE]
 > As a result of the google IO 2024 talks, I became aware that there is some similarity between this proposal and the [speculation rules api](https://developer.chrome.com/blog/speculation-rules-improvements).  This motivated the change to the property from "loading" to loadingEagerness above.
 
-## Separating JS imperative code from JSON serializable config
+## Importing Configuration with configFrom
 
+The `configFrom` property provides a clean way to import MountConfig settings from external modules, enabling better code organization and reusability.
 
-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:
+**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
-//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);
-      }
+// 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'));
    }
-   observer.disconnectedSignal.abort();
-}
-export {doFunction as do}
+};
+```
+
+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!';
+   }
+};
+```
 
-// observer setup
+Then reference it in your observer:
 
+```JavaScript
 const observer = new MountObserver({
-   matching:'my-element',
-   import: [
-      './my-element.js',
-      ['./my-element-small.css', {type: 'css'}],
-      './myActions.js'
-   ],
-   reference: 2
+   configFrom: './my-config.js'
 });
 observer.observe(document);
-
 ```
 
-Here "2" refers to the imported module index ('./myActions.js' in this case).
+### Multiple Configuration Modules
+
+You can import multiple config modules. Later configs override earlier ones (left-to-right merge):
 
-### How the reference property works
+```JavaScript
+const observer = new MountObserver({
+   configFrom: ['./base-config.js', './override-config.js']
+});
+```
 
-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.
+### Inline Config Takes Precedence
 
-**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
+Inline configuration always overrides imported configuration:
 
-**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 };
+```JavaScript
+const observer = new MountObserver({
+   configFrom: './base-config.js',
+   matching: '.custom-selector'  // Overrides matching from base-config.js
+});
 ```
 
-**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)
+### 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:
 
-Multiple references can also be made.
+```JavaScript
+// button-config.js
+export const mountConfig = {
+   matching: 'button',
+   whereInstanceOf: HTMLButtonElement,
+   do: (element, context) => {
+      element.addEventListener('click', () => {
+         console.log('Button clicked!');
+      });
+   }
+};
+```
 
-So for example:
+### 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.
 
-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
+**Safe pattern:**
+```JavaScript
+// config.js - Only exports configuration
+export const mountConfig = {
+   matching: '.element',
+   do: (el) => { /* ... */ }
+};
 ```
 
-[Implemented as [Requirement11](requirements/Done/Requirement11.md)]
+**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 / custom checks [TODO] out of date
+## 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({
-   select: 'div > p + p ~ span[class$="name"]', // not supported by polyfill
+   // not supported by polyfill
+   select: 'div > p + p ~ span[class$="name"]', 
    withMediaMatching: '(max-width: 1250px)',
    whereObservedRootSizeMatches: '(min-width: 700px)',
    whereElementIntersectsWith:{
@@ -436,7 +1338,9 @@ const observer = new MountObserver({
       effectiveTypeIn: ["slow-2g"],
    },
    import: ['./my-element-small.css', {type: 'css'}],
-   do: ...
+   do: function(mountedElement, ctx){
+      console.log({mountedElement, ctx});
+   }
 });
 ```
 
@@ -444,12 +1348,134 @@ const observer = new MountObserver({
 [whereObservedRootSizeMatches implemented]
 [whereElementIntersectsWith implemented]
 [whereConnectionHas implemented]
+[whereLocalNameMatches implemented as [RegularExpressionNameMatching](requirements/Done/RegularExpressionNameMatching.md)]
 
 [withMediaMatching implemented as [Requirement6](requirements/Done/Requirement6.md)]
 
+## LocalName Pattern Matching
+
+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
+const observer = new MountObserver({
+    matching: '*',  // Match all elements
+    whereLocalNameMatches: /^my-/,  // Only mount elements starting with 'my-'
+    do: (element) => {
+        console.log('Mounted:', element.localName);
+    }
+});
+observer.observe(document);
+```
+
+**String patterns are automatically converted to RegExp:**
+
+```javascript
+// These are equivalent
+whereLocalNameMatches: 'button|input'
+whereLocalNameMatches: /button|input/
+```
+
+**Common use cases:**
+
+```javascript
+// Match custom elements with a specific prefix
+whereLocalNameMatches: /^app-/
+
+// Match elements ending with a suffix
+whereLocalNameMatches: /-widget$/
+
+// Match multiple element types
+whereLocalNameMatches: /^(button|input|select)$/
+
+// Match elements containing a pattern
+whereLocalNameMatches: /dialog/
+```
+
+**AND condition logic:**
+
+Like all `where*` properties, `whereLocalNameMatches` forms an AND condition with other filters:
+
+```javascript
+const observer = new MountObserver({
+    matching: '[data-enhanced]',           // Must have data-enhanced attribute
+    whereLocalNameMatches: /^custom-/,     // AND localName starts with 'custom-'
+    whereInstanceOf: HTMLElement,          // AND is an HTMLElement instance
+    do: (element) => { /* ... */ }
+});
+```
+
+This will only mount elements that satisfy ALL three conditions.
+
+## Custom JavaScript Checks with shouldMount
+
+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.
+
+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.
+
+```javascript
+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);
+    }
+});
+```
+
+**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
+
+**Use Cases:**
+
+Authorization checks:
+```javascript
+shouldMount: (el) => currentUser.hasPermission(el.dataset.permission)
+```
+
+Feature flags:
+```javascript
+shouldMount: (el) => featureFlags.isEnabled(el.dataset.feature)
+```
+
+Data validation:
+```javascript
+shouldMount: (el) => {
+    return el.dataset.apiKey && 
+           el.dataset.apiEndpoint && 
+           el.dataset.apiKey.length > 0;
+}
+```
+
+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);
+}
+```
+
+**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.
+
+[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 +1488,67 @@ However, where this support for "whereInstanceOf" would be *most* helpful is whe
 
 -->
 
-### Referenced whereInstanceOf
+## Custom Element Registry Matching
+
+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.
 
-Similar to the `do` function, the `whereInstanceOf` check can also be moved to imported modules for 100% JSON-serializable configuration:
+**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 (Chrome 146+, latest WebKit/Safari).
 
 ```JavaScript
 import 'mount-observer/ElementMountExtension.js';
@@ -532,7 +1573,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:
 
@@ -567,14 +1608,183 @@ class MyComponent extends HTMLElement {
 Browser support: Works in all browsers, but scoped registry features require Chrome 146+ or latest WebKit/Safari.
 
 [Implemented as CustomElementRegistryMounting requirement](requirements/Done/CustomElementRegistryMounting.md).
- 
 
+### Global Propagation with `mountGlobally()`
+
+The `mountGlobally()` method extends `mount()` to automatically propagate mount observers across custom element registry 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 +1792,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 +1808,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 +1855,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 +1908,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 +1946,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 +2057,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 +2207,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 +2234,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 +2268,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 +2292,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 +2416,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 +2584,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 +2682,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 +2697,7 @@ const observer = new MountObserver({
    },
    import: './my-element.js'
 });
-```
+``` -->
 
  
 
@@ -1518,7 +2706,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 +2722,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 => {
   ...
 });