@expressots/studio 4.0.0-preview.1

package/README.md

@@ -0,0 +1,122 @@
+# @expressots/studio
+
+ExpressoTS Studio - Developer Experience Platform. The main package that orchestrates the Studio Agent and Web UI.
+
+## Installation
+
+```bash
+npm install -D @expressots/studio
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Start Studio
+npx expressots-studio start
+
+# With options
+npx expressots-studio start --port 3333 --agent-port 3334
+
+# Show project info
+npx expressots-studio info
+
+# Clean Studio data
+npx expressots-studio clean
+```
+
+### Programmatic Usage
+
+```typescript
+import { Studio } from '@expressots/studio';
+
+const studio = new Studio({
+  uiPort: 3333,
+  agentPort: 3334,
+  dbPath: '.studio/studio.db',
+  srcPath: './src',
+});
+
+await studio.start();
+
+// Studio is now running
+// UI: http://localhost:3333
+// Agent: ws://localhost:3334
+
+// To stop
+await studio.stop();
+```
+
+### Integration with ExpressoTS CLI
+
+```bash
+# Via ExpressoTS CLI (when integrated)
+expressots studio
+```
+
+## CLI Commands
+
+### `start` (default)
+
+Start ExpressoTS Studio.
+
+Options:
+- `-p, --port <port>` - UI port (default: 3333)
+- `-a, --agent-port <port>` - Agent WebSocket port (default: 3334)
+- `-d, --db-path <path>` - Database path (default: .studio/studio.db)
+- `--src <path>` - Source directory to scan (default: ./src)
+- `--no-browser` - Don't open browser automatically
+
+### `info`
+
+Show information about the current project including discovered routes.
+
+Options:
+- `--src <path>` - Source directory to scan (default: ./src)
+
+### `clean`
+
+Remove all Studio data (database, cache).
+
+Options:
+- `-d, --db-path <path>` - Database path (default: .studio/studio.db)
+
+## Configuration
+
+You can also configure Studio via `expressots.config.ts`:
+
+```typescript
+// expressots.config.ts
+export default {
+  studio: {
+    uiPort: 3333,
+    agentPort: 3334,
+    dbPath: '.studio/studio.db',
+  },
+};
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  ExpressoTS Studio                                       │
+│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐     │
+│  │   Web UI    │  │ Studio Agent │  │ MCP Server │     │
+│  │ :3333       │←→│ :3334        │←→│ (AI tools) │     │
+│  └─────────────┘  └──────────────┘  └────────────┘     │
+│         ↓              ↓                                 │
+│  Your ExpressoTS App (instrumented)                     │
+└─────────────────────────────────────────────────────────┘
+```
+
+## What's Included
+
+- **Studio Agent**: Instrumentation, route discovery, request recording
+- **Web UI**: Dashboard with trace visualization, architecture map, metrics
+- **MCP Server**: AI-powered code generation tools (optional)
+
+## License
+
+MIT © ExpressoTS

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * ExpressoTS Studio CLI
+ * Main entry point for launching the Studio
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG"}

package/dist/cli.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * ExpressoTS Studio CLI
+ * Main entry point for launching the Studio
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import open from 'open';
+import { Studio } from './studio.js';
+const program = new Command();
+program
+    .name('expressots-studio')
+    .description('ExpressoTS Studio - Developer Experience Platform')
+    .version('0.1.0');
+program
+    .command('start')
+    .alias('s')
+    .description('Start ExpressoTS Studio')
+    .option('-p, --port <port>', 'UI port', '3333')
+    .option('-a, --agent-port <port>', 'Agent WebSocket port', '3334')
+    .option('-d, --db-path <path>', 'Database path', '.studio/studio.db')
+    .option('--no-browser', 'Do not open browser automatically')
+    .option('--src <path>', 'Source directory to scan', './src')
+    .option('--standalone', 'Run in standalone mode (starts own agent)', false)
+    .action(async (options) => {
+    try {
+        const studio = new Studio({
+            uiPort: parseInt(options.port, 10),
+            agentPort: parseInt(options.agentPort, 10),
+            dbPath: options.dbPath,
+            srcPath: options.src,
+            standalone: options.standalone,
+        });
+        await studio.start();
+        const agentStatus = options.standalone
+            ? chalk.yellow('Standalone')
+            : studio.isAgentConnected()
+                ? chalk.green('Connected')
+                : chalk.gray('Waiting for app...');
+        console.log('');
+        console.log(chalk.green('  Studio is running'));
+        console.log('');
+        console.log(`  UI      ${chalk.cyan(`http://localhost:${options.port}`)}`);
+        console.log(`  Agent   ${agentStatus} ${chalk.gray(`ws://localhost:${options.agentPort}`)}`);
+        console.log('');
+        console.log(chalk.gray('  Press Ctrl+C to stop'));
+        console.log('');
+        if (options.browser !== false) {
+            await open(`http://localhost:${options.port}`);
+        }
+        process.on('SIGINT', async () => {
+            console.log('');
+            await studio.stop();
+            console.log(chalk.gray('  Studio stopped'));
+            process.exit(0);
+        });
+        process.on('SIGTERM', async () => {
+            await studio.stop();
+            process.exit(0);
+        });
+    }
+    catch (error) {
+        console.error(chalk.red('\n  Failed to start Studio:'), error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+program
+    .command('info')
+    .description('Show information about the current project')
+    .option('--src <path>', 'Source directory to scan', './src')
+    .action(async (options) => {
+    const { RouteScanner } = await import('@expressots/studio-agent');
+    const spinner = ora('Scanning project...').start();
+    try {
+        const scanner = new RouteScanner(options.src);
+        const structure = await scanner.scan();
+        spinner.succeed(chalk.green('Project scanned successfully'));
+        console.log('');
+        console.log(chalk.cyan('📁 Project Structure:'));
+        console.log('');
+        console.log(chalk.white(`  Controllers: ${structure.controllers.length}`));
+        console.log(chalk.white(`  Services: ${structure.services.length}`));
+        console.log(chalk.white(`  Providers: ${structure.providers.length}`));
+        console.log(chalk.white(`  Middleware: ${structure.middleware.length}`));
+        console.log('');
+        if (structure.controllers.length > 0) {
+            console.log(chalk.cyan('🛣️  Routes:'));
+            console.log('');
+            const routes = scanner.getRoutes();
+            for (const route of routes) {
+                const methodColor = route.method === 'GET' ? chalk.green :
+                    route.method === 'POST' ? chalk.blue :
+                        route.method === 'PUT' ? chalk.yellow :
+                            route.method === 'DELETE' ? chalk.red :
+                                chalk.white;
+                console.log(`  ${methodColor(route.method.padEnd(7))} ${route.path}`);
+            }
+            console.log('');
+        }
+    }
+    catch (error) {
+        spinner.fail(chalk.red('Failed to scan project'));
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+program
+    .command('clean')
+    .description('Clean Studio data')
+    .option('-d, --db-path <path>', 'Database path', '.studio/studio.db')
+    .action(async (options) => {
+    const fs = await import('fs');
+    const path = await import('path');
+    const dbPath = path.resolve(process.cwd(), options.dbPath);
+    const studioDir = path.dirname(dbPath);
+    if (fs.existsSync(studioDir)) {
+        fs.rmSync(studioDir, { recursive: true });
+        console.log(chalk.green('✓'), 'Studio data cleaned');
+    }
+    else {
+        console.log(chalk.yellow('No Studio data found'));
+    }
+});
+// Default to start if no command is provided
+program
+    .action(() => {
+    const startCmd = program.commands.find((cmd) => cmd.name() === 'start');
+    startCmd?.parse();
+});
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @expressots/studio
+ *
+ * ExpressoTS Studio - Developer Experience Platform
+ * Main orchestrator package that launches the agent and UI
+ */
+export { Studio } from './studio.js';
+export type { StudioConfig } from './studio.js';
+export { StudioAgent, RouteScanner, RequestRecorder } from '@expressots/studio-agent';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @expressots/studio
+ *
+ * ExpressoTS Studio - Developer Experience Platform
+ * Main orchestrator package that launches the agent and UI
+ */
+export { Studio } from './studio.js';
+// Re-export from agent for convenience
+export { StudioAgent, RouteScanner, RequestRecorder } from '@expressots/studio-agent';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,uCAAuC;AACvC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/studio.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Studio Orchestrator
+ *
+ * Two modes:
+ * 1. UI-only mode (default): Just serves the UI, connects to agent in user's app
+ * 2. Standalone mode: Starts its own agent (for demos or when not using core integration)
+ */
+import { StudioAgent } from '@expressots/studio-agent';
+export interface StudioConfig {
+    uiPort: number;
+    agentPort: number;
+    dbPath: string;
+    srcPath: string;
+    serviceName?: string;
+    /** If true, starts a standalone agent (default: false, just serves UI) */
+    standalone?: boolean;
+}
+export declare class Studio {
+    private config;
+    private agent;
+    private uiApp;
+    private uiServer;
+    private agentClient;
+    private agentConnected;
+    constructor(config?: Partial<StudioConfig>);
+    /** Start the Studio */
+    start(): Promise<void>;
+    /** Stop the Studio */
+    stop(): Promise<void>;
+    /** Connect to an existing agent running in the user's app */
+    private connectToAgent;
+    /** Start the Studio Agent (standalone mode only) */
+    private startAgent;
+    /** Start the UI server */
+    private startUIServer;
+    /** Find the bundled UI dist path */
+    private findUIDistPath;
+    /**
+     * Resolve the brand icon SVG as a base64 data URI. Used by the dev-mode
+     * fallback HTML, which is served as a catch-all when the UI bundle is
+     * missing — so we can't rely on `/expressots-icon.svg` being reachable.
+     * Returns a tiny inline SVG placeholder if the asset is missing.
+     */
+    private getIconDataUri;
+    /** Get development mode HTML */
+    private getDevModeHTML;
+    /** Check if agent is connected */
+    isAgentConnected(): boolean;
+    /** Get the Studio Agent instance (standalone mode only) */
+    getAgent(): StudioAgent | null;
+    /** Get configuration */
+    getConfig(): StudioConfig;
+}
+//# sourceMappingURL=studio.d.ts.map

package/dist/studio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"studio.d.ts","sourceRoot":"","sources":["../src/studio.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,cAAc,CAAkB;gBAE5B,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM;IAW9C,uBAAuB;IACjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B,sBAAsB;IAChB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB3B,6DAA6D;YAC/C,cAAc;IAsC5B,oDAAoD;YACtC,UAAU;IAYxB,0BAA0B;YACZ,aAAa;IAkC3B,oCAAoC;IACpC,OAAO,CAAC,cAAc;IAQtB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IA0BtB,gCAAgC;IAChC,OAAO,CAAC,cAAc;IA0HtB,kCAAkC;IAClC,gBAAgB,IAAI,OAAO;IAI3B,2DAA2D;IAC3D,QAAQ,IAAI,WAAW,GAAG,IAAI;IAI9B,wBAAwB;IACxB,SAAS,IAAI,YAAY;CAG1B"}

package/dist/studio.js

@@ -0,0 +1,308 @@
+/**
+ * Studio Orchestrator
+ *
+ * Two modes:
+ * 1. UI-only mode (default): Just serves the UI, connects to agent in user's app
+ * 2. Standalone mode: Starts its own agent (for demos or when not using core integration)
+ */
+import express from 'express';
+import { createServer } from 'http';
+import { io as SocketIOClient } from 'socket.io-client';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { StudioAgent } from '@expressots/studio-agent';
+export class Studio {
+    config;
+    agent = null;
+    uiApp = null;
+    uiServer = null;
+    agentClient = null;
+    agentConnected = false;
+    constructor(config = {}) {
+        this.config = {
+            uiPort: config.uiPort ?? 3333,
+            agentPort: config.agentPort ?? 3334,
+            dbPath: config.dbPath ?? '.studio/studio.db',
+            srcPath: config.srcPath ?? './src',
+            serviceName: config.serviceName ?? 'expressots-app',
+            standalone: config.standalone ?? false,
+        };
+    }
+    /** Start the Studio */
+    async start() {
+        if (this.config.standalone) {
+            await this.startAgent();
+        }
+        else {
+            // UI-only mode: Try to connect to existing agent
+            await this.connectToAgent();
+        }
+        // Start the UI server
+        await this.startUIServer();
+    }
+    /** Stop the Studio */
+    async stop() {
+        // Disconnect from agent
+        if (this.agentClient) {
+            this.agentClient.disconnect();
+            this.agentClient = null;
+        }
+        // Stop UI server
+        if (this.uiServer) {
+            await new Promise((resolve) => {
+                this.uiServer.close(() => resolve());
+            });
+            this.uiServer = null;
+        }
+        // Stop agent (only if we started it)
+        if (this.agent) {
+            await this.agent.stop();
+            this.agent = null;
+        }
+    }
+    /** Connect to an existing agent running in the user's app */
+    async connectToAgent() {
+        const agentUrl = `http://localhost:${this.config.agentPort}`;
+        return new Promise((resolve) => {
+            const probe = SocketIOClient(agentUrl, {
+                transports: ['websocket'],
+                reconnection: false,
+                timeout: 3000,
+            });
+            this.agentClient = probe;
+            const cleanup = (connected) => {
+                this.agentConnected = connected;
+                probe.removeAllListeners();
+                probe.disconnect();
+                if (this.agentClient === probe) {
+                    this.agentClient = null;
+                }
+                resolve();
+            };
+            const timeout = setTimeout(() => {
+                if (!this.agentConnected) {
+                    cleanup(false);
+                }
+            }, 3000);
+            probe.on('connect', () => {
+                clearTimeout(timeout);
+                cleanup(true);
+            });
+            probe.on('connect_error', () => {
+                // Wait for timeout fallback; reconnection is disabled.
+            });
+        });
+    }
+    /** Start the Studio Agent (standalone mode only) */
+    async startAgent() {
+        this.agent = new StudioAgent({
+            port: this.config.agentPort,
+            dbPath: this.config.dbPath,
+            serviceName: this.config.serviceName,
+            enableRecording: true,
+            enableProfiling: true,
+        });
+        await this.agent.start();
+    }
+    /** Start the UI server */
+    async startUIServer() {
+        this.uiApp = express();
+        // Try to find the built UI files
+        const uiDistPath = this.findUIDistPath();
+        if (uiDistPath && fs.existsSync(uiDistPath)) {
+            // Serve static files from the UI build
+            this.uiApp.use(express.static(uiDistPath));
+            // SPA fallback
+            this.uiApp.get('*', (_req, res) => {
+                res.sendFile(path.join(uiDistPath, 'index.html'));
+            });
+        }
+        else {
+            // Development mode - show placeholder
+            this.uiApp.get('*', (_req, res) => {
+                res.send(this.getDevModeHTML());
+            });
+        }
+        this.uiServer = createServer(this.uiApp);
+        return new Promise((resolve, reject) => {
+            this.uiServer.listen(this.config.uiPort, () => {
+                resolve();
+            });
+            this.uiServer.on('error', (err) => {
+                reject(err);
+            });
+        });
+    }
+    /** Find the bundled UI dist path */
+    findUIDistPath() {
+        // The UI is bundled into this package at build time and lives at
+        // `<package>/dist/ui/` next to the orchestrator's compiled JS.
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const candidate = path.resolve(here, 'ui');
+        return fs.existsSync(candidate) ? candidate : null;
+    }
+    /**
+     * Resolve the brand icon SVG as a base64 data URI. Used by the dev-mode
+     * fallback HTML, which is served as a catch-all when the UI bundle is
+     * missing — so we can't rely on `/expressots-icon.svg` being reachable.
+     * Returns a tiny inline SVG placeholder if the asset is missing.
+     */
+    getIconDataUri() {
+        try {
+            const here = path.dirname(fileURLToPath(import.meta.url));
+            const candidates = [
+                path.resolve(here, 'ui', 'expressots-icon.svg'),
+                path.resolve(here, '..', 'public', 'expressots-icon.svg'),
+                path.resolve(here, '..', '..', 'public', 'expressots-icon.svg'),
+            ];
+            for (const c of candidates) {
+                if (fs.existsSync(c)) {
+                    const svg = fs.readFileSync(c, 'utf8');
+                    return `data:image/svg+xml;base64,${Buffer.from(svg).toString('base64')}`;
+                }
+            }
+        }
+        catch {
+            // fall through
+        }
+        // Minimal inline fallback (green circle) — matches the brand tone but
+        // ships zero external dependencies.
+        const fallback = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">' +
+            '<circle cx="32" cy="32" r="30" fill="#171717"/>' +
+            '<circle cx="32" cy="32" r="22" fill="#3de678"/></svg>';
+        return `data:image/svg+xml;base64,${Buffer.from(fallback).toString('base64')}`;
+    }
+    /** Get development mode HTML */
+    getDevModeHTML() {
+        const modeText = this.config.standalone
+            ? '🔧 Standalone Mode - Agent running here'
+            : this.agentConnected
+                ? '✅ Connected to your app\'s agent'
+                : '⏳ Waiting for agent connection...';
+        const modeColor = this.config.standalone
+            ? '#f59e0b'
+            : this.agentConnected
+                ? '#22c55e'
+                : '#6b7280';
+        const iconDataUri = this.getIconDataUri();
+        return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="icon" type="image/svg+xml" href="${iconDataUri}">
+  <title>ExpressoTS Studio</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: #171717;
+      color: #fff;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+    .container { text-align: center; padding: 40px; max-width: 600px; }
+    .logo {
+      width: 96px;
+      height: 96px;
+      margin: 0 auto 20px;
+      display: block;
+      border-radius: 50%;
+      box-shadow: 0 8px 32px rgba(61, 230, 120, 0.2);
+    }
+    h1 {
+      font-size: 2.5rem;
+      margin-bottom: 10px;
+      background: linear-gradient(90deg, #3de678, #19ce59);
+      -webkit-background-clip: text;
+      -webkit-text-fill-color: transparent;
+      background-clip: text;
+    }
+    .subtitle { color: #9ca3af; font-size: 1.1rem; margin-bottom: 30px; }
+    .status {
+      background: rgba(61, 230, 120, 0.08);
+      border: 1px solid ${modeColor}40;
+      border-radius: 12px;
+      padding: 20px 30px;
+      margin-bottom: 30px;
+    }
+    .status h2 { color: ${modeColor}; font-size: 1.2rem; margin-bottom: 10px; }
+    .status p { color: #9ca3af; }
+    .agent-info {
+      background: rgba(34, 197, 94, 0.1);
+      border: 1px solid rgba(34, 197, 94, 0.3);
+      border-radius: 8px;
+      padding: 15px;
+      margin-top: 20px;
+    }
+    .agent-info code { color: #22c55e; font-family: 'JetBrains Mono', monospace; }
+    .instructions { color: #6b7280; font-size: 0.9rem; margin-top: 30px; line-height: 1.8; }
+    .instructions code {
+      background: rgba(255,255,255,0.1);
+      padding: 2px 8px;
+      border-radius: 4px;
+      font-family: 'JetBrains Mono', monospace;
+    }
+    .help-box {
+      background: rgba(99, 102, 241, 0.1);
+      border: 1px solid rgba(99, 102, 241, 0.3);
+      border-radius: 8px;
+      padding: 20px;
+      margin-top: 30px;
+      text-align: left;
+    }
+    .help-box h3 { color: #818cf8; margin-bottom: 10px; }
+    .help-box ol { padding-left: 20px; color: #9ca3af; }
+    .help-box li { margin-bottom: 8px; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <img class="logo" src="${iconDataUri}" alt="ExpressoTS" />
+    <h1>ExpressoTS Studio</h1>
+    <p class="subtitle">Developer Experience Platform</p>
+    
+    <div class="status">
+      <h2>${modeText}</h2>
+      <div class="agent-info">
+        <code>ws://localhost:${this.config.agentPort}</code>
+      </div>
+    </div>
+    
+    ${!this.agentConnected && !this.config.standalone ? `
+    <div class="help-box">
+      <h3>📋 How to capture requests:</h3>
+      <ol>
+        <li>Install the agent in your app: <code>npm install @expressots/studio-agent</code></li>
+        <li>Restart your ExpressoTS app</li>
+        <li>Refresh this page</li>
+      </ol>
+    </div>
+    ` : ''}
+    
+    <p class="instructions">
+      The Studio UI failed to load. Try reinstalling @expressots/studio.
+    </p>
+  </div>
+</body>
+</html>
+    `;
+    }
+    /** Check if agent is connected */
+    isAgentConnected() {
+        return this.agentConnected || this.agent !== null;
+    }
+    /** Get the Studio Agent instance (standalone mode only) */
+    getAgent() {
+        return this.agent;
+    }
+    /** Get configuration */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+//# sourceMappingURL=studio.js.map