@nexus-cortex/executors 4.26.0

package/dist/implementations/addon/ModifySandboxTool.js

@@ -0,0 +1,266 @@
+import { BaseTool } from '../../base/BaseTool.js';
+import { CreateArtifactToolExecutor } from './CreateArtifactTool.js';
+import { visualBridge } from './VisualFeedbackBridge.js';
+import { broadcaster } from './SandboxEventBroadcaster.js';
+import { rebuildReactBundle } from './ReactArtifactBuilder.js';
+import { promises as fs } from 'fs';
+import { join } from 'path';
+/**
+ * ModifySandboxTool - Edit sandbox code with automatic hot reload and verification
+ *
+ * This tool provides a higher-level interface than raw Write tool:
+ * - Edits files within the sandbox directory
+ * - Waits for hot reload to complete
+ * - Captures visual snapshot after changes
+ * - Verifies changes took effect
+ *
+ * Advantages over Write tool:
+ * 1. Sandbox-aware - knows sandbox directory structure
+ * 2. Hot reload integration - waits for restart
+ * 3. Automatic verification - captures post-edit snapshot
+ * 4. Error detection - checks if reload succeeded
+ *
+ * Use Cases:
+ * 1. Iterative development - Edit → See → Edit again
+ * 2. Bug fixing - Modify code, verify fix visually
+ * 3. Feature addition - Add code, test immediately
+ * 4. Styling - Change CSS, see results instantly
+ *
+ * Example:
+ * ```
+ * await modifySandbox({
+ *   sandboxId: "abc-123",
+ *   file: "index.js",
+ *   content: "// fixed code",
+ *   waitForReload: true,
+ *   captureAfterReload: true
+ * });
+ * ```
+ */
+export class ModifySandboxExecutor extends BaseTool {
+    sandboxDir;
+    constructor(config) {
+        const schema = {
+            type: 'object',
+            properties: {
+                sandboxId: {
+                    type: 'string',
+                    description: 'Unique ID of the sandbox to modify'
+                },
+                file: {
+                    type: 'string',
+                    description: 'Filename to edit (relative to sandbox directory, e.g., "index.js")'
+                },
+                content: {
+                    type: 'string',
+                    description: 'New file content'
+                },
+                waitForReload: {
+                    type: 'boolean',
+                    description: 'Wait for hot reload to complete (default: true for dev mode)'
+                },
+                captureAfterReload: {
+                    type: 'boolean',
+                    description: 'Capture visual snapshot after reload (default: true)'
+                },
+                verifyChanges: {
+                    type: 'boolean',
+                    description: 'Verify changes via visual diff (default: false, expensive)'
+                }
+            },
+            required: ['sandboxId', 'file', 'content']
+        };
+        super('ModifySandbox', 'ModifySandbox', 'Edit sandbox code with automatic hot reload and visual verification', schema);
+        this.sandboxDir = join(config.workingDirectory, '.addon-tools');
+    }
+    validateToolParams(params) {
+        if (!params.sandboxId || params.sandboxId.trim().length === 0) {
+            return 'sandboxId is required';
+        }
+        if (!params.file || params.file.trim().length === 0) {
+            return 'file is required';
+        }
+        // Prevent path traversal
+        if (params.file.includes('..') || params.file.startsWith('/')) {
+            return 'file must be a relative path within the sandbox (no .. or absolute paths)';
+        }
+        if (params.content === undefined || params.content === null) {
+            return 'content is required (can be empty string for clearing file)';
+        }
+        return null;
+    }
+    async execute(params, signal) {
+        const startTime = Date.now();
+        const validationError = this.validateToolParams(params);
+        if (validationError) {
+            return this.createErrorResult(validationError);
+        }
+        try {
+            // Get sandbox session
+            const session = CreateArtifactToolExecutor.getActiveSandbox(params.sandboxId);
+            if (!session) {
+                return this.createErrorResult(`Sandbox not found: ${params.sandboxId}. It may have been stopped or never existed.`);
+            }
+            // Prefer the session's real served/built directory (the workspace). Fall back to the
+            // legacy reconstructed path only if the session didn't record one.
+            const sandboxPath = session.path || join(this.sandboxDir, params.sandboxId);
+            // Verify sandbox directory exists
+            try {
+                await fs.access(sandboxPath);
+            }
+            catch {
+                return this.createErrorResult(`Sandbox directory not found: ${sandboxPath}`);
+            }
+            // Capture snapshot before modification (for comparison)
+            let snapshotBefore = session.visualSnapshot;
+            if (params.verifyChanges && session.url) {
+                try {
+                    await visualBridge.initialize();
+                    snapshotBefore = await visualBridge.captureSnapshot(session.url);
+                }
+                catch (error) {
+                    console.warn('Could not capture before snapshot:', error);
+                }
+            }
+            // Write new file content
+            const filePath = join(sandboxPath, params.file);
+            await fs.writeFile(filePath, params.content, 'utf-8');
+            // Emit file changed event
+            broadcaster.emitFileChange(params.sandboxId, params.file, 'modified');
+            // React bundled artifacts: re-run esbuild so the served bundle reflects the edit
+            // (the static http-server has no process to hot-reload). No-op for CDN/non-React.
+            let reactRebuilt = false;
+            const rebuild = await rebuildReactBundle(sandboxPath);
+            if (rebuild.rebuilt) {
+                reactRebuilt = true;
+                broadcaster.emitHotReload(params.sandboxId, params.file);
+            }
+            else if (rebuild.error) {
+                console.warn(`[ModifySandbox] React re-bundle failed: ${rebuild.error}`);
+            }
+            // Determine if we should wait for reload
+            const waitForReload = params.waitForReload ?? (session.mode === 'dev');
+            const captureAfterReload = params.captureAfterReload ?? true;
+            let snapshotAfter = null;
+            let reloadWaitTime = 0;
+            if (waitForReload) {
+                // Wait for hot reload to complete
+                // Hot reload typically takes:
+                // - 100-500ms to detect file change
+                // - 1-2s to restart process
+                // - 500ms for server to be ready
+                reloadWaitTime = 3000; // 3 seconds total
+                await this.wait(reloadWaitTime);
+                // Capture snapshot after reload
+                if (captureAfterReload && session.url) {
+                    try {
+                        await visualBridge.initialize();
+                        snapshotAfter = await visualBridge.captureSnapshot(session.url);
+                        session.visualSnapshot = snapshotAfter;
+                        session.lastActivity = new Date();
+                        // Emit screenshot captured event
+                        broadcaster.emitScreenshot(params.sandboxId, snapshotAfter.screenshot, session.url);
+                    }
+                    catch (error) {
+                        console.warn('Could not capture after snapshot:', error);
+                        broadcaster.emitError(params.sandboxId, error);
+                    }
+                }
+            }
+            // Compute visual diff if requested
+            let visualDiff = null;
+            if (params.verifyChanges && snapshotBefore && snapshotAfter) {
+                // TODO: Implement getVisualDiff in VisualFeedbackBridge
+                // For now, skip visual diff
+                console.warn('Visual diff not yet implemented');
+            }
+            // Format output
+            const output = this.formatModificationOutput(session, params, snapshotAfter, visualDiff, reloadWaitTime, reactRebuilt);
+            return {
+                ...this.createSuccessResult(output),
+                metadata: {
+                    executionTime: Date.now() - startTime,
+                    sandboxId: params.sandboxId,
+                    fileModified: params.file,
+                    bytesWritten: params.content.length,
+                    waitedForReload: waitForReload,
+                    reloadWaitTime,
+                    capturedSnapshot: !!snapshotAfter,
+                    hasVisualDiff: !!visualDiff,
+                    reactRebuilt
+                }
+            };
+        }
+        catch (error) {
+            return this.createErrorResult(`Failed to modify sandbox: ${error.message}`);
+        }
+    }
+    /**
+     * Wait helper
+     */
+    wait(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Format modification output for model consumption
+     */
+    formatModificationOutput(session, params, snapshotAfter, visualDiff, reloadWaitTime, reactRebuilt) {
+        const lines = [];
+        lines.push(`# ✏ Sandbox Modified: ${session.name}`);
+        lines.push('');
+        lines.push(`**Sandbox ID**: ${session.id}`);
+        lines.push(`**File Modified**: ${params.file}`);
+        lines.push(`**Bytes Written**: ${params.content.length}`);
+        lines.push('');
+        if (reactRebuilt) {
+            lines.push('##  React Re-bundle');
+            lines.push('');
+            lines.push('[OK] esbuild re-bundled the React source; the served bundle now reflects your edit.');
+            lines.push('');
+        }
+        if (params.waitForReload) {
+            lines.push('##  Hot Reload');
+            lines.push('');
+            lines.push(`[OK] Waited ${reloadWaitTime}ms for hot reload to complete`);
+            lines.push('[OK] Process restarted automatically');
+            lines.push('');
+        }
+        if (snapshotAfter) {
+            lines.push('---');
+            lines.push('');
+            lines.push('##  Visual State After Modification');
+            lines.push('');
+            lines.push(visualBridge.formatForModel(snapshotAfter));
+            lines.push('');
+        }
+        if (visualDiff) {
+            lines.push('---');
+            lines.push('');
+            lines.push('##  Visual Diff');
+            lines.push('');
+            lines.push(`**Changes Detected**: ${visualDiff.hasChanges ? 'Yes' : 'No'}`);
+            if (visualDiff.hasChanges) {
+                lines.push('');
+                lines.push('**What Changed**:');
+                if (visualDiff.domDiff) {
+                    lines.push(`- DOM: ${visualDiff.domDiff.added || 0} additions, ${visualDiff.domDiff.removed || 0} removals`);
+                }
+                if (visualDiff.screenshotDiff) {
+                    lines.push(`- Visual: ${visualDiff.screenshotDiff.percentDiff}% pixels changed`);
+                }
+            }
+            lines.push('');
+        }
+        lines.push('---');
+        lines.push('');
+        lines.push('**Status**: File successfully modified');
+        lines.push('');
+        lines.push('**Next Steps**:');
+        lines.push('- Verify changes look correct in visual snapshot above');
+        lines.push('- Test functionality (Use InteractWithSandbox)');
+        lines.push('- Continue editing if needed (Call ModifySandbox again)');
+        lines.push('- Inspect detailed state (Use InspectSandbox)');
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=ModifySandboxTool.js.map

package/dist/implementations/addon/ModifySandboxTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModifySandboxTool.js","sourceRoot":"","sources":["../../../src/implementations/addon/ModifySandboxTool.ts"],"names":[],"mappings":"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"}

package/dist/implementations/addon/ReactArtifactBuilder.d.ts

@@ -0,0 +1,27 @@
+export interface ReactBuildOptions {
+    /** The user's entry component source. Should define (or default-export) `App`. */
+    code: string;
+    /** Extra source modules for bundled mode, e.g. { path: 'components/Button.tsx', code }. */
+    additionalFiles?: Array<{
+        path: string;
+        code: string;
+    }>;
+    /** Force a mode. Default: 'bundled' if esbuild is installed, else 'cdn'. */
+    reactMode?: 'cdn' | 'bundled';
+    /** Pin the CDN React version (cdn mode). Default 18. */
+    cdnReactVersion?: string;
+}
+export interface ReactBuildResult {
+    mode: 'cdn' | 'bundled';
+    warnings: string[];
+}
+export declare function buildReactArtifact(artifactPath: string, opts: ReactBuildOptions): Promise<ReactBuildResult>;
+/**
+ * Re-bundle a bundled React artifact after a source edit (Phase 3). No-op for CDN or
+ * non-React artifacts. Returns whether a bundle was produced.
+ */
+export declare function rebuildReactBundle(artifactPath: string): Promise<{
+    rebuilt: boolean;
+    error?: string;
+}>;
+//# sourceMappingURL=ReactArtifactBuilder.d.ts.map

package/dist/implementations/addon/ReactArtifactBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReactArtifactBuilder.d.ts","sourceRoot":"","sources":["../../../src/implementations/addon/ReactArtifactBuilder.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,eAAe,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,4EAA4E;IAC5E,SAAS,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC9B,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,KAAK,GAAG,SAAS,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAgCD,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAqB3B;AAoFD;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAe/C"}

package/dist/implementations/addon/ReactArtifactBuilder.js

@@ -0,0 +1,198 @@
+/**
+ * React artifact builder — turns a user component into a static directory served by
+ * the existing http-server path. Two modes (react_artifact_templates_plan.md):
+ *
+ *  - 'cdn'     : single index.html, React dev UMD + @babel/standalone, JSX compiled in the
+ *                browser with development:true so React records _debugSource (scan/grab see
+ *                componentName + props + a sourceLocation of `App.tsx:line`). Zero deps.
+ *  - 'bundled' : esbuild bundles src/* (react/react-dom resolved from THIS package — no
+ *                per-artifact npm install) with real source maps + jsxDev, so grab's
+ *                sourceLocation points at real `src/App.tsx:line:col`. Optional dep; falls
+ *                back to 'cdn' when esbuild is unavailable.
+ *
+ * Both write index.html and let CreateArtifactTool serve via `npx http-server`.
+ */
+import { promises as fs } from 'fs';
+import { join, dirname } from 'path';
+import { createRequire } from 'module';
+const require_ = createRequire(import.meta.url);
+/** Ensure the entry source default-exports an `App` (idempotent). */
+function ensureDefaultExport(code) {
+    if (/export\s+default/.test(code))
+        return code;
+    if (/(?:function|const|let|class)\s+App\b/.test(code)) {
+        return `${code}\nexport default App;\n`;
+    }
+    return code; // user wrote their own structure; leave as-is
+}
+/** CDN mode: strip module syntax React can't run inline (imports of react / export kw). */
+function stripForInlineScript(code) {
+    return code
+        .replace(/^\s*import\s+[^;]*?from\s+['"]react(?:-dom)?(?:\/[^'"]*)?['"];?\s*$/gm, '')
+        .replace(/^\s*export\s+default\s+function\b/gm, 'function')
+        .replace(/^\s*export\s+default\s+class\b/gm, 'class')
+        .replace(/^\s*export\s+default\s+/gm, 'const __default = ')
+        .replace(/^\s*export\s+/gm, '');
+}
+function isBundledAvailable() {
+    try {
+        require_.resolve('esbuild');
+        require_.resolve('react');
+        require_.resolve('react-dom');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function buildReactArtifact(artifactPath, opts) {
+    const warnings = [];
+    let mode = opts.reactMode ?? (isBundledAvailable() ? 'bundled' : 'cdn');
+    if (mode === 'bundled' && !isBundledAvailable()) {
+        warnings.push('Bundled mode requested but esbuild/react not installed — falling back to CDN mode.');
+        mode = 'cdn';
+    }
+    if (mode === 'bundled') {
+        try {
+            await buildBundled(artifactPath, opts);
+            return { mode: 'bundled', warnings };
+        }
+        catch (err) {
+            warnings.push(`esbuild bundle failed (${err.message}); falling back to CDN mode.`);
+            mode = 'cdn';
+        }
+    }
+    await buildCdn(artifactPath, opts, warnings);
+    return { mode: 'cdn', warnings };
+}
+async function buildCdn(artifactPath, opts, warnings) {
+    if (opts.additionalFiles?.length) {
+        warnings.push('additionalFiles are ignored in CDN mode — use bundled mode for multi-file artifacts.');
+    }
+    const version = opts.cdnReactVersion ?? '18';
+    const userSource = stripForInlineScript(ensureDefaultExport(opts.code));
+    // Keep the user source verbatim in a non-executing block; a bootstrap compiles it with
+    // @babel/standalone using development:true (records JSX _debugSource), then renders <App/>.
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>React Artifact</title>
+  <script crossorigin src="https://unpkg.com/react@${version}/umd/react.development.js"></script>
+  <script crossorigin src="https://unpkg.com/react-dom@${version}/umd/react-dom.development.js"></script>
+  <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="text/plain" id="cortex-app-source">${escapeForScript(userSource)}</script>
+  <script>
+    (function () {
+      try {
+        var src = document.getElementById('cortex-app-source').textContent;
+        var out = Babel.transform(src, {
+          presets: [['react', { development: true }], 'typescript'],
+          filename: 'App.tsx'
+        }).code;
+        // Indirect eval -> global scope, so 'App' is reachable by the render call below.
+        (0, eval)(out);
+        var Root = (typeof App !== 'undefined') ? App
+          : (typeof __default !== 'undefined') ? __default : null;
+        if (!Root) throw new Error('No App component found. Name your component "App" or default-export it.');
+        ReactDOM.createRoot(document.getElementById('root')).render(React.createElement(Root));
+      } catch (e) {
+        document.getElementById('root').innerHTML =
+          '<pre style="color:#c00;white-space:pre-wrap">React artifact error:\\n' +
+          String(e && e.message || e) + '</pre>';
+        console.error('[react-artifact]', e);
+      }
+    })();
+  </script>
+</body>
+</html>
+`;
+    await fs.writeFile(join(artifactPath, 'index.html'), html);
+}
+/** Re-run esbuild for an already-scaffolded bundled artifact (src/main.tsx present). */
+async function runEsbuild(artifactPath) {
+    const esbuild = require_('esbuild');
+    // Resolve react/react-dom from THIS package's node_modules — never per-artifact install.
+    const reactDir = dirname(require_.resolve('react/package.json'));
+    const reactDomDir = dirname(require_.resolve('react-dom/package.json'));
+    const reactNodeModules = join(reactDir, '..');
+    await esbuild.build({
+        entryPoints: [join(artifactPath, 'src', 'main.tsx')],
+        bundle: true,
+        outfile: join(artifactPath, 'dist', 'bundle.js'),
+        sourcemap: true, // dist/bundle.js.map references src/*.tsx
+        jsx: 'automatic',
+        jsxDev: true, // emit jsxDEV(...) with __source -> grab.sourceLocation
+        format: 'iife',
+        target: 'es2020',
+        define: { 'process.env.NODE_ENV': '"development"' },
+        nodePaths: [reactNodeModules], // bare 'react'/'react-dom' resolve here
+        // Dedup React: when the artifact builds INSIDE a monorepo, esbuild's upward
+        // node_modules walk can resolve the user's `import 'react'` and react-dom's internal
+        // `react` to DIFFERENT copies -> "Invalid hook call (more than one copy of React)" ->
+        // <App> crashes and #root stays empty (react-dom still registers a renderer, so detect
+        // reports react:true). Pin every react/react-dom (and subpaths) to ONE resolved dir.
+        alias: { 'react': reactDir, 'react-dom': reactDomDir },
+        logLevel: 'silent'
+    });
+}
+/**
+ * Re-bundle a bundled React artifact after a source edit (Phase 3). No-op for CDN or
+ * non-React artifacts. Returns whether a bundle was produced.
+ */
+export async function rebuildReactBundle(artifactPath) {
+    try {
+        await fs.access(join(artifactPath, 'src', 'main.tsx'));
+    }
+    catch {
+        return { rebuilt: false }; // not a bundled React artifact
+    }
+    if (!isBundledAvailable()) {
+        return { rebuilt: false, error: 'esbuild not available' };
+    }
+    try {
+        await runEsbuild(artifactPath);
+        return { rebuilt: true };
+    }
+    catch (err) {
+        return { rebuilt: false, error: err.message };
+    }
+}
+async function buildBundled(artifactPath, opts) {
+    const srcDir = join(artifactPath, 'src');
+    await fs.mkdir(srcDir, { recursive: true });
+    await fs.writeFile(join(srcDir, 'App.tsx'), ensureDefaultExport(opts.code));
+    await fs.writeFile(join(srcDir, 'main.tsx'), `import { createRoot } from 'react-dom/client';\n` +
+        `import App from './App';\n` +
+        `const el = document.getElementById('root');\n` +
+        `if (el) createRoot(el).render(<App />);\n`);
+    for (const f of opts.additionalFiles ?? []) {
+        const dest = join(srcDir, f.path);
+        await fs.mkdir(dirname(dest), { recursive: true });
+        await fs.writeFile(dest, f.code);
+    }
+    await runEsbuild(artifactPath);
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>React Artifact</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script src="./dist/bundle.js"></script>
+</body>
+</html>
+`;
+    await fs.writeFile(join(artifactPath, 'index.html'), html);
+}
+/** Make user source safe inside a <script> block (only </script> can break out). */
+function escapeForScript(code) {
+    return code.replace(/<\/script>/gi, '<\\/script>');
+}
+//# sourceMappingURL=ReactArtifactBuilder.js.map

package/dist/implementations/addon/ReactArtifactBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReactArtifactBuilder.js","sourceRoot":"","sources":["../../../src/implementations/addon/ReactArtifactBuilder.ts"],"names":[],"mappings":"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"}

package/dist/implementations/addon/SandboxEventBroadcaster.d.ts

@@ -0,0 +1,143 @@
+import { EventEmitter } from 'events';
+/**
+ * Event types emitted by sandboxes
+ */
+export type SandboxEventType = 'sandbox-created' | 'sandbox-started' | 'sandbox-stopped' | 'file-changed' | 'console-log' | 'console-error' | 'console-warn' | 'network-request' | 'network-response' | 'screenshot-captured' | 'interaction-executed' | 'hot-reload-triggered' | 'process-restarted' | 'error-occurred';
+/**
+ * Base event structure
+ */
+export interface SandboxEvent {
+    type: SandboxEventType;
+    sandboxId: string;
+    timestamp: number;
+    data: any;
+}
+/**
+ * SandboxEventBroadcaster - Centralized event system for sandbox operations
+ *
+ * This singleton class provides real-time event broadcasting for all sandbox operations.
+ * It enables:
+ * - User real-time monitoring via WebSocket connections
+ * - Model observability of sandbox state changes
+ * - Debugging and audit trails
+ * - Multi-sandbox coordination
+ *
+ * Event Flow:
+ * 1. Tool (CreateAddon, Modify, Interact) emits event → broadcaster.emit()
+ * 2. Broadcaster stores event in history
+ * 3. Broadcaster notifies all listeners (WebSocket, logs, etc.)
+ * 4. User sees update in dashboard
+ *
+ * Example Usage:
+ * ```
+ * // In CreateAddonToolEnhanced
+ * broadcaster.emit({
+ *   type: 'sandbox-created',
+ *   sandboxId: session.id,
+ *   timestamp: Date.now(),
+ *   data: { name: session.name, url: session.url }
+ * });
+ *
+ * // In SandboxViewServer
+ * broadcaster.on('console-log', (event) => {
+ *   io.to(event.sandboxId).emit('console-log', event.data);
+ * });
+ * ```
+ */
+export declare class SandboxEventBroadcaster extends EventEmitter {
+    private static instance;
+    /**
+     * Event history (last 1000 events per sandbox)
+     */
+    private eventHistory;
+    /**
+     * Maximum events to keep per sandbox
+     */
+    private readonly MAX_EVENTS_PER_SANDBOX;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): SandboxEventBroadcaster;
+    /**
+     * Emit a sandbox event
+     */
+    emitSandboxEvent(event: SandboxEvent): void;
+    /**
+     * Add event to history
+     */
+    private addToHistory;
+    /**
+     * Get event history for a sandbox
+     */
+    getHistory(sandboxId: string, limit?: number): SandboxEvent[];
+    /**
+     * Get all sandbox IDs with events
+     */
+    getActiveSandboxes(): string[];
+    /**
+     * Clear history for a sandbox
+     */
+    clearHistory(sandboxId: string): void;
+    /**
+     * Clear all history
+     */
+    clearAllHistory(): void;
+    /**
+     * Helper: Emit console log
+     */
+    emitConsoleLog(sandboxId: string, level: 'log' | 'error' | 'warn', message: string): void;
+    /**
+     * Helper: Emit file change
+     */
+    emitFileChange(sandboxId: string, filePath: string, changeType: 'created' | 'modified' | 'deleted'): void;
+    /**
+     * Helper: Emit screenshot
+     */
+    emitScreenshot(sandboxId: string, screenshot: string, url: string): void;
+    /**
+     * Helper: Emit network request
+     */
+    emitNetworkRequest(sandboxId: string, method: string, url: string, status?: number): void;
+    /**
+     * Helper: Emit interaction
+     */
+    emitInteraction(sandboxId: string, actionType: string, selector?: string, success?: boolean): void;
+    /**
+     * Helper: Emit hot reload
+     */
+    emitHotReload(sandboxId: string, fileName: string): void;
+    /**
+     * Helper: Emit process restart
+     */
+    emitProcessRestart(sandboxId: string, reason: string): void;
+    /**
+     * Helper: Emit error
+     */
+    emitError(sandboxId: string, error: Error | string): void;
+    /**
+     * Subscribe to all events for a specific sandbox
+     */
+    subscribeToSandbox(sandboxId: string, callback: (event: SandboxEvent) => void): () => void;
+    /**
+     * Subscribe to specific event type
+     */
+    subscribeToEventType(eventType: SandboxEventType, callback: (event: SandboxEvent) => void): () => void;
+    /**
+     * Subscribe to all events
+     */
+    subscribeToAll(callback: (event: SandboxEvent) => void): () => void;
+    /**
+     * Get event statistics
+     */
+    getStats(): {
+        activeSandboxes: number;
+        totalEvents: number;
+        eventsByType: Record<string, number>;
+    };
+}
+/**
+ * Export singleton instance
+ */
+export declare const broadcaster: SandboxEventBroadcaster;
+//# sourceMappingURL=SandboxEventBroadcaster.d.ts.map