@majkapp/plugin-kit 2.0.1 → 2.1.0

package/dist/plugin-kit.js

@@ -4,8 +4,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.definePlugin = definePlugin;
+const http_1 = __importDefault(require("http"));
 const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const registry_1 = require("./registry");
+const transports_1 = require("./transports");
 /**
  * Conditional logging - suppressed in extract mode
  */
@@ -150,16 +153,332 @@ function validateEntity(entityType, entity) {
     }
     return errors;
 }
+/**
+ * Convert JSON Schema to OpenAPI Schema
+ */
+function jsonSchemaToOpenApi(schema) {
+    // OpenAPI doesn't use the $schema property
+    const { ...openApiSchema } = schema;
+    return openApiSchema;
+}
+/**
+ * Generate OpenAPI specification from routes
+ */
+function generateOpenApiSpec(pluginId, pluginName, pluginVersion, routes, baseUrl) {
+    const paths = {};
+    for (const route of routes) {
+        const openApiPath = route.path.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+        if (!paths[openApiPath]) {
+            paths[openApiPath] = {};
+        }
+        const operation = {
+            operationId: `${pluginId}_${route.name.replace(/\s+/g, '_')}`,
+            summary: route.name,
+            description: route.description,
+            tags: route.tags || [pluginId],
+            deprecated: route.deprecated
+        };
+        // Add parameters from request schema
+        if (route.requestSchema) {
+            const parameters = [];
+            // Path parameters
+            if (route.requestSchema.params) {
+                const paramProps = route.requestSchema.params.properties || {};
+                for (const [name, schema] of Object.entries(paramProps)) {
+                    parameters.push({
+                        name,
+                        in: 'path',
+                        required: route.requestSchema.params.required?.includes(name) ?? true,
+                        schema: jsonSchemaToOpenApi(schema),
+                        description: schema.description
+                    });
+                }
+            }
+            // Query parameters
+            if (route.requestSchema.query) {
+                const queryProps = route.requestSchema.query.properties || {};
+                for (const [name, schema] of Object.entries(queryProps)) {
+                    parameters.push({
+                        name,
+                        in: 'query',
+                        required: route.requestSchema.query.required?.includes(name) ?? false,
+                        schema: jsonSchemaToOpenApi(schema),
+                        description: schema.description
+                    });
+                }
+            }
+            if (parameters.length > 0) {
+                operation.parameters = parameters;
+            }
+            // Request body
+            if (route.requestSchema.body) {
+                operation.requestBody = {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: jsonSchemaToOpenApi(route.requestSchema.body)
+                        }
+                    }
+                };
+            }
+        }
+        // Response schema
+        operation.responses = {
+            '200': {
+                description: 'Successful response',
+                content: route.responseSchema ? {
+                    'application/json': {
+                        schema: jsonSchemaToOpenApi(route.responseSchema)
+                    }
+                } : {}
+            },
+            '400': {
+                description: 'Bad request'
+            },
+            '500': {
+                description: 'Internal server error'
+            }
+        };
+        paths[openApiPath][route.method.toLowerCase()] = operation;
+    }
+    return {
+        openapi: '3.0.0',
+        info: {
+            title: `${pluginName} API`,
+            version: pluginVersion,
+            description: `API documentation for the ${pluginName} MAJK plugin`
+        },
+        servers: [
+            {
+                url: baseUrl,
+                description: 'Plugin API server'
+            }
+        ],
+        paths,
+        components: {
+            schemas: {}
+        }
+    };
+}
+/**
+ * Path parameter regex builder
+ */
+function pathToRegex(p) {
+    const keys = [];
+    log(`[pathToRegex] Input path: ${p}`);
+    // First, escape special regex characters EXCEPT the colon (for path params)
+    const escaped = p.replace(/([.+*?=^!${}()[\]|\\])/g, '\\$1');
+    log(`[pathToRegex] After escaping: ${escaped}`);
+    // Then, replace path parameters with capturing groups
+    const pattern = escaped.replace(/\/:([A-Za-z0-9_]+)/g, (_m, k) => {
+        keys.push(k);
+        log(`[pathToRegex] Found param: ${k}`);
+        return '/([^/]+)';
+    });
+    log(`[pathToRegex] Final pattern: ${pattern}`);
+    log(`[pathToRegex] Keys: [${keys.join(', ')}]`);
+    const regex = new RegExp(`^${pattern}$`);
+    log(`[pathToRegex] Final regex: ${regex}`);
+    return { regex, keys };
+}
+/**
+ * CORS headers
+ */
+function corsHeaders(extra = {}) {
+    return {
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'GET, POST, PUT, PATCH, DELETE, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+        ...extra
+    };
+}
+/**
+ * Read request body
+ */
+async function readBody(req) {
+    if (req.method === 'GET' || req.method === 'HEAD' || req.method === 'OPTIONS') {
+        return undefined;
+    }
+    return new Promise((resolve) => {
+        let data = '';
+        req.on('data', (chunk) => (data += chunk.toString()));
+        req.on('end', () => {
+            if (!data) {
+                resolve(undefined);
+                return;
+            }
+            try {
+                resolve(JSON.parse(data));
+            }
+            catch {
+                resolve(data);
+            }
+        });
+    });
+}
+/**
+ * Create response wrapper
+ */
+function makeResponse(res) {
+    return {
+        status(code) {
+            res.statusCode = code;
+            return this;
+        },
+        setHeader(key, value) {
+            res.setHeader(key, value);
+        },
+        json(data) {
+            if (!res.headersSent) {
+                res.writeHead(res.statusCode || 200, corsHeaders({ 'Content-Type': 'application/json' }));
+            }
+            res.end(JSON.stringify(data));
+        },
+        send(data) {
+            if (!res.headersSent) {
+                res.writeHead(res.statusCode || 200, corsHeaders());
+            }
+            res.end(data);
+        }
+    };
+}
+/**
+ * Content type helper
+ */
+function getContentType(filePath) {
+    const ext = path_1.default.extname(filePath).toLowerCase();
+    const types = {
+        '.html': 'text/html',
+        '.js': 'application/javascript',
+        '.css': 'text/css',
+        '.json': 'application/json',
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.svg': 'image/svg+xml',
+        '.woff': 'font/woff',
+        '.woff2': 'font/woff2',
+        '.ttf': 'font/ttf'
+    };
+    return types[ext] || 'application/octet-stream';
+}
+/**
+ * Serve React SPA
+ */
+function serveSpa(ui, req, res, ctx) {
+    const url = new URL(req.url, 'http://localhost');
+    const rel = url.pathname.substring(ui.base.length) || '/';
+    const distPath = path_1.default.join(ctx.pluginRoot, ui.appDir);
+    let filePath = path_1.default.join(distPath, rel);
+    if (filePath.endsWith('/')) {
+        filePath = path_1.default.join(filePath, 'index.html');
+    }
+    // Security: prevent path traversal
+    const normalizedPath = path_1.default.resolve(filePath);
+    if (!normalizedPath.startsWith(path_1.default.resolve(distPath))) {
+        res.writeHead(403, corsHeaders({ 'Content-Type': 'text/plain' }));
+        res.end('Forbidden: Path traversal detected');
+        ctx.logger.warn(`Path traversal attempt blocked: ${rel}`);
+        return;
+    }
+    const exists = fs_1.default.existsSync(filePath) && fs_1.default.statSync(filePath).isFile();
+    const targetFile = exists ? filePath : path_1.default.join(distPath, 'index.html');
+    if (!fs_1.default.existsSync(targetFile)) {
+        res.writeHead(404, corsHeaders({ 'Content-Type': 'text/plain' }));
+        res.end('Not found');
+        return;
+    }
+    let content = fs_1.default.readFileSync(targetFile);
+    // Inject base URL for React apps and MCP DOM Agent
+    if (path_1.default.basename(targetFile) === 'index.html') {
+        const html = content.toString('utf-8');
+        // Inject configuration
+        const configInject = `<script>` +
+            `window.__MAJK_BASE_URL__=${JSON.stringify(ctx.http.baseUrl)};` +
+            `window.__MAJK_IFRAME_BASE__=${JSON.stringify(ui.base)};` +
+            `window.__MAJK_PLUGIN_ID__=${JSON.stringify(ctx.pluginId)};` +
+            `</script>`;
+        // Inject html2canvas library (inline from node_modules)
+        const html2canvasScript = BuiltPlugin.html2canvasScript
+            ? `<script>${BuiltPlugin.html2canvasScript}</script>`
+            : '';
+        // Inject MCP DOM Agent script
+        const mcpScript = BuiltPlugin.mcpDomAgentScript
+            ? `<script>${BuiltPlugin.mcpDomAgentScript}</script>`
+            : '';
+        // Debug logging
+        if (html2canvasScript) {
+            ctx.logger.debug(`[React SPA] Injecting html2canvas (${(BuiltPlugin.html2canvasScript?.length || 0) / 1024} KB)`);
+        }
+        else {
+            ctx.logger.warn('[React SPA] html2canvas NOT injected - script not loaded');
+        }
+        if (mcpScript) {
+            ctx.logger.debug('[React SPA] Injecting MCP DOM Agent');
+        }
+        const allInjections = configInject + html2canvasScript + mcpScript;
+        const injected = html.replace('</head>', `${allInjections}</head>`);
+        content = Buffer.from(injected, 'utf-8');
+    }
+    res.writeHead(200, corsHeaders({ 'Content-Type': getContentType(targetFile) }));
+    res.end(content);
+}
+/**
+ * Load html2canvas library from node_modules
+ */
+function loadHtml2CanvasScript() {
+    try {
+        // Try multiple possible paths for html2canvas
+        const possiblePaths = [
+            // When running from dist/ (after build)
+            path_1.default.join(__dirname, '..', 'node_modules', 'html2canvas', 'dist', 'html2canvas.min.js'),
+            // When running from src/ (development)
+            path_1.default.join(__dirname, '..', '..', 'node_modules', 'html2canvas', 'dist', 'html2canvas.min.js'),
+            // When installed as a dependency in user's project
+            path_1.default.join(__dirname, '..', '..', '..', 'html2canvas', 'dist', 'html2canvas.min.js'),
+        ];
+        for (const scriptPath of possiblePaths) {
+            if (fs_1.default.existsSync(scriptPath)) {
+                log(`[html2canvas] Loaded from: ${scriptPath}`);
+                return fs_1.default.readFileSync(scriptPath, 'utf-8');
+            }
+        }
+        log('[html2canvas] Script file not found in any expected location');
+        return '';
+    }
+    catch (error) {
+        log(`[html2canvas] Failed to load script: ${error.message}`);
+        return '';
+    }
+}
+/**
+ * Load MCP DOM Agent script
+ */
+function loadMcpDomAgentScript() {
+    try {
+        const scriptPath = path_1.default.join(__dirname, 'mcp-dom-agent.js');
+        if (fs_1.default.existsSync(scriptPath)) {
+            return fs_1.default.readFileSync(scriptPath, 'utf-8');
+        }
+        // Fallback: return minimal inline version if file not found
+        log('[MCP DOM Agent] Script file not found, using minimal fallback');
+        return `(function(){if(window.__mcpDomAgent)return;window.__mcpDomAgent=true;console.log('[MCP DOM Agent] Minimal fallback loaded');})();`;
+    }
+    catch (error) {
+        log(`[MCP DOM Agent] Failed to load script: ${error.message}`);
+        return '';
+    }
+}
 /**
  * Main plugin class built by the fluent API
  */
 class BuiltPlugin {
     constructor(id, name, version, capabilities, tools, apiRoutes, uiConfig, reactScreens, htmlScreens, wizard, settings, onReadyFn, healthCheckFn, userProvidedPluginRoot, 
-    // Function registry
-    functionRegistry, 
-    // Configurable entities
+    // New parameters for function-first architecture
+    functionRegistry, transports, 
+    // New parameter for configurable entities
     configurableEntities, 
-    // Secret providers
+    // New parameter for secret providers
     secretProviders) {
         this.capabilities = capabilities;
         this.tools = tools;
@@ -175,10 +494,13 @@ class BuiltPlugin {
         this.configurableEntities = configurableEntities;
         this.secretProviders = secretProviders;
         this.cleanups = [];
+        this.router = [];
+        this.transports = [];
         this.id = id;
         this.name = name;
         this.version = version;
         this.functionRegistry = functionRegistry;
+        this.transports = transports || [];
         this.configurableEntities = configurableEntities || [];
         this.secretProviders = secretProviders || [];
     }
@@ -246,19 +568,6 @@ class BuiltPlugin {
         }
         return false;
     }
-    /**
-     * Get function provider (new async Plugin interface)
-     * Returns null if plugin has no functions
-     */
-    async getFunctions() {
-        if (!this.functionRegistry) {
-            return null;
-        }
-        if (!this._functionProvider) {
-            this._functionProvider = new registry_1.FunctionProviderImpl(this.functionRegistry, this.context);
-        }
-        return this._functionProvider;
-    }
     async createTool(toolName) {
         const handler = this.tools.get(toolName);
         if (!handler) {
@@ -296,17 +605,77 @@ class BuiltPlugin {
         }
     }
     async onLoad(context) {
-        // NOTE: context.resources is now provided by MAJK (ResourceProvider abstraction)
-        // Plugin-kit no longer manages HTTP servers or file paths directly
-        this.context = context;
+        // Use user-provided pluginRoot (from __dirname) if available, otherwise fall back to context.pluginRoot
+        // The user-provided path comes from Node's __dirname which automatically resolves to the real directory
+        // (following symlinks), making it work correctly in both local development and npm installed scenarios
+        const effectivePluginRoot = this.userProvidedPluginRoot || context.pluginRoot;
+        this.context = {
+            ...context,
+            pluginRoot: effectivePluginRoot
+        };
         context.logger.info('═══════════════════════════════════════════════════════');
         context.logger.info(`🚀 Loading Plugin: ${this.name} (${this.id}) v${this.version}`);
-        context.logger.info(`🔧 Plugin Kit Version: @majkapp/plugin-kit@2.0.0`);
+        context.logger.info(`🔧 Plugin Kit Version: @majkapp/plugin-kit@1.0.19`);
+        context.logger.info(`📍 Plugin Root: ${effectivePluginRoot}`);
+        if (this.userProvidedPluginRoot) {
+            context.logger.info(`   (user-provided via .pluginRoot(__dirname))`);
+        }
+        else {
+            context.logger.info(`   (from MAJK context - consider using .pluginRoot(__dirname) for better reliability)`);
+        }
+        context.logger.info(`🌐 HTTP Port: ${context.http.port}`);
         context.logger.info(`🔗 Base URL: ${context.http.baseUrl}`);
         context.logger.info('═══════════════════════════════════════════════════════');
+        // Load html2canvas and MCP DOM Agent scripts once for all plugins
+        if (!BuiltPlugin.html2canvasScript) {
+            BuiltPlugin.html2canvasScript = loadHtml2CanvasScript();
+            if (BuiltPlugin.html2canvasScript) {
+                const sizeKB = (BuiltPlugin.html2canvasScript.length / 1024).toFixed(2);
+                context.logger.info(`✅ html2canvas library loaded (${sizeKB} KB) - screenshot support enabled`);
+            }
+            else {
+                context.logger.warn('⚠️  html2canvas not found - screenshots will use fallback mode');
+            }
+        }
+        if (!BuiltPlugin.mcpDomAgentScript) {
+            BuiltPlugin.mcpDomAgentScript = loadMcpDomAgentScript();
+            if (BuiltPlugin.mcpDomAgentScript) {
+                context.logger.info('✅ MCP DOM Agent script loaded - will be injected into all screens');
+            }
+        }
+        // Validate file paths now that we have pluginRoot context
+        if (this.reactScreens.length > 0 && this.uiConfig) {
+            const indexPath = path_1.default.join(this.context.pluginRoot, this.uiConfig.appDir || '', 'index.html');
+            if (!fs_1.default.existsSync(indexPath)) {
+                throw new PluginRuntimeError(`React app not built: ${indexPath} does not exist. Run "npm run build" in your UI directory to build the React app.`, 'onLoad', { appDir: this.uiConfig.appDir, indexPath, pluginRoot: this.context.pluginRoot });
+            }
+            context.logger.info(`✅ React UI found at: ${indexPath}`);
+        }
+        // Validate HTML screen files
+        for (const screen of this.htmlScreens) {
+            if ('htmlFile' in screen) {
+                const filePath = path_1.default.join(this.context.pluginRoot, screen.htmlFile);
+                if (!fs_1.default.existsSync(filePath)) {
+                    throw new PluginRuntimeError(`HTML screen file not found: ${screen.htmlFile}. Create the HTML file at ${filePath} or fix the path.`, 'onLoad', { screen: screen.id, file: screen.htmlFile, resolvedPath: filePath, pluginRoot: this.context.pluginRoot });
+                }
+                context.logger.info(`✅ HTML screen file found: ${screen.htmlFile}`);
+            }
+        }
         try {
-            // Log registered functions
+            await this.startServer();
+            // Initialize transports for function-first architecture
             if (this.functionRegistry) {
+                context.logger.info('');
+                context.logger.info('🔌 Initializing Transports...');
+                for (const transport of this.transports) {
+                    await transport.initialize(this.functionRegistry, this.context);
+                    await transport.start();
+                    const metadata = transport.getMetadata();
+                    context.logger.info(`  ✅ ${transport.name} transport initialized`);
+                    context.logger.info(`     • Base Path: ${metadata.endpoint}`);
+                    context.logger.info(`     • Discovery: ${metadata.discovery}`);
+                }
+                // Log registered functions
                 const functionNames = this.functionRegistry.getFunctionNames();
                 if (functionNames.length > 0) {
                     context.logger.info('');
@@ -322,21 +691,136 @@ class BuiltPlugin {
                     }
                 }
             }
+            // Register API routes (legacy)
+            for (const route of this.apiRoutes) {
+                const { regex, keys } = pathToRegex(route.path);
+                this.router.push({
+                    method: route.method,
+                    regex,
+                    keys,
+                    name: route.name,
+                    description: route.description,
+                    handler: route.handler,
+                    requestSchema: route.requestSchema,
+                    responseSchema: route.responseSchema,
+                    tags: route.tags,
+                    deprecated: route.deprecated
+                });
+                context.logger.info(`📝 Registered route: ${route.method} ${route.path} - ${route.name}`);
+            }
+            // Register the discovery endpoint at /majk/plugin/api
+            const discoveryPath = '/majk/plugin/api';
+            const { regex: discoveryRegex, keys: discoveryKeys } = pathToRegex(discoveryPath);
+            this.router.push({
+                method: 'GET',
+                regex: discoveryRegex,
+                keys: discoveryKeys,
+                name: 'API Discovery',
+                description: 'Get OpenAPI specification for all plugin API routes',
+                handler: async (_req, _res, _ctx) => {
+                    // If using function-first architecture, generate spec from function registry
+                    if (this.functionRegistry && this.functionRegistry.getFunctionNames().length > 0) {
+                        return this.functionRegistry.toOpenAPISpec();
+                    }
+                    // Otherwise fall back to legacy API routes
+                    const openApiSpec = generateOpenApiSpec(this.id, this.name, this.version, this.apiRoutes, this.context.http.baseUrl);
+                    return openApiSpec;
+                }
+            });
+            context.logger.info(`📝 Registered discovery route: GET ${discoveryPath}`);
+            // Also register a simpler JSON format at /majk/plugin/routes for quick access
+            const routesPath = '/majk/plugin/routes';
+            const { regex: routesRegex, keys: routesKeys } = pathToRegex(routesPath);
+            this.router.push({
+                method: 'GET',
+                regex: routesRegex,
+                keys: routesKeys,
+                name: 'Routes List',
+                description: 'Get a simple JSON list of all available API routes',
+                handler: async (_req, _res, _ctx) => {
+                    return {
+                        plugin: {
+                            id: this.id,
+                            name: this.name,
+                            version: this.version
+                        },
+                        routes: this.apiRoutes.map(route => ({
+                            method: route.method,
+                            path: route.path,
+                            name: route.name,
+                            description: route.description,
+                            deprecated: route.deprecated,
+                            tags: route.tags,
+                            requestSchema: route.requestSchema,
+                            responseSchema: route.responseSchema
+                        })),
+                        discoveryUrl: `${this.context.http.baseUrl}/majk/plugin/api`
+                    };
+                }
+            });
+            context.logger.info(`📝 Registered routes list: GET ${routesPath}`);
             // Call onReady hook
             if (this.onReadyFn) {
-                context.logger.info('');
                 context.logger.info('⚙️  Calling onReady hook...');
                 await this.onReadyFn(this.context, (fn) => this.cleanups.push(fn));
                 context.logger.info('✅ onReady hook completed');
             }
-            // Print summary
+            // Print comprehensive summary
             context.logger.info('');
             context.logger.info('╔══════════════════════════════════════════════════════════╗');
             context.logger.info('║ 🎉 PLUGIN LOADED SUCCESSFULLY                       ║');
+            context.logger.info('╟──────────────────────────────────────────────────────────╢');
+            context.logger.info('║ 🌐 API ENDPOINTS                                   ║');
+            context.logger.info('╟──────────────────────────────────────────────────────────╢');
+            // API Discovery endpoints
+            context.logger.info(`║ 🔍 Discovery:                                      ║`);
+            context.logger.info(`║    ${context.http.baseUrl}/majk/plugin/api`);
+            context.logger.info(`║    ${context.http.baseUrl}/majk/plugin/routes`);
+            // Function endpoints
+            if (this.functionRegistry && this.functionRegistry.getFunctionNames().length > 0) {
+                context.logger.info(`║                                                      ║`);
+                context.logger.info(`║ 🚀 Function Endpoints:                             ║`);
+                for (const fname of this.functionRegistry.getFunctionNames()) {
+                    context.logger.info(`║    POST ${context.http.baseUrl}/api/fn/${fname}`);
+                }
+            }
+            // Legacy API routes
+            if (this.apiRoutes.length > 0) {
+                context.logger.info(`║                                                      ║`);
+                context.logger.info(`║ 📋 Legacy API Routes:                              ║`);
+                for (const route of this.apiRoutes) {
+                    context.logger.info(`║    ${route.method} ${context.http.baseUrl}${route.path}`);
+                }
+            }
+            // UI Screens
+            const allScreens = [...this.reactScreens, ...this.htmlScreens];
+            if (allScreens.length > 0 || this.uiConfig) {
+                context.logger.info('╟──────────────────────────────────────────────────────────╢');
+                context.logger.info('║ 🕹  UI SCREENS                                      ║');
+                context.logger.info('╟──────────────────────────────────────────────────────────╢');
+                for (const screen of allScreens) {
+                    context.logger.info(`║ • ${screen.name || screen.id}`);
+                    context.logger.info(`║   ${context.http.baseUrl}${screen.route}`);
+                }
+            }
+            // Config Wizard
+            if (this.wizard) {
+                context.logger.info('╟──────────────────────────────────────────────────────────╢');
+                context.logger.info('║ 🧙 CONFIG WIZARD                                   ║');
+                context.logger.info('╟──────────────────────────────────────────────────────────╢');
+                context.logger.info(`║ ${this.wizard.title}`);
+                context.logger.info(`║ ${context.http.baseUrl}${this.wizard.path}`);
+            }
+            // Settings
+            if (this.settings) {
+                context.logger.info('╟──────────────────────────────────────────────────────────╢');
+                context.logger.info('║ ⚙️  SETTINGS                                        ║');
+                context.logger.info('╟──────────────────────────────────────────────────────────╢');
+                context.logger.info(`║ ${this.settings.title}`);
+                context.logger.info(`║ ${context.http.baseUrl}${this.settings.path}`);
+            }
             context.logger.info('╚══════════════════════════════════════════════════════════╝');
             context.logger.info('');
-            context.logger.info('ℹ️  Note: HTTP serving is managed by MAJK, not plugin-kit');
-            context.logger.info('');
         }
         catch (error) {
             context.logger.error(`❌ Failed to load plugin "${this.name}": ${error.message}`);
@@ -357,10 +841,17 @@ class BuiltPlugin {
                 this.context.logger.error(`Error during cleanup: ${error.message}`);
             }
         }
+        // Stop HTTP server
+        if (this.server) {
+            await new Promise((resolve) => {
+                this.server.close(() => {
+                    this.context.logger.info('✅ HTTP server stopped');
+                    resolve();
+                });
+            });
+        }
         this.context.logger.info(`✅ Plugin "${this.name}" unloaded`);
     }
-    // isHealthy() - implements both old and new interface
-    // Returns compatible format for both interfaces
     async isHealthy() {
         if (this.healthCheckFn) {
             try {
@@ -369,25 +860,325 @@ class BuiltPlugin {
                     storage: this.context.storage,
                     logger: this.context.logger
                 });
-                return {
-                    healthy: result.healthy,
-                    checks: result.details,
-                    errors: [],
-                    warnings: []
-                };
+                return { ...result, errors: [], warnings: [] };
             }
             catch (error) {
                 return {
                     healthy: false,
-                    error: `Health check failed: ${error.message}`,
-                    errors: [`Health check failed: ${error.message}`],
-                    warnings: []
+                    errors: [`Health check failed: ${error.message}`]
                 };
             }
         }
-        return { healthy: true, errors: [], warnings: [] };
+        return { healthy: true };
+    }
+    async startServer() {
+        const { port } = this.context.http;
+        this.server = http_1.default.createServer(async (req, res) => {
+            const startTime = Date.now();
+            const method = req.method || 'UNKNOWN';
+            const url = req.url || '/';
+            try {
+                // Log incoming request
+                this.context.logger.debug(`→ ${method} ${url}`);
+                // CORS preflight
+                if (req.method === 'OPTIONS') {
+                    res.writeHead(204, corsHeaders());
+                    res.end();
+                    const duration = Date.now() - startTime;
+                    this.context.logger.debug(`← ${method} ${url} 204 (${duration}ms)`);
+                    return;
+                }
+                // Health check
+                if (req.method === 'GET' && req.url === '/health') {
+                    const health = await this.isHealthy();
+                    res.writeHead(200, corsHeaders({ 'Content-Type': 'application/json' }));
+                    res.end(JSON.stringify({ ...health, plugin: this.name, version: this.version }));
+                    const duration = Date.now() - startTime;
+                    this.context.logger.debug(`← ${method} ${url} 200 (${duration}ms)`);
+                    return;
+                }
+                // MCP Screenshot endpoint
+                if (req.method === 'POST' && req.url === '/api/mcp/screenshot') {
+                    try {
+                        const body = await readBody(req);
+                        if (!body || !body.data) {
+                            res.writeHead(400, corsHeaders({ 'Content-Type': 'application/json' }));
+                            res.end(JSON.stringify({ error: 'Missing screenshot data' }));
+                            return;
+                        }
+                        // Create screenshots directory if it doesn't exist
+                        const screenshotsDir = path_1.default.join(this.context.pluginRoot, 'screenshots');
+                        if (!fs_1.default.existsSync(screenshotsDir)) {
+                            fs_1.default.mkdirSync(screenshotsDir, { recursive: true });
+                        }
+                        // Generate filename
+                        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+                        const metadata = body.metadata || {};
+                        const customName = metadata.filename || `screenshot-${timestamp}`;
+                        const filename = `${customName}.png`;
+                        const filepath = path_1.default.join(screenshotsDir, filename);
+                        // Extract base64 data (remove data:image/png;base64, prefix if present)
+                        const base64Data = body.data.replace(/^data:image\/\w+;base64,/, '');
+                        const buffer = Buffer.from(base64Data, 'base64');
+                        // Write file
+                        fs_1.default.writeFileSync(filepath, buffer);
+                        // Also save metadata
+                        const metadataPath = path_1.default.join(screenshotsDir, `${customName}.json`);
+                        fs_1.default.writeFileSync(metadataPath, JSON.stringify({
+                            ...metadata,
+                            filename,
+                            filepath,
+                            timestamp: new Date().toISOString(),
+                            size: buffer.length
+                        }, null, 2));
+                        // Log with full details
+                        const absolutePath = path_1.default.resolve(filepath);
+                        const absoluteMetadataPath = path_1.default.resolve(metadataPath);
+                        this.context.logger.info(`📸 Screenshot saved successfully:`);
+                        this.context.logger.info(`   Image: ${absolutePath}`);
+                        this.context.logger.info(`   Metadata: ${absoluteMetadataPath}`);
+                        this.context.logger.info(`   Size: ${(buffer.length / 1024).toFixed(2)} KB`);
+                        res.writeHead(200, corsHeaders({ 'Content-Type': 'application/json' }));
+                        res.end(JSON.stringify({
+                            success: true,
+                            filename,
+                            filepath,
+                            size: buffer.length,
+                            message: 'Screenshot saved successfully'
+                        }));
+                        const duration = Date.now() - startTime;
+                        this.context.logger.debug(`← ${method} ${url} 200 (${duration}ms)`);
+                        return;
+                    }
+                    catch (error) {
+                        this.context.logger.error(`Failed to save screenshot: ${error.message}`);
+                        res.writeHead(500, corsHeaders({ 'Content-Type': 'application/json' }));
+                        res.end(JSON.stringify({
+                            success: false,
+                            error: error.message || 'Failed to save screenshot'
+                        }));
+                        return;
+                    }
+                }
+                // HTML screens virtual route
+                if (req.method === 'GET' && req.url?.startsWith('/__html/')) {
+                    const id = decodeURIComponent(req.url.substring('/__html/'.length)).split('?')[0];
+                    const screen = this.htmlScreens.find(s => s.id === id);
+                    if (!screen) {
+                        res.writeHead(404, corsHeaders({ 'Content-Type': 'text/plain' }));
+                        res.end('HTML screen not found');
+                        const duration = Date.now() - startTime;
+                        this.context.logger.debug(`← ${method} ${url} 404 (${duration}ms)`);
+                        return;
+                    }
+                    res.writeHead(200, corsHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
+                    let htmlContent;
+                    if ('html' in screen) {
+                        htmlContent = screen.html;
+                    }
+                    else {
+                        const filePath = path_1.default.join(this.context.pluginRoot, screen.htmlFile);
+                        // Security check
+                        const normalized = path_1.default.resolve(filePath);
+                        const pluginRoot = path_1.default.resolve(this.context.pluginRoot);
+                        if (!normalized.startsWith(pluginRoot)) {
+                            res.writeHead(403, corsHeaders({ 'Content-Type': 'text/plain' }));
+                            res.end('Forbidden');
+                            this.context.logger.warn(`Path traversal attempt: ${screen.htmlFile}`);
+                            const duration = Date.now() - startTime;
+                            this.context.logger.debug(`← ${method} ${url} 403 (${duration}ms)`);
+                            return;
+                        }
+                        try {
+                            htmlContent = fs_1.default.readFileSync(filePath, 'utf-8');
+                        }
+                        catch (error) {
+                            this.context.logger.error(`Failed to read HTML file: ${error.message}`);
+                            res.writeHead(500, corsHeaders({ 'Content-Type': 'text/html' }));
+                            res.end('<!doctype html><html><body><h1>Error loading screen</h1></body></html>');
+                            const duration = Date.now() - startTime;
+                            this.context.logger.debug(`← ${method} ${url} 500 (${duration}ms)`);
+                            return;
+                        }
+                    }
+                    // Inject html2canvas and MCP DOM Agent script into HTML screens
+                    if (BuiltPlugin.mcpDomAgentScript) {
+                        const html2canvasScript = BuiltPlugin.html2canvasScript
+                            ? `<script>${BuiltPlugin.html2canvasScript}</script>`
+                            : '';
+                        const mcpScript = `<script>${BuiltPlugin.mcpDomAgentScript}</script>`;
+                        const allScripts = html2canvasScript + mcpScript;
+                        // Debug logging
+                        if (html2canvasScript) {
+                            this.context.logger.debug(`[HTML Screen] Injecting html2canvas (${(BuiltPlugin.html2canvasScript?.length || 0) / 1024} KB)`);
+                        }
+                        else {
+                            this.context.logger.warn('[HTML Screen] html2canvas NOT injected - script not loaded');
+                        }
+                        this.context.logger.debug('[HTML Screen] Injecting MCP DOM Agent');
+                        // Try to inject before </body>, fallback to </head>, fallback to end of HTML
+                        if (htmlContent.includes('</body>')) {
+                            htmlContent = htmlContent.replace('</body>', `${allScripts}</body>`);
+                        }
+                        else if (htmlContent.includes('</head>')) {
+                            htmlContent = htmlContent.replace('</head>', `${allScripts}</head>`);
+                        }
+                        else {
+                            htmlContent += allScripts;
+                        }
+                    }
+                    res.end(htmlContent);
+                    const duration = Date.now() - startTime;
+                    this.context.logger.debug(`← ${method} ${url} 200 (${duration}ms)`);
+                    return;
+                }
+                // React SPA
+                if (req.method === 'GET' && this.uiConfig && req.url?.startsWith(this.uiConfig.base)) {
+                    serveSpa(this.uiConfig, req, res, this.context);
+                    const duration = Date.now() - startTime;
+                    this.context.logger.debug(`← ${method} ${url} ${res.statusCode || 200} (${duration}ms)`);
+                    return;
+                }
+                // Function calls (new function-first API)
+                if (req.method === 'POST' && req.url?.startsWith('/api/fn/')) {
+                    const functionName = req.url.substring('/api/fn/'.length).split('?')[0];
+                    if (this.functionRegistry && this.transports.length > 0) {
+                        // Use the first HTTP transport to handle the function call
+                        const httpTransport = this.transports.find(t => t.name === 'http');
+                        if (httpTransport) {
+                            const body = await readBody(req);
+                            const request = {
+                                method: 'POST',
+                                url: req.url,
+                                pathname: req.url.split('?')[0],
+                                query: new URL(req.url, `http://localhost:${port}`).searchParams,
+                                params: {},
+                                body,
+                                headers: req.headers
+                            };
+                            const response = makeResponse(res);
+                            await httpTransport.handleFunctionCall(functionName, request, response, {
+                                majk: this.context.majk,
+                                storage: this.context.storage,
+                                logger: this.context.logger,
+                                http: this.context.http
+                            });
+                            const duration = Date.now() - startTime;
+                            this.context.logger.debug(`← POST /api/fn/${functionName} ${res.statusCode || 200} (${duration}ms)`);
+                            return;
+                        }
+                    }
+                }
+                // Function discovery endpoint
+                if (req.method === 'GET' && req.url === '/api/fn/discovery') {
+                    if (this.functionRegistry && this.transports.length > 0) {
+                        const httpTransport = this.transports.find(t => t.name === 'http');
+                        if (httpTransport) {
+                            const discovery = httpTransport.getDiscovery();
+                            res.writeHead(200, corsHeaders({ 'Content-Type': 'application/json' }));
+                            res.end(JSON.stringify(discovery));
+                            const duration = Date.now() - startTime;
+                            this.context.logger.debug(`← GET /api/fn/discovery 200 (${duration}ms)`);
+                            return;
+                        }
+                    }
+                }
+                // API routes (including discovery endpoints) - legacy
+                if (req.url?.startsWith('/api/') || req.url?.startsWith('/majk/plugin/')) {
+                    const url = new URL(req.url, `http://localhost:${port}`);
+                    const pathname = url.pathname;
+                    const method = req.method;
+                    this.context.logger.info(`[ROUTE MATCHING] Incoming: ${method} ${pathname}`);
+                    this.context.logger.info(`[ROUTE MATCHING] Available routes: ${this.router.length}`);
+                    this.router.forEach((r, idx) => {
+                        const matches = r.regex.test(pathname);
+                        this.context.logger.info(`[ROUTE MATCHING] Route ${idx}: ${r.method} ${r.name} - regex: ${r.regex} - keys: [${r.keys.join(', ')}] - matches: ${matches}`);
+                    });
+                    const route = this.router.find(r => r.method === method && r.regex.test(pathname));
+                    if (!route) {
+                        res.writeHead(404, corsHeaders({ 'Content-Type': 'application/json' }));
+                        res.end(JSON.stringify({
+                            error: 'Route not found',
+                            path: pathname,
+                            method,
+                            hint: `Available routes: ${this.router.map(r => `${r.method} ${r.name}`).join(', ')}`
+                        }));
+                        const duration = Date.now() - startTime;
+                        this.context.logger.debug(`← ${method} ${pathname} 404 (${duration}ms)`);
+                        return;
+                    }
+                    const body = await readBody(req);
+                    const match = pathname.match(route.regex);
+                    const params = {};
+                    route.keys.forEach((key, i) => {
+                        params[key] = decodeURIComponent(match[i + 1]);
+                    });
+                    const request = {
+                        method,
+                        url: req.url,
+                        pathname,
+                        query: url.searchParams,
+                        params,
+                        body,
+                        headers: req.headers
+                    };
+                    const response = makeResponse(res);
+                    const routeContext = {
+                        majk: this.context.majk,
+                        storage: this.context.storage,
+                        logger: this.context.logger,
+                        http: this.context.http
+                    };
+                    try {
+                        const result = await route.handler(request, response, routeContext);
+                        if (!res.headersSent) {
+                            res.writeHead(200, corsHeaders({ 'Content-Type': 'application/json' }));
+                            res.end(JSON.stringify(result ?? { success: true }));
+                        }
+                        const duration = Date.now() - startTime;
+                        this.context.logger.debug(`← ${method} ${pathname} ${res.statusCode || 200} (${duration}ms)`);
+                    }
+                    catch (error) {
+                        this.context.logger.error(`API route error: ${method} ${pathname} - ${error.message}`);
+                        if (error.stack) {
+                            this.context.logger.error(error.stack);
+                        }
+                        if (!res.headersSent) {
+                            res.writeHead(500, corsHeaders({ 'Content-Type': 'application/json' }));
+                            res.end(JSON.stringify({
+                                error: error.message || 'Internal server error',
+                                route: route.name,
+                                path: pathname
+                            }));
+                        }
+                        const duration = Date.now() - startTime;
+                        this.context.logger.debug(`← ${method} ${pathname} 500 (${duration}ms)`);
+                    }
+                    return;
+                }
+                // 404
+                res.writeHead(404, corsHeaders({ 'Content-Type': 'application/json' }));
+                res.end(JSON.stringify({ error: 'Not found', path: req.url }));
+            }
+            catch (error) {
+                this.context.logger.error(`Unhandled server error: ${error.message}`);
+                if (!res.headersSent) {
+                    res.writeHead(500, corsHeaders({ 'Content-Type': 'text/plain' }));
+                    res.end('Internal server error');
+                }
+            }
+        });
+        await new Promise((resolve) => {
+            this.server.listen(port, () => {
+                this.context.logger.info(`✅ HTTP server listening on port ${port}`);
+                resolve();
+            });
+        });
     }
 }
+// MCP DOM Agent script (loaded once at startup, accessible to serveSpa function)
+BuiltPlugin.mcpDomAgentScript = null;
+BuiltPlugin.html2canvasScript = null;
 /**
  * Group tools by scope
  */
@@ -420,6 +1211,7 @@ function definePlugin(id, name, version) {
     const _secretProviders = [];
     // Function-first architecture state
     const _functionRegistry = new registry_1.FunctionRegistryImpl(id, name, version);
+    const _transports = [];
     let _clientConfig = null;
     let _ui = { appDir: 'ui/dist', base: '/', history: 'browser' };
     let _uiConfigured = false;
@@ -523,16 +1315,17 @@ function definePlugin(id, name, version) {
             if (!screen.route.startsWith(`/plugin-screens/${id}/`)) {
                 throw new PluginBuildError(`React screen route must start with "/plugin-screens/${id}/"`, `Change route from "${screen.route}" to "/plugin-screens/${id}/your-route"`, { screen: screen.id, route: screen.route });
             }
+            const iframeUrl = `http://localhost:{port}${_ui.base}${screen.reactPath}`;
             _reactScreens.push(screen);
             log(`  🕹  Registered React screen: ${screen.name} at ${screen.route}`);
             const capability = {
                 type: 'screen',
                 id: screen.id,
                 path: screen.route,
-                pluginRoute: screen.reactPath
+                iframeUrl
             };
             if (screen.hash) {
-                capability.pluginRouteHash = screen.hash;
+                capability.hash = screen.hash;
             }
             _capabilities.push(capability);
             return this;
@@ -542,13 +1335,14 @@ function definePlugin(id, name, version) {
             if (!screen.route.startsWith(`/plugin-screens/${id}/`)) {
                 throw new PluginBuildError(`HTML screen route must start with "/plugin-screens/${id}/"`, `Change route from "${screen.route}" to "/plugin-screens/${id}/your-route"`, { screen: screen.id, route: screen.route });
             }
+            const iframeUrl = `http://localhost:{port}/__html/${encodeURIComponent(screen.id)}`;
             _htmlScreens.push(screen);
             log(`  📋 Registered HTML screen: ${screen.name} at ${screen.route}`);
             _capabilities.push({
                 type: 'screen',
                 id: screen.id,
                 path: screen.route,
-                pluginRoute: `/__html/${encodeURIComponent(screen.id)}`
+                iframeUrl
             });
             return this;
         },
@@ -614,7 +1408,7 @@ function definePlugin(id, name, version) {
             return this;
         },
         transport(transport) {
-            log('⚠️  WARNING: .transport() is deprecated in v2.0.0. HTTP serving is now managed by MAJK. This call does nothing.');
+            _transports.push(transport);
             return this;
         },
         generateClient(config) {
@@ -969,6 +1763,10 @@ function definePlugin(id, name, version) {
             // ========== Build Plugin Class ==========
             // MAJK expects a class/constructor, not an instance
             // Return a class that instantiates BuiltPlugin
+            // If no transports specified but functions were defined, add default HTTP transport
+            if (_functionRegistry.functions.size > 0 && _transports.length === 0) {
+                _transports.push(new transports_1.HttpTransport());
+            }
             // TODO: Implement client generation if configured
             if (_clientConfig) {
                 // This would generate the client files based on the function registry
@@ -1017,8 +1815,8 @@ function definePlugin(id, name, version) {
             return class extends BuiltPlugin {
                 constructor() {
                     super(id, name, version, _capabilities, _tools, _apiRoutes, _uiConfigured ? _ui : null, _reactScreens, _htmlScreens, _wizard, _settings, _onReady, _healthCheck, _pluginRoot, 
-                    // Pass function registry if functions were defined
-                    _functionRegistry.functions.size > 0 ? _functionRegistry : undefined, 
+                    // Pass function registry and transports if functions were defined
+                    _functionRegistry.functions.size > 0 ? _functionRegistry : undefined, _transports.length > 0 ? _transports : undefined, 
                     // Pass configurable entities
                     _configurableEntities.length > 0 ? _configurableEntities : undefined, 
                     // Pass secret providers