@mostfeatured/dbi 0.2.13 → 0.2.15

package/dist/src/types/Components/HTMLComponentsV2/index.d.ts

@@ -1,7 +1,7 @@
 import { NamespaceEnums } from "../../../../generated/namespaceData";
 import { DBI } from "../../../DBI";
 import { DBIBaseInteraction, IDBIBaseExecuteCtx, TDBIReferencedData } from "../../Interaction";
-export type TDBIHTMLComponentsV2Omitted<TNamespace extends NamespaceEnums> = Omit<DBIHTMLComponentsV2<TNamespace>, "type" | "dbi" | "toJSON" | "description" | "send" | "destroy" | "destroyAll"> & {
+export type TDBIHTMLComponentsV2Omitted<TNamespace extends NamespaceEnums> = Omit<DBIHTMLComponentsV2<TNamespace>, "type" | "dbi" | "toJSON" | "description" | "send" | "destroy" | "destroyAll" | "__lastRenderModals__" | "_pendingModals" | "_initPromise"> & {
     /**
      * Use 'svelte' for Svelte 5 components, 'eta' for Eta templates (default)
      */
@@ -34,9 +34,23 @@ export declare class DBIHTMLComponentsV2<TNamespace extends NamespaceEnums> exte
     private svelteComponentInfo;
     private _userOnExecute?;
     private _activeContexts;
+    _pendingModals: Map<string, {
+        resolve: (result: any) => void;
+        reject: (error: any) => void;
+    }>;
+    private _initPromise;
     constructor(dbi: DBI<TNamespace>, args: TDBIHTMLComponentsV2Omitted<TNamespace>);
     private _initSvelteComponent;
     private _handleExecute;
+    /**
+     * Execute a modal submit handler
+     */
+    private _executeModalSubmit;
+    /**
+     * Execute an element handler (button, select, etc.)
+     */
+    private _executeElementHandler;
+    __lastRenderModals__: Map<string, any> | null;
     toJSON(arg?: TDBIHTMLComponentsV2ToJSONArgs): Promise<any>;
     /**
      * Send the component to an interaction or channel and initialize lifecycle hooks (onMount)
@@ -80,6 +94,24 @@ export declare class DBIHTMLComponentsV2<TNamespace extends NamespaceEnums> exte
      * ```
      */
     destroy(refOrData: string | Record<string, any>): boolean;
+    /**
+     * Extract all field values from a modal interaction
+     * Supports text inputs, select menus (string, user, role, mentionable, channel), and file uploads
+     *
+     * Returns an object where keys are the custom_id of each component and values are:
+     * - For text inputs: string value
+     * - For string selects: string[] of selected values
+     * - For user selects: string[] of user IDs
+     * - For role selects: string[] of role IDs
+     * - For mentionable selects: { users: string[], roles: string[] }
+     * - For channel selects: string[] of channel IDs
+     * - For file uploads: attachment objects array
+     */
+    private _extractModalFields;
+    /**
+     * Recursively extract field values from component structure
+     */
+    private _extractFieldsFromComponents;
     /**
      * Destroy all active instances of this component
      * Useful for cleanup when the bot shuts down or component is unloaded

package/dist/src/types/Components/HTMLComponentsV2/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/types/Components/HTMLComponentsV2/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAgB,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAM7G,MAAM,MAAM,2BAA2B,CAAC,UAAU,SAAS,cAAc,IAAI,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC,GAAG;IAClM;;OAEG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC;IACxB;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,8BAA8B,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;CACvE,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B,CAAA;AAED,MAAM,WAAW,+BAA+B;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,8FAA8F;IAC9F,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,8BAA8B,CAAC,UAAU,SAAS,cAAc,CAAE,SAAQ,kBAAkB,CAAC,UAAU,CAAC;IACvH,IAAI,EAAE,kBAAkB,EAAE,CAAC;CAC5B;AAED,qBAAa,mBAAmB,CAAC,UAAU,SAAS,cAAc,CAAE,SAAQ,kBAAkB,CAAC,UAAU,CAAC;IACxG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAS;IAC/B,OAAO,CAAC,mBAAmB,CAAa;IACxC,OAAO,CAAC,cAAc,CAAC,CAA4D;IAInF,OAAO,CAAC,eAAe,CAA+B;gBAE1C,GAAG,EAAE,GAAG,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,2BAA2B,CAAC,UAAU,CAAC;YAiCjE,oBAAoB;IAMlC,OAAO,CAAC,cAAc;IA0GP,MAAM,CAAC,GAAG,GAAE,8BAAmC,GAAG,OAAO,CAAC,GAAG,CAAC;IA4B7E;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,GAAE,+BAAoC,GAAG,OAAO,CAAC,GAAG,CAAC;IAyEpF;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO;IAsBzD;;;;;OAKG;IACH,UAAU,IAAI,MAAM;IAapB,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAM;CACvB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/types/Components/HTMLComponentsV2/index.ts"],"names":[],"mappings":"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"}

package/dist/src/types/Components/HTMLComponentsV2/index.js

@@ -7,6 +7,151 @@ const parser_1 = require("./parser");
 const svelteRenderer_1 = require("./svelteRenderer");
 const svelteParser_1 = require("./svelteParser");
 const fs_1 = tslib_1.__importDefault(require("fs"));
+/**
+ * Parse Discord API error and provide helpful context about which HTML element caused the error
+ */
+function parseDiscordAPIError(error, source, componentName) {
+    // Check if it's a Discord API error with form body issues
+    const message = error.message || '';
+    const rawError = error.rawError || error;
+    // Extract the path from error message like "data.components[0].components[0].accessory.media.url"
+    const pathMatch = message.match(/data\.components(\[[^\]]+\](?:\.[^\[\s\[]+|\[[^\]]+\])*)/);
+    if (!pathMatch) {
+        return error; // Not a parseable Discord API error
+    }
+    const errorPath = pathMatch[1];
+    const errorCode = message.match(/\[([A-Z_]+)\]/)?.[1] || 'UNKNOWN';
+    // Parse the path to understand the component structure
+    // e.g., "[0].components[0].accessory.media.url" -> component index 0, child 0, accessory.media.url
+    const parts = errorPath.split(/\.|\[|\]/).filter(Boolean);
+    // Build a human-readable path description
+    let description = '';
+    let elementHint = '';
+    let currentPath = [];
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (!isNaN(Number(part))) {
+            currentPath.push(`[${part}]`);
+        }
+        else {
+            currentPath.push(part);
+            // Provide hints based on known Discord component structure
+            if (part === 'accessory') {
+                elementHint = '<section> element\'s accessory (thumbnail/button)';
+            }
+            else if (part === 'media') {
+                elementHint = '<thumbnail> or <media-gallery> element';
+            }
+            else if (part === 'url') {
+                elementHint = 'media URL attribute';
+            }
+            else if (part === 'components') {
+                // Skip, it's container
+            }
+            else if (part === 'content') {
+                elementHint = 'text content of a <text-display> element';
+            }
+            else if (part === 'label') {
+                elementHint = 'label attribute of a <button> or <option>';
+            }
+            else if (part === 'custom_id') {
+                elementHint = 'name attribute of an interactive element';
+            }
+            else if (part === 'placeholder') {
+                elementHint = 'placeholder attribute of a select menu';
+            }
+            else if (part === 'title') {
+                elementHint = 'title attribute of a <modal> or <section>';
+            }
+            else if (part === 'options') {
+                elementHint = '<option> elements inside a <string-select>';
+            }
+            else if (part === 'value') {
+                elementHint = 'value attribute of an <option> or <text-input>';
+            }
+            else if (part === 'description') {
+                elementHint = 'description attribute of an <option>';
+            }
+        }
+    }
+    // Map error codes to helpful messages
+    const errorMessages = {
+        'BASE_TYPE_REQUIRED': 'This field is required but was empty or undefined',
+        'STRING_TYPE_REQUIRED': 'This field must be a string',
+        'NUMBER_TYPE_REQUIRED': 'This field must be a number',
+        'BOOLEAN_TYPE_REQUIRED': 'This field must be a boolean',
+        'INVALID_URL': 'The URL provided is not valid',
+        'MAX_LENGTH': 'The value exceeds the maximum allowed length',
+        'MIN_LENGTH': 'The value is shorter than the minimum required length',
+        'CHOICE_NOT_FOUND': 'The selected value is not in the list of options',
+    };
+    const errorExplanation = errorMessages[errorCode] || `Error code: ${errorCode}`;
+    // Build the enhanced error message
+    let enhancedMessage = `
+╔══════════════════════════════════════════════════════════════╗
+║  Discord API Error - Invalid Component Data                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+📍 Component: ${componentName || 'unknown'}
+📍 Error Path: data.components${errorPath}
+📍 Error Code: ${errorCode}
+
+❌ ${errorExplanation}
+${elementHint ? `\n💡 This error is likely in: ${elementHint}` : ''}
+
+🔍 What to check:
+`;
+    // Add specific suggestions based on error type
+    if (errorPath.includes('media.url')) {
+        enhancedMessage += `   • Make sure the image/media URL is provided and valid
+   • Check that the data property used for the image exists
+   • Example: <thumbnail media={product?.image}> - is product.image defined?
+`;
+    }
+    else if (errorPath.includes('accessory')) {
+        enhancedMessage += `   • The <section> element requires valid content in its accessory
+   • If using <thumbnail>, ensure the media URL is valid
+`;
+    }
+    else if (errorPath.includes('content')) {
+        enhancedMessage += `   • Text content cannot be empty or undefined
+   • Check your template expressions like {variable?.property}
+`;
+    }
+    else if (errorPath.includes('options')) {
+        enhancedMessage += `   • Select menu options must have valid value and label
+   • Each <option> needs: value="..." and text content
+`;
+    }
+    else if (errorPath.includes('label') || errorPath.includes('custom_id')) {
+        enhancedMessage += `   • Interactive elements (buttons, selects) need valid labels/names
+   • Check that text content and name attributes are not empty
+`;
+    }
+    // If we have source, try to highlight relevant section
+    if (source && elementHint) {
+        const elementType = elementHint.match(/<(\w+-?\w*)>/)?.[1];
+        if (elementType) {
+            const elementRegex = new RegExp(`<${elementType}[^>]*>`, 'g');
+            const matches = source.match(elementRegex);
+            if (matches && matches.length > 0) {
+                enhancedMessage += `\n📝 Found ${matches.length} <${elementType}> element(s) in template:`;
+                matches.slice(0, 3).forEach((m, i) => {
+                    enhancedMessage += `\n   ${i + 1}. ${m.substring(0, 80)}${m.length > 80 ? '...' : ''}`;
+                });
+                if (matches.length > 3) {
+                    enhancedMessage += `\n   ... and ${matches.length - 3} more`;
+                }
+            }
+        }
+    }
+    const enhancedError = new Error(enhancedMessage);
+    enhancedError.originalError = error;
+    enhancedError.type = 'discord-api-error';
+    enhancedError.path = errorPath;
+    enhancedError.code = errorCode;
+    return enhancedError;
+}
 class DBIHTMLComponentsV2 extends Interaction_1.DBIBaseInteraction {
     template;
     file;
@@ -16,6 +161,11 @@ class DBIHTMLComponentsV2 extends Interaction_1.DBIBaseInteraction {
     // Store handler contexts per ref for lifecycle management
     // Key: ref id, Value: handlerContext with lifecycle hooks
     _activeContexts = new Map();
+    // Store pending modal promises for await showModal() support
+    // Key: modal customId, Value: { resolve, reject } functions
+    _pendingModals = new Map();
+    // Track initialization promise
+    _initPromise = null;
     constructor(dbi, args) {
         // Store user's onExecute callback before passing to super
         const userOnExecute = args.onExecute;
@@ -37,8 +187,8 @@ class DBIHTMLComponentsV2 extends Interaction_1.DBIBaseInteraction {
         }
         // Pre-extract Svelte handlers at registration time (lazy loaded)
         if (this.mode === 'svelte' && this.template) {
-            // Defer the parsing to avoid sync import issues
-            this._initSvelteComponent();
+            // Store the promise so we can await it in _handleExecute
+            this._initPromise = this._initSvelteComponent();
         }
         // Re-assign onExecute method after super() call because parent class sets it to undefined
         this.onExecute = this._handleExecute.bind(this);
@@ -48,7 +198,11 @@ class DBIHTMLComponentsV2 extends Interaction_1.DBIBaseInteraction {
             this.svelteComponentInfo = await (0, svelteParser_1.parseSvelteComponent)(this.template);
         }
     }
-    _handleExecute(ctx) {
+    async _handleExecute(ctx) {
+        // Wait for Svelte component initialization if not yet completed
+        if (this._initPromise) {
+            await this._initPromise;
+        }
         // Call user's onExecute callback first if provided
         if (this._userOnExecute) {
             this._userOnExecute(ctx);
@@ -57,83 +211,158 @@ class DBIHTMLComponentsV2 extends Interaction_1.DBIBaseInteraction {
         if (this.mode === 'svelte' && this.svelteComponentInfo) {
             const [elementName, ...handlerData] = ctx.data;
             if (typeof elementName === 'string') {
-                // Find the handler info for this element
+                // Check if this is a modal submit (elementName is the modal id)
+                const modalHandlerInfo = this.svelteComponentInfo.modalHandlers.get(elementName);
+                if (modalHandlerInfo) {
+                    // This is a modal submit - execute the onsubmit handler (or just resolve promise if no handler)
+                    this._executeModalSubmit(ctx, elementName, modalHandlerInfo.onsubmitHandler, handlerData);
+                    return;
+                }
+                // Find the handler info for this element (button, select, etc.)
                 const handlerInfo = this.svelteComponentInfo.handlers.get(elementName);
                 if (handlerInfo) {
-                    // Extract current state from handlerData (refs that were passed)
-                    // The second element in data array contains the current state
-                    const currentState = handlerData[0] || {};
-                    // Get ref id for lifecycle tracking (if available)
-                    const refId = currentState?.$ref || null;
-                    // Check if this is first execution for this ref
-                    const isFirstExecution = refId && !this._activeContexts.has(refId);
-                    // Get existing context if any (to preserve lifecycle callbacks like intervals)
-                    const existingContext = refId ? this._activeContexts.get(refId) : null;
-                    // Create a NEW handler context for each execution with the current state
-                    // This ensures each interaction has its own isolated state
-                    // Pass 'this' so handlers can access component methods like toJSON()
-                    // Pass ctx so handlers can access ctx.interaction, ctx.data, ctx.locale, etc.
-                    const handlerContext = (0, svelteParser_1.createHandlerContext)(this.svelteComponentInfo.scriptContent, typeof currentState === 'object' ? currentState : {}, this, ctx);
-                    const handlerFn = handlerContext.handlers[handlerInfo.handlerName];
-                    if (handlerFn && typeof handlerFn === 'function') {
-                        try {
-                            // Store context for lifecycle management
-                            if (refId) {
-                                // If there's an existing context, transfer its destroy callbacks to the new context
-                                // This preserves intervals/timers created in onMount
-                                if (existingContext && existingContext.destroyCallbacks) {
-                                    // Merge existing destroy callbacks (don't run them!)
-                                    handlerContext.destroyCallbacks.push(...existingContext.destroyCallbacks);
-                                }
-                                this._activeContexts.set(refId, handlerContext);
-                                // Wrap $unRef to call onDestroy when ref is deleted (only wrap once)
-                                const stateObj = currentState;
-                                if (stateObj.$unRef && !stateObj.__unRefWrapped__) {
-                                    const originalUnRef = stateObj.$unRef.bind(stateObj);
-                                    stateObj.$unRef = () => {
-                                        // Run destroy callbacks before unref
-                                        const ctx = this._activeContexts.get(refId);
-                                        if (ctx && ctx.runDestroy) {
-                                            ctx.runDestroy();
-                                        }
-                                        this._activeContexts.delete(refId);
-                                        return originalUnRef();
-                                    };
-                                    stateObj.__unRefWrapped__ = true;
-                                }
-                            }
-                            // Run onMount callbacks only on first execution
-                            if (isFirstExecution && handlerContext.runMount) {
-                                handlerContext.runMount();
-                            }
-                            // Mark that we're inside handler execution (prevents auto-render during handler)
-                            handlerContext.setInHandler(true);
-                            try {
-                                // Bind 'this' to the DBIHTMLComponentsV2 instance so handlers can use this.toJSON()
-                                // Pass wrappedCtx so handlers use the proxy-wrapped ctx that tracks interaction calls
-                                // This ensures __asyncInteractionCalled__ flag is set when handler calls ctx.interaction.reply() etc.
-                                handlerFn.call(this, handlerContext.wrappedCtx, ...handlerData.slice(1));
-                            }
-                            finally {
-                                // Always reset handler execution flag
-                                handlerContext.setInHandler(false);
-                            }
-                            // Run effects after handler execution (state may have changed)
-                            handlerContext.runEffects();
-                            // If there are pending data changes and no interaction method was called,
-                            // flush the render now (synchronously uses interaction.update)
-                            if (handlerContext.hasPendingRender()) {
-                                handlerContext.flushRender();
+                    this._executeElementHandler(ctx, handlerInfo, handlerData);
+                }
+            }
+        }
+    }
+    /**
+     * Execute a modal submit handler
+     */
+    _executeModalSubmit(ctx, modalId, handlerName, handlerData) {
+        // Extract current state from handlerData (refs that were passed)
+        const currentState = handlerData[0] || {};
+        // Get ref id for lifecycle tracking (if available)
+        const refId = currentState?.$ref || null;
+        // Extract all field values from modal interaction (text inputs, selects, file uploads, etc.)
+        const modalInteraction = ctx.interaction;
+        const fields = this._extractModalFields(modalInteraction);
+        // Check if there's a pending promise for this modal (from await showModal())
+        // Use the modal's customId to find the pending promise
+        const pendingKey = modalInteraction.customId;
+        const pendingModal = this._pendingModals.get(pendingKey);
+        if (pendingModal) {
+            // Resolve the promise with fields and interaction
+            pendingModal.resolve({
+                fields,
+                interaction: modalInteraction,
+                ctx: ctx
+            });
+            this._pendingModals.delete(pendingKey);
+        }
+        // If no onsubmit handler defined, just return (promise-based usage)
+        if (!handlerName) {
+            return;
+        }
+        // Create handler context for modal submit
+        const handlerContext = (0, svelteParser_1.createHandlerContext)(this.svelteComponentInfo.scriptContent, typeof currentState === 'object' ? currentState : {}, this, ctx);
+        const handlerFn = handlerContext.handlers[handlerName];
+        if (handlerFn && typeof handlerFn === 'function') {
+            try {
+                // Store context for lifecycle management
+                if (refId) {
+                    const existingContext = this._activeContexts.get(refId);
+                    if (existingContext && existingContext.destroyCallbacks) {
+                        handlerContext.destroyCallbacks.push(...existingContext.destroyCallbacks);
+                    }
+                    this._activeContexts.set(refId, handlerContext);
+                }
+                handlerContext.setInHandler(true);
+                try {
+                    // Call handler with ctx and fields object
+                    handlerFn.call(this, handlerContext.wrappedCtx, fields, ...handlerData.slice(1));
+                }
+                finally {
+                    handlerContext.setInHandler(false);
+                }
+                handlerContext.runEffects();
+                if (handlerContext.hasPendingRender()) {
+                    handlerContext.flushRender();
+                }
+            }
+            catch (error) {
+                // Modal handler execution failed
+            }
+        }
+    }
+    /**
+     * Execute an element handler (button, select, etc.)
+     */
+    _executeElementHandler(ctx, handlerInfo, handlerData) {
+        // Extract current state from handlerData (refs that were passed)
+        // The second element in data array contains the current state
+        const currentState = handlerData[0] || {};
+        // Get ref id for lifecycle tracking (if available)
+        const refId = currentState?.$ref || null;
+        // Check if this is first execution for this ref
+        const isFirstExecution = refId && !this._activeContexts.has(refId);
+        // Get existing context if any (to preserve lifecycle callbacks like intervals)
+        const existingContext = refId ? this._activeContexts.get(refId) : null;
+        // Create a NEW handler context for each execution with the current state
+        // This ensures each interaction has its own isolated state
+        // Pass 'this' so handlers can access component methods like toJSON()
+        // Pass ctx so handlers can access ctx.interaction, ctx.data, ctx.locale, etc.
+        const handlerContext = (0, svelteParser_1.createHandlerContext)(this.svelteComponentInfo.scriptContent, typeof currentState === 'object' ? currentState : {}, this, ctx);
+        const handlerFn = handlerContext.handlers[handlerInfo.handlerName];
+        if (handlerFn && typeof handlerFn === 'function') {
+            try {
+                // Store context for lifecycle management
+                if (refId) {
+                    // If there's an existing context, transfer its destroy callbacks to the new context
+                    // This preserves intervals/timers created in onMount
+                    if (existingContext && existingContext.destroyCallbacks) {
+                        // Merge existing destroy callbacks (don't run them!)
+                        handlerContext.destroyCallbacks.push(...existingContext.destroyCallbacks);
+                    }
+                    this._activeContexts.set(refId, handlerContext);
+                    // Wrap $unRef to call onDestroy when ref is deleted (only wrap once)
+                    const stateObj = currentState;
+                    if (stateObj.$unRef && !stateObj.__unRefWrapped__) {
+                        const originalUnRef = stateObj.$unRef.bind(stateObj);
+                        stateObj.$unRef = () => {
+                            // Run destroy callbacks before unref
+                            const ctx = this._activeContexts.get(refId);
+                            if (ctx && ctx.runDestroy) {
+                                ctx.runDestroy();
                             }
-                        }
-                        catch (error) {
-                            // Handler execution failed
-                        }
+                            this._activeContexts.delete(refId);
+                            return originalUnRef();
+                        };
+                        stateObj.__unRefWrapped__ = true;
                     }
                 }
+                // Run onMount callbacks only on first execution
+                if (isFirstExecution && handlerContext.runMount) {
+                    handlerContext.runMount();
+                }
+                // Mark that we're inside handler execution (prevents auto-render during handler)
+                handlerContext.setInHandler(true);
+                try {
+                    // Bind 'this' to the DBIHTMLComponentsV2 instance so handlers can use this.toJSON()
+                    // Pass wrappedCtx so handlers use the proxy-wrapped ctx that tracks interaction calls
+                    // This ensures __asyncInteractionCalled__ flag is set when handler calls ctx.interaction.reply() etc.
+                    handlerFn.call(this, handlerContext.wrappedCtx, ...handlerData.slice(1));
+                }
+                finally {
+                    // Always reset handler execution flag
+                    handlerContext.setInHandler(false);
+                }
+                // Run effects after handler execution (state may have changed)
+                handlerContext.runEffects();
+                // If there are pending data changes and no interaction method was called,
+                // flush the render now (synchronously uses interaction.update)
+                if (handlerContext.hasPendingRender()) {
+                    handlerContext.flushRender();
+                }
+            }
+            catch (error) {
+                // Handler execution failed
             }
         }
     }
+    // Store last render's modals for showModal() to access
+    // Note: Used internally by handler context, not truly private
+    __lastRenderModals__ = null;
     async toJSON(arg = {}) {
         if (this.mode === 'svelte' && this.template) {
             // Render Svelte component
@@ -141,6 +370,8 @@ class DBIHTMLComponentsV2 extends Interaction_1.DBIBaseInteraction {
                 data: arg.data,
                 ttl: this.ttl
             });
+            // Store modals for showModal() to access
+            this.__lastRenderModals__ = result.modals;
             return result.components;
         }
         else {
@@ -173,8 +404,12 @@ class DBIHTMLComponentsV2 extends Interaction_1.DBIBaseInteraction {
      * ```
      */
     async send(target, options = {}) {
+        // Wait for Svelte component initialization if not yet completed
+        if (this._initPromise) {
+            await this._initPromise;
+        }
         const { data = {}, flags = ["IsComponentsV2"], content, ephemeral, reply, followUp } = options;
-        // Render components (toJSON is async)
+        // Render components (toJSON is async) - this also creates $ref in data if not present
         const components = await this.toJSON({ data });
         // Build message options
         const messageOptions = { components, flags };
@@ -186,21 +421,32 @@ class DBIHTMLComponentsV2 extends Interaction_1.DBIBaseInteraction {
         let message;
         const isInteraction = target.reply && target.user; // Interactions have both reply method and user property
         const isChannel = target.send && !target.user; // Channels have send but no user
-        if (isInteraction) {
-            if (followUp) {
-                message = await target.followUp(messageOptions);
+        try {
+            if (isInteraction) {
+                if (followUp) {
+                    message = await target.followUp(messageOptions);
+                }
+                else {
+                    message = await target.reply(messageOptions);
+                }
+            }
+            else if (isChannel) {
+                message = await target.send(messageOptions);
             }
             else {
-                message = await target.reply(messageOptions);
+                throw new Error("Invalid target: must be an interaction or channel");
             }
         }
-        else if (isChannel) {
-            message = await target.send(messageOptions);
-        }
-        else {
-            throw new Error("Invalid target: must be an interaction or channel");
+        catch (error) {
+            // Check if it's a Discord API error and enhance it with helpful context
+            if (error.code || error.rawError || (error.message && error.message.includes('Invalid Form Body'))) {
+                const source = this.file ? fs_1.default.readFileSync(this.file, 'utf-8') : this.template;
+                throw parseDiscordAPIError(error, source, this.name);
+            }
+            throw error;
         }
         // If Svelte mode, create initial handler context and run onMount
+        // After toJSON, data.$ref is guaranteed to exist (created in renderSvelteComponent)
         if (this.mode === 'svelte' && this.svelteComponentInfo && data.$ref) {
             const refId = data.$ref;
             // Create handler context with a fake ctx that has the message
@@ -268,6 +514,86 @@ class DBIHTMLComponentsV2 extends Interaction_1.DBIBaseInteraction {
         this.dbi.data.refs.delete(refId);
         return true;
     }
+    /**
+     * Extract all field values from a modal interaction
+     * Supports text inputs, select menus (string, user, role, mentionable, channel), and file uploads
+     *
+     * Returns an object where keys are the custom_id of each component and values are:
+     * - For text inputs: string value
+     * - For string selects: string[] of selected values
+     * - For user selects: string[] of user IDs
+     * - For role selects: string[] of role IDs
+     * - For mentionable selects: { users: string[], roles: string[] }
+     * - For channel selects: string[] of channel IDs
+     * - For file uploads: attachment objects array
+     */
+    _extractModalFields(modalInteraction) {
+        const fields = {};
+        // Handle classic text input fields via ModalSubmitFields
+        if (modalInteraction.fields && modalInteraction.fields.fields) {
+            for (const [customId, field] of modalInteraction.fields.fields) {
+                // Text input - field.value is the string
+                fields[customId] = field.value;
+            }
+        }
+        // Handle new modal components from interaction.data.components
+        // The new modal structure uses Label wrappers with nested components
+        const data = modalInteraction.data || modalInteraction.data;
+        if (data && data.components) {
+            this._extractFieldsFromComponents(data.components, fields);
+        }
+        return fields;
+    }
+    /**
+     * Recursively extract field values from component structure
+     */
+    _extractFieldsFromComponents(components, fields) {
+        for (const component of components) {
+            const type = component.type;
+            const customId = component.custom_id;
+            // Type 18 = Label - has nested component
+            if (type === 18 && component.component) {
+                this._extractFieldsFromComponents([component.component], fields);
+                continue;
+            }
+            // Type 1 = Action Row - has nested components array
+            if (type === 1 && component.components) {
+                this._extractFieldsFromComponents(component.components, fields);
+                continue;
+            }
+            if (!customId)
+                continue;
+            switch (type) {
+                case 4: // Text Input
+                    fields[customId] = component.value || '';
+                    break;
+                case 3: // String Select
+                    fields[customId] = component.values || [];
+                    break;
+                case 5: // User Select
+                    fields[customId] = component.values || [];
+                    break;
+                case 6: // Role Select
+                    fields[customId] = component.values || [];
+                    break;
+                case 7: // Mentionable Select - can have both users and roles
+                    // Discord returns resolved data for mentionables
+                    fields[customId] = {
+                        values: component.values || [],
+                        users: component.resolved?.users ? Object.keys(component.resolved.users) : [],
+                        roles: component.resolved?.roles ? Object.keys(component.resolved.roles) : []
+                    };
+                    break;
+                case 8: // Channel Select
+                    fields[customId] = component.values || [];
+                    break;
+                case 19: // File Upload
+                    // File uploads come through as attachments
+                    fields[customId] = component.attachments || [];
+                    break;
+            }
+        }
+    }
     /**
      * Destroy all active instances of this component
      * Useful for cleanup when the bot shuts down or component is unloaded