mount-observer-script-element 0.0.1

package/.hintrc

@@ -0,0 +1,15 @@
+{
+  "extends": [
+    "development"
+  ],
+  "hints": {
+    "compat-api/html": [
+      "default",
+      {
+        "ignore": [
+          "template[shadowrootmode]"
+        ]
+      }
+    ]
+  }
+}

package/.kiro/steering/tech.md

@@ -0,0 +1,251 @@
+# Technology Stack
+
+## Language & Build System
+
+- **Primary Language**: TypeScript (compiled to JavaScript ES modules)
+- **Target**: ESNext with strict mode enabled
+- **Module System**: ES Modules (ESM)
+- **No Build Tool**: TypeScript compiler only, no bundler (Webpack, Rollup, etc.)
+
+## TypeScript Configuration
+
+- Strict mode enabled
+- Experimental decorators: false
+- Source maps: disabled
+- Line endings: LF (Unix-style)
+- Skip lib check: true
+
+## Testing
+
+- **Test Framework**: Playwright (browser automation testing)
+- **Test Files**: Located in `tests/` directory with `.spec.mjs` extension
+- **HTML Test Files**: Corresponding `.html` files for each test spec
+
+## Dependencies
+
+- **Runtime**: None (zero runtime dependencies)
+- **Dev Dependencies**: 
+  - `@playwright/test` - Browser testing
+  - `spa-ssi` - Development server
+
+## Common Commands
+
+```bash
+# Install dependencies
+npm ci
+
+# Run tests
+npm test
+
+# Start development server
+npm run serve
+
+# Run Safari browser tests
+npm run safari
+
+# Update dependencies
+npm run update
+```
+
+## Compilation
+
+TypeScript files are compiled to JavaScript using `tsc`. Both `.ts` and `.js` files are committed to the repository. The JavaScript files are the actual runtime artifacts.
+
+**CRITICAL**: Always compile TypeScript using the configuration in `tsconfig.json`:
+```bash
+tsc
+```
+
+Do NOT use `tsc` with individual file arguments or custom flags. The `tsconfig.json` contains the correct compiler settings for the entire project.
+
+**Legacy Folder**: The `legacy/` folder contains old code that is not maintained. Do not expect files in the `legacy/` folder to compile or pass tests. Focus only on the root-level code and tests.
+
+## Type Definition Files
+
+**Type-Only Files**: Files containing only TypeScript type definitions should use the `.d.ts` extension and must not generate a `.js` file when compiled.
+
+**Key Rules**:
+- Type definition files must end with `.d.ts` (e.g., `types.d.ts`)
+- `.d.ts` files should contain only types, interfaces, and type aliases
+- Never include runtime values (constants, functions, classes) in `.d.ts` files
+- Constants and runtime values belong in separate `.ts` files that compile to `.js`
+
+**Pattern**:
+```typescript
+// types.d.ts - Type definitions only
+export interface MountInit {
+    whereElementMatches: string;
+}
+export type mountEventName = 'mount';
+
+// constants.ts - Runtime values
+export const mountEventName = 'mount';
+export const dismountEventName = 'dismount';
+```
+
+**Why this matters**:
+- Prevents unnecessary `.js` files from being generated for type-only code
+- Keeps type definitions separate from runtime code
+- Follows TypeScript best practices for library distribution
+- Reduces bundle size by excluding type-only code from runtime
+
+**When to apply**:
+- Creating files that only contain TypeScript types, interfaces, or type aliases
+- Separating type definitions from implementation
+- Defining public API types for library consumers
+
+## Custom Event Classes
+
+**Event Classes over CustomEvent**: When dispatching events, define custom classes that extend the Event class rather than using CustomEvent with detail objects.
+
+**Key Rules**:
+- Create dedicated event classes that extend Event
+- Define event properties as public class members
+- Include a static eventName property for the event type string
+- Export corresponding interfaces for type safety
+
+**Pattern**:
+```typescript
+// Events.ts - Event class definitions
+export class MountEvent extends Event implements IMountEvent {
+    static eventName: mountEventName = 'mount';
+    
+    constructor(public mountedElement: Element, public modules: any[]) {
+        super(MountEvent.eventName);
+    }
+}
+
+// Usage in code
+this.dispatchEvent(new MountEvent(element, modules));
+
+// Listening with proper typing
+observer.addEventListener('mount', (e: MountEvent) => {
+    console.log(e.mountedElement, e.modules);
+});
+```
+
+**Why this matters**:
+- CustomEvent is a legacy approach that uses untyped detail objects
+- Custom event classes provide better type safety and IDE autocomplete
+- Properties are directly accessible without going through event.detail
+- Follows modern JavaScript/TypeScript best practices
+- Makes the API more discoverable and self-documenting
+
+**When to apply**:
+- All event dispatching in the library
+- When defining public event APIs
+- When you need strongly-typed event data
+
+## Code Splitting Principle
+
+**Conditional Code Loading**: If a significant block of code (>6 lines) only executes based on optional configuration settings, extract it to a separate module and load it dynamically using `import()`.
+
+**Benefits**:
+- Reduces initial bundle size for users who don't need the feature
+- Improves tree-shaking effectiveness
+- Keeps core modules lean and focused
+
+**Example**:
+```typescript
+// Instead of including all import logic in MountObserver
+async #loadImports(): Promise<void> {
+    // Dynamically load only when MountInit.import is specified
+    const { loadImports } = await import('./loadImports.js');
+    this.#modules = await loadImports(this.#init.import);
+}
+```
+
+**When to apply**:
+- Feature-specific utilities (e.g., import loading, intersection observers)
+- Complex conditional logic blocks
+- Optional API surface areas
+- Heavy dependencies used conditionally
+
+## Memory Management
+
+**WeakRef for DOM Nodes**: Store references to DOM nodes (especially observed root nodes) as `WeakRef<Node>` to prevent memory leaks when nodes are removed from the document.
+
+**Why this matters**:
+- If a MountObserver instance outlives the observed DOM subtree, a strong reference would prevent garbage collection
+- Shadow roots and detached fragments are particularly vulnerable
+- WeakRef allows the DOM to be GC'd even if the observer is still referenced
+
+**Pattern**:
+```typescript
+class MountObserver {
+    #rootNode: WeakRef<Node> | undefined;
+    
+    observe(rootNode: Node): void {
+        this.#rootNode = new WeakRef(rootNode);
+        // Use rootNode directly here while it's in scope
+    }
+    
+    someMethod(): void {
+        const rootNode = this.#rootNode?.deref();
+        if (!rootNode) {
+            // Node was garbage collected, handle gracefully
+            return;
+        }
+        // Use rootNode
+    }
+}
+```
+
+**When to apply**:
+- Storing references to observed DOM nodes
+- Caching DOM elements that might be removed
+- Any long-lived object holding DOM references
+
+## Package Exports
+
+The package uses conditional exports in package.json, providing both default (JS) and types (TS) for each module. Main entry point is `MountObserver.js`.
+
+## Bare Specifier Imports & Import Maps
+
+**Import Pattern for Node Dependencies**: This package uses bare specifiers with explicit `.js` extensions when importing from node_modules dependencies.
+
+**Example**:
+```typescript
+import { assignGingerly } from 'assign-gingerly/assignGingerly.js';
+```
+
+**Key Rules**:
+- Always include the `.js` extension in bare specifier imports
+- Use the full path including the file (e.g., `/index.js`)
+- This works natively in browsers via import maps
+
+**Import Map Setup**: The project uses server-side includes (SSI) to inject import maps into HTML files during development.
+
+**Pattern**:
+```html
+<!-- In demo/test HTML files -->
+<!-- #include virtual="/imports.html" -->
+```
+
+**What this does**:
+- The `spa-ssi` development server (configured in `package.json` scripts) processes SSI directives
+- The `imports.html` file at the project root contains the import map
+- The import map maps bare specifiers to `/node_modules/` paths
+- This enables native browser support for bare imports without bundling
+
+**Import Map Structure** (`imports.html`):
+```html
+<script type=importmap>
+{
+    "imports": {
+        "assign-gingerly/": "/node_modules/assign-gingerly/"
+    }
+}
+</script>
+```
+
+**Benefits**:
+- No build step required for development
+- Native ES modules work directly in the browser
+- Dependencies resolve naturally via import maps
+- Matches production CDN patterns (e.g., unpkg, esm.sh)
+
+**When to apply**:
+- All imports from node_modules dependencies
+- Demo and test HTML files need the SSI include directive
+- Import map must be updated when adding new dependencies

package/.vscode/settings.json

@@ -0,0 +1,2 @@
+{
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruce B. Anderson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MOSE.js

@@ -0,0 +1,189 @@
+import { getHighestCERNode } from './getHighestCERNode.js';
+import { MountObserver } from 'mount-observer/MountObserver.js';
+import { mountEventName } from 'mount-observer/Events.js';
+/**
+ * Symbol to track if MountObserver has been set up for an element
+ */
+const MOUNT_OBSERVER_SETUP = Symbol.for('cteH9dMG-UWwxVaMwFgvQA');
+/**
+ * MOSE (Mount Observer Script Element) Mixin
+ *
+ * This mixin adds functionality to:
+ * 1. Check for duplicate custom element registrations within the same custom element registry scope
+ * 2. Monitor for <script type="mountobserver"> elements and apply their configurations
+ *
+ * @param Base - The base class to extend
+ * @returns Extended class with MOSE functionality
+ */
+export function MOSE(Base) {
+    return class extends Base {
+        #mountObserver;
+        constructor(...args) {
+            super(...args);
+            this.#checkForDuplicateRegistration();
+            this.#setupMountObserver();
+        }
+        #checkForDuplicateRegistration() {
+            // Get the tag name of this element
+            // const tagName = this.tagName.toLowerCase();
+            const { localName } = this;
+            // Find the highest node with the same custom element registry
+            const highestCERNode = getHighestCERNode(this);
+            if (!highestCERNode) {
+                return;
+            }
+            // Get the custom element registry for this scope
+            // const registry = (highestCERNode as any).customElementRegistry as CustomElementRegistry | undefined;
+            // // If there's no custom registry, use the global one
+            // const targetRegistry = registry || customElements;
+            // Check if an element with this name is already defined in this registry
+            try {
+                const existingTags = Array.from(highestCERNode.querySelectorAll(localName)).filter(x => x !== this);
+                if (existingTags.length > 0) {
+                    throw new Error(`Custom element "${localName}" is already defined in this custom element registry scope.`);
+                }
+            }
+            catch (error) {
+                // If get() throws, it means the element isn't registered yet, which is fine
+                // But if it's our error, re-throw it
+                if (error instanceof Error && error.message.includes('already defined')) {
+                    throw error;
+                }
+            }
+            // Copy mountobserver script elements from container
+            this.#getContainerMOSEs(highestCERNode);
+        }
+        #getContainerMOSEs(highestCERNode) {
+            // Step 1: Don't do anything if highestCERNode is the document root
+            if (highestCERNode === document) {
+                return;
+            }
+            // Step 2: Get parent element or host
+            let parentNode = null;
+            if (highestCERNode instanceof Element) {
+                parentNode = highestCERNode.parentElement;
+            }
+            else if (highestCERNode instanceof ShadowRoot) {
+                parentNode = highestCERNode.host;
+            }
+            if (!parentNode) {
+                return;
+            }
+            // Step 3: Find the highestCERNode of the parent
+            const parentHighestCERNode = getHighestCERNode(parentNode);
+            // Find parent custom element with same localName
+            if (!parentHighestCERNode || !('querySelector' in parentHighestCERNode)) {
+                return;
+            }
+            const parentCE = parentHighestCERNode.querySelector(this.localName);
+            if (!parentCE) {
+                return;
+            }
+            // If highestCERNode contains parentCE, exit
+            if (highestCERNode.contains?.(parentCE)) {
+                return;
+            }
+            // Clone and append script elements
+            this.#cloneAndAppendScripts(parentCE);
+            // Add event listener for future mount events
+            parentCE.addEventListener(mountEventName, (e) => {
+                const mountedElement = e.mountedElement;
+                if (mountedElement instanceof HTMLScriptElement && mountedElement.type === 'mountobserver') {
+                    this.#cloneAndAppendScripts(parentCE);
+                }
+            });
+        }
+        #cloneAndAppendScripts(sourceElement) {
+            const scripts = Array.from(sourceElement.querySelectorAll('script[type="mountobserver"]'));
+            // Get exclude value from property or attribute
+            const exclude = this.exclude ?? this.getAttribute('exclude');
+            for (const script of scripts) {
+                // Check if script matches exclude criteria
+                if (exclude && script.matches(exclude)) {
+                    continue;
+                }
+                const src = script.getAttribute('src');
+                // Check if we already have a script with the same src
+                const existingScripts = Array.from(this.querySelectorAll('script[type="mountobserver"]'));
+                const alreadyExists = existingScripts.some(existing => {
+                    const existingSrc = existing.getAttribute('src');
+                    return existingSrc === src;
+                });
+                if (!alreadyExists) {
+                    const clonedScript = script.cloneNode(true);
+                    this.appendChild(clonedScript);
+                }
+            }
+        }
+        async #setupMountObserver() {
+            // Find the highest node with the same custom element registry
+            const highestCERNode = getHighestCERNode(this);
+            if (!highestCERNode) {
+                return;
+            }
+            // Check if MountObserver has already been set up for this element
+            const existingObserver = highestCERNode[MOUNT_OBSERVER_SETUP];
+            if (existingObserver) {
+                // Subscribe to the existing observer's mount event and re-dispatch from this element
+                existingObserver.addEventListener(mountEventName, (e) => {
+                    const { mountedElement } = e;
+                    if (this.contains(mountedElement)) {
+                        this.dispatchEvent(e);
+                    }
+                });
+                return;
+            }
+            // Set up MountObserver to watch for <script type="mountobserver"> elements
+            this.#mountObserver = new MountObserver({
+                whereElementMatches: 'script[type="mountobserver"]',
+                do: async (scriptElement) => {
+                    await this.#processScriptElement(scriptElement, highestCERNode);
+                }
+            });
+            // Mark that we've set up the MountObserver for this element
+            highestCERNode[MOUNT_OBSERVER_SETUP] = this.#mountObserver;
+            await this.#mountObserver.observe(highestCERNode);
+        }
+        async #processScriptElement(scriptElement, rootNode) {
+            let config = {};
+            // Step 1: Check if script has src attribute and load JSON
+            const src = scriptElement.getAttribute('src');
+            if (src) {
+                try {
+                    const response = await import(src, { with: { type: 'json' } });
+                    config = structuredClone(response.default);
+                }
+                catch (error) {
+                    console.error(`Failed to load JSON from ${scriptElement.src}:`, error);
+                    return;
+                }
+            }
+            // Step 2: If innerHTML is non-trivial, parse and merge it
+            const innerHTML = scriptElement.innerHTML.trim();
+            if (innerHTML) {
+                try {
+                    const parsedJSON = JSON.parse(innerHTML);
+                    // Step 3: Import assignGingerly and merge
+                    const { assignGingerly } = await import('assign-gingerly/assignGingerly.js');
+                    config = assignGingerly(config, parsedJSON, {
+                        registry: scriptElement.customElementRegistry.assignGingerlyRegistry
+                    });
+                }
+                catch (error) {
+                    console.error('Failed to parse script innerHTML as JSON:', error);
+                    return;
+                }
+            }
+            // Step 4: Apply MountObserver with the merged config
+            if (Object.keys(config).length > 0) {
+                try {
+                    const observer = new MountObserver(config);
+                    observer.observe(rootNode);
+                }
+                catch (error) {
+                    console.error('Failed to create MountObserver with config:', error);
+                }
+            }
+        }
+    };
+}