diff --git a/Dockerfile b/Dockerfile
index 7924a0645..ccee00ece 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -91,6 +91,7 @@ ENV NODE_ENV=production
 ENV HOST=0.0.0.0
 ENV PORT=5003
 ENV OPENCODE_SERVER_PORT=5551
+ENV DEV_PREVIEW_PORT=3056
 ENV DATABASE_PATH=/app/data/opencode.db
 ENV WORKSPACE_PATH=/workspace
 ENV XDG_CACHE_HOME=/home/node/.cache
@@ -112,7 +113,7 @@ RUN chmod +x /docker-entrypoint.sh
 RUN mkdir -p /workspace /app/data /home/node/.cache /home/node/.opencode && \
     chown -R node:node /workspace /app/data /home/node
 
-EXPOSE 5003 5100 5101 5102 5103
+EXPOSE 5003 3055 3056
 
 HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
   CMD curl -f http://localhost:5003/api/health || exit 1
diff --git a/backend/eslint.config.js b/backend/eslint.config.js
index f0084db62..a2972da61 100644
--- a/backend/eslint.config.js
+++ b/backend/eslint.config.js
@@ -26,6 +26,7 @@ export default defineConfig([
       '@typescript-eslint/no-explicit-any': 'warn',
       '@typescript-eslint/no-unused-vars': 'error',
       'no-useless-escape': 'warn',
+      'no-empty': ['error', { allowEmptyCatch: true }],
     },
   },
   {
diff --git a/backend/src/constants.ts b/backend/src/constants.ts
index ca4d348d3..e2da00f44 100644
--- a/backend/src/constants.ts
+++ b/backend/src/constants.ts
@@ -1,56 +1,3 @@
-export const DEFAULT_AGENTS_MD = `# OpenCode Manager - Global Agent Instructions
+import defaultAgentsMd from './default-agents.md' with { type: 'text' }
 
-## Critical System Constraints
-
-- **DO NOT** use ports 5003 or 5551 - these are reserved for OpenCode Manager
-- **DO NOT** kill or stop processes on ports 5003 or 5551
-- **DO NOT** modify files in the \`.config/opencode\` directory unless explicitly requested
-
-## Dev Server Ports
-
-When starting dev servers, use the pre-allocated ports 5100-5103:
-- Port 5100: Primary dev server (frontend)
-- Port 5101: Secondary dev server (API/backend)
-- Port 5102: Additional service
-- Port 5103: Additional service
-
-Always bind to \`0.0.0.0\` to allow external access from the Docker host.
-
-## Package Management
-
-### Node.js Packages
-Prefer **pnpm** or **bun** over npm for installing dependencies to save disk space:
-- Use \`pnpm install\` instead of \`npm install\`
-- Use \`bun install\` as an alternative
-- Both are pre-installed in the container
-
- ### Python Packages
- Always create a virtual environment in the repository directory before installing packages:
-
- 1. Create virtual environment in repo:
-   \`cd \`<repo_path>\`
-   \`uv venv .venv\`
-
- 2. Activate the virtual environment:
-   \`source .venv/bin/activate\`  # or \`uv pip sync\` for project-based workflows
-
- 3. Install packages into activated environment:
-   \`uv pip install \`<package>\`
-   \`uv pip install -r requirements.txt\`
-
- 4. Run Python commands:
-   \`python script.py\`  # Uses activated .venv
-
- Alternative: Use \`uv run python script.py\` to skip explicit activation
-
- **Important:**
- - Always create .venv in the repository directory (not workspace root)
- - Activate the environment before running pip operations
- - uv is pre-installed in the container and provides faster package installation
- - .venv directories created in repos will persist but can be removed safely
-
-## General Guidelines
-
-- This file is merged with any AGENTS.md files in individual repositories
-- Repository-specific instructions take precedence for their respective codebases
-`
+export const DEFAULT_AGENTS_MD = defaultAgentsMd
diff --git a/backend/src/default-agents.md b/backend/src/default-agents.md
new file mode 100644
index 000000000..1b85361f0
--- /dev/null
+++ b/backend/src/default-agents.md
@@ -0,0 +1,56 @@
+# OpenCode Manager - Global Agent Instructions
+
+## Critical System Constraints
+
+- **DO NOT** use ports 5003 or 5551 - these are reserved for OpenCode Manager
+- **DO NOT** kill or stop processes on ports 5003 or 5551
+- **DO NOT** modify files in the `.config/opencode` directory unless explicitly requested
+
+## Dev Server Port
+
+The preview feature checks the port provided in the `OCM_DEV_SERVER_PORT` environment variable. Always run the dev server on that port so it can be previewed.
+
+- Start the dev server on the port in `$OCM_DEV_SERVER_PORT` (e.g. `PORT=$OCM_DEV_SERVER_PORT <dev command>` or pass `--port $OCM_DEV_SERVER_PORT`).
+- Bind to `0.0.0.0` to allow external access from the Docker host.
+
+## Package Management
+
+### Node.js Packages
+
+Prefer **pnpm** or **bun** over npm for installing dependencies to save disk space:
+
+- Use `pnpm install` instead of `npm install`
+- Use `bun install` as an alternative
+- Both are pre-installed in the container
+
+### Python Packages
+
+Always create a virtual environment in the repository directory before installing packages:
+
+1. Create virtual environment in repo:
+   `cd <repo_path>`
+   `uv venv .venv`
+
+2. Activate the virtual environment:
+   `source .venv/bin/activate`  # or `uv pip sync` for project-based workflows
+
+3. Install packages into activated environment:
+   `uv pip install <package>`
+   `uv pip install -r requirements.txt`
+
+4. Run Python commands:
+   `python script.py`  # Uses activated .venv
+
+Alternative: Use `uv run python script.py` to skip explicit activation
+
+**Important:**
+
+- Always create .venv in the repository directory (not workspace root)
+- Activate the environment before running pip operations
+- uv is pre-installed in the container and provides faster package installation
+- .venv directories created in repos will persist but can be removed safely
+
+## General Guidelines
+
+- This file is merged with any AGENTS.md files in individual repositories
+- Repository-specific instructions take precedence for their respective codebases
diff --git a/backend/src/index.ts b/backend/src/index.ts
index 21dd615b2..3893ba5cb 100644
--- a/backend/src/index.ts
+++ b/backend/src/index.ts
@@ -37,6 +37,8 @@ import { createPromptTemplateRoutes } from './routes/prompt-templates'
 import { createInternalRoutes } from './routes/internal'
 import { sweepStaleUploadSessions } from './routes/internal/repo-mirror-helpers'
 import { createOpenCodeProxyRoutes } from './routes/opencode-proxy'
+import { createDevServerRoutes } from './routes/dev-server'
+import { startPreviewServer } from './services/dev-server/preview-server'
 import { sseAggregator } from './services/sse-aggregator'
 import { ensureDirectoryExists, writeFileContent, fileExists, readFileContent } from './services/file-operations'
 import { SettingsService } from './services/settings'
@@ -342,6 +344,7 @@ protectedApi.route('/ssh', createSSHRoutes(gitAuthService))
 protectedApi.route('/notifications', createNotificationRoutes(notificationService))
 protectedApi.route('/prompt-templates', createPromptTemplateRoutes(db))
 protectedApi.route('/schedules', createScheduleRoutes(scheduleService))
+protectedApi.route('/dev-server', createDevServerRoutes(db))
 
 app.route('/api', protectedApi)
 
@@ -467,4 +470,7 @@ serve({
   hostname: HOST,
 })
 
+startPreviewServer(auth, db)
+
 logger.info(`🚀 OpenCode WebUI API running on http://${HOST}:${PORT}`)
+logger.info(`🔍 Dev preview proxy running on http://${HOST}:${ENV.DEV_PREVIEW.PORT}`)
diff --git a/backend/src/routes/dev-server.ts b/backend/src/routes/dev-server.ts
new file mode 100644
index 000000000..6f7965cb6
--- /dev/null
+++ b/backend/src/routes/dev-server.ts
@@ -0,0 +1,28 @@
+import { Hono } from 'hono'
+import type { Database } from 'bun:sqlite'
+import { getRepoById } from '../db/queries'
+import { getDevServerState } from '../services/dev-server/manager'
+import { resolveDevPreviewUrl } from '../services/dev-server/proxy-utils'
+
+export function createDevServerRoutes(db: Database): Hono {
+  const app = new Hono()
+
+  app.get('/:repoId/status', async (c) => {
+    const repoId = parseInt(c.req.param('repoId'), 10)
+    if (isNaN(repoId)) {
+      return c.json({ error: 'Invalid repoId' }, 400)
+    }
+
+    const repo = getRepoById(db, repoId)
+    if (!repo) {
+      return c.json({ error: 'Repository not found' }, 404)
+    }
+
+    const previewUrl = resolveDevPreviewUrl(c.req.header('host'), c.req.header('x-forwarded-proto'))
+    const state = await getDevServerState(db, repo.id, previewUrl)
+
+    return c.json(state)
+  })
+
+  return app
+}
diff --git a/backend/src/routes/files.ts b/backend/src/routes/files.ts
index 4b43f6e46..eb1623721 100644
--- a/backend/src/routes/files.ts
+++ b/backend/src/routes/files.ts
@@ -23,12 +23,139 @@ function getSpecialRoutePathFromRequest(c: Context, routeName: string): string |
   return match?.[1] ? decodeFilePath(match[1]) : undefined
 }
 
+function getPreviewPathFromRequest(c: Context): string | undefined {
+  const path = c.req.path
+  const prefix = '/api/files/preview'
+
+  const queryPath = c.req.query('path')
+  if (queryPath !== undefined) {
+    return queryPath
+  }
+
+  if (path.startsWith(prefix + '/')) {
+    const previewPath = path.slice(prefix.length + 1)
+    return decodeURIComponent(previewPath)
+  }
+
+  return undefined
+}
+
+const PREVIEWABLE_MIME_TYPES = new Set([
+  'text/html',
+  'text/css',
+  'text/javascript',
+  'application/javascript',
+  'application/json',
+  'application/xml',
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/svg+xml',
+])
+
+function isPreviewableMimeType(mimeType?: string): boolean {
+  return mimeType !== undefined && PREVIEWABLE_MIME_TYPES.has(mimeType)
+}
+
+function buildPreviewValidators(stat: { size: number; lastModified: Date }): { etag: string; lastModified: string } {
+  return {
+    etag: `"${stat.size.toString(16)}-${stat.lastModified.getTime().toString(16)}"`,
+    lastModified: stat.lastModified.toUTCString(),
+  }
+}
+
+function isPreviewFresh(c: Context, validators: { etag: string; lastModified: string }): boolean {
+  const ifNoneMatch = c.req.header('if-none-match')
+  if (ifNoneMatch !== undefined) {
+    return ifNoneMatch.split(',').some((tag: string) => tag.trim() === validators.etag)
+  }
+
+  const ifModifiedSince = c.req.header('if-modified-since')
+  if (ifModifiedSince !== undefined) {
+    const since = Date.parse(ifModifiedSince)
+    return !Number.isNaN(since) && Date.parse(validators.lastModified) <= since
+  }
+
+  return false
+}
+
+function getPreviewHeaders(result: {
+  name: string
+  size: number
+  mimeType?: string
+  lastModified: Date
+}): Record<string, string> {
+  const isHtmlSvg = result.mimeType === 'text/html' || result.mimeType === 'image/svg+xml'
+  const validators = buildPreviewValidators(result)
+  const headers: Record<string, string> = {
+    'Content-Type': result.mimeType || 'application/octet-stream',
+    'Content-Length': result.size.toString(),
+    'Content-Disposition': `inline; filename="${result.name}"`,
+    'X-Content-Type-Options': 'nosniff',
+    'Referrer-Policy': 'no-referrer',
+    'Cache-Control': 'private, must-revalidate, max-age=0',
+    'ETag': validators.etag,
+    'Last-Modified': validators.lastModified,
+  }
+
+  if (isHtmlSvg) {
+    headers['Content-Security-Policy'] = [
+      'sandbox allow-scripts allow-same-origin;',
+      "default-src 'self' http: https: data: blob: 'unsafe-inline' 'unsafe-eval';",
+      "script-src 'self' http: https: 'unsafe-inline' 'unsafe-eval';",
+      "style-src 'self' http: https: 'unsafe-inline';",
+      "img-src 'self' http: https: data: blob:;",
+      "font-src 'self' http: https: data:;",
+      "connect-src 'self' http: https:;",
+      "media-src 'self' http: https: data: blob:;",
+      "object-src 'none';",
+      "base-uri 'none';",
+      "frame-ancestors 'self'",
+    ].join(' ')
+  }
+
+  return headers
+}
+
 export function createFileRoutes() {
   const app = new Hono()
 
   app.get('*', async (c) => {
     const path = c.req.path
 
+    if (path === '/api/files/preview' || path.startsWith('/api/files/preview/')) {
+      const userPath = getPreviewPathFromRequest(c)
+
+      if (!userPath) {
+        return c.json({ error: 'No path provided' }, 400)
+      }
+
+      try {
+        const stat = await fileService.getFilePreviewStat(userPath)
+
+        if (stat.isDirectory) {
+          return c.json({ error: 'Cannot preview directories' }, 400)
+        }
+
+        if (!isPreviewableMimeType(stat.mimeType)) {
+          return c.json({ error: 'File type cannot be previewed' }, 415)
+        }
+
+        const headers = getPreviewHeaders(stat)
+
+        if (isPreviewFresh(c, buildPreviewValidators(stat))) {
+          return new Response(null, { status: 304, headers })
+        }
+
+        const content = await fileService.getRawFileContent(userPath)
+
+        return new Response(content, { headers })
+      } catch (error: unknown) {
+        logger.error('Failed to preview file:', error)
+        return c.json({ error: getErrorMessage(error) || 'Failed to preview file' }, getStatusCode(error) as ContentfulStatusCode)
+      }
+    }
+
     if (path.endsWith('/download-zip')) {
       const userPath = getSpecialRoutePathFromRequest(c, 'download-zip')
 
diff --git a/backend/src/routes/internal/git-credentials.ts b/backend/src/routes/internal/git-credentials.ts
deleted file mode 100644
index 53a1c470e..000000000
--- a/backend/src/routes/internal/git-credentials.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { Hono } from 'hono'
-import type { Database } from 'bun:sqlite'
-import { CredentialProvider } from '../../services/credential-provider'
-
-export function createInternalGitCredentialsRoutes(db: Database) {
-  const app = new Hono()
-
-  app.get('/gh-env', (c) => {
-    const provider = new CredentialProvider(db)
-    return c.json(provider.getGhCliEnv({ cwd: c.req.query('cwd') }))
-  })
-
-  return app
-}
diff --git a/backend/src/routes/internal/index.ts b/backend/src/routes/internal/index.ts
index 590ef337e..a3200857f 100644
--- a/backend/src/routes/internal/index.ts
+++ b/backend/src/routes/internal/index.ts
@@ -13,7 +13,7 @@ import { createInternalRepoSyncRoutes } from './repo-sync'
 import { createInternalRepoMirrorRoutes as mirrorRoutes } from './repo-mirror'
 import { createInternalOpenCodeWorkspacesRoutes } from './opencode-workspaces'
 import { createInternalAssistantRoutes } from './assistant'
-import { createInternalGitCredentialsRoutes } from './git-credentials'
+import { createInternalShellEnvRoutes } from './shell-env'
 
 export function createInternalRoutes(
   db: Database,
@@ -35,6 +35,6 @@ export function createInternalRoutes(
   app.route('/repos', repos)
   app.route('/opencode-workspaces', createInternalOpenCodeWorkspacesRoutes(db))
   app.route('/assistant', createInternalAssistantRoutes(openCodeClient))
-  app.route('/git-credentials', createInternalGitCredentialsRoutes(db))
+  app.route('/shell-env', createInternalShellEnvRoutes(db))
   return app
 }
diff --git a/backend/src/routes/internal/shell-env.ts b/backend/src/routes/internal/shell-env.ts
new file mode 100644
index 000000000..19b4d8876
--- /dev/null
+++ b/backend/src/routes/internal/shell-env.ts
@@ -0,0 +1,18 @@
+import { Hono } from 'hono'
+import type { Database } from 'bun:sqlite'
+import { CredentialProvider } from '../../services/credential-provider'
+import { getDevServerPort } from '../../services/dev-server/manager'
+
+export function createInternalShellEnvRoutes(db: Database) {
+  const app = new Hono()
+
+  app.get('/', (c) => {
+    const provider = new CredentialProvider(db)
+    return c.json({
+      ...provider.getGhCliEnv({ cwd: c.req.query('cwd') }),
+      OCM_DEV_SERVER_PORT: String(getDevServerPort(db)),
+    })
+  })
+
+  return app
+}
diff --git a/backend/src/services/dev-server/manager.ts b/backend/src/services/dev-server/manager.ts
new file mode 100644
index 000000000..91445b581
--- /dev/null
+++ b/backend/src/services/dev-server/manager.ts
@@ -0,0 +1,22 @@
+import type { Database } from 'bun:sqlite'
+import { DEFAULT_DEV_SERVER_PORT, type DevServerState } from '@opencode-manager/shared/types'
+import { SettingsService } from '../settings'
+import { isPortOpen } from './ports'
+
+export function getDevServerPort(db: Database): number {
+  const port = new SettingsService(db).getSettings('default').preferences.devServerPort
+  return port ?? DEFAULT_DEV_SERVER_PORT
+}
+
+export async function getDevServerState(db: Database, repoId: number, previewUrl: string): Promise<DevServerState> {
+  const port = getDevServerPort(db)
+  const isRunning = await isPortOpen(port)
+
+  return {
+    repoId,
+    status: isRunning ? 'running' : 'stopped',
+    port,
+    error: isRunning ? null : `No dev server detected on localhost:${port}`,
+    previewUrl: isRunning ? previewUrl : null,
+  }
+}
diff --git a/backend/src/services/dev-server/ports.ts b/backend/src/services/dev-server/ports.ts
new file mode 100644
index 000000000..4944ed7d5
--- /dev/null
+++ b/backend/src/services/dev-server/ports.ts
@@ -0,0 +1,19 @@
+import net from 'net'
+
+export async function isPortOpen(port: number, host = '127.0.0.1', timeoutMs = 1000): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = new net.Socket()
+    const onError = () => {
+      socket.destroy()
+      resolve(false)
+    }
+    socket.setTimeout(timeoutMs)
+    socket.once('connect', () => {
+      socket.destroy()
+      resolve(true)
+    })
+    socket.once('error', onError)
+    socket.once('timeout', onError)
+    socket.connect(port, host)
+  })
+}
diff --git a/backend/src/services/dev-server/preview-server.ts b/backend/src/services/dev-server/preview-server.ts
new file mode 100644
index 000000000..4ee0b443a
--- /dev/null
+++ b/backend/src/services/dev-server/preview-server.ts
@@ -0,0 +1,182 @@
+import type { Database } from 'bun:sqlite'
+import { ENV } from '@opencode-manager/shared/config/env'
+import type { AuthInstance } from '../../auth'
+import { getDevServerPort } from './manager'
+import { buildUpstreamUrl, filterProxyHeaders, sanitizeUpstreamResponseHeaders } from './proxy-utils'
+import { logger } from '../../utils/logger'
+
+const PreviewResponse = Response
+
+type WebSocketMessage = string | ArrayBuffer | Uint8Array
+
+interface PreviewWebSocketData {
+  upstreamUrl: string
+  protocol: string | null
+  upstream: WebSocket | null
+  pendingMessages: WebSocketMessage[]
+}
+
+function getUnauthorizedHtml(): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Sign in required</title></head>
+<body>
+<h1>Sign in required</h1>
+<p>Open the preview from an authenticated OpenCode Manager session.</p>
+</body>
+</html>`
+}
+
+function getNotRunningHtml(port: number): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Dev Server Not Running</title></head>
+<body>
+<h1>Dev Server Not Running</h1>
+<p>No development server responded on localhost:${port}.</p>
+</body>
+</html>`
+}
+
+function htmlResponse(html: string, status: number): Response {
+  return new PreviewResponse(html, {
+    status,
+    headers: { 'content-type': 'text/html; charset=UTF-8' },
+  })
+}
+
+async function hasValidSession(auth: AuthInstance, headers: Headers): Promise<boolean> {
+  try {
+    const session = await auth.api.getSession({ headers })
+    return Boolean(session)
+  } catch {
+    return false
+  }
+}
+
+async function handleAuthenticatedPreviewRequest(request: Request, db: Database, port: number): Promise<Response> {
+  const url = new URL(request.url)
+  const upstreamUrl = buildUpstreamUrl(port, url.pathname, url.search)
+
+  const headers = filterProxyHeaders(request.headers)
+  let body: RequestInit['body'] = undefined
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    body = request.body
+  }
+
+  let upstreamResponse: Response
+  try {
+    upstreamResponse = await fetch(upstreamUrl, {
+      method: request.method,
+      headers,
+      body,
+      redirect: 'manual',
+      duplex: 'half',
+    } as RequestInit)
+  } catch {
+    return htmlResponse(getNotRunningHtml(port), 503)
+  }
+
+  return new PreviewResponse(upstreamResponse.body, {
+    status: upstreamResponse.status,
+    statusText: upstreamResponse.statusText,
+    headers: sanitizeUpstreamResponseHeaders(upstreamResponse.headers),
+  })
+}
+
+export function buildUpstreamWebSocketUrl(port: number, path: string, search: string): string {
+  return `ws://127.0.0.1:${port}${path}${search}`
+}
+
+export function selectWebSocketProtocol(protocolHeader: string | null): string | null {
+  if (!protocolHeader) return null
+  return protocolHeader
+    .split(',')
+    .map(protocol => protocol.trim())
+    .find(Boolean) ?? null
+}
+
+function createPendingWebSocketData(upstreamUrl: string, protocol: string | null): PreviewWebSocketData {
+  return {
+    upstreamUrl,
+    protocol,
+    upstream: null,
+    pendingMessages: [],
+  }
+}
+
+function sendToUpstream(data: PreviewWebSocketData, message: WebSocketMessage): void {
+  if (data.upstream?.readyState === WebSocket.OPEN) {
+    data.upstream.send(message)
+    return
+  }
+  data.pendingMessages.push(message)
+}
+
+function flushPendingMessages(data: PreviewWebSocketData): void {
+  if (!data.upstream || data.upstream.readyState !== WebSocket.OPEN) return
+  for (const message of data.pendingMessages) {
+    data.upstream.send(message)
+  }
+  data.pendingMessages = []
+}
+
+function createUpstreamWebSocket(ws: Bun.ServerWebSocket<PreviewWebSocketData>): WebSocket {
+  const data = ws.data
+  const upstream = data.protocol
+    ? new WebSocket(data.upstreamUrl, data.protocol)
+    : new WebSocket(data.upstreamUrl)
+
+  upstream.addEventListener('open', () => flushPendingMessages(data))
+  upstream.addEventListener('message', event => ws.send(event.data))
+  upstream.addEventListener('close', event => ws.close(event.code, event.reason))
+  upstream.addEventListener('error', event => {
+    logger.warn('Dev preview upstream websocket error', event)
+    ws.close()
+  })
+  return upstream
+}
+
+function isPreviewWebSocketRequest(url: URL): boolean {
+  return url.searchParams.has('token')
+    || url.pathname.includes('webpack-hmr')
+    || url.pathname === '/ws'
+    || url.pathname.endsWith('/ws')
+    || url.pathname.includes('/sockjs-node')
+}
+
+export function startPreviewServer(auth: AuthInstance, db: Database): Bun.Server<PreviewWebSocketData> {
+  return Bun.serve<PreviewWebSocketData>({
+    port: ENV.DEV_PREVIEW.PORT,
+    hostname: ENV.SERVER.HOST,
+    async fetch(request, server) {
+      if (!(await hasValidSession(auth, request.headers))) {
+        return htmlResponse(getUnauthorizedHtml(), 401)
+      }
+
+      const port = getDevServerPort(db)
+      const url = new URL(request.url)
+      if (isPreviewWebSocketRequest(url)) {
+        const protocol = selectWebSocketProtocol(request.headers.get('sec-websocket-protocol'))
+        const upgraded = server.upgrade(request, {
+          data: createPendingWebSocketData(buildUpstreamWebSocketUrl(port, url.pathname, url.search), protocol),
+          headers: protocol ? { 'Sec-WebSocket-Protocol': protocol } : undefined,
+        })
+        if (upgraded) return undefined
+      }
+
+      return handleAuthenticatedPreviewRequest(request, db, port)
+    },
+    websocket: {
+      open(ws) {
+        ws.data.upstream = createUpstreamWebSocket(ws)
+      },
+      message(ws, message) {
+        sendToUpstream(ws.data, message)
+      },
+      close(ws) {
+        ws.data.upstream?.close()
+      },
+    },
+  })
+}
diff --git a/backend/src/services/dev-server/proxy-utils.ts b/backend/src/services/dev-server/proxy-utils.ts
new file mode 100644
index 000000000..efe76716e
--- /dev/null
+++ b/backend/src/services/dev-server/proxy-utils.ts
@@ -0,0 +1,69 @@
+import { ENV } from '@opencode-manager/shared/config/env'
+
+const HOP_BY_HOP_HEADERS = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'te',
+  'trailers',
+  'upgrade',
+  'transfer-encoding',
+  'content-length',
+  'content-encoding',
+  'host',
+])
+
+const FRAME_BLOCKING_HEADERS = new Set(['x-frame-options', 'content-security-policy'])
+
+export function buildUpstreamUrl(port: number, path: string, search: string): string {
+  return `http://127.0.0.1:${port}${path}${search}`
+}
+
+export function filterProxyHeaders(headers: Headers): Record<string, string> {
+  const result: Record<string, string> = {}
+  headers.forEach((value, key) => {
+    if (!HOP_BY_HOP_HEADERS.has(key.toLowerCase())) {
+      result[key] = value
+    }
+  })
+  return result
+}
+
+export function sanitizeUpstreamResponseHeaders(headers: Headers): Record<string, string> {
+  const result: Record<string, string> = {}
+  headers.forEach((value, key) => {
+    const lower = key.toLowerCase()
+    if (!HOP_BY_HOP_HEADERS.has(lower) && !FRAME_BLOCKING_HEADERS.has(lower)) {
+      result[key] = value
+    }
+  })
+  result['referrer-policy'] = 'no-referrer'
+  return result
+}
+
+export function resolveDevPreviewUrl(requestHost: string | undefined, forwardedProto: string | undefined): string {
+  const publicUrl = ENV.DEV_PREVIEW.PUBLIC_URL.trim()
+  if (publicUrl) {
+    return publicUrl.endsWith('/') ? publicUrl : `${publicUrl}/`
+  }
+
+  const hostname = stripPort(requestHost) || 'localhost'
+  const protocol = normalizeProtocol(forwardedProto)
+  return `${protocol}://${hostname}:${ENV.DEV_PREVIEW.PORT}/`
+}
+
+function stripPort(host: string | undefined): string {
+  if (!host) return ''
+  const trimmed = host.trim()
+  if (trimmed.startsWith('[')) {
+    const closing = trimmed.indexOf(']')
+    return closing === -1 ? trimmed : trimmed.slice(0, closing + 1)
+  }
+  return trimmed.replace(/:\d+$/, '')
+}
+
+function normalizeProtocol(forwardedProto: string | undefined): string {
+  const proto = forwardedProto?.split(',')[0]?.trim().toLowerCase()
+  return proto === 'https' ? 'https' : 'http'
+}
diff --git a/backend/src/services/files.ts b/backend/src/services/files.ts
index 4dfc77f12..5c4b7a4fe 100644
--- a/backend/src/services/files.ts
+++ b/backend/src/services/files.ts
@@ -61,6 +61,33 @@ export async function getRawFileContent(userPath: string): Promise<Buffer> {
   }
 }
 
+export interface FilePreviewStat {
+  isDirectory: boolean
+  name: string
+  size: number
+  mimeType: string
+  lastModified: Date
+}
+
+export async function getFilePreviewStat(userPath: string): Promise<FilePreviewStat> {
+  const validatedPath = validatePath(userPath)
+
+  const exists = await fileExists(validatedPath)
+  if (!exists) {
+    throw { message: 'File not found or cannot be read', statusCode: 404 }
+  }
+
+  const stats = await getFileStats(validatedPath)
+
+  return {
+    isDirectory: stats.isDirectory,
+    name: path.basename(validatedPath),
+    size: stats.size,
+    mimeType: getMimeType(validatedPath),
+    lastModified: stats.lastModified,
+  }
+}
+
 export async function getFile(userPath: string): Promise<FileInfo> {
   const validatedPath = validatePath(userPath)
   logger.info(`Getting file for path: ${userPath} -> ${validatedPath}`)
@@ -253,6 +280,7 @@ function getMimeType(filePath: string): AllowedMimeType {
   const mimeTypes: Record<string, AllowedMimeType> = {
     '.txt': 'text/plain',
     '.html': 'text/html',
+    '.htm': 'text/html',
     '.css': 'text/css',
     '.js': 'text/javascript',
     '.ts': 'text/typescript',
diff --git a/backend/src/services/opencode-gh-env-plugin.ts b/backend/src/services/opencode-gh-env-plugin.ts
index 81e908d0f..7911156e6 100644
--- a/backend/src/services/opencode-gh-env-plugin.ts
+++ b/backend/src/services/opencode-gh-env-plugin.ts
@@ -16,7 +16,7 @@ async function fetchGhEnv(cwd) {
   const cached = cache.get(cacheKey)
   if (cached && now < cached.expiry) return cached.env
   try {
-    const url = new URL(baseUrl + '/git-credentials/gh-env')
+    const url = new URL(baseUrl + '/shell-env')
     if (cwd) url.searchParams.set('cwd', cwd)
     const res = await fetch(url, {
       headers: { Authorization: 'Bearer ' + token },
diff --git a/backend/src/text-modules.d.ts b/backend/src/text-modules.d.ts
new file mode 100644
index 000000000..43d00fea7
--- /dev/null
+++ b/backend/src/text-modules.d.ts
@@ -0,0 +1,4 @@
+declare module '*.md' {
+  const content: string
+  export default content
+}
diff --git a/backend/test/routes/dev-server.test.ts b/backend/test/routes/dev-server.test.ts
new file mode 100644
index 000000000..64d506f23
--- /dev/null
+++ b/backend/test/routes/dev-server.test.ts
@@ -0,0 +1,63 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('../../src/services/dev-server/manager', () => ({
+  getDevServerState: vi.fn(),
+  getDevServerPort: vi.fn(() => 5100),
+}))
+
+vi.mock('../../src/db/queries', () => ({
+  getRepoById: vi.fn(),
+}))
+
+import { getDevServerState } from '../../src/services/dev-server/manager'
+import { getRepoById } from '../../src/db/queries'
+import { createDevServerRoutes } from '../../src/routes/dev-server'
+
+describe('DevServer Management Routes', () => {
+  let devServerApp: ReturnType<typeof createDevServerRoutes>
+  let mockDb: any
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockDb = {} as any
+    devServerApp = createDevServerRoutes(mockDb)
+  })
+
+  describe('GET /:repoId/status', () => {
+    it('returns 404 when repo is not found', async () => {
+      vi.mocked(getRepoById).mockReturnValue(null)
+
+      const res = await devServerApp.fetch(new Request('http://localhost/999/status'))
+      expect(res.status).toBe(404)
+      const body = await res.json() as Record<string, unknown>
+      expect(body.error).toBe('Repository not found')
+    })
+
+    it('returns 400 for invalid repoId', async () => {
+      const res = await devServerApp.fetch(new Request('http://localhost/abc/status'))
+      expect(res.status).toBe(400)
+    })
+
+    it('returns status with an absolute preview url derived from the request host', async () => {
+      const mockRepo = { id: 1, fullPath: '/test/repo', repoUrl: null, localPath: '/test/repo' }
+      vi.mocked(getRepoById).mockReturnValue(mockRepo as any)
+      vi.mocked(getDevServerState).mockImplementation(async (_db, repoId, previewUrl) => ({
+        repoId,
+        status: 'running' as const,
+        port: 5100,
+        error: null,
+        previewUrl,
+      }))
+
+      const res = await devServerApp.fetch(new Request('http://manager.example:5003/1/status', {
+        headers: { host: 'manager.example:5003' },
+      }))
+      expect(res.status).toBe(200)
+      const body = await res.json() as Record<string, unknown>
+      expect(body.status).toBe('running')
+      expect(body.port).toBe(5100)
+      expect(body.previewUrl).toBe('http://manager.example:3056/')
+      expect(getDevServerState).toHaveBeenCalledWith(mockDb, 1, 'http://manager.example:3056/')
+    })
+  })
+})
diff --git a/backend/test/routes/files.test.ts b/backend/test/routes/files.test.ts
index 23aaa5adb..ceddc700d 100644
--- a/backend/test/routes/files.test.ts
+++ b/backend/test/routes/files.test.ts
@@ -30,6 +30,7 @@ vi.mock('@opencode-manager/shared/config/env', () => ({
 
 vi.mock('../../src/services/files', () => ({
   getFile: vi.fn(),
+  getFilePreviewStat: vi.fn(),
   getRawFileContent: vi.fn(),
   getFileRange: vi.fn(),
   uploadFile: vi.fn(),
@@ -47,6 +48,8 @@ vi.mock('../../src/services/archive', () => ({
 }))
 
 const getFile = fileService.getFile as MockedFunction<typeof fileService.getFile>
+const getFilePreviewStat = fileService.getFilePreviewStat as MockedFunction<typeof fileService.getFilePreviewStat>
+const getRawFileContent = fileService.getRawFileContent as MockedFunction<typeof fileService.getRawFileContent>
 const getFileRange = fileService.getFileRange as MockedFunction<typeof fileService.getFileRange>
 const uploadFile = fileService.uploadFile as MockedFunction<typeof fileService.uploadFile>
 const createFileOrFolder = fileService.createFileOrFolder as MockedFunction<typeof fileService.createFileOrFolder>
@@ -69,6 +72,139 @@ describe('File Routes', () => {
     app.route('/api/files', filesApp)
   })
 
+  describe('GET /preview/* - HTML Preview Assets', () => {
+    const lastModified = new Date('2024-01-01T00:00:00.000Z')
+
+    const htmlStat = {
+      name: 'index.html',
+      isDirectory: false,
+      size: 31,
+      mimeType: 'text/html' as const,
+      lastModified,
+    }
+
+    it('should serve HTML files with sandbox CSP and caching headers', async () => {
+      getFilePreviewStat.mockResolvedValue(htmlStat)
+      getRawFileContent.mockResolvedValue(Buffer.from('<html><body>Hello</body></html>'))
+
+      const response = await app.request('/api/files/preview/test-repo/index.html')
+      const body = await response.text()
+
+      expect(response.status).toBe(200)
+      expect(body).toBe('<html><body>Hello</body></html>')
+      expect(response.headers.get('Content-Type')).toContain('text/html')
+      expect(response.headers.get('Content-Disposition')).toContain('inline')
+      expect(response.headers.get('X-Content-Type-Options')).toBe('nosniff')
+      expect(response.headers.get('Referrer-Policy')).toBe('no-referrer')
+      expect(response.headers.get('Content-Security-Policy')).toContain('sandbox allow-scripts allow-same-origin')
+      expect(response.headers.get('Content-Security-Policy')).toContain('https:')
+      expect(response.headers.get('Cache-Control')).toBe('private, must-revalidate, max-age=0')
+      expect(response.headers.get('ETag')).toBeTruthy()
+      expect(response.headers.get('Last-Modified')).toBe(lastModified.toUTCString())
+      expect(getFilePreviewStat).toHaveBeenCalledWith('test-repo/index.html')
+      expect(getRawFileContent).toHaveBeenCalledWith('test-repo/index.html')
+    })
+
+    it('should return 304 when ETag matches If-None-Match without reading the file', async () => {
+      getFilePreviewStat.mockResolvedValue(htmlStat)
+      getRawFileContent.mockResolvedValue(Buffer.from('<html><body>Hello</body></html>'))
+
+      const first = await app.request('/api/files/preview/test-repo/index.html')
+      const etag = first.headers.get('ETag') as string
+      await first.text()
+      getRawFileContent.mockClear()
+
+      const response = await app.request('/api/files/preview/test-repo/index.html', {
+        headers: { 'If-None-Match': etag },
+      })
+
+      expect(response.status).toBe(304)
+      expect(getRawFileContent).not.toHaveBeenCalled()
+    })
+
+    it('should serve CSS files with text/css Content-Type', async () => {
+      getFilePreviewStat.mockResolvedValue({
+        name: 'styles.css',
+        isDirectory: false,
+        size: 50,
+        mimeType: 'text/css',
+        lastModified,
+      })
+      getRawFileContent.mockResolvedValue(Buffer.from('body { color: red }'))
+
+      const response = await app.request('/api/files/preview/test-repo/styles/app.css')
+
+      expect(response.status).toBe(200)
+      expect(response.headers.get('Content-Type')).toContain('text/css')
+      expect(response.headers.get('Content-Security-Policy')).toBeNull()
+      expect(getFilePreviewStat).toHaveBeenCalledWith('test-repo/styles/app.css')
+    })
+
+    it('should support query-based path parameter', async () => {
+      getFilePreviewStat.mockResolvedValue(htmlStat)
+      getRawFileContent.mockResolvedValue(Buffer.from('<html><body>Hello</body></html>'))
+
+      const response = await app.request('/api/files/preview?path=test-repo/index.html')
+      const body = await response.text()
+
+      expect(response.status).toBe(200)
+      expect(body).toBe('<html><body>Hello</body></html>')
+      expect(getFilePreviewStat).toHaveBeenCalledWith('test-repo/index.html')
+    })
+
+    it('should return 400 for directory results', async () => {
+      getFilePreviewStat.mockResolvedValue({
+        name: 'test-repo',
+        isDirectory: true,
+        size: 0,
+        mimeType: 'text/plain',
+        lastModified,
+      })
+
+      const response = await app.request('/api/files/preview/test-repo')
+
+      expect(response.status).toBe(400)
+      const body = await response.json() as { error: string }
+      expect(body.error).toContain('Cannot preview directories')
+    })
+
+    it('should return 415 for non-previewable MIME types', async () => {
+      getFilePreviewStat.mockResolvedValue({
+        name: 'doc.pdf',
+        isDirectory: false,
+        size: 100,
+        mimeType: 'application/pdf' as never,
+        lastModified,
+      })
+
+      const response = await app.request('/api/files/preview/test-repo/doc.pdf')
+
+      expect(response.status).toBe(415)
+      const body = await response.json() as { error: string }
+      expect(body.error).toContain('File type cannot be previewed')
+      expect(getRawFileContent).not.toHaveBeenCalled()
+    })
+
+    it('should return 400 when no path is provided', async () => {
+      const response = await app.request('/api/files/preview')
+
+      expect(response.status).toBe(400)
+      const body = await response.json() as { error: string }
+      expect(body.error).toContain('No path provided')
+    })
+
+    it('should return 403 for path traversal attempts', async () => {
+      const error = { message: 'Path traversal detected', statusCode: 403 }
+      getFilePreviewStat.mockRejectedValue(error)
+
+      const response = await app.request('/api/files/preview/test-repo/../outside')
+
+      expect(response.status).toBe(403)
+      const body = await response.json() as { error: string }
+      expect(body.error).toContain('Path traversal detected')
+    })
+  })
+
   describe('GET /*/download-zip - Route Order Regression Test', () => {
     it('should route to archive service for directory download, not file service', async () => {
       const mockStream = {
@@ -175,6 +311,17 @@ describe('File Routes', () => {
       expect(response.status).toBe(404)
       expect(body).toHaveProperty('error')
     })
+
+    it('should route paths starting with "preview" but not matching /preview/ to generic handler', async () => {
+      getFile.mockResolvedValue(mockFileInfo)
+
+      const response = await app.request('/api/files/previewer')
+      const body = await response.json() as FileInfo
+
+      expect(response.status).toBe(200)
+      expect(body).toHaveProperty('isDirectory', false)
+      expect(getFile).toHaveBeenCalledWith('previewer')
+    })
   })
 
   describe('GET /* with ?startLine&endLine - File Range', () => {
diff --git a/backend/test/routes/internal/git-credentials.test.ts b/backend/test/routes/internal/git-credentials.test.ts
deleted file mode 100644
index 4ae326be5..000000000
--- a/backend/test/routes/internal/git-credentials.test.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest'
-import { Database } from 'bun:sqlite'
-import { migrate } from '../../../src/db/migration-runner'
-import { allMigrations } from '../../../src/db/migrations'
-import { SettingsService } from '../../../src/services/settings'
-import { createInternalGitCredentialsRoutes } from '../../../src/routes/internal/git-credentials'
-import type { GitCredential } from '@opencode-manager/shared'
-
-describe('internal git-credentials routes', () => {
-  let db: Database
-  let settingsService: SettingsService
-  let app: ReturnType<typeof createInternalGitCredentialsRoutes>
-
-  beforeEach(() => {
-    db = new Database(':memory:')
-    migrate(db, allMigrations)
-    settingsService = new SettingsService(db)
-    app = createInternalGitCredentialsRoutes(db)
-  })
-
-  it('GET /gh-env returns GH_TOKEN and GITHUB_TOKEN for a GitHub PAT', async () => {
-    settingsService.updateSettings({
-      gitCredentials: [
-        { name: 'github', host: 'github.com', type: 'pat', token: 'ghp_test_token' } as GitCredential,
-      ],
-    })
-
-    const res = await app.request('/gh-env')
-
-    expect(res.status).toBe(200)
-    expect(await res.json()).toEqual({ GH_TOKEN: 'ghp_test_token', GITHUB_TOKEN: 'ghp_test_token' })
-  })
-
-  it('GET /gh-env returns an empty object when no GitHub credential exists', async () => {
-    const res = await app.request('/gh-env')
-
-    expect(res.status).toBe(200)
-    expect(await res.json()).toEqual({})
-  })
-})
diff --git a/backend/test/routes/internal/shell-env.test.ts b/backend/test/routes/internal/shell-env.test.ts
new file mode 100644
index 000000000..961e0d3d9
--- /dev/null
+++ b/backend/test/routes/internal/shell-env.test.ts
@@ -0,0 +1,48 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+
+const getGhCliEnvMock = vi.hoisted(() => vi.fn())
+const getDevServerPortMock = vi.hoisted(() => vi.fn())
+
+vi.mock('../../../src/services/credential-provider', () => ({
+  CredentialProvider: vi.fn().mockImplementation(() => ({ getGhCliEnv: getGhCliEnvMock })),
+}))
+
+vi.mock('../../../src/services/dev-server/manager', () => ({
+  getDevServerPort: getDevServerPortMock,
+}))
+
+import { createInternalShellEnvRoutes } from '../../../src/routes/internal/shell-env'
+
+describe('internal shell-env routes', () => {
+  const mockDb = {} as never
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    getGhCliEnvMock.mockReturnValue({ GH_TOKEN: 'ghp', GITHUB_TOKEN: 'ghp' })
+    getDevServerPortMock.mockReturnValue(4321)
+  })
+
+  it('GET / merges gh env with the dev server port and forwards cwd', async () => {
+    const app = createInternalShellEnvRoutes(mockDb)
+
+    const res = await app.request('/?cwd=%2Frepo')
+
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({
+      GH_TOKEN: 'ghp',
+      GITHUB_TOKEN: 'ghp',
+      OCM_DEV_SERVER_PORT: '4321',
+    })
+    expect(getGhCliEnvMock).toHaveBeenCalledWith({ cwd: '/repo' })
+  })
+
+  it('GET / returns only the dev server port when no GitHub credential exists', async () => {
+    getGhCliEnvMock.mockReturnValue({})
+    const app = createInternalShellEnvRoutes(mockDb)
+
+    const res = await app.request('/')
+
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ OCM_DEV_SERVER_PORT: '4321' })
+  })
+})
diff --git a/backend/test/services/dev-server/preview-server.test.ts b/backend/test/services/dev-server/preview-server.test.ts
new file mode 100644
index 000000000..540f20b31
--- /dev/null
+++ b/backend/test/services/dev-server/preview-server.test.ts
@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest'
+import {
+  buildUpstreamWebSocketUrl,
+  selectWebSocketProtocol,
+} from '../../../src/services/dev-server/preview-server'
+
+describe('buildUpstreamWebSocketUrl', () => {
+  it('targets the loopback dev server with path and search', () => {
+    expect(buildUpstreamWebSocketUrl(3055, '/_next/webpack-hmr', '?token=abc')).toBe(
+      'ws://127.0.0.1:3055/_next/webpack-hmr?token=abc'
+    )
+  })
+})
+
+describe('selectWebSocketProtocol', () => {
+  it('selects the first offered protocol', () => {
+    expect(selectWebSocketProtocol('vite-hmr, other')).toBe('vite-hmr')
+  })
+
+  it('returns null when no protocol is offered', () => {
+    expect(selectWebSocketProtocol(null)).toBeNull()
+  })
+})
diff --git a/backend/test/services/dev-server/proxy-utils.test.ts b/backend/test/services/dev-server/proxy-utils.test.ts
new file mode 100644
index 000000000..ebfcfccdd
--- /dev/null
+++ b/backend/test/services/dev-server/proxy-utils.test.ts
@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest'
+import {
+  buildUpstreamUrl,
+  filterProxyHeaders,
+  sanitizeUpstreamResponseHeaders,
+  resolveDevPreviewUrl,
+} from '../../../src/services/dev-server/proxy-utils'
+
+describe('buildUpstreamUrl', () => {
+  it('targets the loopback dev server with path and search', () => {
+    expect(buildUpstreamUrl(3055, '/_next/static/chunk.js', '?v=1')).toBe(
+      'http://127.0.0.1:3055/_next/static/chunk.js?v=1'
+    )
+  })
+})
+
+describe('filterProxyHeaders', () => {
+  it('drops hop-by-hop and host headers', () => {
+    const headers = new Headers({
+      host: 'manager.example',
+      connection: 'keep-alive',
+      'content-type': 'text/html',
+      accept: '*/*',
+    })
+
+    const result = filterProxyHeaders(headers)
+
+    expect(result.host).toBeUndefined()
+    expect(result.connection).toBeUndefined()
+    expect(result['content-type']).toBe('text/html')
+    expect(result.accept).toBe('*/*')
+  })
+})
+
+describe('sanitizeUpstreamResponseHeaders', () => {
+  it('strips framing/security headers and forces no-referrer', () => {
+    const headers = new Headers({
+      'content-type': 'text/html',
+      'x-frame-options': 'DENY',
+      'content-security-policy': "frame-ancestors 'none'",
+    })
+
+    const result = sanitizeUpstreamResponseHeaders(headers)
+
+    expect(result['content-type']).toBe('text/html')
+    expect(result['x-frame-options']).toBeUndefined()
+    expect(result['content-security-policy']).toBeUndefined()
+    expect(result['referrer-policy']).toBe('no-referrer')
+  })
+})
+
+describe('resolveDevPreviewUrl', () => {
+  it('derives the preview origin from the request host and preview port', () => {
+    expect(resolveDevPreviewUrl('manager.example:5003', undefined)).toBe('http://manager.example:3056/')
+  })
+
+  it('honours the forwarded protocol', () => {
+    expect(resolveDevPreviewUrl('manager.example:5003', 'https')).toBe('https://manager.example:3056/')
+  })
+
+  it('handles bracketed IPv6 hosts', () => {
+    expect(resolveDevPreviewUrl('[::1]:5003', undefined)).toBe('http://[::1]:3056/')
+  })
+
+  it('falls back to localhost when no host is provided', () => {
+    expect(resolveDevPreviewUrl(undefined, undefined)).toBe('http://localhost:3056/')
+  })
+})
diff --git a/backend/test/services/opencode-gh-env-plugin.test.ts b/backend/test/services/opencode-gh-env-plugin.test.ts
index 4ac101ee8..c3b40fb80 100644
--- a/backend/test/services/opencode-gh-env-plugin.test.ts
+++ b/backend/test/services/opencode-gh-env-plugin.test.ts
@@ -53,7 +53,7 @@ describe('ocm-gh-env plugin', () => {
 
     expect(output.env).toEqual({ GH_TOKEN: 'ghp', GITHUB_TOKEN: 'ghp' })
     const [url, options] = fetchMock.mock.calls[0]!
-    expect(url.toString()).toBe('http://localhost:5003/api/internal/git-credentials/gh-env?cwd=%2Frepo')
+    expect(url.toString()).toBe('http://localhost:5003/api/internal/shell-env?cwd=%2Frepo')
     expect(options).toEqual({ headers: { Authorization: 'Bearer secret-token' } })
   })
 
diff --git a/backend/vitest.config.ts b/backend/vitest.config.ts
index da53ef821..cfdd9d479 100644
--- a/backend/vitest.config.ts
+++ b/backend/vitest.config.ts
@@ -2,6 +2,18 @@ import { defineConfig } from 'vitest/config'
 import path from 'path'
 
 export default defineConfig({
+  plugins: [
+    {
+      name: 'markdown-as-text',
+      enforce: 'pre',
+      transform(code: string, id: string) {
+        if (id.endsWith('.md')) {
+          return { code: `export default ${JSON.stringify(code)};`, map: null }
+        }
+        return null
+      },
+    },
+  ],
   test: {
     globals: true,
     environment: 'node',
diff --git a/docker-compose.yml b/docker-compose.yml
index 00a023348..87614e015 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -8,16 +8,16 @@ services:
     container_name: opencode-manager
     ports:
       - "5003:5003"
-      - "5100:5100"
-      - "5101:5101"
-      - "5102:5102"
-      - "5103:5103"
+      - "3055:3055"
+      - "3056:3056"
     environment:
       - NODE_ENV=${NODE_ENV:-production}
       - HOST=0.0.0.0
       - PORT=5003
       - OPENCODE_SERVER_PORT=5551
       - OPENCODE_HOST=127.0.0.1
+      - DEV_PREVIEW_PORT=3056
+      - DEV_PREVIEW_PUBLIC_URL=${DEV_PREVIEW_PUBLIC_URL:-}
       - DATABASE_PATH=/app/data/opencode.db
       - WORKSPACE_PATH=/workspace
       - PROCESS_START_WAIT_MS=2000
diff --git a/docs/configuration/docker.md b/docs/configuration/docker.md
index 3c8bcf3fb..e8f68c341 100644
--- a/docs/configuration/docker.md
+++ b/docs/configuration/docker.md
@@ -38,16 +38,16 @@ services:
     container_name: opencode-manager
     ports:
       - "5003:5003"
-      - "5100:5100"
-      - "5101:5101"
-      - "5102:5102"
-      - "5103:5103"
+      - "3055:3055"
+      - "3056:3056"
     environment:
       - NODE_ENV=${NODE_ENV:-production}
       - HOST=0.0.0.0
       - PORT=5003
       - OPENCODE_SERVER_PORT=5551
       - OPENCODE_HOST=127.0.0.1
+      - DEV_PREVIEW_PORT=3056
+      - DEV_PREVIEW_PUBLIC_URL=${DEV_PREVIEW_PUBLIC_URL:-}
       - DATABASE_PATH=/app/data/opencode.db
       - WORKSPACE_PATH=/workspace
       - PROCESS_START_WAIT_MS=2000
@@ -146,19 +146,22 @@ ports:
   - "8080:5003"  # Access at localhost:8080
 ```
 
-### Dev Server Ports
+### Dev Server Port & Preview Proxy
 
-Ports 5100-5103 are exposed for running dev servers inside repositories:
+A repository's dev server listens on `$OCM_DEV_SERVER_PORT` inside the container. It defaults to `3055`, is configurable in **Settings** (`devServerPort`), and is passed to agents as the `$OCM_DEV_SERVER_PORT` environment variable.
+
+The in-app preview is served by a dedicated **authenticated preview listener** on a separate origin (`DEV_PREVIEW_PORT`, default `3056`). It validates your OpenCode Manager session, then proxies every request and HMR WebSocket to the dev server at the origin root with no path rewriting. Serving at root is what lets framework HMR work transparently across Vite, Next.js, Remix, SvelteKit, etc.
+
+Because the preview is a separate origin loaded directly by the browser, `3056` must be published to the host:
 
 ```yaml
 ports:
-  - "5100:5100"
-  - "5101:5101"
-  - "5102:5102"
-  - "5103:5103"
+  - "3056:3056"
 ```
 
-Configure your dev server to use one of these ports:
+The session cookie is shared with the preview origin because it is the same host on a different port (same site). Behind a reverse proxy that cannot expose `3056` directly, set `DEV_PREVIEW_PUBLIC_URL` to the externally reachable preview origin (e.g. `https://preview.example.com`).
+
+Run your dev server on `$OCM_DEV_SERVER_PORT` and bind to `0.0.0.0`:
 
 === "Vite"
 
@@ -166,7 +169,7 @@ Configure your dev server to use one of these ports:
     // vite.config.ts
     export default {
       server: {
-        port: 5100,
+        port: Number(process.env.OCM_DEV_SERVER_PORT) || 3055,
         host: '0.0.0.0'
       }
     }
@@ -175,13 +178,13 @@ Configure your dev server to use one of these ports:
 === "Next.js"
 
     ```bash
-    next dev -p 5100 -H 0.0.0.0
+    next dev -p $OCM_DEV_SERVER_PORT -H 0.0.0.0
     ```
 
 === "Express"
 
     ```javascript
-    app.listen(5100, '0.0.0.0')
+    app.listen(process.env.OCM_DEV_SERVER_PORT || 3055, '0.0.0.0')
     ```
 
 ## Volume Mounts
@@ -372,7 +375,7 @@ The container creates a default `AGENTS.md` file at `/workspace/.config/opencode
 
 Instructions for AI agents working in the container:
 - Reserved ports information
-- Available dev server ports
+- Dev server port (`$OCM_DEV_SERVER_PORT`, default 3055)
 - Docker-specific guidelines
 
 ### Editing
diff --git a/frontend/src/api/devServer.ts b/frontend/src/api/devServer.ts
new file mode 100644
index 000000000..60ddea1fc
--- /dev/null
+++ b/frontend/src/api/devServer.ts
@@ -0,0 +1,7 @@
+import { fetchWrapper } from './fetchWrapper'
+import { API_BASE_URL } from '@/config'
+import type { DevServerState } from '@opencode-manager/shared/types'
+
+export async function getDevServerStatus(repoId: number): Promise<DevServerState> {
+  return fetchWrapper(`${API_BASE_URL}/api/dev-server/${repoId}/status`)
+}
diff --git a/frontend/src/api/files.test.ts b/frontend/src/api/files.test.ts
new file mode 100644
index 000000000..13373d12a
--- /dev/null
+++ b/frontend/src/api/files.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest'
+import { getFileApiUrl } from './files'
+import { encodePathForRoute, getFilePreviewUrl } from './files'
+
+describe('getFilePreviewUrl', () => {
+  it('constructs preview URL with encoded path segments', () => {
+    const url = getFilePreviewUrl('repo/dir/index.html')
+    expect(url).toBe('/api/files/preview/repo/dir/index.html')
+  })
+
+  it('encodes spaces per segment', () => {
+    const url = getFilePreviewUrl('my repo/file name.html')
+    expect(url).toBe('/api/files/preview/my%20repo/file%20name.html')
+  })
+
+  it('encodes hash characters per segment', () => {
+    const url = getFilePreviewUrl('repo/file#1.html')
+    expect(url).toBe('/api/files/preview/repo/file%231.html')
+  })
+})
+
+describe('encodePathForRoute', () => {
+  it('encodes each path segment separately', () => {
+    const result = encodePathForRoute('repo/dir/index.html')
+    expect(result).toBe('repo/dir/index.html')
+  })
+
+  it('encodes special characters per segment', () => {
+    const result = encodePathForRoute('my dir/file name.html')
+    expect(result).toBe('my%20dir/file%20name.html')
+  })
+})
+
+describe('getFileApiUrl - existing behavior unchanged', () => {
+  it('still returns a URL with path query param', () => {
+    const url = getFileApiUrl('repo/dir/index.html')
+    expect(url).toContain('/api/files')
+    expect(url).toContain('path=repo%2Fdir%2Findex.html')
+  })
+})
diff --git a/frontend/src/api/files.ts b/frontend/src/api/files.ts
index 7337d9f31..df4a12cd8 100644
--- a/frontend/src/api/files.ts
+++ b/frontend/src/api/files.ts
@@ -77,3 +77,12 @@ export async function applyFilePatches(path: string, patches: PatchOperation[]):
     body: JSON.stringify({ patches }),
   })
 }
+
+export function encodePathForRoute(path: string): string {
+  return path.split('/').map(encodeURIComponent).join('/')
+}
+
+export function getFilePreviewUrl(path: string): string {
+  const encodedPath = encodePathForRoute(path)
+  return `${API_BASE_URL}/api/files/preview/${encodedPath}`
+}
diff --git a/frontend/src/api/types/settings.ts b/frontend/src/api/types/settings.ts
index cabc73b2b..8439f09b9 100644
--- a/frontend/src/api/types/settings.ts
+++ b/frontend/src/api/types/settings.ts
@@ -71,6 +71,7 @@ export interface UserPreferences {
   repoSortMode?: 'recent' | 'manual' | 'name'
   serverEnvVars?: Array<{ key: string; value: string }>
   disabledDefaultServerEnvVars?: string[]
+  devServerPort?: number
 }
 
 export interface SettingsResponse {
diff --git a/frontend/src/components/dev-server/DevServerPreviewButton.test.tsx b/frontend/src/components/dev-server/DevServerPreviewButton.test.tsx
new file mode 100644
index 000000000..732bc98e5
--- /dev/null
+++ b/frontend/src/components/dev-server/DevServerPreviewButton.test.tsx
@@ -0,0 +1,55 @@
+import { render, screen, fireEvent } from '@testing-library/react'
+import { describe, it, expect, vi } from 'vitest'
+import { DevServerPreviewButton } from './DevServerPreviewButton'
+import { useMutation } from '@tanstack/react-query'
+
+vi.mock('@tanstack/react-query', () => ({
+  useMutation: vi.fn(),
+}))
+
+vi.mock('@/api/devServer', () => ({
+  getDevServerStatus: vi.fn(),
+}))
+
+describe('DevServerPreviewButton', () => {
+  it('calls onOpen with devserver input when configured port is running', () => {
+    const onOpen = vi.fn()
+
+    type RunningState = { status: 'running'; port: number; previewUrl: string }
+    let capturedOnSuccess: ((state: RunningState) => void) | undefined
+    vi.mocked(useMutation).mockImplementation(((options: { onSuccess?: (state: RunningState) => void }) => {
+      capturedOnSuccess = options.onSuccess
+      return {
+        mutate: () => capturedOnSuccess?.({ status: 'running', port: 5100, previewUrl: 'http://manager.example:3056/' }),
+        isPending: false,
+      } as unknown as ReturnType<typeof useMutation>
+    }) as typeof useMutation)
+
+    render(<DevServerPreviewButton repoId={3} onOpen={onOpen} />)
+
+    const button = screen.getByLabelText('Open app preview')
+    expect(button).toBeInTheDocument()
+
+    fireEvent.click(button)
+
+    expect(onOpen).toHaveBeenCalledTimes(1)
+    expect(onOpen).toHaveBeenCalledWith({
+      source: 'devserver',
+      previewUrl: 'http://manager.example:3056/',
+      title: 'App preview',
+    })
+  })
+
+  it('disables button while pending', () => {
+    const onOpen = vi.fn()
+    vi.mocked(useMutation).mockReturnValue({
+      mutate: vi.fn(),
+      isPending: true,
+    } as unknown as ReturnType<typeof useMutation>)
+
+    render(<DevServerPreviewButton repoId={1} onOpen={onOpen} />)
+
+    const button = screen.getByLabelText('Open app preview')
+    expect(button).toBeDisabled()
+  })
+})
diff --git a/frontend/src/components/dev-server/DevServerPreviewButton.tsx b/frontend/src/components/dev-server/DevServerPreviewButton.tsx
new file mode 100644
index 000000000..b13b2fd65
--- /dev/null
+++ b/frontend/src/components/dev-server/DevServerPreviewButton.tsx
@@ -0,0 +1,44 @@
+import { useMutation } from '@tanstack/react-query'
+import { getDevServerStatus } from '@/api/devServer'
+import { Button } from '@/components/ui/button'
+import { showToast } from '@/lib/toast'
+import { Loader2, Play } from 'lucide-react'
+import type { OpenHtmlArtifactInput } from '@/lib/htmlArtifacts'
+
+interface DevServerPreviewButtonProps {
+  repoId: number
+  onOpen: (input: OpenHtmlArtifactInput) => void
+}
+
+export function DevServerPreviewButton({ repoId, onOpen }: DevServerPreviewButtonProps) {
+  const { mutate, isPending } = useMutation({
+    mutationFn: () => getDevServerStatus(repoId),
+    onSuccess: (state) => {
+      if (state.status !== 'running' || !state.previewUrl) {
+        showToast.error(`No app detected on localhost:${state.port}`)
+        return
+      }
+
+      onOpen({
+        source: 'devserver',
+        previewUrl: state.previewUrl,
+        title: 'App preview',
+      })
+    },
+    onError: () => {
+      showToast.error('Failed to check preview port')
+    },
+  })
+
+  return (
+    <Button
+      variant="ghost"
+      size="sm"
+      onClick={() => mutate()}
+      disabled={isPending}
+      aria-label="Open app preview"
+    >
+      {isPending ? <Loader2 className="size-4 animate-spin" /> : <Play className="size-4" />}
+    </Button>
+  )
+}
diff --git a/frontend/src/components/file-browser/FileBrowser.tsx b/frontend/src/components/file-browser/FileBrowser.tsx
index c6df1a35d..59d1db7cd 100644
--- a/frontend/src/components/file-browser/FileBrowser.tsx
+++ b/frontend/src/components/file-browser/FileBrowser.tsx
@@ -12,6 +12,9 @@ import { FolderOpen, Upload, RefreshCw, X } from 'lucide-react'
 import type { FileInfo } from '@/types/files'
 import { useMobile } from '@/hooks/useMobile'
 import { getFileApiUrl, useFile } from '@/api/files'
+import { HtmlArtifactPanel } from '@/components/html-preview/HtmlArtifactPanel'
+import type { HtmlArtifact } from '@/lib/htmlArtifacts'
+import { createHtmlArtifact, isHtmlPath } from '@/lib/htmlArtifacts'
 
 export interface FileBrowserHandle {
   goBack: () => void
@@ -51,6 +54,10 @@ const encodeBase64 = (content: string) => {
   return btoa(binary)
 }
 
+const isHtmlFileInfo = (file: FileInfo): boolean => (
+  isHtmlPath(file.path) || isHtmlPath(file.name) || file.mimeType === 'text/html'
+)
+
 async function readFileEntry(entry: FileSystemFileEntry): Promise<File> {
   return new Promise((resolve, reject) => {
     entry.file(resolve, reject)
@@ -135,6 +142,7 @@ export const FileBrowser = forwardRef<FileBrowserHandle, FileBrowserProps>(funct
   const [currentPath, setCurrentPath] = useState(basePath)
   const [files, setFiles] = useState<FileInfo | null>(null)
   const [selectedFile, setSelectedFile] = useState<FileInfo | null>(null)
+  const [htmlArtifact, setHtmlArtifact] = useState<HtmlArtifact | null>(null)
   const [searchQuery, setSearchQuery] = useState('')
   const [loading, setLoading] = useState(false)
   const [error, setError] = useState<string | null>(null)
@@ -146,17 +154,27 @@ export const FileBrowser = forwardRef<FileBrowserHandle, FileBrowserProps>(funct
   const uploadCancelledRef = useRef(false)
   const isMobile = useMobile()
 
+  const openMobilePreview = useCallback((file: FileInfo) => {
+    if (isHtmlFileInfo(file)) {
+      setHtmlArtifact(createHtmlArtifact({ source: 'file', path: file.path, title: file.name }))
+      setIsPreviewModalOpen(false)
+    } else {
+      setHtmlArtifact(null)
+      setIsPreviewModalOpen(true)
+    }
+    onPreviewStateChange?.(true)
+  }, [onPreviewStateChange])
+
   const { data: initialFileData, error: initialFileError } = useFile(initialSelectedFile)
 
 useEffect(() => {
   if (initialFileData) {
     setSelectedFile(initialFileData)
     if (isMobile) {
-      setIsPreviewModalOpen(true)
-      onPreviewStateChange?.(true)
+      openMobilePreview(initialFileData)
     }
   }
-}, [initialFileData, isMobile, onPreviewStateChange])
+}, [initialFileData, isMobile, openMobilePreview])
 
 useEffect(() => {
   if (initialFileError) {
@@ -262,8 +280,7 @@ useEffect(() => {
       
       // On mobile, open preview in modal
       if (isMobile) {
-        setIsPreviewModalOpen(true)
-        onPreviewStateChange?.(true)
+        openMobilePreview(fullFileData)
       }
     } catch (err) {
       setError(err instanceof Error ? err.message : 'Failed to load file')
@@ -271,10 +288,11 @@ useEffect(() => {
     } finally {
       setLoading(false)
     }
-  }, [onFileSelect, isMobile, onPreviewStateChange])
+  }, [onFileSelect, isMobile, openMobilePreview])
 
-  const handleCloseModal = useCallback(() => {
+  const handleClosePreview = useCallback(() => {
     setIsPreviewModalOpen(false)
+    setHtmlArtifact(null)
     setSelectedFile(null)
     onPreviewStateChange?.(false)
   }, [onPreviewStateChange])
@@ -476,13 +494,13 @@ useEffect(() => {
 
     const handleEscape = (e: KeyboardEvent) => {
       if (e.key === 'Escape') {
-        handleCloseModal()
+        handleClosePreview()
       }
     }
 
     document.addEventListener('keydown', handleEscape)
     return () => document.removeEventListener('keydown', handleEscape)
-  }, [isPreviewModalOpen, handleCloseModal])
+  }, [isPreviewModalOpen, handleClosePreview])
 
   const showNavigateUp = allowNavigateAboveBase && normalizePath(currentPath) !== '..'
     ? true
@@ -555,6 +573,15 @@ useEffect(() => {
     </Dialog>
   )
 
+  const htmlArtifactPanel = isMobile && htmlArtifact && (
+    <HtmlArtifactPanel
+      artifact={htmlArtifact}
+      isFullscreen={true}
+      isMobile={true}
+      onClose={handleClosePreview}
+    />
+  )
+
   if (embedded) {
     return (
       <div 
@@ -641,10 +668,12 @@ useEffect(() => {
 {/* Mobile: File Preview Modal */}
         <MobileFilePreviewModal 
           isOpen={isMobile && isPreviewModalOpen}
-          onClose={handleCloseModal}
+          onClose={handleClosePreview}
           file={selectedFile}
           showFilePreviewHeader={true}
         />
+
+        {htmlArtifactPanel}
       </div>
     )
   }
@@ -743,9 +772,11 @@ useEffect(() => {
 {/* Mobile: File Preview Modal */}
       <MobileFilePreviewModal 
         isOpen={isMobile && isPreviewModalOpen}
-        onClose={handleCloseModal}
+        onClose={handleClosePreview}
         file={selectedFile}
       />
+
+      {htmlArtifactPanel}
       
       {uploadDialog}
     </div>
diff --git a/frontend/src/components/file-browser/FileBrowserSheet.test.tsx b/frontend/src/components/file-browser/FileBrowserSheet.test.tsx
index af322b0a8..421c97a62 100644
--- a/frontend/src/components/file-browser/FileBrowserSheet.test.tsx
+++ b/frontend/src/components/file-browser/FileBrowserSheet.test.tsx
@@ -7,6 +7,15 @@ import { FileBrowser } from './FileBrowser'
 import type { FileBrowserHandle } from './FileBrowser'
 import * as useMobile from '../../hooks/useMobile'
 
+vi.mock('@/components/html-preview/HtmlArtifactPanel', () => ({
+  HtmlArtifactPanel: ({ artifact, onClose }: { artifact: { path?: string } | null; onClose: () => void }) => (
+    <div data-testid="html-artifact-panel">
+      <span>{artifact?.path}</span>
+      <button aria-label="Close preview" onClick={onClose}>Close</button>
+    </div>
+  ),
+}))
+
 function createQueryClient() {
   return new QueryClient({
     defaultOptions: {
@@ -87,6 +96,60 @@ describe('FileBrowserSheet', () => {
 })
 
 describe('FileBrowser navigation', () => {
+  it('opens mobile HTML files with the shared HTML artifact panel', async () => {
+    const mobileSpy = vi.spyOn(useMobile, 'useMobile').mockReturnValue(true)
+    const originalFetch = globalThis.fetch
+    const htmlFile = {
+      name: 'dashboard.html',
+      path: 'test-repo/dashboard.html',
+      isDirectory: false,
+      size: 24,
+      mimeType: 'text/html',
+      content: btoa('<h1>Dashboard</h1>'),
+      lastModified: new Date(),
+    }
+
+    globalThis.fetch = vi.fn(async (input: RequestInfo | URL) => {
+      const url = new URL(String(input), 'http://localhost')
+      const path = url.searchParams.get('path')
+
+      if (path === htmlFile.path) {
+        return {
+          ok: true,
+          json: async () => htmlFile,
+        } as Response
+      }
+
+      return {
+        ok: true,
+        json: async () => ({
+          name: 'test-repo',
+          path: 'test-repo',
+          isDirectory: true,
+          children: [htmlFile],
+        }),
+      } as Response
+    })
+
+    try {
+      render(
+        <FileBrowser
+          basePath="test-repo"
+          embedded={true}
+        />,
+        { wrapper: createWrapper() }
+      )
+
+      fireEvent.click(await screen.findByText('dashboard.html'))
+
+      expect(await screen.findByTestId('html-artifact-panel')).toHaveTextContent('test-repo/dashboard.html')
+      expect(screen.queryByTitle('HTML preview: dashboard.html')).not.toBeInTheDocument()
+    } finally {
+      globalThis.fetch = originalFetch
+      mobileSpy.mockRestore()
+    }
+  })
+
   it('exposes imperative handle with goBack, canGoBack, and getCurrentPath', () => {
     const ref = { current: null as unknown as FileBrowserHandle }
     
@@ -1091,5 +1154,3 @@ describe('FileBrowserSheet swipe decision integration', () => {
     mockUseSwipeBack.mockRestore()
   })
 })
-
-
diff --git a/frontend/src/components/file-browser/FilePreview.test.tsx b/frontend/src/components/file-browser/FilePreview.test.tsx
new file mode 100644
index 000000000..99918745a
--- /dev/null
+++ b/frontend/src/components/file-browser/FilePreview.test.tsx
@@ -0,0 +1,104 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import '@testing-library/jest-dom'
+import { FilePreview } from './FilePreview'
+import type { FileInfo } from '@/types/files'
+
+vi.mock('@/api/files', () => ({
+  getFileApiUrl: (path: string) => `/api/files?path=${encodeURIComponent(path)}`,
+  getFilePreviewUrl: (path: string) => {
+    const encodedPath = path.split('/').map(encodeURIComponent).join('/')
+    return `/api/files/preview/${encodedPath}`
+  },
+}))
+
+vi.mock('@/components/ui/virtualized-text-view', () => ({
+  VirtualizedTextView: vi.fn(() => <div data-testid="virtualized-text-view" />),
+}))
+
+function htmlFile(content: string, overrides?: Partial<FileInfo>): FileInfo {
+  return {
+    name: 'dashboard.html',
+    path: 'test-repo/dashboard.html',
+    isDirectory: false,
+    size: content.length,
+    mimeType: 'text/html',
+    content: btoa(content),
+    lastModified: new Date(),
+    ...overrides,
+  }
+}
+
+function textFile(name: string, content: string, mimeType: string): FileInfo {
+  return {
+    name,
+    path: `test-repo/${name}`,
+    isDirectory: false,
+    size: content.length,
+    mimeType,
+    content: btoa(content),
+    lastModified: new Date(),
+  }
+}
+
+describe('FilePreview - HTML preview', () => {
+  it('renders HTML preview iframe by default for .html file', () => {
+    render(<FilePreview file={htmlFile('<h1>Dashboard</h1>')} />)
+
+    const iframe = screen.getByTitle('HTML preview: dashboard.html')
+    expect(iframe).toBeInTheDocument()
+    expect(iframe).toHaveAttribute('sandbox', 'allow-scripts allow-same-origin')
+    expect(iframe.getAttribute('src')).toContain('/api/files/preview/test-repo/dashboard.html')
+  })
+
+  it('toggles to source view when code button is clicked', () => {
+    render(<FilePreview file={htmlFile('<h1>Dashboard</h1>')} />)
+
+    const toggleButton = screen.getByTitle('Show HTML source')
+    expect(toggleButton).toBeInTheDocument()
+
+    fireEvent.click(toggleButton)
+
+    expect(screen.queryByTitle('HTML preview: dashboard.html')).not.toBeInTheDocument()
+    expect(screen.getByText('<h1>Dashboard</h1>')).toBeInTheDocument()
+  })
+
+  it('toggles back to preview when eye button is clicked from source view', () => {
+    render(<FilePreview file={htmlFile('<h1>Dashboard</h1>')} />)
+
+    const showSourceButton = screen.getByTitle('Show HTML source')
+    fireEvent.click(showSourceButton)
+    expect(screen.queryByTitle('HTML preview: dashboard.html')).not.toBeInTheDocument()
+
+    const showPreviewButton = screen.getByTitle('Preview rendered HTML')
+    expect(showPreviewButton).toBeInTheDocument()
+
+    fireEvent.click(showPreviewButton)
+
+    const iframe = screen.getByTitle('HTML preview: dashboard.html')
+    expect(iframe).toBeInTheDocument()
+  })
+
+  it('renders HTML preview for .htm file', () => {
+    render(<FilePreview file={htmlFile('<p>HTM test</p>', { name: 'test.htm', path: 'test-repo/test.htm', mimeType: 'text/html' })} />)
+
+    const iframe = screen.getByTitle('HTML preview: test.htm')
+    expect(iframe).toBeInTheDocument()
+    expect(iframe.getAttribute('src')).toContain('/api/files/preview/test-repo/test.htm')
+  })
+
+  it('does not show HTML preview toggle for non-HTML text file', () => {
+    render(<FilePreview file={textFile('readme.txt', 'Hello world', 'text/plain')} />)
+
+    expect(screen.queryByTitle('Show HTML source')).not.toBeInTheDocument()
+    expect(screen.queryByTitle('Preview rendered HTML')).not.toBeInTheDocument()
+    expect(screen.getByText('Hello world')).toBeInTheDocument()
+  })
+
+  it('preserves markdown preview behavior for .md files', () => {
+    render(<FilePreview file={textFile('readme.md', '# Hello', 'text/markdown')} />)
+
+    const toggleButton = screen.getByTitle('Show raw markdown')
+    expect(toggleButton).toBeInTheDocument()
+  })
+})
diff --git a/frontend/src/components/file-browser/FilePreview.tsx b/frontend/src/components/file-browser/FilePreview.tsx
index 9f8dfcb33..155da0d4c 100644
--- a/frontend/src/components/file-browser/FilePreview.tsx
+++ b/frontend/src/components/file-browser/FilePreview.tsx
@@ -2,9 +2,11 @@ import { useState, useCallback, useRef, useEffect, memo } from 'react'
 import { Button } from '@/components/ui/button'
 import { Download, X, Edit3, Save, X as XIcon, WrapText, Eye, Code } from 'lucide-react'
 import type { FileInfo } from '@/types/files'
-import { getFileApiUrl } from '@/api/files'
+import { getFileApiUrl, getFilePreviewUrl } from '@/api/files'
 import { VirtualizedTextView, type VirtualizedTextViewHandle } from '@/components/ui/virtualized-text-view'
 import { MarkdownRenderer } from './MarkdownRenderer'
+import { HtmlPreviewFrame } from '@/components/html-preview/HtmlPreviewFrame'
+import { isHtmlPath } from '@/lib/htmlArtifacts'
 
 
 const VIRTUALIZATION_THRESHOLD_BYTES = 50_000
@@ -21,6 +23,7 @@ interface FilePreviewProps {
 
 export const FilePreview = memo(function FilePreview({ file, hideHeader = false, isMobileModal = false, onCloseModal, onFileSaved, initialLineNumber }: FilePreviewProps) {
   const isMarkdownFile = file.name.toLowerCase().endsWith('.md') || file.name.toLowerCase().endsWith('.mdx') || file.mimeType === 'text/markdown'
+  const isHtmlFile = isHtmlPath(file.name) || file.mimeType === 'text/html'
   
   const [viewMode, setViewMode] = useState<'preview' | 'edit'>('preview')
   const [editContent, setEditContent] = useState('')
@@ -29,6 +32,7 @@ export const FilePreview = memo(function FilePreview({ file, hideHeader = false,
   const [highlightedLine, setHighlightedLine] = useState<number | undefined>(initialLineNumber)
   const [lineWrap, setLineWrap] = useState(true)
   const [markdownPreview, setMarkdownPreview] = useState(isMarkdownFile)
+  const [htmlPreview, setHtmlPreview] = useState(isHtmlFile)
   const [isLoadingAllContent, setIsLoadingAllContent] = useState(false)
   const [fullContentLoaded, setFullContentLoaded] = useState(false)
   const [fullContent, setFullContent] = useState<string | null>(null)
@@ -42,9 +46,10 @@ export const FilePreview = memo(function FilePreview({ file, hideHeader = false,
   useEffect(() => {
     setFullContentLoaded(false)
     setMarkdownPreview(isMarkdownFile)
+    setHtmlPreview(isHtmlFile)
     setFullContent(null)
     setLocalMdContent(null)
-  }, [file.path, isMarkdownFile])
+  }, [file.path, isMarkdownFile, isHtmlFile])
   
   useEffect(() => {
     if (shouldVirtualize && isMarkdownFile && markdownPreview && !isMarkdownTooLarge && !fullContentLoaded) {
@@ -214,6 +219,12 @@ export const FilePreview = memo(function FilePreview({ file, hideHeader = false,
     ['application/json', 'application/xml', 'text/javascript', 'text/typescript'].includes(file.mimeType || '')
 
   const renderContent = () => {
+    const htmlPreviewFrame = (
+      <div className="h-[calc(100vh-12rem)] min-h-[480px] rounded border border-border overflow-hidden bg-white">
+        <HtmlPreviewFrame title={`HTML preview: ${file.name}`} src={getFilePreviewUrl(file.path)} />
+      </div>
+    )
+
     if (file.mimeType?.startsWith('image/')) {
       return (
         <div className="flex justify-center p-4">
@@ -227,8 +238,13 @@ export const FilePreview = memo(function FilePreview({ file, hideHeader = false,
     }
 
     if (shouldVirtualize && isTextFile) {
+      const showHtmlPreview = isHtmlFile && htmlPreview && viewMode !== 'edit'
       const showMarkdownPreview = isMarkdownFile && markdownPreview && viewMode !== 'edit'
       
+      if (showHtmlPreview) {
+        return htmlPreviewFrame
+      }
+      
       return (
         <>
           <div className={showMarkdownPreview && fullContentLoaded ? 'hidden' : 'h-full'}>
@@ -285,6 +301,10 @@ export const FilePreview = memo(function FilePreview({ file, hideHeader = false,
           />
         )
       }
+
+      if (isHtmlFile && htmlPreview) {
+        return htmlPreviewFrame
+      }
       
       try {
         const textContent = decodeBase64(file.content)
@@ -392,8 +412,20 @@ export const FilePreview = memo(function FilePreview({ file, hideHeader = false,
                   {markdownPreview ? <Code className="w-3 h-3" /> : <Eye className="w-3 h-3" />}
                 </Button>
               )}
+
+              {isHtmlFile && viewMode !== 'edit' && (
+                <Button 
+                  variant="outline" 
+                  size="sm" 
+                  onClick={(e) => { e.stopPropagation(); e.preventDefault(); setHtmlPreview(!htmlPreview) }} 
+                  className={`h-7 w-7 p-0 ${htmlPreview ? 'bg-primary text-primary-foreground' : ''}`}
+                  title={htmlPreview ? "Show HTML source" : "Preview rendered HTML"}
+                >
+                  {htmlPreview ? <Code className="w-3 h-3" /> : <Eye className="w-3 h-3" />}
+                </Button>
+              )}
               
-              {isTextFile && !markdownPreview && (
+              {isTextFile && !markdownPreview && !htmlPreview && (
                 <Button 
                   variant="outline" 
                   size="sm" 
diff --git a/frontend/src/components/file-browser/MobileFilePreviewModal.tsx b/frontend/src/components/file-browser/MobileFilePreviewModal.tsx
index 9e70cd7f9..7319823dd 100644
--- a/frontend/src/components/file-browser/MobileFilePreviewModal.tsx
+++ b/frontend/src/components/file-browser/MobileFilePreviewModal.tsx
@@ -1,9 +1,11 @@
 import { memo, useCallback, useState, useEffect, useRef } from "react";
 import { FilePreview } from "./FilePreview";
 import { FullscreenSheet } from "@/components/ui/fullscreen-sheet";
+import { Button } from "@/components/ui/button";
 import type { FileInfo } from "@/types/files";
 import { GPU_ACCELERATED_STYLE, MODAL_TRANSITION_MS } from "@/lib/utils";
 import { useSwipeBack } from "@/hooks/useMobile";
+import { X } from "lucide-react";
 
 interface MobileFilePreviewModalProps {
   isOpen: boolean;
@@ -69,13 +71,24 @@ export const MobileFilePreviewModal = memo(function MobileFilePreviewModal({
 
   return (
     <div ref={containerRef} style={{ isolation: 'isolate' }}>
-      <FullscreenSheet style={{ ...GPU_ACCELERATED_STYLE, ...swipeStyles }}>
-        <div className={`h-full overflow-hidden bg-background pt-safe ${showFilePreviewHeader ? "" : "pb-8"}`}>
+      <FullscreenSheet className="h-dvh max-h-dvh w-screen max-w-screen overflow-hidden" style={{ ...GPU_ACCELERATED_STYLE, ...swipeStyles }}>
+        <div className="flex h-full min-h-0 flex-1 flex-col overflow-hidden bg-background pt-safe">
+          {!showFilePreviewHeader && (
+            <Button
+              variant="ghost"
+              size="icon-sm"
+              onClick={handleClose}
+              aria-label="Close preview"
+              className="absolute right-2 top-2 z-10"
+            >
+              <X className="size-4" />
+            </Button>
+          )}
           <FilePreview
             key={localFile.path}
             file={localFile}
             hideHeader={!showFilePreviewHeader}
-            isMobileModal={showFilePreviewHeader}
+            isMobileModal
             onCloseModal={handleClose}
           />
         </div>
diff --git a/frontend/src/components/html-preview/HtmlArtifactPanel.test.tsx b/frontend/src/components/html-preview/HtmlArtifactPanel.test.tsx
new file mode 100644
index 000000000..5bbc15fa6
--- /dev/null
+++ b/frontend/src/components/html-preview/HtmlArtifactPanel.test.tsx
@@ -0,0 +1,273 @@
+import { render, screen, fireEvent } from '@testing-library/react'
+import { describe, it, expect, vi } from 'vitest'
+import { HtmlArtifactPanel } from './HtmlArtifactPanel'
+import type { HtmlArtifact } from '@/lib/htmlArtifacts'
+
+vi.mock('@/api/files', () => ({
+  getFilePreviewUrl: (path: string) => `/api/files/preview/${encodeURIComponent(path)}`,
+}))
+
+function createInlineArtifact(overrides?: Partial<HtmlArtifact>): HtmlArtifact {
+  return {
+    id: 'test-1',
+    title: 'Test Preview',
+    source: 'inline',
+    html: '<h1>Hello World</h1>',
+    ...overrides,
+  }
+}
+
+function createFileArtifact(overrides?: Partial<HtmlArtifact>): HtmlArtifact {
+  return {
+    id: 'test-2',
+    title: 'File Preview',
+    source: 'file',
+    path: 'my-repo/dist/index.html',
+    ...overrides,
+  }
+}
+
+function createDevServerArtifact(overrides?: Partial<HtmlArtifact>): HtmlArtifact {
+  return {
+    id: 'test-3',
+    title: 'App Preview',
+    source: 'devserver',
+    previewUrl: 'http://manager.example:3056/',
+    ...overrides,
+  }
+}
+
+describe('HtmlArtifactPanel', () => {
+  it('renders inline artifact with srcdoc and sandbox attribute', () => {
+    const artifact = createInlineArtifact()
+    render(
+      <HtmlArtifactPanel
+        artifact={artifact}
+        isFullscreen={false}
+        isMobile={false}
+        onClose={() => {}}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    const iframe = screen.getByTitle('Test Preview')
+    expect(iframe).toBeInTheDocument()
+    expect(iframe.getAttribute('srcdoc')).toContain('<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">')
+    expect(iframe.getAttribute('srcdoc')).toContain('<h1>Hello World</h1>')
+    expect(iframe).toHaveAttribute('sandbox', 'allow-scripts')
+  })
+
+  it('renders file artifact iframe with src pointing to preview API', () => {
+    const artifact = createFileArtifact()
+    render(
+      <HtmlArtifactPanel
+        artifact={artifact}
+        isFullscreen={false}
+        isMobile={false}
+        onClose={() => {}}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    const iframe = screen.getByTitle('File Preview')
+    expect(iframe).toBeInTheDocument()
+    expect(iframe).toHaveAttribute('src')
+    expect(iframe.getAttribute('src')).toContain('/api/files/preview/')
+    expect(iframe).toHaveAttribute('sandbox', 'allow-scripts allow-same-origin')
+  })
+
+  it('does not include allow-same-origin in sandbox', () => {
+    const artifact = createInlineArtifact()
+    render(
+      <HtmlArtifactPanel
+        artifact={artifact}
+        isFullscreen={false}
+        isMobile={false}
+        onClose={() => {}}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    const iframe = screen.getByTitle('Test Preview')
+    const sandbox = iframe.getAttribute('sandbox')
+    expect(sandbox).not.toContain('allow-same-origin')
+  })
+
+  it('calls onClose when close button is clicked', () => {
+    const onClose = vi.fn()
+    const artifact = createInlineArtifact()
+    render(
+      <HtmlArtifactPanel
+        artifact={artifact}
+        isFullscreen={false}
+        isMobile={false}
+        onClose={onClose}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    const closeButton = screen.getByLabelText('Close preview')
+    fireEvent.click(closeButton)
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('renders fullscreen toggle button on desktop', () => {
+    const artifact = createInlineArtifact()
+    render(
+      <HtmlArtifactPanel
+        artifact={artifact}
+        isFullscreen={false}
+        isMobile={false}
+        onClose={() => {}}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    const toggleButton = screen.getByLabelText('Enter fullscreen')
+    expect(toggleButton).toBeInTheDocument()
+  })
+
+  it('renders FullscreenSheet on mobile', () => {
+    const artifact = createInlineArtifact()
+    const { container } = render(
+      <HtmlArtifactPanel
+        artifact={artifact}
+        isFullscreen={false}
+        isMobile={true}
+        onClose={() => {}}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    const sheetRoot = container.querySelector('.fixed.inset-0')
+    expect(sheetRoot).toBeInTheDocument()
+  })
+
+  it('renders FullscreenSheet when isFullscreen is true (desktop)', () => {
+    const artifact = createInlineArtifact()
+    const { container } = render(
+      <HtmlArtifactPanel
+        artifact={artifact}
+        isFullscreen={true}
+        isMobile={false}
+        onClose={() => {}}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    const sheetRoot = container.querySelector('.fixed.inset-0')
+    expect(sheetRoot).toBeInTheDocument()
+  })
+
+  it('returns null when artifact is null', () => {
+    const { container } = render(
+      <HtmlArtifactPanel
+        artifact={null}
+        isFullscreen={false}
+        isMobile={false}
+        onClose={() => {}}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    expect(container.innerHTML).toBe('')
+  })
+
+  it('shows desktop side-panel classes on desktop', () => {
+    const artifact = createInlineArtifact()
+    const { container } = render(
+      <HtmlArtifactPanel
+        artifact={artifact}
+        isFullscreen={false}
+        isMobile={false}
+        onClose={() => {}}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    const panel = container.querySelector('.hidden.md\\:flex')
+    expect(panel).toBeInTheDocument()
+  })
+
+  it('does not show desktop side panel on mobile', () => {
+    const artifact = createInlineArtifact()
+    const { container } = render(
+      <HtmlArtifactPanel
+        artifact={artifact}
+        isFullscreen={false}
+        isMobile={true}
+        onClose={() => {}}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    const panel = container.querySelector('.hidden.md\\:flex')
+    expect(panel).not.toBeInTheDocument()
+  })
+
+  it('renders devserver artifact iframe with src and widened sandbox', () => {
+    const artifact = createDevServerArtifact()
+    render(
+      <HtmlArtifactPanel
+        artifact={artifact}
+        isFullscreen={false}
+        isMobile={false}
+        onClose={() => {}}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    const iframe = screen.getByTitle('App Preview')
+    expect(iframe).toBeInTheDocument()
+    expect(iframe).toHaveAttribute('src', 'http://manager.example:3056/')
+    expect(iframe).toHaveAttribute(
+      'sandbox',
+      'allow-scripts allow-same-origin allow-forms allow-popups allow-modals allow-downloads',
+    )
+  })
+
+  it('shows reload button for devserver artifact', () => {
+    const artifact = createDevServerArtifact()
+    render(
+      <HtmlArtifactPanel
+        artifact={artifact}
+        isFullscreen={false}
+        isMobile={false}
+        onClose={() => {}}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    expect(screen.getByLabelText('Reload preview')).toBeInTheDocument()
+  })
+
+  it('shows reload button for file artifact', () => {
+    const artifact = createFileArtifact()
+    render(
+      <HtmlArtifactPanel
+        artifact={artifact}
+        isFullscreen={false}
+        isMobile={false}
+        onClose={() => {}}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    expect(screen.getByLabelText('Reload preview')).toBeInTheDocument()
+  })
+
+  it('does not show reload button for inline artifact', () => {
+    const artifact = createInlineArtifact()
+    render(
+      <HtmlArtifactPanel
+        artifact={artifact}
+        isFullscreen={false}
+        isMobile={false}
+        onClose={() => {}}
+        onToggleFullscreen={() => {}}
+      />,
+    )
+
+    expect(screen.queryByLabelText('Reload preview')).not.toBeInTheDocument()
+  })
+})
diff --git a/frontend/src/components/html-preview/HtmlArtifactPanel.tsx b/frontend/src/components/html-preview/HtmlArtifactPanel.tsx
new file mode 100644
index 000000000..ad5dd1057
--- /dev/null
+++ b/frontend/src/components/html-preview/HtmlArtifactPanel.tsx
@@ -0,0 +1,111 @@
+import { getFilePreviewUrl } from '@/api/files'
+import {
+  FullscreenSheet,
+  FullscreenSheetContent,
+} from '@/components/ui/fullscreen-sheet'
+import { Button } from '@/components/ui/button'
+import { X, Maximize2, Minimize2, RotateCw } from 'lucide-react'
+import { useState } from 'react'
+import { HtmlPreviewFrame } from './HtmlPreviewFrame'
+import type { HtmlArtifact } from '@/lib/htmlArtifacts'
+
+interface HtmlArtifactPanelProps {
+  artifact: HtmlArtifact | null
+  isFullscreen: boolean
+  isMobile: boolean
+  onClose: () => void
+  onToggleFullscreen?: () => void
+}
+
+export function HtmlArtifactPanel({
+  artifact,
+  isFullscreen,
+  isMobile,
+  onClose,
+  onToggleFullscreen,
+}: HtmlArtifactPanelProps) {
+  const [frameKey, setFrameKey] = useState(0)
+
+  if (!artifact) return null
+
+  const previewSrc = artifact.source === 'file' && artifact.path
+    ? getFilePreviewUrl(artifact.path)
+    : artifact.source === 'devserver'
+      ? artifact.previewUrl
+      : undefined
+  const previewSrcDoc = artifact.source === 'inline' ? artifact.html : undefined
+  const title = artifact.title
+
+  const frameSandbox = artifact.source === 'devserver'
+    ? 'allow-scripts allow-same-origin allow-forms allow-popups allow-modals allow-downloads'
+    : undefined
+
+  const showReload = artifact.source === 'devserver' || artifact.source === 'file'
+
+  const headerButtons = (
+    <div className="flex items-center gap-1">
+      {showReload && (
+        <Button
+          variant="ghost"
+          size="icon-sm"
+          onClick={() => setFrameKey(k => k + 1)}
+          aria-label="Reload preview"
+        >
+          <RotateCw className="size-4" />
+        </Button>
+      )}
+      {!isMobile && (
+        <Button
+          variant="ghost"
+          size="icon-sm"
+          onClick={onToggleFullscreen}
+          aria-label={isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}
+        >
+          {isFullscreen ? <Minimize2 className="size-4" /> : <Maximize2 className="size-4" />}
+        </Button>
+      )}
+      <Button
+        variant="ghost"
+        size="icon-sm"
+        onClick={onClose}
+        aria-label="Close preview"
+      >
+        <X className="size-4" />
+      </Button>
+    </div>
+  )
+
+  const frame = (
+    <HtmlPreviewFrame
+      key={frameKey}
+      title={title}
+      src={previewSrc}
+      srcDoc={previewSrcDoc}
+      sandbox={frameSandbox}
+    />
+  )
+
+  if (isMobile || isFullscreen) {
+    return (
+      <FullscreenSheet className="h-dvh max-h-dvh w-screen max-w-screen overflow-hidden">
+        <FullscreenSheetContent className="relative h-full max-h-full w-full max-w-full">
+          <div className="absolute top-2 right-2 z-10">
+            {headerButtons}
+          </div>
+          {frame}
+        </FullscreenSheetContent>
+      </FullscreenSheet>
+    )
+  }
+
+  return (
+    <div className="hidden md:flex w-[45%] max-w-[720px] min-w-[360px] border-l border-border bg-background flex-col relative">
+      <div className="flex-1 min-h-0">
+        {frame}
+      </div>
+      <div className="absolute top-2 right-2 z-10">
+        {headerButtons}
+      </div>
+    </div>
+  )
+}
diff --git a/frontend/src/components/html-preview/HtmlPreviewFrame.tsx b/frontend/src/components/html-preview/HtmlPreviewFrame.tsx
new file mode 100644
index 000000000..9b49279b0
--- /dev/null
+++ b/frontend/src/components/html-preview/HtmlPreviewFrame.tsx
@@ -0,0 +1,27 @@
+import { useMemo } from 'react'
+import { cn } from '@/lib/utils'
+import { normalizeHtmlPreviewDocument } from '@/lib/htmlArtifacts'
+
+interface HtmlPreviewFrameProps {
+  title: string
+  src?: string
+  srcDoc?: string
+  className?: string
+  sandbox?: string
+}
+
+export function HtmlPreviewFrame({ title, src, srcDoc, className, sandbox }: HtmlPreviewFrameProps) {
+  const resolvedSandbox = sandbox ?? (src ? 'allow-scripts allow-same-origin' : 'allow-scripts')
+  const normalizedSrcDoc = useMemo(() => (srcDoc ? normalizeHtmlPreviewDocument(srcDoc) : undefined), [srcDoc])
+  return (
+    <iframe
+      title={title}
+      src={src}
+      srcDoc={normalizedSrcDoc}
+      sandbox={resolvedSandbox}
+      referrerPolicy="no-referrer"
+      scrolling="yes"
+      className={cn('block h-full max-h-full min-h-0 w-full max-w-full border-0 bg-white', className)}
+    />
+  )
+}
diff --git a/frontend/src/components/html-preview/PreviewHtmlButton.tsx b/frontend/src/components/html-preview/PreviewHtmlButton.tsx
new file mode 100644
index 000000000..72099e354
--- /dev/null
+++ b/frontend/src/components/html-preview/PreviewHtmlButton.tsx
@@ -0,0 +1,21 @@
+import { cn } from '@/lib/utils'
+
+interface PreviewHtmlButtonProps {
+  onClick: () => void
+  className?: string
+}
+
+export function PreviewHtmlButton({ onClick, className }: PreviewHtmlButtonProps) {
+  return (
+    <button
+      onClick={onClick}
+      className={cn(
+        'rounded bg-card hover:bg-card-hover text-muted-foreground hover:text-foreground text-xs',
+        className,
+      )}
+      title="Preview HTML artifact"
+    >
+      Preview HTML
+    </button>
+  )
+}
diff --git a/frontend/src/components/message/CodePreview.test.tsx b/frontend/src/components/message/CodePreview.test.tsx
new file mode 100644
index 000000000..9ff170c07
--- /dev/null
+++ b/frontend/src/components/message/CodePreview.test.tsx
@@ -0,0 +1,111 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { CodePreview } from './CodePreview'
+
+const mocks = vi.hoisted(() => ({
+  useMobile: vi.fn(() => false),
+}))
+
+vi.mock('@/hooks/useMobile', () => ({
+  useMobile: () => mocks.useMobile(),
+}))
+
+describe('CodePreview', () => {
+  beforeEach(() => {
+    mocks.useMobile.mockReturnValue(false)
+  })
+
+  it('shows artifact button for .html files', () => {
+    const onHtmlArtifactOpen = vi.fn()
+    render(
+      <CodePreview
+        fileName="dist/report.html"
+        content="<h1>Report</h1>"
+        onHtmlArtifactOpen={onHtmlArtifactOpen}
+      />
+    )
+
+    const button = screen.getByTitle('Preview HTML artifact')
+    expect(button).toBeInTheDocument()
+  })
+
+  it('calls onHtmlArtifactOpen with file source when artifact button is clicked', () => {
+    const onHtmlArtifactOpen = vi.fn()
+    render(
+      <CodePreview
+        fileName="dist/report.html"
+        content="<h1>Report</h1>"
+        onHtmlArtifactOpen={onHtmlArtifactOpen}
+      />
+    )
+
+    const button = screen.getByTitle('Preview HTML artifact')
+    fireEvent.click(button)
+
+    expect(onHtmlArtifactOpen).toHaveBeenCalledWith({
+      source: 'file',
+      path: 'dist/report.html',
+      title: expect.stringContaining('report'),
+    })
+  })
+
+  it('shows artifact button for .htm files', () => {
+    const onHtmlArtifactOpen = vi.fn()
+    render(
+      <CodePreview
+        fileName="page.htm"
+        content="<h1>Hello</h1>"
+        onHtmlArtifactOpen={onHtmlArtifactOpen}
+      />
+    )
+
+    expect(screen.getByTitle('Preview HTML artifact')).toBeInTheDocument()
+  })
+
+  it('does not show artifact button for .ts files', () => {
+    const onHtmlArtifactOpen = vi.fn()
+    render(
+      <CodePreview
+        fileName="component.ts"
+        content="const x = 1"
+        onHtmlArtifactOpen={onHtmlArtifactOpen}
+      />
+    )
+
+    expect(screen.queryByTitle('Preview HTML artifact')).not.toBeInTheDocument()
+  })
+
+  it('shows show-more button for large files', () => {
+    const lines = Array.from({ length: 30 }, (_, i) => `line ${i + 1}`)
+    const content = lines.join('\n')
+
+    render(
+      <CodePreview
+        fileName="large.ts"
+        content={content}
+      />
+    )
+
+    expect(screen.getByText(/10 more lines/)).toBeInTheDocument()
+  })
+
+  it('uses inline fallback when fileName is empty', () => {
+    const onHtmlArtifactOpen = vi.fn()
+    render(
+      <CodePreview
+        fileName=""
+        content="<h1>Hello</h1>"
+        onHtmlArtifactOpen={onHtmlArtifactOpen}
+      />
+    )
+
+    const button = screen.getByTitle('Preview HTML artifact')
+    fireEvent.click(button)
+
+    expect(onHtmlArtifactOpen).toHaveBeenCalledWith({
+      source: 'inline',
+      html: '<h1>Hello</h1>',
+      title: 'HTML artifact',
+    })
+  })
+})
diff --git a/frontend/src/components/message/CodePreview.tsx b/frontend/src/components/message/CodePreview.tsx
index 8ee22e484..e82568a1b 100644
--- a/frontend/src/components/message/CodePreview.tsx
+++ b/frontend/src/components/message/CodePreview.tsx
@@ -2,10 +2,14 @@ import React from 'react'
 import { CopyButton } from '@/components/ui/copy-button'
 import { useMobile } from '@/hooks/useMobile'
 import { cn } from '@/lib/utils'
+import { isHtmlPath } from '@/lib/htmlArtifacts'
+import type { OpenHtmlArtifactInput } from '@/lib/htmlArtifacts'
+import { PreviewHtmlButton } from '@/components/html-preview/PreviewHtmlButton'
 
 interface CodePreviewProps {
   fileName: string
   content: string
+  onHtmlArtifactOpen?: (input: OpenHtmlArtifactInput) => void
 }
 
 const INITIAL_CODE_LINES = 20
@@ -57,7 +61,7 @@ function detectLanguage(fileName: string): string {
   return langMap[ext || ''] || 'plaintext'
 }
 
-export function CodePreview({ fileName, content }: CodePreviewProps) {
+export function CodePreview({ fileName, content, onHtmlArtifactOpen }: CodePreviewProps) {
   const isMobile = useMobile()
   const [showMore, setShowMore] = React.useState(false)
 
@@ -72,11 +76,27 @@ export function CodePreview({ fileName, content }: CodePreviewProps) {
     ? lines.slice(0, INITIAL_CODE_LINES).join('\n')
     : content
 
+  const isHtmlFile = fileName ? isHtmlPath(fileName) : true
+
+  const handleHtmlArtifact = () => {
+    if (!onHtmlArtifactOpen) return
+    if (fileName) {
+      onHtmlArtifactOpen({ source: 'file', path: fileName, title: extractFileFromPath(fileName) })
+    } else {
+      onHtmlArtifactOpen({ source: 'inline', html: content, title: 'HTML artifact' })
+    }
+  }
+
   return (
     <div className="flex flex-col bg-background">
       <div className="px-3 py-2 bg-muted/30 border-b border-border/50 flex items-center justify-between text-xs">
         <span className="font-medium truncate flex-1">{extractFileFromPath(fileName)}</span>
-        <CopyButton content={content} title="Copy" iconSize="sm" variant="ghost" className="flex-shrink-0" />
+        <div className="flex items-center gap-1 flex-shrink-0">
+          {isHtmlFile && onHtmlArtifactOpen && (
+            <PreviewHtmlButton onClick={handleHtmlArtifact} className="px-2 py-1" />
+          )}
+          <CopyButton content={content} title="Copy" iconSize="sm" variant="ghost" />
+        </div>
       </div>
 
       <div className={cn('overflow-y-auto', isMobile ? 'max-h-64' : 'max-h-96')}>
diff --git a/frontend/src/components/message/FileToolRender.tsx b/frontend/src/components/message/FileToolRender.tsx
index ea6848033..29a1beda0 100644
--- a/frontend/src/components/message/FileToolRender.tsx
+++ b/frontend/src/components/message/FileToolRender.tsx
@@ -1,5 +1,6 @@
 import React, { useState } from 'react'
 import type { components } from '@/api/opencode-types'
+import type { OpenHtmlArtifactInput } from '@/lib/htmlArtifacts'
 import { useSettings } from '@/hooks/useSettings'
 import { DiffStats } from './DiffStats'
 import { ContentDiffViewer } from './ContentDiffViewer'
@@ -60,9 +61,10 @@ interface FileToolRenderProps {
   content?: string
   toolName: string
   onFileClick?: (filePath: string, lineNumber?: number) => void
+  onHtmlArtifactOpen?: (input: OpenHtmlArtifactInput) => void
 }
 
-export function FileToolRender({ part, filediff, filePath, content, toolName, onFileClick }: FileToolRenderProps) {
+export function FileToolRender({ part, filediff, filePath, content, toolName, onFileClick, onHtmlArtifactOpen }: FileToolRenderProps) {
   const { preferences } = useSettings()
   const isReadTool = toolName === 'Read'
   const isEditTool = toolName === 'Edit'
@@ -119,21 +121,21 @@ export function FileToolRender({ part, filediff, filePath, content, toolName, on
       {expanded && hasExpandableContent && (
         <div className="bg-card p-0">
           {filediff && <ContentDiffViewer before={filediff.before} after={filediff.after} />}
-          {content && !filediff && <CodePreview fileName={filePath || ''} content={content} />}
+          {content && !filediff && <CodePreview fileName={filePath || ''} content={content} onHtmlArtifactOpen={onHtmlArtifactOpen} />}
         </div>
       )}
     </div>
   )
 }
 
-export function getToolSpecificRender(part: ToolPart, onFileClick?: (filePath: string) => void): React.ReactElement | null {
+export function getToolSpecificRender(part: ToolPart, onFileClick?: (filePath: string) => void, onHtmlArtifactOpen?: (input: OpenHtmlArtifactInput) => void): React.ReactElement | null {
   if (part.state.status !== 'completed') return null
 
   if (part.tool === 'edit') {
     const filediff = part.state.metadata?.filediff
     const filePath = part.state.input?.filePath as string | undefined
     if (filediff && isFileDiff(filediff)) {
-      return <FileToolRender part={part} filediff={filediff} filePath={filePath} toolName="Edit" onFileClick={onFileClick} />
+      return <FileToolRender part={part} filediff={filediff} filePath={filePath} toolName="Edit" onFileClick={onFileClick} onHtmlArtifactOpen={onHtmlArtifactOpen} />
     }
   }
 
@@ -141,14 +143,14 @@ export function getToolSpecificRender(part: ToolPart, onFileClick?: (filePath: s
     const filePath = part.state.input?.filePath as string | undefined
     const content = part.state.input?.content as string | undefined
     if (filePath) {
-      return <FileToolRender part={part} filePath={filePath} content={content} toolName="Write" onFileClick={onFileClick} />
+      return <FileToolRender part={part} filePath={filePath} content={content} toolName="Write" onFileClick={onFileClick} onHtmlArtifactOpen={onHtmlArtifactOpen} />
     }
   }
 
   if (part.tool === 'read') {
     const filePath = part.state.input?.filePath as string | undefined
     if (filePath) {
-      return <FileToolRender part={part} filePath={filePath} toolName="Read" onFileClick={onFileClick} />
+      return <FileToolRender part={part} filePath={filePath} toolName="Read" onFileClick={onFileClick} onHtmlArtifactOpen={onHtmlArtifactOpen} />
     }
   }
 
diff --git a/frontend/src/components/message/MessagePart.tsx b/frontend/src/components/message/MessagePart.tsx
index 223fc0f4c..98d554f01 100644
--- a/frontend/src/components/message/MessagePart.tsx
+++ b/frontend/src/components/message/MessagePart.tsx
@@ -14,6 +14,8 @@ type RetryPartType = components['schemas']['RetryPart']
 
 type Part = components['schemas']['Part']
 
+import type { OpenHtmlArtifactInput } from '@/lib/htmlArtifacts'
+
 interface MessagePartProps {
   part: Part
   role?: string
@@ -21,6 +23,7 @@ interface MessagePartProps {
   partIndex?: number
   onFileClick?: (filePath: string, lineNumber?: number) => void
   onChildSessionClick?: (sessionId: string) => void
+  onHtmlArtifactOpen?: (input: OpenHtmlArtifactInput) => void
   messageTextContent?: string
 }
 
@@ -102,7 +105,7 @@ function TTSButton({ messageId, content, className = "" }: TTSButtonProps) {
   )
 }
 
-export const MessagePart = memo(function MessagePart({ part, role, allParts, partIndex, onFileClick, onChildSessionClick, messageTextContent }: MessagePartProps) {
+export const MessagePart = memo(function MessagePart({ part, role, allParts, partIndex, onFileClick, onChildSessionClick, onHtmlArtifactOpen, messageTextContent }: MessagePartProps) {
   const { preferences } = useSettings()
   const simpleChatMode = preferences?.simpleChatMode ?? false
   const showReasoning = preferences?.showReasoning ?? false
@@ -118,13 +121,13 @@ export const MessagePart = memo(function MessagePart({ part, role, allParts, par
           return null
         }
       }
-      return <TextPart part={part} />
+      return <TextPart part={part} onHtmlArtifactOpen={onHtmlArtifactOpen} />
     case 'patch':
       if (simpleChatMode) return null
       return <PatchPart part={part} onFileClick={onFileClick} />
     case 'tool':
       if (simpleChatMode && part.tool !== 'task') return null
-      return <ToolCallPart part={part} onFileClick={onFileClick} onChildSessionClick={onChildSessionClick} />
+      return <ToolCallPart part={part} onFileClick={onFileClick} onChildSessionClick={onChildSessionClick} onHtmlArtifactOpen={onHtmlArtifactOpen} />
     case 'reasoning':
       if (simpleChatMode || !showReasoning) return null
       return (
diff --git a/frontend/src/components/message/MessageThread.tsx b/frontend/src/components/message/MessageThread.tsx
index 6dba2aa5c..7cf18b35e 100644
--- a/frontend/src/components/message/MessageThread.tsx
+++ b/frontend/src/components/message/MessageThread.tsx
@@ -8,6 +8,7 @@ import type { Message, Part, MessageWithParts } from '@/api/types'
 import { useSessionStatusForSession } from '@/stores/sessionStatusStore'
 import { useSessionTodos } from '@/stores/sessionTodosStore'
 import { useSettings } from '@/hooks/useSettings'
+import type { OpenHtmlArtifactInput } from '@/lib/htmlArtifacts'
 import type { components } from '@/api/opencode-types'
 import type { Todo } from '@/components/message/SessionTodoDisplay'
 import type { OpenCodeError } from '@/lib/opencode-errors'
@@ -27,6 +28,7 @@ interface MessageThreadProps {
   messages?: MessageWithParts[]
   onFileClick?: (filePath: string, lineNumber?: number) => void
   onChildSessionClick?: (sessionId: string) => void
+  onHtmlArtifactOpen?: (input: OpenHtmlArtifactInput) => void
   onUndoMessage?: (restoredPrompt: string) => void
   model?: string
 }
@@ -147,6 +149,7 @@ interface MessageRowProps {
   directory?: string
   onFileClick?: (filePath: string, lineNumber?: number) => void
   onChildSessionClick?: (sessionId: string) => void
+  onHtmlArtifactOpen?: (input: OpenHtmlArtifactInput) => void
   handleStartEditUserMessage: (userMessageId: string, assistantMessageId: string) => void
   handleCancelEdit: () => void
   model?: string
@@ -168,6 +171,7 @@ const MessageRow = memo(function MessageRow({
   directory,
   onFileClick,
   onChildSessionClick,
+  onHtmlArtifactOpen,
   handleStartEditUserMessage,
   handleCancelEdit,
   model,
@@ -212,6 +216,7 @@ const MessageRow = memo(function MessageRow({
                 partIndex={partIndex}
                 onFileClick={onFileClick}
                 onChildSessionClick={onChildSessionClick}
+                onHtmlArtifactOpen={onHtmlArtifactOpen}
                 messageTextContent={messageTextContent}
               />
             </div>
@@ -308,6 +313,7 @@ const MessageRow = memo(function MessageRow({
                   partIndex={partIndex}
                   onFileClick={onFileClick}
                   onChildSessionClick={onChildSessionClick}
+                  onHtmlArtifactOpen={onHtmlArtifactOpen}
                   messageTextContent={msg.role === 'assistant' ? messageTextContent : undefined}
                 />
               </div>
@@ -329,6 +335,7 @@ export const MessageThread = memo(function MessageThread({
   messages, 
   onFileClick, 
   onChildSessionClick,
+  onHtmlArtifactOpen,
   onUndoMessage,
   model
 }: MessageThreadProps) {
@@ -442,6 +449,7 @@ export const MessageThread = memo(function MessageThread({
           directory={directory}
           onFileClick={onFileClick}
           onChildSessionClick={onChildSessionClick}
+          onHtmlArtifactOpen={onHtmlArtifactOpen}
           handleStartEditUserMessage={handleStartEditUserMessage}
           handleCancelEdit={handleCancelEdit}
           model={model}
diff --git a/frontend/src/components/message/TextPart.test.tsx b/frontend/src/components/message/TextPart.test.tsx
new file mode 100644
index 000000000..e0febd7ad
--- /dev/null
+++ b/frontend/src/components/message/TextPart.test.tsx
@@ -0,0 +1,100 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { TextPart } from './TextPart'
+
+const mocks = vi.hoisted(() => ({
+  useTheme: vi.fn(() => 'dark'),
+}))
+
+vi.mock('@/hooks/useTheme', () => ({
+  useTheme: () => mocks.useTheme(),
+}))
+
+vi.mock('mermaid', () => ({
+  default: {
+    initialize: vi.fn(),
+    render: vi.fn(),
+  },
+}))
+
+const createTextPart = (text: string) => ({
+  type: 'text' as const,
+  text,
+  sessionID: 'test-session',
+  id: 'part-1',
+})
+
+describe('TextPart', () => {
+  beforeEach(() => {
+    mocks.useTheme.mockReturnValue('dark')
+  })
+
+  it('renders HTML fenced code block with artifact button', () => {
+    const onHtmlArtifactOpen = vi.fn()
+    const markdown = 'Here is a page:\n\n```html\n<html><body><h1>Hello artifact</h1></body></html>\n```'
+    const part = createTextPart(markdown)
+
+    render(<TextPart part={part} onHtmlArtifactOpen={onHtmlArtifactOpen} />)
+
+    const button = screen.getByTitle('Preview HTML artifact')
+    expect(button).toBeInTheDocument()
+  })
+
+  it('calls onHtmlArtifactOpen with correct data when artifact button is clicked', () => {
+    const onHtmlArtifactOpen = vi.fn()
+    const markdown = 'Here is a page:\n\n```html\n<html><body><h1>Hello artifact</h1></body></html>\n```'
+    const part = createTextPart(markdown)
+
+    render(<TextPart part={part} onHtmlArtifactOpen={onHtmlArtifactOpen} />)
+
+    const button = screen.getByTitle('Preview HTML artifact')
+    fireEvent.click(button)
+
+    expect(onHtmlArtifactOpen).toHaveBeenCalledWith({
+      source: 'inline',
+      html: '<html><body><h1>Hello artifact</h1></body></html>',
+      title: 'HTML artifact',
+    })
+  })
+
+  it('does not show artifact button for non-HTML code blocks', () => {
+    const onHtmlArtifactOpen = vi.fn()
+    const markdown = '```ts\nconst x = 1\n```'
+    const part = createTextPart(markdown)
+
+    render(<TextPart part={part} onHtmlArtifactOpen={onHtmlArtifactOpen} />)
+
+    expect(screen.queryByTitle('Preview HTML artifact')).not.toBeInTheDocument()
+  })
+
+  it('still shows copy button for code blocks', () => {
+    const onHtmlArtifactOpen = vi.fn()
+    const markdown = '```html\n<p>test</p>\n```'
+    const part = createTextPart(markdown)
+
+    render(<TextPart part={part} onHtmlArtifactOpen={onHtmlArtifactOpen} />)
+
+    expect(screen.getByTitle('Copy code')).toBeInTheDocument()
+  })
+
+  it('preserves leading/trailing whitespace when copying code content', () => {
+    const onHtmlArtifactOpen = vi.fn()
+    const markdown = '```\n  const x = 1\n  \n```'
+    const part = createTextPart(markdown)
+
+    render(<TextPart part={part} onHtmlArtifactOpen={onHtmlArtifactOpen} />)
+
+    const copyButton = screen.getByTitle('Copy code')
+    expect(copyButton).toBeInTheDocument()
+  })
+
+  it('does not show artifact button for mermaid code blocks', () => {
+    const onHtmlArtifactOpen = vi.fn()
+    const markdown = '```mermaid\ngraph TD;\nA-->B;\n```'
+    const part = createTextPart(markdown)
+
+    render(<TextPart part={part} onHtmlArtifactOpen={onHtmlArtifactOpen} />)
+
+    expect(screen.queryByTitle('Preview HTML artifact')).not.toBeInTheDocument()
+  })
+})
diff --git a/frontend/src/components/message/TextPart.tsx b/frontend/src/components/message/TextPart.tsx
index 721c0dfaf..89565e473 100644
--- a/frontend/src/components/message/TextPart.tsx
+++ b/frontend/src/components/message/TextPart.tsx
@@ -6,7 +6,9 @@ import rehypeRaw from 'rehype-raw'
 import mermaid from 'mermaid'
 import { Maximize2, X, AlertCircle } from 'lucide-react'
 import { CopyButton } from '@/components/ui/copy-button'
+import { PreviewHtmlButton } from '@/components/html-preview/PreviewHtmlButton'
 import type { components } from '@/api/opencode-types'
+import type { OpenHtmlArtifactInput } from '@/lib/htmlArtifacts'
 import { useTheme } from '@/hooks/useTheme'
 import 'highlight.js/styles/github-dark.css'
 
@@ -14,6 +16,7 @@ type TextPart = components['schemas']['TextPart']
 
 interface TextPartProps {
   part: TextPart
+  onHtmlArtifactOpen?: (input: OpenHtmlArtifactInput) => void
 }
 
 interface MermaidBlockProps {
@@ -146,10 +149,11 @@ function MermaidBlock({ code }: MermaidBlockProps) {
 interface CodeBlockProps {
   children?: React.ReactNode
   className?: string
+  onHtmlArtifactOpen?: (input: OpenHtmlArtifactInput) => void
   [key: string]: unknown
 }
 
-function CodeBlock({ children, className, ...props }: CodeBlockProps) {
+function CodeBlock({ children, className, onHtmlArtifactOpen, ...props }: CodeBlockProps) {
   const extractTextContent = (node: React.ReactNode): string => {
     if (typeof node === 'string') return node
     if (typeof node === 'number') return node.toString()
@@ -163,14 +167,30 @@ function CodeBlock({ children, className, ...props }: CodeBlockProps) {
     return ''
   }
   
-  const codeContent = extractTextContent(children)
+  const rawCodeContent = extractTextContent(children)
+  const codeContent = rawCodeContent.trim()
+
+  const childArray = React.Children.toArray(children)
+  const codeElement = childArray.find(
+    (child): child is React.ReactElement<{ className?: string }> => React.isValidElement(child)
+  )
+  const codeClassName = codeElement?.props?.className
+  const isHtmlCode = typeof codeClassName === 'string' && (codeClassName.includes('language-html') || codeClassName.includes('language-htm'))
 
   return (
     <div className="relative">
       <pre className={`bg-accent p-1 rounded-lg overflow-x-auto whitespace-pre-wrap break-words border border-border my-4 ${className || ''}`} {...props}>
         {children}
       </pre>
-      <CopyButton content={codeContent} title="Copy code" className="absolute top-2 right-2" />
+      <div className="absolute top-2 right-2 flex gap-1">
+        {isHtmlCode && onHtmlArtifactOpen && (
+          <PreviewHtmlButton
+            onClick={() => onHtmlArtifactOpen({ source: 'inline', html: codeContent, title: 'HTML artifact' })}
+            className="p-1.5"
+          />
+        )}
+        <CopyButton content={rawCodeContent} title="Copy code" />
+      </div>
     </div>
   )
 }
@@ -184,7 +204,7 @@ function isMermaidBlockComplete(text: string): boolean {
   return false
 }
 
-export function TextPart({ part }: TextPartProps) {
+export function TextPart({ part, onHtmlArtifactOpen }: TextPartProps) {
   const mermaidComplete = React.useMemo(() => {
     return part.text ? isMermaidBlockComplete(part.text) : false
   }, [part.text])
@@ -234,7 +254,7 @@ export function TextPart({ part }: TextPartProps) {
           },
           pre({ children }) {
             return (
-              <CodeBlock>
+              <CodeBlock onHtmlArtifactOpen={onHtmlArtifactOpen}>
                 {children}
               </CodeBlock>
             )
diff --git a/frontend/src/components/message/ToolCallPart.tsx b/frontend/src/components/message/ToolCallPart.tsx
index 77ceae93a..6d4f287ab 100644
--- a/frontend/src/components/message/ToolCallPart.tsx
+++ b/frontend/src/components/message/ToolCallPart.tsx
@@ -5,6 +5,7 @@ import { useUserBash } from '@/stores/userBashStore'
 import { useSessionStatusForSession } from '@/stores/sessionStatusStore'
 import { usePermissions, useQuestions } from '@/contexts/EventContext'
 import { detectFileReferences } from '@/lib/fileReferences'
+import type { OpenHtmlArtifactInput } from '@/lib/htmlArtifacts'
 import { ExternalLink, Loader2 } from 'lucide-react'
 import { CopyButton } from '@/components/ui/copy-button'
 import { getToolSpecificRender } from './FileToolRender'
@@ -15,6 +16,7 @@ interface ToolCallPartProps {
   part: ToolPart
   onFileClick?: (filePath: string, lineNumber?: number) => void
   onChildSessionClick?: (sessionId: string) => void
+  onHtmlArtifactOpen?: (input: OpenHtmlArtifactInput) => void
   simpleChatMode?: boolean
 }
 
@@ -26,7 +28,7 @@ function getTaskSessionId(part: ToolPart): string | undefined {
   return sessionId
 }
 
-function ClickableJson({ json, onFileClick }: { json: unknown; onFileClick?: (filePath: string) => void }) {
+function ClickableJson({ json, onFileClick }: { json: unknown; onFileClick?: (filePath: string, lineNumber?: number) => void }) {
   const jsonString = JSON.stringify(json, null, 2)
   const references = detectFileReferences(jsonString)
 
@@ -47,7 +49,7 @@ function ClickableJson({ json, onFileClick }: { json: unknown; onFileClick?: (fi
         key={`ref-${index}`}
         onClick={(e) => {
           e.stopPropagation()
-          onFileClick?.(ref.filePath)
+          onFileClick?.(ref.filePath, ref.lineNumber)
         }}
         className="text-blue-600 dark:text-blue-400 hover:text-blue-700 dark:hover:text-blue-300 cursor-pointer underline decoration-dotted"
         title={`Click to open ${ref.filePath}`}
@@ -66,7 +68,7 @@ function ClickableJson({ json, onFileClick }: { json: unknown; onFileClick?: (fi
   return <pre className="bg-accent p-2 rounded text-xs overflow-x-auto whitespace-pre-wrap break-words">{parts}</pre>
 }
 
-export function ToolCallPart({ part, onFileClick, onChildSessionClick }: ToolCallPartProps) {
+export function ToolCallPart({ part, onFileClick, onChildSessionClick, onHtmlArtifactOpen }: ToolCallPartProps) {
   const { preferences } = useSettings()
   const { userBashCommands } = useUserBash()
   const taskSessionId = part.tool === 'task' ? getTaskSessionId(part) : undefined
@@ -219,7 +221,7 @@ export function ToolCallPart({ part, onFileClick, onChildSessionClick }: ToolCal
     return null
   }
 
-  const toolSpecificRender = getToolSpecificRender(part, onFileClick)
+  const toolSpecificRender = getToolSpecificRender(part, onFileClick, onHtmlArtifactOpen)
   if (toolSpecificRender) {
     return toolSpecificRender
   }
diff --git a/frontend/src/components/settings/GeneralSettings.tsx b/frontend/src/components/settings/GeneralSettings.tsx
index 69e22b78a..051483b19 100644
--- a/frontend/src/components/settings/GeneralSettings.tsx
+++ b/frontend/src/components/settings/GeneralSettings.tsx
@@ -1,14 +1,33 @@
+import { useState, useEffect } from 'react'
 import { useSettings } from '@/hooks/useSettings'
 import { useVersionCheck } from '@/hooks/useVersionCheck'
 import { Loader2 } from 'lucide-react'
 import { Label } from '@/components/ui/label'
+import { Input } from '@/components/ui/input'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
 import { Switch } from '@/components/ui/switch'
+import { DEFAULT_DEV_SERVER_PORT } from '@opencode-manager/shared'
 
 export function GeneralSettings() {
   const { preferences, isLoading, updateSettings, isUpdating } = useSettings()
   const { data: versionInfo, isLoading: isVersionLoading } = useVersionCheck()
 
+  const [devServerPort, setDevServerPort] = useState('')
+  useEffect(() => {
+    setDevServerPort(String(preferences?.devServerPort ?? DEFAULT_DEV_SERVER_PORT))
+  }, [preferences?.devServerPort])
+
+  const commitDevServerPort = () => {
+    const parsed = parseInt(devServerPort, 10)
+    if (Number.isInteger(parsed) && parsed > 0 && parsed <= 65535) {
+      if (parsed !== preferences?.devServerPort) {
+        updateSettings({ devServerPort: parsed })
+      }
+    } else {
+      setDevServerPort(String(preferences?.devServerPort ?? DEFAULT_DEV_SERVER_PORT))
+    }
+  }
+
   if (isLoading) {
     return (
       <div className="flex items-center justify-center py-12">
@@ -67,6 +86,22 @@ export function GeneralSettings() {
           </p>
         </div>
 
+        <div className="space-y-2">
+          <Label htmlFor="devServerPort">Dev server port</Label>
+          <Input
+            id="devServerPort"
+            type="number"
+            min={1}
+            max={65535}
+            value={devServerPort}
+            onChange={(e) => setDevServerPort(e.target.value)}
+            onBlur={commitDevServerPort}
+          />
+          <p className="text-sm text-muted-foreground">
+            Port the preview proxy checks, and the value agents receive in <span className="font-mono">$OCM_DEV_SERVER_PORT</span> to run the dev server on.
+          </p>
+        </div>
+
         <div className="flex flex-row items-center justify-between rounded-lg border border-border p-4">
           <div className="space-y-0.5">
             <Label htmlFor="simpleChatMode" className="text-base">Simple chat mode</Label>
diff --git a/frontend/src/lib/htmlArtifacts.test.ts b/frontend/src/lib/htmlArtifacts.test.ts
new file mode 100644
index 000000000..f371499df
--- /dev/null
+++ b/frontend/src/lib/htmlArtifacts.test.ts
@@ -0,0 +1,194 @@
+import { describe, it, expect } from 'vitest'
+import {
+  isHtmlPath,
+  normalizeWorkspaceFilePath,
+  createHtmlArtifact,
+  getArtifactTitle,
+  normalizeHtmlPreviewDocument,
+} from './htmlArtifacts'
+
+describe('isHtmlPath', () => {
+  it('returns true for .html paths', () => {
+    expect(isHtmlPath('repo/report.html')).toBe(true)
+  })
+
+  it('returns true for .HTM paths (case-insensitive)', () => {
+    expect(isHtmlPath('page.HTM')).toBe(true)
+    expect(isHtmlPath('page.Htm')).toBe(true)
+  })
+
+  it('returns false for .tsx paths', () => {
+    expect(isHtmlPath('component.tsx')).toBe(false)
+  })
+
+  it('returns false for .md paths', () => {
+    expect(isHtmlPath('readme.md')).toBe(false)
+  })
+
+  it('returns false for missing path', () => {
+    expect(isHtmlPath(undefined)).toBe(false)
+    expect(isHtmlPath('')).toBe(false)
+  })
+
+  it('ignores query strings and hash fragments', () => {
+    expect(isHtmlPath('index.html?raw=true')).toBe(true)
+    expect(isHtmlPath('index.html#section')).toBe(true)
+    expect(isHtmlPath('page.htm?query=1#hash')).toBe(true)
+  })
+})
+
+describe('normalizeWorkspaceFilePath', () => {
+  it('strips workspace repos path prefix', () => {
+    const result = normalizeWorkspaceFilePath(
+      '/workspace/repos/my-repo/dist/index.html',
+      '/workspace/repos/my-repo',
+    )
+    expect(result).toBe('my-repo/dist/index.html')
+  })
+
+  it('returns non-matching absolute paths unchanged', () => {
+    const result = normalizeWorkspaceFilePath(
+      '/some/other/path/file.html',
+      '/workspace/repos/my-repo',
+    )
+    expect(result).toBe('/some/other/path/file.html')
+  })
+
+  it('returns relative paths unchanged', () => {
+    const result = normalizeWorkspaceFilePath('relative/path.html', '/workspace/repos/my-repo')
+    expect(result).toBe('relative/path.html')
+  })
+
+  it('returns path unchanged when repoFullPath is missing', () => {
+    const result = normalizeWorkspaceFilePath('/workspace/repos/my-repo/file.html')
+    expect(result).toBe('/workspace/repos/my-repo/file.html')
+  })
+})
+
+describe('createHtmlArtifact', () => {
+  it('creates an inline artifact with required html', () => {
+    const artifact = createHtmlArtifact({ source: 'inline', html: '<h1>Hello</h1>' })
+    expect(artifact.source).toBe('inline')
+    expect(artifact.html).toBe('<h1>Hello</h1>')
+    expect(artifact.id).toBeTruthy()
+    expect(artifact.title).toBe('Untitled Artifact')
+  })
+
+  it('creates a file artifact with required path', () => {
+    const artifact = createHtmlArtifact({ source: 'file', path: 'my-repo/dist/index.html' })
+    expect(artifact.source).toBe('file')
+    expect(artifact.path).toBe('my-repo/dist/index.html')
+    expect(artifact.id).toBeTruthy()
+    expect(artifact.title).toBe('index')
+  })
+
+  it('uses provided title', () => {
+    const artifact = createHtmlArtifact({
+      source: 'inline',
+      html: '<h1>Hello</h1>',
+      title: 'My Artifact',
+    })
+    expect(artifact.title).toBe('My Artifact')
+  })
+
+  it('throws when path is missing for file artifact', () => {
+    expect(() => createHtmlArtifact({ source: 'file' })).toThrow('path is required')
+  })
+
+  it('throws when html is missing for inline artifact', () => {
+    expect(() => createHtmlArtifact({ source: 'inline' })).toThrow('html is required')
+  })
+
+  it('creates a devserver artifact with previewUrl', () => {
+    const artifact = createHtmlArtifact({ source: 'devserver', previewUrl: 'http://manager.example:3056/' })
+    expect(artifact.source).toBe('devserver')
+    expect(artifact.previewUrl).toBe('http://manager.example:3056/')
+    expect(artifact.id).toBeTruthy()
+    expect(artifact.title).toBe('App preview')
+  })
+
+  it('throws when previewUrl is missing for devserver artifact', () => {
+    expect(() => createHtmlArtifact({ source: 'devserver' })).toThrow('previewUrl is required')
+  })
+})
+
+describe('handleFileClick path detection (normalize + isHtml combo)', () => {
+  it('classifies normalized .html path as artifact', () => {
+    const path = normalizeWorkspaceFilePath(
+      '/workspace/repos/my-repo/dist/index.html',
+      '/workspace/repos/my-repo',
+    )
+    expect(path).toBe('my-repo/dist/index.html')
+    expect(isHtmlPath(path)).toBe(true)
+  })
+
+  it('classifies normalized .htm path as artifact', () => {
+    const path = normalizeWorkspaceFilePath(
+      '/workspace/repos/my-repo/public/page.htm',
+      '/workspace/repos/my-repo',
+    )
+    expect(path).toBe('my-repo/public/page.htm')
+    expect(isHtmlPath(path)).toBe(true)
+  })
+
+  it('does not classify non-HTML path as artifact', () => {
+    const path = normalizeWorkspaceFilePath(
+      '/workspace/repos/my-repo/src/app.tsx',
+      '/workspace/repos/my-repo',
+    )
+    expect(path).toBe('my-repo/src/app.tsx')
+    expect(isHtmlPath(path)).toBe(false)
+  })
+
+  it('does not classify relative non-HTML path as artifact', () => {
+    expect(isHtmlPath(normalizeWorkspaceFilePath('src/utils.ts'))).toBe(false)
+  })
+
+  it('classifies .html path without repo prefix as artifact', () => {
+    const path = normalizeWorkspaceFilePath('some-folder/index.html')
+    expect(isHtmlPath(path)).toBe(true)
+  })
+})
+
+describe('getArtifactTitle', () => {
+  it('returns file name without extension for .html paths', () => {
+    expect(getArtifactTitle('my-repo/dist/index.html')).toBe('index')
+  })
+
+  it('returns file name without extension for .htm paths', () => {
+    expect(getArtifactTitle('page.htm')).toBe('page')
+  })
+
+  it('returns last segment for non-HTML paths', () => {
+    expect(getArtifactTitle('some/path/file.txt')).toBe('file.txt')
+  })
+
+  it('returns Untitled Artifact for undefined', () => {
+    expect(getArtifactTitle(undefined)).toBe('Untitled Artifact')
+  })
+})
+
+describe('normalizeHtmlPreviewDocument', () => {
+  it('adds viewport meta and sizing style to html fragments', () => {
+    const result = normalizeHtmlPreviewDocument('<h1>Hello</h1>')
+
+    expect(result).toContain('name="viewport"')
+    expect(result).toContain('opencode-html-preview-sizing')
+    expect(result).toContain('overflow-y:auto!important')
+    expect(result).toContain('<h1>Hello</h1>')
+  })
+
+  it('does not duplicate an existing viewport meta tag', () => {
+    const result = normalizeHtmlPreviewDocument('<head><meta name="viewport" content="width=device-width"></head>')
+
+    expect(result.match(/name="viewport"/g)).toHaveLength(1)
+    expect(result).toContain('opencode-html-preview-sizing')
+  })
+
+  it('inserts preview sizing before an existing closing head tag', () => {
+    const result = normalizeHtmlPreviewDocument('<html><head><title>Demo</title></head><body>Demo</body></html>')
+
+    expect(result).toContain('<title>Demo</title><meta name="viewport"')
+    expect(result).toContain('opencode-html-preview-sizing')
+  })
+})
diff --git a/frontend/src/lib/htmlArtifacts.ts b/frontend/src/lib/htmlArtifacts.ts
new file mode 100644
index 000000000..af07ffdf0
--- /dev/null
+++ b/frontend/src/lib/htmlArtifacts.ts
@@ -0,0 +1,82 @@
+export interface HtmlArtifact {
+  id: string
+  title: string
+  source: 'inline' | 'file' | 'devserver'
+  html?: string
+  path?: string
+  previewUrl?: string
+}
+
+export interface OpenHtmlArtifactInput {
+  title?: string
+  source: 'inline' | 'file' | 'devserver'
+  html?: string
+  path?: string
+  previewUrl?: string
+}
+
+const HTML_EXTENSIONS = new Set(['.html', '.htm'])
+const HTML_PREVIEW_STYLE_ID = 'opencode-html-preview-sizing'
+const HTML_PREVIEW_VIEWPORT_META = '<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">'
+const HTML_PREVIEW_SIZING_STYLE = `<style id="${HTML_PREVIEW_STYLE_ID}">html,body{width:100%;max-width:100%;min-width:0;min-height:100%;height:auto!important;margin:0;overflow-x:hidden!important;overflow-y:auto!important;}#root,#__next{min-height:100%;height:auto!important;max-width:100%;overflow-x:hidden;}*,*::before,*::after{box-sizing:border-box;}img,svg,video,canvas{max-width:100%;}</style>`
+const VIEWPORT_META_PATTERN = /<meta\s+[^>]*name=["']viewport["'][^>]*>/i
+const HEAD_OPEN_PATTERN = /<head([^>]*)>/i
+const HEAD_CLOSE_PATTERN = /<\/head>/i
+
+export function isHtmlPath(path: string | undefined): boolean {
+  if (!path) return false
+  const clean = path.split(/[?#]/)[0].toLowerCase()
+  return HTML_EXTENSIONS.has(clean.slice(clean.lastIndexOf('.')))
+}
+
+export function getArtifactTitle(pathOrTitle: string | undefined): string {
+  if (!pathOrTitle) return 'Untitled Artifact'
+  const lastSegment = pathOrTitle.split('/').pop() || pathOrTitle
+  if (isHtmlPath(lastSegment)) {
+    return lastSegment.slice(0, lastSegment.lastIndexOf('.'))
+  }
+  return lastSegment
+}
+
+export function createHtmlArtifact(input: OpenHtmlArtifactInput): HtmlArtifact {
+  if (input.source === 'file' && !input.path) {
+    throw new Error('path is required for file artifacts')
+  }
+  if (input.source === 'inline' && !input.html) {
+    throw new Error('html is required for inline artifacts')
+  }
+  if (input.source === 'devserver' && !input.previewUrl) {
+    throw new Error('previewUrl is required for devserver artifacts')
+  }
+  const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+  const defaultTitle = input.source === 'devserver' ? 'App preview' : undefined
+  const title = input.title ?? defaultTitle ?? getArtifactTitle(input.source === 'file' ? input.path : undefined)
+  return { id, title, source: input.source, html: input.html, path: input.path, previewUrl: input.previewUrl }
+}
+
+export function normalizeHtmlPreviewDocument(html: string): string {
+  const viewportMeta = VIEWPORT_META_PATTERN.test(html) ? '' : HTML_PREVIEW_VIEWPORT_META
+  const sizingStyle = html.includes(HTML_PREVIEW_STYLE_ID) ? '' : HTML_PREVIEW_SIZING_STYLE
+  const headContent = `${viewportMeta}${sizingStyle}`
+
+  if (!headContent) return html
+
+  if (HEAD_CLOSE_PATTERN.test(html)) {
+    return html.replace(HEAD_CLOSE_PATTERN, `${headContent}</head>`)
+  }
+
+  if (HEAD_OPEN_PATTERN.test(html)) {
+    return html.replace(HEAD_OPEN_PATTERN, `<head$1>${headContent}`)
+  }
+
+  return `<head>${headContent}</head>${html}`
+}
+
+export function normalizeWorkspaceFilePath(filePath: string, repoFullPath?: string): string {
+  if (!filePath.startsWith('/') || !repoFullPath) return filePath
+  const workspaceReposPath = repoFullPath.substring(0, repoFullPath.lastIndexOf('/'))
+  if (filePath.startsWith(`${workspaceReposPath}/`)) {
+    return filePath.substring(workspaceReposPath.length + 1)
+  }
+  return filePath
+}
diff --git a/frontend/src/pages/SessionDetail.tsx b/frontend/src/pages/SessionDetail.tsx
index 2242592ec..7db425ce2 100644
--- a/frontend/src/pages/SessionDetail.tsx
+++ b/frontend/src/pages/SessionDetail.tsx
@@ -52,6 +52,10 @@ import { SessionTodoDisplay } from "@/components/message/SessionTodoDisplay";
 import { useDialogParam } from "@/hooks/useDialogParam";
 import { useSidebarAction } from "@/hooks/useSidebarAction";
 import { SessionMoreButton } from "@/components/navigation/SessionMoreButton";
+import { HtmlArtifactPanel } from "@/components/html-preview/HtmlArtifactPanel";
+import { DevServerPreviewButton } from "@/components/dev-server/DevServerPreviewButton";
+import type { HtmlArtifact, OpenHtmlArtifactInput } from '@/lib/htmlArtifacts'
+import { createHtmlArtifact, isHtmlPath, normalizeWorkspaceFilePath } from '@/lib/htmlArtifacts'
 
 const compareMessageIds = (id1: string, id2: string): number => {
   const num1 = parseInt(id1, 10)
@@ -84,6 +88,8 @@ export function SessionDetail() {
   const [showScrollButton, setShowScrollButton] = useState(false);
   const [hasPromptContent, setHasPromptContent] = useState(false);
   const [minimizedQuestion, setMinimizedQuestion] = useState<QuestionRequest | null>(null);
+  const [htmlArtifact, setHtmlArtifact] = useState<HtmlArtifact | null>(null);
+  const [htmlArtifactFullscreen, setHtmlArtifactFullscreen] = useState(false);
 
   const isMobile = useMobile();
   const { keyboardHeight } = useVisualViewport();
@@ -202,6 +208,28 @@ export function SessionDetail() {
     setMinimizedQuestion(null)
   }, [])
 
+  const handleHtmlArtifactOpen = useCallback((input: OpenHtmlArtifactInput) => {
+    try {
+      const normalizedPath = input.source === 'file' && input.path
+        ? normalizeWorkspaceFilePath(input.path, repo?.fullPath)
+        : input.path
+      const artifact = createHtmlArtifact({ ...input, path: normalizedPath })
+      setHtmlArtifact(artifact)
+      setHtmlArtifactFullscreen(isMobile)
+    } catch {
+      showToast.error('Failed to create artifact')
+    }
+  }, [isMobile, repo?.fullPath])
+
+  const handleHtmlArtifactClose = useCallback(() => {
+    setHtmlArtifact(null)
+    setHtmlArtifactFullscreen(false)
+  }, [])
+
+  const handleHtmlArtifactFullscreenToggle = useCallback(() => {
+    setHtmlArtifactFullscreen(v => !v)
+  }, [])
+
   useEffect(() => {
     if (minimizedQuestion && minimizedQuestion.sessionID !== sessionId) {
       setMinimizedQuestion(null)
@@ -336,22 +364,21 @@ export function SessionDetail() {
     },
   });
 
-  
-
   const handleFileClick = useCallback((filePath: string) => {
-    let pathToOpen = filePath
-    
-    if (filePath.startsWith('/') && repo?.fullPath) {
-      const workspaceReposPath = repo.fullPath.substring(0, repo.fullPath.lastIndexOf('/'))
-      
-      if (filePath.startsWith(workspaceReposPath + '/')) {
-        pathToOpen = filePath.substring(workspaceReposPath.length + 1)
-      }
+    const pathToOpen = normalizeWorkspaceFilePath(filePath, repo?.fullPath)
+
+    if (isHtmlPath(pathToOpen)) {
+      handleHtmlArtifactOpen({
+        source: 'file',
+        path: pathToOpen,
+        title: pathToOpen.split('/').pop() || 'HTML artifact',
+      })
+      return
     }
-    
+
     setSelectedFilePath(pathToOpen)
     setFileBrowserOpen(true)
-  }, [repo?.fullPath, setFileBrowserOpen]);
+  }, [repo?.fullPath, handleHtmlArtifactOpen, setFileBrowserOpen]);
 
   const handleSessionTitleUpdate = useCallback((newTitle: string) => {
     if (sessionId) {
@@ -400,10 +427,6 @@ export function SessionDetail() {
     promptInputRef.current?.clearPrompt()
   }, []);
 
-  
-
-  
-
   if (!sessionId) {
     return <Navigate to="/" replace />;
   }
@@ -461,6 +484,7 @@ export function SessionDetail() {
             />
           </div>
           <Header.Actions className="gap-2 sm:gap-4">
+            <DevServerPreviewButton repoId={repoId} onOpen={handleHtmlArtifactOpen} />
             <div className="flex items-center gap-1">
               <PendingActionsGroup />
             </div>
@@ -480,29 +504,31 @@ export function SessionDetail() {
         </div>
       </div>
 
-      <div className="relative flex-1 overflow-hidden flex flex-col">
-        <div key={sessionId} ref={messageContainerRef} className="flex-1 overflow-y-auto overflow-x-hidden overscroll-contain [mask-image:linear-gradient(to_bottom,transparent,black_16px,black)]" style={{ paddingBottom: promptOverlayHeight + inputBottomOffset + PROMPT_OVERLAY_CLEARANCE_PX }}>
-          {repoLoading || sessionLoading || messagesLoading ? (
-            <MessageSkeleton />
-          ) : opcodeUrl && repoDirectory ? (
-            <MessageThread 
-              opcodeUrl={opcodeUrl} 
-              sessionID={sessionId} 
-              directory={repoDirectory}
-              messages={messages}
-              onFileClick={handleFileClick}
-              onChildSessionClick={handleChildSessionClick}
-              onUndoMessage={handleUndoMessage}
-              model={modelString || undefined}
-            />
-          ) : null}
-        </div>
-        {opcodeUrl && repoDirectory && !isEditingMessage && (
-          <div
-            ref={promptOverlayRef}
-            className="absolute left-0 right-0 flex justify-center"
-            style={{ bottom: inputBottomOffset }}
-          >
+      <div className="relative flex-1 overflow-hidden flex flex-row">
+        <div className="relative flex-1 min-w-0 overflow-hidden flex flex-col">
+          <div key={sessionId} ref={messageContainerRef} className="flex-1 overflow-y-auto overflow-x-hidden overscroll-contain [mask-image:linear-gradient(to_bottom,transparent,black_16px,black)]" style={{ paddingBottom: promptOverlayHeight + inputBottomOffset + PROMPT_OVERLAY_CLEARANCE_PX }}>
+            {repoLoading || sessionLoading || messagesLoading ? (
+              <MessageSkeleton />
+            ) : opcodeUrl && repoDirectory ? (
+              <MessageThread 
+                opcodeUrl={opcodeUrl} 
+                sessionID={sessionId} 
+                directory={repoDirectory}
+                messages={messages}
+                onFileClick={handleFileClick}
+                onChildSessionClick={handleChildSessionClick}
+                onUndoMessage={handleUndoMessage}
+                onHtmlArtifactOpen={handleHtmlArtifactOpen}
+                model={modelString || undefined}
+              />
+            ) : null}
+          </div>
+          {opcodeUrl && repoDirectory && !isEditingMessage && (
+            <div
+              ref={promptOverlayRef}
+              className="absolute left-0 right-0 flex justify-center"
+              style={{ bottom: inputBottomOffset }}
+            >
             <div className="relative w-[94%] md:max-w-4xl">
               <div className="absolute -top-9 right-0 z-50 flex flex-col items-end gap-2">
                 {ttsEnabled && !hasPromptContent && !isSessionActive && latestPlayableAssistant && (
@@ -567,6 +593,16 @@ export function SessionDetail() {
             </div>
           </div>
         )}
+        </div>
+        {htmlArtifact && !htmlArtifactFullscreen && !isMobile && (
+          <HtmlArtifactPanel
+            artifact={htmlArtifact}
+            isFullscreen={false}
+            isMobile={false}
+            onClose={handleHtmlArtifactClose}
+            onToggleFullscreen={handleHtmlArtifactFullscreenToggle}
+          />
+        )}
       </div>
 
       {/* Sessions Dialog */}
@@ -598,6 +634,16 @@ export function SessionDetail() {
         initialSelectedFile={selectedFilePath}
       />
 
+      {htmlArtifact && (htmlArtifactFullscreen || isMobile) && (
+        <HtmlArtifactPanel
+          artifact={htmlArtifact}
+          isFullscreen={true}
+          isMobile={isMobile}
+          onClose={handleHtmlArtifactClose}
+          onToggleFullscreen={handleHtmlArtifactFullscreenToggle}
+        />
+      )}
+
       <RepoLspDialog
         open={lspDialogOpen}
         onOpenChange={setLspDialogOpen}
diff --git a/shared/src/config/defaults.ts b/shared/src/config/defaults.ts
index 478a64726..7822627d2 100644
--- a/shared/src/config/defaults.ts
+++ b/shared/src/config/defaults.ts
@@ -19,6 +19,11 @@ export const DEFAULTS = {
     HEALTH_FAILURE_THRESHOLD: 2,
   },
 
+  DEV_PREVIEW: {
+    PORT: 3056,
+    PUBLIC_URL: '', // Optional: public origin for the preview iframe behind a reverse proxy (e.g., https://preview.mydomain.com)
+  },
+
   DATABASE: {
     PATH: './data/opencode.db',
   },
diff --git a/shared/src/config/env.ts b/shared/src/config/env.ts
index 0c8b8f3d8..a7dbd0253 100644
--- a/shared/src/config/env.ts
+++ b/shared/src/config/env.ts
@@ -63,6 +63,11 @@ export const ENV = {
     SERVER_USERNAME: getEnvString('OPENCODE_SERVER_USERNAME', 'opencode'),
   },
 
+  DEV_PREVIEW: {
+    PORT: getEnvNumber('DEV_PREVIEW_PORT', DEFAULTS.DEV_PREVIEW.PORT),
+    PUBLIC_URL: getEnvString('DEV_PREVIEW_PUBLIC_URL', DEFAULTS.DEV_PREVIEW.PUBLIC_URL),
+  },
+
   DATABASE: {
     PATH: getEnvString('DATABASE_PATH', DEFAULTS.DATABASE.PATH),
   },
diff --git a/shared/src/schemas/settings.ts b/shared/src/schemas/settings.ts
index 3a6eea81b..78c6937d2 100644
--- a/shared/src/schemas/settings.ts
+++ b/shared/src/schemas/settings.ts
@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { NotificationPreferencesSchema, DEFAULT_NOTIFICATION_PREFERENCES } from "./notifications";
+import { DEFAULT_DEV_SERVER_PORT } from "../types/dev-server";
 
 export const CustomCommandSchema = z.object({
   name: z.string(),
@@ -157,6 +158,7 @@ export const UserPreferencesSchema = z.object({
   repoSortMode: z.enum(['recent', 'manual', 'name']).optional(),
   serverEnvVars: z.array(ServerEnvVarSchema).optional(),
   disabledDefaultServerEnvVars: z.array(z.string()).optional(),
+  devServerPort: z.number().int().positive().optional(),
 });
 
 export const DEFAULT_TTS_CONFIG: TTSConfig = {
@@ -207,6 +209,7 @@ export const DEFAULT_USER_PREFERENCES = {
   repoSortMode: 'recent' as const,
   serverEnvVars: [] as ServerEnvVar[],
   disabledDefaultServerEnvVars: [] as string[],
+  devServerPort: DEFAULT_DEV_SERVER_PORT,
 };
 
 export const SettingsResponseSchema = z.object({
diff --git a/shared/src/types/dev-server.ts b/shared/src/types/dev-server.ts
new file mode 100644
index 000000000..ceec08791
--- /dev/null
+++ b/shared/src/types/dev-server.ts
@@ -0,0 +1,11 @@
+export const DEFAULT_DEV_SERVER_PORT = 3055
+
+export type DevServerStatus = 'running' | 'stopped'
+
+export interface DevServerState {
+  repoId: number
+  status: DevServerStatus
+  port: number
+  error: string | null
+  previewUrl: string | null
+}
diff --git a/shared/src/types/index.ts b/shared/src/types/index.ts
index 4d87df200..1453d6476 100644
--- a/shared/src/types/index.ts
+++ b/shared/src/types/index.ts
@@ -121,6 +121,9 @@ export type {
   UpdatePromptTemplateRequest,
 } from '../schemas/schedule'
 
+export { DEFAULT_DEV_SERVER_PORT } from './dev-server'
+export type { DevServerStatus, DevServerState } from './dev-server'
+
 export type {
   SkillScope,
   SkillFrontmatter,