mount-observer 0.1.28 → 0.1.30

package/README.md

@@ -1555,6 +1555,264 @@ The handler looks for the nearest scope container using `.closest()`:
 
 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.
 
+## Scoped Parser Registry for EMC Scripts
+
+The scoped parser registry system enables lazy-loading of complex parsers for enhancement attributes while maintaining framework isolation. Each synthesizer element (be-hive, htmx-container, alpine-scope, etc.) maintains its own parser registry to prevent conflicts between different framework libraries.
+
+**Why use scoped parser registries?**
+
+- Lazy load complex parsers only when needed (e.g., nested-regex-groups)
+- Maintain framework isolation (HTMX, Alpine, be-hive can coexist)
+- Declarative parser loading via HTML script tags
+- Programmatic parser registration for dynamic scenarios
+- Automatic parser waiting before enhancement initialization
+- Built-in parsers remain globally available
+
+### Basic Usage - Declarative Parser Loading
+
+Load parsers declaratively using `<script type="emc-parser">` elements:
+
+```html
+<be-hive>
+    <!-- Load parser first -->
+    <script type="emc-parser" 
+            src="nested-regex-groups/parser.js" 
+            parser-name="nestedRegexGroups"></script>
+    
+    <!-- Then load enhancement that depends on it -->
+    <script type="emc" 
+            src="be-switched/emc.json" 
+            wait-for-parsers="nestedRegexGroups"></script>
+</be-hive>
+
+<script type="module">
+    import { MountObserver } from 'mount-observer/MountObserver.js';
+    
+    // Bootstrap the handlers
+    new MountObserver({
+        do: 'builtIns.emcScript'
+    }).observe(document);
+</script>
+```
+
+**What happens:**
+
+1. The `emc-parser` script loads the parser module via dynamic import
+2. Parser is registered in the be-hive element's scoped registry
+3. `parser-registered` event is dispatched
+4. The `emc` script waits for the parser to be registered
+5. Once ready, the enhancement is processed with access to the parser
+
+### Multiple Parsers
+
+Wait for multiple parsers using space-delimited names:
+
+```html
+<be-hive>
+    <script type="emc-parser" src="parser1.js" parser-name="parser1"></script>
+    <script type="emc-parser" src="parser2.js" parser-name="parser2"></script>
+    
+    <!-- Wait for both parsers -->
+    <script type="emc" 
+            src="my-enhancement/emc.json" 
+            wait-for-parsers="parser1 parser2"></script>
+</be-hive>
+```
+
+### Custom Timeout
+
+Configure parser loading timeout (default: 60 seconds):
+
+```html
+<be-hive>
+    <script type="emc-parser" src="slow-parser.js" parser-name="slowParser"></script>
+    
+    <!-- Wait up to 2 minutes -->
+    <script type="emc" 
+            src="my-enhancement/emc.json" 
+            wait-for-parsers="slowParser"
+            data-parser-timeout="120000"></script>
+</be-hive>
+```
+
+### Programmatic Parser Registration
+
+Register parsers programmatically via JavaScript:
+
+```html
+<be-hive id="myHive">
+    <script type="emc" 
+            src="my-enhancement/emc.json" 
+            wait-for-parsers="customParser"></script>
+</be-hive>
+
+<script type="module">
+    import { registerParser } from 'assign-gingerly/parserRegistry.js';
+    
+    // Load parser programmatically
+    const parser = await import('./custom-parser.js');
+    const beHive = document.getElementById('myHive');
+    
+    registerParser(beHive, 'customParser', parser.default);
+</script>
+```
+
+### Parser Interface
+
+Parsers are simple functions that transform attribute string values:
+
+```javascript
+// my-parser.js
+export default function parse(value) {
+    // Transform the string value
+    if (value === null) return null;
+    
+    // Your parsing logic here
+    return parsedValue;
+}
+```
+
+**Requirements:**
+- Parser must be a function with signature `(v: string | null) => any`
+- Must be exported as the default export
+- Should handle `null` values appropriately
+- Should throw descriptive errors for invalid input
+
+### Scoped vs Global Parsers
+
+**Scoped parsers** (registered in be-hive elements):
+- Isolated to a specific synthesizer element and its descendants
+- Different frameworks can use the same parser names without conflicts
+- Registered via `emc-parser` scripts or `registerParser()`
+
+**Global parsers** (built-in):
+- Available everywhere without registration
+- Includes: `timestamp`, `date`, `csv`, `int`, `float`, `boolean`, `json`
+- Fallback when parser not found in scoped registry
+
+**Resolution order:**
+1. Check scoped registry (if synthesizer element exists)
+2. Fall back to global registry
+3. Throw error if not found in either
+
+### Shadow DOM Syndication
+
+Parser registries are scoped to synthesizer elements and apply to all shadow roots within that scope:
+
+```html
+<!-- Syndicator in document root -->
+<be-hive>
+    <script type="emc-parser" src="parser.js" parser-name="myParser"></script>
+    <script type="emc" src="enhancement/emc.json" wait-for-parsers="myParser"></script>
+</be-hive>
+
+<!-- Component with shadow root -->
+<my-component>
+    #shadow
+        <!-- Subscriber receives scripts from syndicator -->
+        <be-hive></be-hive>
+        
+        <!-- Elements here can use the parser -->
+        <div be-switched="...">Content</div>
+</my-component>
+```
+
+**How it works:**
+1. Parser script is syndicated to shadow root's be-hive
+2. Parser is registered in the shadow root's scoped registry
+3. EMC script is syndicated and waits for parser
+4. Enhancements in shadow root have access to the parser
+
+### Error Handling
+
+**Parser loading errors:**
+
+```html
+<!-- Parser module fails to load -->
+<script type="emc-parser" 
+        src="broken-parser.js" 
+        parser-name="broken"
+        data-parser-error="Module not found"></script>
+```
+
+**Parser waiting timeout:**
+
+```html
+<!-- EMC script times out waiting for parser -->
+<script type="emc" 
+        src="my-enhancement/emc.json" 
+        wait-for-parsers="missingParser"
+        data-emc-error="Timeout waiting for parsers: missingParser"></script>
+```
+
+**Error messages include:**
+- Which parser(s) are missing
+- Which EMC script is waiting
+- Suggestions to check parser-name and script order
+
+### Complete Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <script type="module">
+        import { MountObserver } from 'mount-observer/MountObserver.js';
+        import { Synthesizer } from 'mount-observer/Synthesizer.js';
+        
+        // Define synthesizer element
+        class BeHive extends Synthesizer {}
+        customElements.define('be-hive', BeHive);
+    </script>
+</head>
+<body>
+    <!-- Syndicator with parser and enhancement -->
+    <be-hive>
+        <!-- Load complex parser -->
+        <script type="emc-parser" 
+                src="nested-regex-groups/parser.js" 
+                parser-name="nestedRegexGroups"></script>
+        
+        <!-- Enhancement that uses the parser -->
+        <script type="emc" 
+                src="be-switched/emc.json" 
+                wait-for-parsers="nestedRegexGroups"></script>
+    </be-hive>
+    
+    <!-- Component using the enhancement -->
+    <my-component>
+        #shadow
+            <be-hive></be-hive>
+            
+            <!-- This element will be enhanced -->
+            <div be-switched="case1: /pattern1/ | case2: /pattern2/">
+                Content
+            </div>
+    </my-component>
+</body>
+</html>
+```
+
+### Benefits
+
+- **Lazy loading**: Load parsers only when needed
+- **Framework isolation**: Different frameworks don't conflict
+- **Declarative**: HTML-first approach with script tags
+- **Flexible**: Supports both declarative and programmatic registration
+- **Automatic**: Parser waiting handled by the framework
+- **Scoped**: Each synthesizer has its own parser registry
+- **Efficient**: Parsers are cached and reused
+
+### Requirements
+
+- Must import `mount-observer/handlers/EMCParserScript.js` for parser loading
+- Must import `mount-observer/handlers/EMCScript.js` for EMC processing
+- Must use a synthesizer element (be-hive, etc.) for scoped registries
+- Parser modules must export a function as default export
+- EMC scripts must specify `wait-for-parsers` attribute to wait for parsers
+
+[Implemented as Scoped Parser Registry requirement](.kiro/specs/scoped-parser-registry-requirements.md)
+
 
 # Thorough Exposition Begins Here
 

package/Synthesizer.js

@@ -11,6 +11,8 @@ import 'mount-observer/handlers/HoistTemplate.js';
 import { hoist } from 'mount-observer/handlers/HoistTemplate.js';
 import { emc } from 'mount-observer/handlers/EMCScript.js';
 import 'mount-observer/handlers/EMCScript.js';
+import 'mount-observer/handlers/EMCParserScript.js';
+import { emcParser } from 'mount-observer/handlers/EMCParserScript.js';
 /**
  * Track which root nodes have already had handlers activated.
  * Uses WeakSet to avoid memory leaks when nodes are garbage collected.
@@ -53,7 +55,7 @@ export class Synthesizer extends HTMLElement {
      * List of built-in handlers to activate.
      */
     static builtInHandlers = [
-        mos, scriptExport, include, hoist, emc
+        mos, scriptExport, include, hoist, emcParser, emc
     ];
     connectedCallback() {
         // Synthesizer elements are infrastructure, not UI
@@ -145,7 +147,7 @@ export class Synthesizer extends HTMLElement {
      */
     #initializeSyndicator() {
         // Process existing script elements
-        const scripts = this.querySelectorAll('script[type="mountobserver"], script[type="emc"]');
+        const scripts = this.querySelectorAll('script[type="mountobserver"], script[type="emc"], script[type="emc-parser"]');
         scripts.forEach(script => {
             if (this.checkIfAllowed(script)) {
                 this.#broadcastScript(script);
@@ -157,7 +159,7 @@ export class Synthesizer extends HTMLElement {
                 for (const node of mutation.addedNodes) {
                     if (node instanceof HTMLScriptElement) {
                         const type = node.getAttribute('type');
-                        if (type === 'mountobserver' || type === 'emc') {
+                        if (type === 'mountobserver' || type === 'emc' || type === 'emc-parser') {
                             if (this.checkIfAllowed(node)) {
                                 this.#broadcastScript(node);
                             }
@@ -190,7 +192,7 @@ export class Synthesizer extends HTMLElement {
         }
         // Process existing scripts from syndicator
         // Only process scripts that pass the syndicator's filtering
-        const scripts = syndicator.querySelectorAll('script[type="mountobserver"], script[type="emc"]');
+        const scripts = syndicator.querySelectorAll('script[type="mountobserver"], script[type="emc"], script[type="emc-parser"]');
         scripts.forEach(script => {
             if (syndicator.checkIfAllowed(script)) {
                 this.#processScript(script);

package/Synthesizer.ts

@@ -12,6 +12,8 @@ import 'mount-observer/handlers/HoistTemplate.js';
 import {hoist} from 'mount-observer/handlers/HoistTemplate.js';
 import {emc} from 'mount-observer/handlers/EMCScript.js';
 import 'mount-observer/handlers/EMCScript.js';
+import 'mount-observer/handlers/EMCParserScript.js';
+import {emcParser} from 'mount-observer/handlers/EMCParserScript.js';
 
 /**
  * Track which root nodes have already had handlers activated.
@@ -57,7 +59,7 @@ export abstract class Synthesizer extends HTMLElement {
      * List of built-in handlers to activate.
      */
     protected static builtInHandlers = [
-        mos, scriptExport, include, hoist, emc
+        mos, scriptExport, include, hoist, emcParser, emc
     ];
 
     connectedCallback(): void {
@@ -164,7 +166,7 @@ export abstract class Synthesizer extends HTMLElement {
      */
     #initializeSyndicator(): void {
         // Process existing script elements
-        const scripts = this.querySelectorAll('script[type="mountobserver"], script[type="emc"]');
+        const scripts = this.querySelectorAll('script[type="mountobserver"], script[type="emc"], script[type="emc-parser"]');
         scripts.forEach(script => {
             if (this.checkIfAllowed(script as HTMLScriptElement)) {
                 this.#broadcastScript(script as HTMLScriptElement);
@@ -177,7 +179,7 @@ export abstract class Synthesizer extends HTMLElement {
                 for (const node of mutation.addedNodes) {
                     if (node instanceof HTMLScriptElement) {
                         const type = node.getAttribute('type');
-                        if (type === 'mountobserver' || type === 'emc') {
+                        if (type === 'mountobserver' || type === 'emc' || type === 'emc-parser') {
                             if (this.checkIfAllowed(node)) {
                                 this.#broadcastScript(node);
                             }
@@ -215,7 +217,7 @@ export abstract class Synthesizer extends HTMLElement {
         
         // Process existing scripts from syndicator
         // Only process scripts that pass the syndicator's filtering
-        const scripts = syndicator.querySelectorAll('script[type="mountobserver"], script[type="emc"]');
+        const scripts = syndicator.querySelectorAll('script[type="mountobserver"], script[type="emc"], script[type="emc-parser"]');
         scripts.forEach(script => {
             if (syndicator.checkIfAllowed(script as HTMLScriptElement)) {
                 this.#processScript(script as HTMLScriptElement);

package/handlers/EMCParserScript.js

@@ -0,0 +1,108 @@
+import { EvtRt } from '../EvtRt.js';
+import { getParserRegistry } from 'assign-gingerly/parserRegistry.js';
+/**
+ * Handler for EMC Parser Script Elements.
+ * Processes script[type="emc-parser"] elements to load and register parser modules
+ * in the containing synthesizer element's scoped parser registry.
+ *
+ * Usage:
+ * <script type="emc-parser" src="./my-parser.js" parser-name="myParser"></script>
+ *
+ * The parser module should export a parser function as the default export:
+ * export default function myParser(v: string | null): any { ... }
+ */
+export class EMCParserScriptHandler extends EvtRt {
+    // Static properties define default MountConfig constraints
+    static matching = 'script[type="emc-parser"]';
+    static whereInstanceOf = HTMLScriptElement;
+    async mount(mountedElement, mountConfig, context) {
+        this.abort(); // Clean up event listeners (one-time operation)
+        const scriptElement = mountedElement;
+        // Read required attributes
+        const src = scriptElement.getAttribute('src');
+        const parserName = scriptElement.getAttribute('parser-name');
+        // Validate required attributes
+        if (!src) {
+            const errorMsg = 'EMCParserScript: missing src attribute';
+            console.error(errorMsg, scriptElement);
+            scriptElement.setAttribute('data-parser-error', 'missing src attribute');
+            return;
+        }
+        if (!parserName) {
+            const errorMsg = 'EMCParserScript: missing parser-name attribute';
+            console.error(errorMsg, scriptElement);
+            scriptElement.setAttribute('data-parser-error', 'missing parser-name attribute');
+            return;
+        }
+        // Find containing synthesizer element
+        const synthesizerElement = this.findContainingSynthesizer(scriptElement);
+        if (!synthesizerElement) {
+            const errorMsg = 'EMCParserScript: no containing synthesizer element found';
+            console.error(errorMsg, scriptElement);
+            scriptElement.setAttribute('data-parser-error', 'no containing synthesizer element');
+            return;
+        }
+        try {
+            // Dynamic import the parser module
+            const module = await import(src);
+            // Get parser function from default export
+            const parser = module.default;
+            // Validate parser is a function
+            if (typeof parser !== 'function') {
+                throw new Error(`Parser module "${src}" must export a function as default export. ` +
+                    `Received: ${typeof parser}`);
+            }
+            // Get scoped registry and register parser
+            const registry = getParserRegistry(synthesizerElement);
+            registry.register(parserName, parser);
+            // Dispatch parser-registered event
+            scriptElement.dispatchEvent(new CustomEvent('parser-registered', {
+                detail: { parserName },
+                bubbles: true
+            }));
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            console.error(`Failed to load parser "${parserName}" from "${src}":`, errorMessage);
+            scriptElement.setAttribute('data-parser-error', errorMessage);
+        }
+    }
+    /**
+     * Find the nearest ancestor synthesizer element.
+     * Traverses up through shadow root boundaries.
+     * Looks for elements with data-synthesizer attribute, be-hive tag, or __isSynthesizer property.
+     */
+    findContainingSynthesizer(element) {
+        let current = element;
+        while (current) {
+            if (current instanceof Element) {
+                // Check for synthesizer marker or known synthesizer tag names
+                if (current.hasAttribute('data-synthesizer') ||
+                    current.localName === 'be-hive' ||
+                    current.__isSynthesizer === true) {
+                    return current;
+                }
+            }
+            // Try parent element
+            if (current.parentElement) {
+                current = current.parentElement;
+            }
+            // Try shadow root host
+            else if (current instanceof ShadowRoot) {
+                current = current.host;
+            }
+            // Try parent node (for document fragments)
+            else if (current.parentNode) {
+                current = current.parentNode;
+            }
+            else {
+                break;
+            }
+        }
+        return undefined;
+    }
+}
+// Register built-in handler
+import { MountObserver } from '../MountObserver.js';
+export const emcParser = 'builtIns.emcParserScript';
+MountObserver.define(emcParser, EMCParserScriptHandler);

package/handlers/EMCParserScript.ts

@@ -76,8 +76,6 @@ export class EMCParserScriptHandler extends EvtRt {
                 bubbles: true
             }));
             
-            console.log(`Registered parser "${parserName}" from ${src}`);
-            
         } catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
             console.error(`Failed to load parser "${parserName}" from "${src}":`, errorMessage);

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "mount-observer",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Observe and act on css matches.",
   "main": "MountObserver.js",
   "module": "MountObserver.js",
   "dependencies": {
-    "assign-gingerly": "0.0.27",
+    "assign-gingerly": "0.0.28",
     "id-generation": "0.0.4"
   },
   "devDependencies": {

package/types/assign-gingerly/types.d.ts

@@ -112,7 +112,7 @@ export type ParserFunction<T = any> =
   | ((attrValue: string | null) => any)
   | ((attrValue: string | null, context?: ParserContext<T>) => any);
 
-export interface AttrConfig<T = any> {
+export interface AttrConfig<T = unknown, TParserConfig = unknown> {
   /**
    * Type of the property value (JSON-serializable string format)
    */
@@ -152,6 +152,12 @@ export interface AttrConfig<T = any> {
     | ParserFunction<T>
     | string
   ;
+
+  /**
+   * configuration information needed by a custom parser to properly
+   * parse the attribute.
+   */
+  parserConfig?: TParserConfig;
   
   /**
    * Default value to use when attribute is missing

package/types/do-invoke/types.d.ts

@@ -0,0 +1,28 @@
+export interface Specifier {
+    selector?: string;
+    prop?: string;
+}
+
+export interface EndUserProps{
+    invokeParamSets: Array<InvokingParameters>,
+}
+
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element;
+    rawStatements: Array<string>,
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP  = Promise<PAP>
+
+export interface Actions{
+    hydrate(self: AP): ProPAP;
+}
+
+export interface InvokingParameters {
+    remoteSpecifier: Specifier,
+    localEventType?: string,
+}

package/types/nested-regex-groups/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Type definitions for nested-regex-groups
+ * 
+ * These types can be imported in JavaScript files using JSDoc:
+ * @example
+ * // In JavaScript:
+ * /** @type {import('nested-regex-groups').ParseResult} *\/
+ * const result = parser('input');
+ */
+
+/**
+ * Result of a successful parse operation
+ */
+export interface ParseSuccess<T = any> {
+  success: true;
+  value: T;
+  matched: string;
+  rest: string;
+}
+
+/**
+ * Result of a failed parse operation
+ */
+export interface ParseFailure {
+  success: false;
+  error: string;
+  position?: number;
+}
+
+/**
+ * Union type for parse results
+ */
+export type ParseResult<T = any> = ParseSuccess<T> | ParseFailure;
+
+/**
+ * A pattern definition with metadata (internal use with compiled RegExp)
+ */
+export interface ParsePattern {
+  name: string;
+  regex: RegExp;
+  description?: string;
+  /**
+   * Optional mapping from regex group names to dot-notation paths
+   * Example: { user_name: 'user.name', user_domain: 'user.domain' }
+   */
+  groupMap?: Record<string, string>;
+}
+
+/**
+ * Pattern configuration for parsePatterns and parsePattern functions
+ * Used when loading patterns from JSON or defining patterns as strings
+ */
+export interface PatternConfig {
+  name: string;
+  pattern: string;
+  description?: string;
+}
+
+/**
+ * Options for nestedRegex function
+ */
+export interface NestedRegexOptions {
+  /**
+   * Optional name for the pattern (used in error messages)
+   */
+  name?: string;
+  /**
+   * Optional mapping from regex group names to dot-notation paths
+   * Example: { user_name: 'user.name', user_domain: 'user.domain' }
+   */
+  groupMap?: Record<string, string>;
+}
+
+/**
+ * Options for creating a parser
+ */
+export interface ParserOptions {
+  /**
+   * If true, returns detailed error information when no pattern matches
+   */
+  verbose?: boolean;
+}
+
+/**
+ * Result type for parsing multiple statements
+ */
+export interface StatementsResult<T = any> {
+  success: boolean;
+  statements: Array<{
+    pattern?: string;
+    value?: T;
+    error?: string;
+    matched?: string;
+  }>;
+}