slidev-addon-web-terminal 0.2.0

package/README.md

@@ -0,0 +1,126 @@
+# Slidev Addon Web Terminal
+
+This addon provides a `WebTerminal` component for [Slidev](https://sli.dev/) presentations, allowing you to embed a fully functional terminal connected to a backend process.
+
+## Features
+
+- **Xterm.js Integration**: Uses a full-featured terminal emulator.
+- **Backend Connection**: Connects to a backend WebSocket/API service.
+  - See: [berttejeda/bert.webterminal](https://github.com/berttejeda/bert.webterminal)
+- **Zero-Config Dynamic Proxy**: Specify any `backendUrl` (including different domains and ports) in your markdown, and the addon handles CORS and proxying automatically.
+- **Click to Execute**: Commands are automatically sent to the terminal when clicking an element with the `.clickable-code` class (e.g. a wrapper around a code block).
+- **Auto-fit**: Automatically resizes the terminal to fit the container.
+- **Theme Support**: Styled for dark mode by default.
+
+## Installation
+
+```bash
+npm install slidev-addon-web-terminal
+```
+
+## Backend Setup
+
+This addon requires a backend service to handle the terminal sessions.
+
+To get started quickly, run the [Webterminal Agent](https://github.com/berttejeda/bert.webterminal) using Docker:
+
+```bash
+docker run -d --name webterminal --rm -p {{ HOSTPORT }}:10001 berttejeda/bill-webterminal
+```
+
+Example (port 10001):
+```bash
+docker run -d --name webterminal --rm -p 10001:10001 berttejeda/bill-webterminal
+```
+
+## Configuration
+
+To enable the **Dynamic Port Proxy** (which solves CORS issues when using different hosts or ports), you must add the proxy plugin to your `vite.config.ts`.
+
+### 1. Install `http-proxy`
+```bash
+npm install -s http-proxy
+```
+
+### 2. Update `vite.config.ts`
+Add the following plugin to your Vite configuration:
+
+```typescript
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    {
+      name: 'dynamic-terminal-proxy',
+      configureServer(server) {
+        const httpProxy = require('http-proxy')
+        const proxy = httpProxy.createProxyServer({ changeOrigin: true, ws: true })
+
+        const proxyPattern = /^\/proxy\/([^\/]+)\/([^\/]+)\/([^\/]+)(.*)/
+
+        server.middlewares.use((req, res, next) => {
+          const match = req.url?.match(proxyPattern)
+          if (match) {
+            const [_, protocol, host, port, rest] = match
+            const target = `${protocol}://${host}:${port}`
+            req.url = rest || '/'
+            proxy.web(req, res, { target, secure: protocol === 'https' }, (e) => {
+              res.statusCode = 502
+              res.end(`Proxy error: ${e.message}`)
+            })
+            return
+          }
+          next()
+        })
+
+        server.httpServer?.on('upgrade', (req, socket, head) => {
+          const match = req.url?.match(proxyPattern)
+          if (match) {
+            const [_, protocol, host, port, rest] = match
+            req.url = rest || '/'
+            proxy.ws(req, socket, head, { target: `${protocol}://${host}:${port}`, secure: protocol === 'https' })
+          }
+        })
+      }
+    }
+  ]
+})
+```
+
+## Usage
+
+In your slides configuration (e.g., `slides.md`):
+
+```markdown
+---
+addons:
+  - web-terminal
+---
+```
+
+Then use the component in your slides. You can point to any backend URL directly:
+
+```markdown
+<!-- Localhost with default port -->
+<WebTerminal backendUrl="http://localhost:10001" />
+
+<!-- Arbitrary remote host (handles CORS automatically) -->
+<WebTerminal backendUrl="https://my-websocket-host.example.com:4443" />
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `backendUrl` | `string` | - | The base URL of the terminal backend. If pointing to `localhost`, it automatically uses the dynamic proxy. |
+| `wsUrl` | `string` | - | (Optional) Direct WebSocket URL to bypass session creation API. |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run linter
+npm run lint
+```

package/components/WebTerminal.vue

@@ -0,0 +1,238 @@
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted, watch } from 'vue'
+import { Terminal } from 'xterm'
+import { FitAddon } from 'xterm-addon-fit'
+import { WebLinksAddon } from 'xterm-addon-web-links'
+import { AttachAddon } from 'xterm-addon-attach'
+import 'xterm/css/xterm.css'
+
+const props = defineProps<{
+  wsUrl?: string
+  backendUrl?: string
+}>()
+
+const terminalContainer = ref<HTMLElement | null>(null)
+let terminal: Terminal | null = null
+let socket: WebSocket | null = null
+let fitAddon: FitAddon | null = null
+let attachAddon: AttachAddon | null = null
+let pid: string | null = null
+
+const handleCodeClick = (e: MouseEvent) => {
+  const target = e.target as HTMLElement
+  // Only trigger if nested inside or is an element with class 'clickable-code'
+  const clickableElement = target.closest('.clickable-code') as HTMLElement | null
+  
+  if (clickableElement) {
+    // Don't execute if it's inside the terminal itself
+    if (terminalContainer.value?.contains(clickableElement)) return
+
+    const code = clickableElement.innerText.trim()
+    if (code && socket && socket.readyState === WebSocket.OPEN) {
+      // Send the code to the terminal
+      socket.send(code + '\n')
+      // Visual feedback: focus the terminal
+      terminal?.focus()
+    }
+  }
+}
+
+const initTerminal = async () => {
+    if (!terminalContainer.value) return
+
+    // Initialize Terminal
+    terminal = new Terminal({
+        cursorBlink: true,
+        cursorStyle: 'block',
+        macOptionIsMeta: true,
+        scrollback: 10000,
+        tabStopWidth: 10,
+        allowProposedApi: true
+    })
+
+    // Initialize Addons
+    fitAddon = new FitAddon()
+    const webLinksAddon = new WebLinksAddon()
+
+    terminal.loadAddon(fitAddon)
+    terminal.loadAddon(webLinksAddon)
+
+    terminal.open(terminalContainer.value)
+    fitAddon.fit()
+    terminal.focus()
+
+    // Handle resizing
+    window.addEventListener('resize', handleResize)
+    
+    // Add global click listener for 'click to execute' feature
+    document.addEventListener('click', handleCodeClick)
+    
+    // Determine connection URL
+// ... (lines 49-142 remain unchanged but I'll include them in the snippet if needed)
+    let connectionUrl = props.wsUrl
+    
+    if (!connectionUrl && props.backendUrl) {
+      try {
+        let cleanBackendUrl = props.backendUrl.replace(/\/$/, '')
+        
+        // Check if we are pointing to a cross-origin backend
+        try {
+            const url = new URL(cleanBackendUrl, window.location.origin)
+            if (url.origin !== window.location.origin) {
+                const protocol = url.protocol.replace(':', '')
+                const host = url.hostname
+                // url.port is empty if it's the default (80/443) or omitted
+                const port = url.port || (url.protocol === 'https:' ? '443' : '80')
+                
+                // Rewrite to use our dynamic proxy in vite.config.ts
+                // Pattern: /proxy/protocol/host/port
+                cleanBackendUrl = `/proxy/${protocol}/${host}/${port}`
+            }
+        } catch (e) {
+            console.warn(`URL parsing failed for backendUrl with error ${e}, falling back to original: ${cleanBackendUrl}`)
+        }
+
+        const response = await fetch(`${cleanBackendUrl}/api/terminals`, { method: 'POST' })
+        if (response.ok) {
+           pid = await response.text()
+           
+           // Construct WS URL
+           if (cleanBackendUrl.startsWith('/proxy/')) {
+               // Use relative WS URL for the proxy
+               const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
+               connectionUrl = `${protocol}//${window.location.host}${cleanBackendUrl}/terminals/${pid}`
+           } else {
+               const url = new URL(cleanBackendUrl, window.location.href)
+               const protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
+               connectionUrl = `${protocol}//${url.host}/terminals/${pid}`
+           }
+        } else {
+             console.error('Failed to create terminal:', response.statusText)
+             terminal.write(`\r\nFailed to create terminal: ${response.statusText}\r\n`)
+             return
+        }
+      } catch (e) {
+         console.error('Error creating terminal:', e)
+         terminal.write(`\r\nError creating terminal: ${e}\r\n`)
+         return
+      }
+    }
+
+    // Connect to WebSocket
+    if (connectionUrl) {
+       // If using proxy (relative backendUrl), connectionUrl might be ws://localhost:3030/terminals/pid
+       // which is correct for Vite proxy.
+       connectWebSocket(connectionUrl)
+    } else {
+       terminal.write('\r\nNo WebSocket URL or Backend URL provided.\r\n')
+    }
+}
+
+const connectWebSocket = (url: string) => {
+    socket = new WebSocket(url)
+
+    socket.onopen = () => {
+        if (terminal && socket) {
+            attachAddon = new AttachAddon(socket)
+            terminal.loadAddon(attachAddon)
+            
+            // Resize adjustment
+            if(fitAddon) fitAddon.fit()
+            
+            terminal.focus()
+        }
+    }
+
+    socket.onclose = () => {
+        if (terminal) {
+            terminal.write('\r\nConnection closed.\r\n')
+        }
+    }
+    
+    socket.onerror = (err) => {
+        console.error("WebSocket error:", err)
+        if (terminal) {
+            terminal.write('\r\nWebSocket error.\r\n')
+        }
+    }
+}
+
+const handleResize = () => {
+    if (fitAddon) {
+        fitAddon.fit()
+    }
+}
+
+const dispose = () => {
+    window.removeEventListener('resize', handleResize)
+    document.removeEventListener('click', handleCodeClick)
+    if (socket) {
+        socket.close()
+        socket = null
+    }
+    if (terminal) {
+        terminal.dispose()
+        terminal = null
+    }
+}
+
+onMounted(() => {
+    initTerminal()
+})
+
+onUnmounted(() => {
+    dispose()
+})
+
+watch(() => [props.wsUrl, props.backendUrl], () => {
+    dispose()
+    initTerminal()
+})
+
+</script>
+<style>
+/* Global styles for clickable code blocks */
+.clickable-code, .clickable-code * {
+  cursor: pointer;
+}
+.clickable-code {
+  transition: opacity 0.2s;
+}
+.clickable-code:hover {
+  opacity: 0.8;
+}
+.clickable-code:hover code {
+  outline: 1px dashed #555;
+  outline-offset: 2px;
+}
+</style>
+
+<template>
+  <div 
+    class="web-terminal-wrapper"
+  >
+    <div 
+      ref="terminalContainer" 
+      class="web-terminal-container" 
+    />
+  </div>
+</template>
+
+<style scoped>
+.web-terminal-wrapper {
+  width: 100%;
+  height: 100%;
+  padding: 1rem;
+  background-color: #000;
+  border-radius: 4px;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+
+.web-terminal-container {
+  width: 100%;
+  height: 100%;
+  flex: 1; /* Grow to fill available space */
+}
+</style>

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "slidev-addon-web-terminal",
+  "version": "0.2.0",
+  "description": "A Slidev addon that provides a web terminal using xterm.js",
+  "keywords": [
+    "slidev-addon",
+    "slidev",
+    "terminal",
+    "xterm"
+  ],
+  "scripts": {
+    "lint": "eslint ."
+  },
+  "license": "MIT",
+  "slidev": {
+    "components": [
+      "components/WebTerminal.vue"
+    ]
+  },
+  "files": [
+    "components",
+    "README.md"
+  ],
+  "dependencies": {
+    "xterm": "^5.3.0",
+    "xterm-addon-fit": "^0.8.0",
+    "xterm-addon-web-links": "^0.9.0",
+    "xterm-addon-attach": "^0.9.0"
+  },
+  "peerDependencies": {
+    "@slidev/cli": ">=0.40.0",
+    "vue": "^3.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@slidev/cli": "^0.49.0",
+    "@slidev/theme-default": "latest",
+    "eslint": "^9.0.0",
+    "eslint-plugin-vue": "^9.0.0",
+    "typescript-eslint": "^8.0.0",
+    "vue-eslint-parser": "^9.0.0"
+  }
+}