mount-observer 0.1.26 → 0.1.28

package/handlers/EMCParserScript.ts

@@ -0,0 +1,132 @@
+import { EvtRt } from '../EvtRt.js';
+import { MountConfig, MountContext } from '../types/mount-observer/types.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: Element, mountConfig: MountConfig, context: MountContext): Promise<void> {
+        this.abort(); // Clean up event listeners (one-time operation)
+        
+        const scriptElement = mountedElement as HTMLScriptElement;
+        
+        // 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
+            }));
+            
+            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);
+            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.
+     */
+    private findContainingSynthesizer(element: Element): Element | undefined {
+        let current: Node | null = 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 as any).__isSynthesizer === true) {
+                    return current;
+                }
+            }
+            
+            // Try parent element
+            if (current.parentElement) {
+                current = current.parentElement;
+            }
+            // Try shadow root host
+            else if (current instanceof ShadowRoot) {
+                current = (current as ShadowRoot).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/EMCScript.js

@@ -1,6 +1,7 @@
 import { EvtRt } from '../EvtRt.js';
 import '../ElementMountExtension.js';
 import 'assign-gingerly/object-extension.js';
+import { getParserRegistry } from 'assign-gingerly/parserRegistry.js';
 /**
  * Handler for EMC (Element Mount Configuration) Script Elements.
  * Processes script[type="emc"] elements to declaratively configure element enhancements.
@@ -18,6 +19,29 @@ export class EMCScriptHandler extends EvtRt {
     async mount(mountedElement, MountConfig, context) {
         this.abort(); // Clean up event listeners (one-time operation)
         const scriptElement = mountedElement;
+        // Find containing synthesizer element early (needed for parser waiting)
+        const synthesizerElement = this.findContainingSynthesizer(scriptElement);
+        // Check for parser waiting before processing EMC config
+        const waitForParsers = scriptElement.getAttribute('wait-for-parsers');
+        if (waitForParsers && synthesizerElement) {
+            const parserNames = waitForParsers.trim().split(/\s+/).filter(name => name.length > 0);
+            if (parserNames.length > 0) {
+                // Read timeout attribute (default: 60000ms = 1 minute)
+                const timeoutAttr = scriptElement.getAttribute('data-parser-timeout');
+                const timeout = timeoutAttr ? parseInt(timeoutAttr, 10) : 60000;
+                try {
+                    // Get scoped registry and wait for parsers
+                    const registry = getParserRegistry(synthesizerElement);
+                    await registry.waitFor(parserNames, timeout);
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    console.error(`Parser waiting failed for EMC script:`, errorMessage, scriptElement);
+                    scriptElement.setAttribute('data-emc-error', errorMessage);
+                    return; // Stop processing on timeout/error
+                }
+            }
+        }
         let emcConfig = scriptElement.export;
         if (!emcConfig) {
             // Check if script has src attribute
@@ -68,14 +92,14 @@ export class EMCScriptHandler extends EvtRt {
             scriptElement.id = `${scriptElement.parentElement.localName}.${enhKey}`;
         }
         // Construct MountConfig from EMC config and mount it
-        const mountConfig = await this.buildMountConfig(emcConfig);
+        const mountConfig = await this.buildMountConfig(emcConfig, synthesizerElement);
         await scriptElement.mount(mountConfig);
     }
     /**
      * Build a MountConfig from an EMC config.
      * Combines the matching selector with withAttrs if present.
      */
-    async buildMountConfig(emcConfig) {
+    async buildMountConfig(emcConfig, synthesizerElement) {
         const { enhConfig, ...mountConfigBase } = emcConfig;
         let matching = mountConfigBase.matching || '';
         // If withAttrs is defined, use buildCSSQuery to combine with matching
@@ -96,7 +120,7 @@ export class EMCScriptHandler extends EvtRt {
             ...mountConfigBase,
             matching,
             do: (mountedElement) => {
-                return this.handleMount(mountedElement, emcConfig);
+                return this.handleMount(mountedElement, emcConfig, synthesizerElement);
             }
         };
         return mountConfig;
@@ -104,7 +128,7 @@ export class EMCScriptHandler extends EvtRt {
     /**
      * Handle when an element mounts that matches the EMC config.
      */
-    async handleMount(mountedElement, emcConfig) {
+    async handleMount(mountedElement, emcConfig, synthesizerElement) {
         const enhKey = emcConfig.enhConfig.enhKey;
         // Step 1: Check if element already has this enhancement
         const enh = mountedElement.enh;
@@ -128,7 +152,9 @@ export class EMCScriptHandler extends EvtRt {
         if (!enh) {
             throw new Error('Element does not have enh property. Make sure ElementMountExtension is loaded.');
         }
-        await enh.get(enhancementConfig);
+        // Pass synthesizerElement through SpawnContext if available
+        const spawnContext = synthesizerElement ? { synthesizerElement } : undefined;
+        await enh.get(enhancementConfig, spawnContext);
     }
     /**
      * Register an enhancement in the enhancement registry.
@@ -165,6 +191,40 @@ export class EMCScriptHandler extends EvtRt {
         enhancementRegistry.push(enhancementConfig);
         return enhancementConfig;
     }
+    /**
+     * 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';

package/handlers/EMCScript.ts

@@ -2,6 +2,7 @@ import { EvtRt } from '../EvtRt.js';
 import { EMC, MountConfig, MountContext } from '../types/mount-observer/types.js';
 import '../ElementMountExtension.js';
 import 'assign-gingerly/object-extension.js';
+import { getParserRegistry } from 'assign-gingerly/parserRegistry.js';
 
 /**
  * Handler for EMC (Element Mount Configuration) Script Elements.
@@ -23,6 +24,32 @@ export class EMCScriptHandler extends EvtRt {
         
         const scriptElement = mountedElement as HTMLScriptElement;
         
+        // Find containing synthesizer element early (needed for parser waiting)
+        const synthesizerElement = this.findContainingSynthesizer(scriptElement);
+        
+        // Check for parser waiting before processing EMC config
+        const waitForParsers = scriptElement.getAttribute('wait-for-parsers');
+        if (waitForParsers && synthesizerElement) {
+            const parserNames = waitForParsers.trim().split(/\s+/).filter(name => name.length > 0);
+            
+            if (parserNames.length > 0) {
+                // Read timeout attribute (default: 60000ms = 1 minute)
+                const timeoutAttr = scriptElement.getAttribute('data-parser-timeout');
+                const timeout = timeoutAttr ? parseInt(timeoutAttr, 10) : 60000;
+                
+                try {
+                    // Get scoped registry and wait for parsers
+                    const registry = getParserRegistry(synthesizerElement);
+                    await registry.waitFor(parserNames, timeout);
+                } catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    console.error(`Parser waiting failed for EMC script:`, errorMessage, scriptElement);
+                    scriptElement.setAttribute('data-emc-error', errorMessage);
+                    return; // Stop processing on timeout/error
+                }
+            }
+        }
+        
         let emcConfig = (scriptElement as any).export;
         if (!emcConfig) {
             // Check if script has src attribute
@@ -80,7 +107,7 @@ export class EMCScriptHandler extends EvtRt {
         }
         
         // Construct MountConfig from EMC config and mount it
-        const mountConfig = await this.buildMountConfig(emcConfig);
+        const mountConfig = await this.buildMountConfig(emcConfig, synthesizerElement);
         await scriptElement.mount(mountConfig);
     }
     
@@ -88,7 +115,7 @@ export class EMCScriptHandler extends EvtRt {
      * Build a MountConfig from an EMC config.
      * Combines the matching selector with withAttrs if present.
      */
-    private async buildMountConfig(emcConfig: EMC): Promise<MountConfig> {
+    private async buildMountConfig(emcConfig: EMC, synthesizerElement?: Element): Promise<MountConfig> {
         const { enhConfig, ...mountConfigBase } = emcConfig;
         
         let matching = mountConfigBase.matching || '';
@@ -112,7 +139,7 @@ export class EMCScriptHandler extends EvtRt {
             ...mountConfigBase,
             matching,
             do: (mountedElement: Element) => {
-                return this.handleMount(mountedElement, emcConfig);
+                return this.handleMount(mountedElement, emcConfig, synthesizerElement);
             }
         };
         
@@ -122,7 +149,7 @@ export class EMCScriptHandler extends EvtRt {
     /**
      * Handle when an element mounts that matches the EMC config.
      */
-    private async handleMount(mountedElement: Element, emcConfig: EMC): Promise<void> {
+    private async handleMount(mountedElement: Element, emcConfig: EMC, synthesizerElement?: Element): Promise<void> {
         const enhKey = emcConfig.enhConfig.enhKey;
         
         // Step 1: Check if element already has this enhancement
@@ -153,7 +180,9 @@ export class EMCScriptHandler extends EvtRt {
             throw new Error('Element does not have enh property. Make sure ElementMountExtension is loaded.');
         }
         
-        await enh.get(enhancementConfig);
+        // Pass synthesizerElement through SpawnContext if available
+        const spawnContext = synthesizerElement ? { synthesizerElement } : undefined;
+        await enh.get(enhancementConfig, spawnContext);
     }
     
     /**
@@ -198,6 +227,44 @@ export class EMCScriptHandler extends EvtRt {
         
         return enhancementConfig;
     }
+    
+    /**
+     * 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.
+     */
+    private findContainingSynthesizer(element: Element): Element | undefined {
+        let current: Node | null = 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 as any).__isSynthesizer === true) {
+                    return current;
+                }
+            }
+            
+            // Try parent element
+            if (current.parentElement) {
+                current = current.parentElement;
+            }
+            // Try shadow root host
+            else if (current instanceof ShadowRoot) {
+                current = (current as ShadowRoot).host;
+            }
+            // Try parent node (for document fragments)
+            else if (current.parentNode) {
+                current = current.parentNode;
+            }
+            else {
+                break;
+            }
+        }
+        
+        return undefined;
+    }
 }
 
 // Register built-in handler

package/package.json

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

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

@@ -74,6 +74,44 @@ export type pathString = `?.${string}`;
 export type CustomElementName = string;
 export type CustomElementConstructorStaticMethodName = string;
 
+/**
+ * Context passed to parser functions
+ * Provides access to configuration and spawn context for advanced parsing scenarios
+ */
+export interface ParserContext<T = any> {
+  /**
+   * The attribute configuration that matched this attribute
+   * Useful for parsers that need to access additional config properties
+   */
+  attrConfig: AttrConfig<T>;
+  
+  /**
+   * The spawn context containing enhancement config and synthesizer element
+   * Useful for parsers that need access to the enhancement or synthesizer context
+   */
+  spawnContext?: SpawnContext<T>;
+  
+  /**
+   * The element being enhanced
+   * Useful for parsers that need to read other attributes or element properties
+   */
+  element: Element;
+  
+  /**
+   * The attribute name that was matched (resolved from template)
+   * Useful for parsers that handle multiple attributes
+   */
+  attrName: string;
+}
+
+/**
+ * Parser function signature
+ * Can accept just the attribute value (simple form) or value + context (advanced form)
+ */
+export type ParserFunction<T = any> = 
+  | ((attrValue: string | null) => any)
+  | ((attrValue: string | null, context?: ParserContext<T>) => any);
+
 export interface AttrConfig<T = any> {
   /**
    * Type of the property value (JSON-serializable string format)
@@ -100,13 +138,19 @@ export interface AttrConfig<T = any> {
   /**
    * Parser to transform attribute string value
    * - Function: Inline parser function (not JSON serializable)
-   * - String: Named parser reference (JSON serializable) - looks up in global parser registry (e.g., 'timestamp', 'csv')
-   * - Tuple: [CustomElementName, StaticMethodName] - looks up static method on custom element constructor (e.g., ['my-widget', 'parseSpecial'])
+   *   - Simple form: (attrValue: string | null) => any
+   *   - Advanced form: (attrValue: string | null, context: ParserContext) => any
+   * - String: Named parser reference (JSON serializable) - looks up in scoped registry (if available) then global parser registry (e.g., 'timestamp', 'csv')
+   * 
+   * Parser functions can optionally accept a second parameter (ParserContext) which provides:
+   * - attrConfig: The full AttrConfig object for this attribute
+   * - spawnContext: The SpawnContext with enhancement config and synthesizer element
+   * - element: The element being enhanced
+   * - attrName: The resolved attribute name
    */
   parser?: 
-    | ((attrValue: string | null) => any) 
-    | string 
-    | [CustomElementName, CustomElementConstructorStaticMethodName]
+    | ParserFunction<T>
+    | string
   ;
   
   /**
@@ -156,6 +200,12 @@ export type AttrPatterns<T = any> = {
 export interface SpawnContext<T = any, TMountContext = any> {
   config: EnhancementConfig<T>;
   mountCtx?: TMountContext;
+  /**
+   * Reference to the synthesizer element (be-hive, htmx-container, alpine-scope, etc.)
+   * that contains the EMC script defining this enhancement.
+   * Used for scoped parser registry access during attribute parsing.
+   */
+  synthesizerElement?: Element;
 }
 
 /**
@@ -169,6 +219,7 @@ export type IEnhancementRegistryItem<T = any> = EnhancementConfig<T>;
 export interface IAssignGingerlyOptions {
   registry?: typeof EnhancementRegistry | EnhancementRegistry;
   bypassChecks?: boolean;
+  withMethods?: string[] | Set<string>;
 }
 
 /**

package/types/be-a-beacon/types.d.ts

@@ -1,3 +1,17 @@
-export interface BeABeaconProps {
+export interface EndUserProps {
     eventName: string;
+}
+
+export interface AllProps extends EndUserProps {
+    enhancedElement: Element;
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+export interface Actions {
+    hydrate(self: AP): PAP;
 }

package/types/be-buttoned-up/types.d.ts

@@ -0,0 +1,19 @@
+export interface EndUserProps{
+    closeOnSelect: boolean;
+    eventName: string;
+}
+
+export interface AllProps extends EndUserProps {
+    enhancedElement: Element;
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+export interface Actions{
+    init(self: AllProps, enhancedElement: Element, initVals: PAP): void;
+    hydrate(self: AP): PAP | void
+}

package/types/be-clonable/types.d.ts

@@ -0,0 +1,36 @@
+export interface EndUserProps{
+    triggerInsertPosition: InsertPosition;
+    cloneInsertPosition: InsertPosition;
+    buttonContent: string;
+}
+
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element;
+    byob?: boolean;
+    trigger: HTMLButtonElement;
+    resolved: boolean;
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+export interface CustomData {
+    triggerSettings: {
+        type: string;
+        '?.classList?.add': string;
+        ariaLabel: string;
+        title: string;
+    },
+    withMethods: string[]
+    
+}
+
+export interface Actions{
+    addCloneBtn(self: AP): ProPAP;
+    setBtnContent(self: AP): void;
+    beCloned(self: AP): void;
+    init(self: AP, enhancedElement: Element, initVals: PAP): Promise<void>
+}

package/types/be-committed/types.d.ts

@@ -15,12 +15,8 @@ export type PAP = Partial<AP>;
 
 export type ProPAP = Promise<PAP>;
 
-export type BAP = AllProps // & BEAllProps & RoundaboutReady;
-
 export interface Actions{
     
-    hydrate(self: BAP): ProPAP;
-    init(self: BAP, initVals: PAP): Promise<void>
-    // findTarget(self: this): Promise<void>;
-    // handleCommit(self: this, e: KeyboardEvent): Promise<void>;
+    hydrate(self: AP): ProPAP;
+    init(self: AP, enhancedElement: Element, initVals: PAP): Promise<void>
 }

package/types/be-delible/types.d.ts

@@ -0,0 +1,25 @@
+export interface EndUserProps{
+    triggerInsertPosition: InsertPosition;
+    buttonContent: string;
+}
+
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element;
+    byob?: boolean,
+    trigger: HTMLButtonElement;
+    resolved: boolean,
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+export interface Actions{
+    
+    addDeleteBtn(self: AP): ProPAP ;
+    setBtnContent(self: AP): void;
+    beDeleted(self: AP): void;
+    init(self: AP & Actions, enhancedElement: Element, initVals: PAP): Promise<void>;
+}

package/types/be-render-neutral/types.d.ts

@@ -0,0 +1,29 @@
+export interface RenderingHTMLScriptElement extends HTMLScriptElement{
+    renderer: (vm: any, html: any) => any,
+}
+
+export interface EndUserProps{
+    vm: any,
+    with: Array<string>,
+}
+
+export type Renderer = (vm: any, html: any) => any;
+
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element;
+    renderer: Renderer,
+    absorbingObject: any
+}
+
+export type PAP = Partial<AllProps>;
+
+export type AP = AllProps;
+
+export type ProPAP = Promise<PAP>;
+
+export interface Actions {
+    getRenderer(self: AP): PAP;
+    doRender(self: AP): void;
+    observe(self: AP): ProPAP;
+    absorb(self: AP, e?: Event): ProPAP;
+}

package/types/be-typed/types.d.ts

@@ -0,0 +1,31 @@
+export interface EndUserProps {
+    triggerInsertPosition: InsertPosition;
+    labelTextContainer: string;
+    buttonContent: string;
+    nudge?: boolean;
+}
+
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element;
+    byob?: boolean;
+    trigger: WeakRef<HTMLButtonElement>
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+
+
+export interface Actions{
+    addTypeBtn(self: AP): ProPAP;
+    setBtnContent(self: AP): void;
+    openDialog(self: AP): Promise<void>
+}
+
+export interface ITyper{
+    showDialog(): void;
+    dispose(): void;
+}

package/types/roundabout/types.d.ts

@@ -71,13 +71,34 @@ export interface Positraction<TProps = any, TActions = TProps> extends LogicOp<T
     assignTo?: Array<null | (keyof TProps & string)>
 }
 
-export interface RAConfig<TProps = unknown, TActions = TProps, ETProps = TProps> {
+export interface RAConfig<TProps = unknown, TActions = TProps, ETProps = TProps, TCustomData = unknown> {
     actions?: Actions<TProps,TActions>,
     compacts?: Compacts<TProps, TActions>,
     //onsets?: Onsets<TProps, TActions>,
     handlers?: Handlers<ETProps, TActions>,
     hitch?: Hitches<TProps, TActions>,
     positractions?: Positractions<TProps>,
+    /**
+     * Configure automatic WeakRef wrapping for properties
+     * 
+     * Properties listed here will automatically wrap values in WeakRef when set,
+     * and automatically deref when accessed. This prevents memory leaks for
+     * DOM elements and other objects that should be garbage collected.
+     * 
+     * Options:
+     * - Array of property names: ['trigger', 'enhancedElement']
+     * - Object with configuration: { properties: ['trigger'], logIfCollected: 'warn' }
+     * 
+     * When a WeakRef'd value is garbage collected, the getter returns undefined.
+     * Use logIfCollected to get notified when this happens.
+     */
+    weakRef?: WeakRefConfig<TProps>,
+
+    defaultPropVals?: Partial<{[key in keyof TProps & string]: unknown}>,
+
+    customData?: TCustomData,
+
+    initialPropVals?: Partial<{[key in keyof TProps & string]: unknown}>,
 }
 
 export interface RoundaboutOptions<TProps = unknown, TActions = TProps, ETProps = TProps> extends RAConfig<TProps, TActions, ETProps> {
@@ -107,6 +128,27 @@ export interface RoundaboutOptions<TProps = unknown, TActions = TProps, ETProps
      * - Diamond dependencies (A→B, A→C, B→D, C→D)
      */
     internalRouting?: boolean,
+    
+
+}
+
+/**
+ * Configuration for automatic WeakRef wrapping
+ */
+export interface WeakRefConfig<TProps = any> {
+    /**
+     * Properties to automatically wrap in WeakRef
+     */
+    properties: Array<keyof TProps & string>;
+    
+    /**
+     * Logging behavior when deref returns null/undefined
+     * - 'error': console.error (default)
+     * - 'warn': console.warn
+     * - 'silent': no logging
+     * - function: custom logging function
+     */
+    logIfCollected?: 'error' | 'warn' | 'silent' | ((propName: string) => void);
 }
 
 export interface RoundaboutReady{