thinkpool-pair 0.7.206 → 0.7.207

package/README.md

@@ -56,6 +56,25 @@ every byte mirrors to the web. The web's **"+ New terminal"** spawns additional
 **headless** terminals here (same directory, same env), driven entirely from
 the room. One bridge, many terminals.
 
+### Built-in viewport capture
+
+Structured Claude and Codex lanes have bridge-owned visual QA tools, even when
+their own sandbox cannot bind localhost or launch Chrome:
+
+- `preview_start` serves a built directory inside that lane's workspace
+  (`dist` by default; it must contain `index.html`).
+- `preview_capture` returns exact desktop (1440×900) and mobile (390×844)
+  screenshots to the agent and surfaces them in the room.
+- `preview_inspect` returns rendered DOM text, document size, and optional
+  selector geometry at either viewport.
+- `preview_stop` releases the preview port.
+
+The bridge launches the host's Chrome/Chromium lazily. Set `TP_BROWSER_PATH`
+if it is installed somewhere non-standard. Preview files are read-only, roots
+cannot escape the lane workspace (including through symlinks), and page network
+requests are restricted to the preview server's exact loopback origin. The
+tools never execute a caller-supplied command or open an arbitrary URL.
+
 ## Run it in the cloud (remote host / VM / container)
 
 The bridge connects **outbound** to Supabase — no inbound ports, no public IP, no

package/bridge.mjs

@@ -63,6 +63,7 @@ import { normalizePlanOutput, laneModelFor } from './flow-task-graph.mjs'   // F
 import { writeLaneArtifact, digestSlice, appendDigest, resumeLane } from './flow-context-store.mjs'
 import { createFlowWorktree, worktreeSpec } from './flow-worktree.mjs'
 import { startPreview, stopAllPreviews, previews } from './flow-preview.mjs'
+import { ViewportManager, createViewportTools, sharedViewportBrowser } from './viewport.mjs'
 // FL-M9 — per-lane preview servers leak (one per done lane, never stopped until shutdown).
 // Lane previews are keyed `lane:<flowId>:<laneId>`; stop a whole flow's set when it assembles
 // (the assembled preview supersedes them) or when a lane is reverted.
@@ -1747,6 +1748,9 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
   // they land on this session even after other terminals open/close.
   const mockupOutbox = ownerOutbox('sessions', id)
   entry.mockupWatcher = watchOutbox(mockupOutbox, () => id)
+  // Visual QA runs in the bridge process, outside either agent runtime's sandbox.
+  // It remains scoped to this lane's cwd and private mockup outbox.
+  entry.viewport = new ViewportManager({ workspaceRoot: cwd || process.cwd(), ownerId: id, outbox: mockupOutbox })
   if (entry.log.length) process.stderr.write(`\n  ◆ restored ${entry.log.length} prior events (${id.slice(0, 8)})${resume ? ' + resuming live context' : ''}.\n`)
   // Persist the permission mode alongside the transcript so a bridge restart
   // restores the session in the SAME mode (a bypass room stays bypass on resume).
@@ -1776,6 +1780,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
     name: 'thinkpool',
     version: '1.0.0',
     tools: [
+      ...createViewportTools({ tool, z, manager: entry.viewport }),
       tool(
         'read_terminal',
         'Read-only view of ANOTHER terminal in this ThinkPool Code room (a sibling agent or a shell the people are using). Call with no arguments to list the other open terminals; call with `terminal` (a ref, id, or command from that list) to read its recent activity. It never changes another terminal — reading only. Use it when your work depends on what another terminal is doing.',
@@ -2199,6 +2204,7 @@ function openStructured({ id, runtime = 'claude', model, effort, resume, log, co
         process.stderr.write(`\n  ◆ saved session expired — starting fresh (transcript kept).\n`)
         try { entry.session?.end() } catch { /* noop */ }
         try { entry.mockupWatcher?.close() } catch { /* noop */ }
+        try { void entry.viewport?.stop()?.catch(() => {}) } catch { /* noop */ }
         sessions.delete(id)
         openStructured({ id, runtime: entry.runtime, model, log: entry.log, commands: entry.commands, mode: entry.mode })
         return
@@ -2544,6 +2550,7 @@ function respawnStructured(id, provider) {
   drainPending(s)
   try { s.session?.end() } catch { /* noop */ }
   try { s.mockupWatcher?.close() } catch { /* noop */ }
+  try { void s.viewport?.stop()?.catch(() => {}) } catch { /* noop */ }
   sessions.delete(id)   // openStructured early-returns if the id is still mapped
   // Re-open under the SAME id with the new provider env. openStructured persists
   // sessionData() (provider included) synchronously on open, so a bridge restart
@@ -2586,6 +2593,7 @@ function endStructured(id) {
     drainPending(s)
     try { s.session?.end() } catch { /* noop */ }
     try { s.mockupWatcher?.close() } catch { /* noop */ }
+    try { void s.viewport?.stop()?.catch(() => {}) } catch { /* noop */ }
     sessions.delete(id)
     bcast('term-exit', { id })
     reapTerminalRow(id)    // bridge-side reap: delete the code_terminals row ourselves — the
@@ -3709,6 +3717,7 @@ async function shutdown(code = 0, farewell = true) {
   setTimeout(() => process.exit(code), 1500)
   clearInterval(flushTimer)
   try { stopAllPreviews() } catch { /* Flow preview servers — best-effort close */ }
+  try { void sharedViewportBrowser.close().catch(() => {}) } catch { /* bridge-owned Chrome — best-effort close */ }
   if (farewell) {
     try {
       const bye = Buffer.from('\r\n[ shared session ended ]\r\n', 'utf8').toString('base64')

package/claude-session.mjs

@@ -486,6 +486,11 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
     if (toolName === 'mcp__thinkpool__read_terminal') {
       return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: 'Auto-approved (read-only ThinkPool cross-terminal read).' } }
     }
+    // Bridge-owned visual QA is constrained to the lane cwd + a loopback URL
+    // created by the bridge itself, so it does not need a room permission card.
+    if (/^mcp__thinkpool__preview_(start|capture|inspect|stop)$/.test(toolName)) {
+      return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: 'Auto-approved (contained bridge-owned viewport preview).' } }
+    }
     // FL-B1 — the Flow conductor submits its task-graph through this tool (replaces the
     // deferred/hanging ExitPlanMode). It only broadcasts a plan for HUMAN approval — no FS or
     // system effect — so auto-allow it (the conductor runs in plan mode, which would otherwise
@@ -699,6 +704,7 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
       'Whenever you produce an HTML artifact (a demo, mockup, preview, report, or page) or surface ANY link meant to be opened or shared, NEVER hand the room a local path, a file:// URL, or a localhost/127.0.0.1 address. Publish it to a GitHub-shareable URL that renders in a browser — push the HTML to a GitHub repo and give its GitHub Pages URL (or an equivalent raw-HTML URL that actually renders, not raw.githubusercontent.com which serves HTML as plain text) — so anyone in the room can open it. The same applies to any other link you surface: it must be one the room can reach, not a host-only path.',
       'If you cannot publish a shareable link, say so and ask how to proceed — do not fall back to handing over a local path.',
       'SHOW YOUR WORK, do not just describe it: the room is watched live from a phone, where a wall of text is painful to read. Whenever you build, change, or fix anything visual — a UI, a page, an HTML artifact, a chart, a diagram, a rendered result — capture a screenshot and surface the PNG (for example, read the image file into your turn) so it appears inline in the room. The room auto-uploads any image you surface. Default to showing a picture of the result over narrating it; err toward more screenshots, not fewer.',
+      'BRIDGE VIEWPORTS: for a built web UI, use preview_start (default root: dist), then preview_capture for exact desktop 1440×900 + mobile 390×844 screenshots, and preview_inspect when DOM text or selector geometry helps. These tools run in the bridge, so they work even when your lane sandbox cannot bind localhost or launch Chrome. They only serve built files inside your own lane workspace; run the project build first. Stop the server with preview_stop when you are done.',
       'HTML PREVIEWS: for any HTML you produce, give the room something it can actually open, by whichever path is available. (a) IN-ROOM PREVIEW: if a mockup render helper is present — one that writes a manifest into the directory named by $TP_MOCKUP_OUTBOX, such as the mockup-iterate render.sh script when the bridge was launched from the thinkpool repo — use it; it surfaces an inline card with desktop and mobile views that the room can expand. (b) SHAREABLE LINK: additionally or otherwise, publish the HTML to a GitHub Pages URL per the LINKS & ARTIFACTS rule above and post the link. Never leave an HTML artifact viewable only as a local path.',
       'RUN IT, DO NOT ASK: verify your own work before calling it done. Actually run or serve what you changed, observe that it behaves correctly, and show the evidence in the room — a screenshot of the running result, the passing test output, or the real response — rather than telling the user "this should work, go test it." If you could not verify something, say exactly what is unverified. This room follows verify-before-claiming: runtime evidence you produced, not assertion.',
       'CROSS-TERMINAL AWARENESS: this room may have other terminals open alongside yours — other agents working, or shells the people are driving. You have a READ-ONLY tool, read_terminal: call it with no arguments to list the other open terminals, or with a terminal ref/id/command to read that terminal\'s recent activity. Reach for it when your work depends on what another terminal is doing (e.g. someone says "see what the other terminal hit", or you need to coordinate with a sibling agent before acting). It only ever reads — it never changes another terminal. Identify a terminal by its NAME or its ref/id from the roster, never by an on-screen number like "Terminal 2" — those positional labels renumber when a terminal is closed, so they do not reliably point at a lane.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.206",
+  "version": "0.7.207",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -33,6 +33,7 @@
     "flow-worktree.mjs",
     "flow-task-graph.mjs",
     "flow-preview.mjs",
+    "viewport.mjs",
     "flow-review.mjs",
     "flow-review-gate.mjs",
     "flow-review-reflect.mjs",

package/viewport.mjs

@@ -0,0 +1,445 @@
+// Bridge-owned visual QA for ThinkPool Code lanes.
+//
+// Agent sandboxes should not need permission to bind localhost or launch a GUI
+// process. The bridge already owns a contained static preview server
+// (flow-preview.mjs), so this module adds the missing half: an exact-viewport,
+// dependency-free Chrome DevTools Protocol capture worker plus per-lane tools.
+//
+// Security boundary:
+//   - preview roots must resolve inside the lane's own cwd (symlinks included)
+//   - the browser only opens the loopback URL created by startPreview()
+//   - no caller-supplied commands, executables, ports, hosts, or arbitrary URLs
+
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { previews, startPreview } from './flow-preview.mjs'
+
+export const DEFAULT_VIEWPORTS = Object.freeze({
+  desktop: Object.freeze({ width: 1440, height: 900 }),
+  mobile: Object.freeze({ width: 390, height: 844 }),
+})
+
+const MAX_CAPTURE_HEIGHT = 20000
+const MAX_SETTLE_MS = 5000
+const CDP_TIMEOUT_MS = 12000
+
+const isInside = (parent, child) => {
+  const rel = path.relative(parent, child)
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
+}
+
+export async function resolveContainedRoot(workspaceRoot, requested = 'dist') {
+  if (!workspaceRoot) throw new Error('A lane workspace is required.')
+  if (path.isAbsolute(requested)) throw new Error('Preview root must be relative to the lane workspace.')
+  const workspace = await fsp.realpath(path.resolve(workspaceRoot))
+  const candidate = path.resolve(workspace, requested || 'dist')
+  let resolved
+  try { resolved = await fsp.realpath(candidate) }
+  catch { throw new Error(`Preview root does not exist: ${requested || 'dist'}. Build the app first, or choose a directory containing index.html.`) }
+  if (!isInside(workspace, resolved)) throw new Error('Preview root escapes the lane workspace.')
+  const stat = await fsp.stat(resolved)
+  if (!stat.isDirectory()) throw new Error('Preview root must be a directory.')
+  if (!fs.existsSync(path.join(resolved, 'index.html'))) throw new Error(`No index.html found in preview root: ${requested || 'dist'}.`)
+  return resolved
+}
+
+export function normalizeRoute(value = '/') {
+  const route = String(value || '/').trim()
+  if (!route.startsWith('/') || route.startsWith('//')) throw new Error('Preview path must start with one "/" and cannot be a URL.')
+  const parsed = new URL(route, 'http://127.0.0.1')
+  if (parsed.origin !== 'http://127.0.0.1') throw new Error('Preview path cannot change the preview origin.')
+  return `${parsed.pathname}${parsed.search}${parsed.hash}`
+}
+
+export function safeSlug(value = 'viewport') {
+  return String(value || 'viewport')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 56) || 'viewport'
+}
+
+export function findBrowserExecutable({ env = process.env, platform = process.platform, exists = fs.existsSync } = {}) {
+  const candidates = [
+    env.TP_BROWSER_PATH,
+    platform === 'darwin' && '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    platform === 'darwin' && '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    platform === 'win32' && env.PROGRAMFILES && path.join(env.PROGRAMFILES, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+    platform === 'win32' && env['PROGRAMFILES(X86)'] && path.join(env['PROGRAMFILES(X86)'], 'Google', 'Chrome', 'Application', 'chrome.exe'),
+    platform === 'linux' && '/usr/bin/google-chrome',
+    platform === 'linux' && '/usr/bin/google-chrome-stable',
+    platform === 'linux' && '/usr/bin/chromium',
+    platform === 'linux' && '/usr/bin/chromium-browser',
+  ].filter(Boolean)
+  return candidates.find((candidate) => {
+    try { return exists(candidate) } catch { return false }
+  }) || null
+}
+
+class CdpPipe {
+  constructor(child, timeoutMs = CDP_TIMEOUT_MS) {
+    this.child = child
+    this.timeoutMs = timeoutMs
+    this.nextId = 1
+    this.buffer = Buffer.alloc(0)
+    this.pending = new Map()
+    this.waiters = new Set()
+    this.subscribers = new Set()
+    child.stdio[4].on('data', (chunk) => this.onData(chunk))
+    child.once('exit', (code, signal) => this.failAll(new Error(`Chrome exited (${signal || code || 'unknown'}).`)))
+    child.once('error', (error) => this.failAll(error))
+  }
+
+  onData(chunk) {
+    this.buffer = Buffer.concat([this.buffer, chunk])
+    for (;;) {
+      const end = this.buffer.indexOf(0)
+      if (end < 0) break
+      const raw = this.buffer.subarray(0, end).toString('utf8')
+      this.buffer = this.buffer.subarray(end + 1)
+      if (!raw) continue
+      let message
+      try { message = JSON.parse(raw) } catch { continue }
+      if (message.id) {
+        const pending = this.pending.get(message.id)
+        if (!pending) continue
+        clearTimeout(pending.timer)
+        this.pending.delete(message.id)
+        if (message.error) pending.reject(new Error(message.error.message || 'Chrome DevTools error'))
+        else pending.resolve(message.result || {})
+        continue
+      }
+      for (const waiter of [...this.waiters]) {
+        if (waiter.method !== message.method) continue
+        if (waiter.sessionId && waiter.sessionId !== message.sessionId) continue
+        if (waiter.predicate && !waiter.predicate(message.params || {})) continue
+        clearTimeout(waiter.timer)
+        this.waiters.delete(waiter)
+        waiter.resolve(message.params || {})
+      }
+      for (const subscriber of [...this.subscribers]) {
+        if (subscriber.method !== message.method) continue
+        if (subscriber.sessionId && subscriber.sessionId !== message.sessionId) continue
+        try { subscriber.handler(message.params || {}) } catch { /* subscriber owns recovery */ }
+      }
+    }
+  }
+
+  failAll(error) {
+    for (const pending of this.pending.values()) { clearTimeout(pending.timer); pending.reject(error) }
+    this.pending.clear()
+    for (const waiter of this.waiters) { clearTimeout(waiter.timer); waiter.reject(error) }
+    this.waiters.clear()
+    this.subscribers.clear()
+  }
+
+  send(method, params = {}, sessionId) {
+    const id = this.nextId++
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error(`Chrome timed out running ${method}.`))
+      }, this.timeoutMs)
+      this.pending.set(id, { resolve, reject, timer })
+      const message = { id, method, params, ...(sessionId ? { sessionId } : {}) }
+      this.child.stdio[3].write(`${JSON.stringify(message)}\0`)
+    })
+  }
+
+  waitFor(method, sessionId, predicate) {
+    return new Promise((resolve, reject) => {
+      const waiter = { method, sessionId, predicate, resolve, reject, timer: null }
+      waiter.timer = setTimeout(() => {
+        this.waiters.delete(waiter)
+        reject(new Error(`Chrome timed out waiting for ${method}.`))
+      }, this.timeoutMs)
+      this.waiters.add(waiter)
+    })
+  }
+
+  subscribe(method, sessionId, handler) {
+    const subscriber = { method, sessionId, handler }
+    this.subscribers.add(subscriber)
+    return () => this.subscribers.delete(subscriber)
+  }
+}
+
+export class CdpBrowser {
+  constructor({ executable, spawnImpl = spawn, timeoutMs = CDP_TIMEOUT_MS } = {}) {
+    this.executable = executable || null
+    this.spawnImpl = spawnImpl
+    this.timeoutMs = timeoutMs
+    this.child = null
+    this.pipe = null
+    this.profileDir = null
+    this.starting = null
+    this.stderr = ''
+  }
+
+  async ensureStarted() {
+    if (this.child && this.pipe) return
+    if (this.starting) return this.starting
+    this.starting = this.start().finally(() => { this.starting = null })
+    return this.starting
+  }
+
+  async start() {
+    const executable = this.executable || findBrowserExecutable()
+    if (!executable) throw new Error('No supported Chrome/Chromium executable found. Install Google Chrome or set TP_BROWSER_PATH on the bridge host.')
+    this.profileDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'thinkpool-viewport-'))
+    const args = [
+      '--headless=new', '--remote-debugging-pipe', '--no-first-run', '--no-default-browser-check',
+      '--disable-background-networking', '--disable-component-update', '--disable-sync',
+      '--disable-extensions', '--disable-default-apps',
+      '--metrics-recording-only', '--mute-audio', '--hide-scrollbars',
+      `--user-data-dir=${this.profileDir}`, 'about:blank',
+    ]
+    const child = this.spawnImpl(executable, args, { stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'] })
+    this.child = child
+    child.stderr?.on('data', (chunk) => { this.stderr = (this.stderr + chunk.toString('utf8')).slice(-4000) })
+    this.pipe = new CdpPipe(child, this.timeoutMs)
+    try { await this.pipe.send('Browser.getVersion') }
+    catch (error) {
+      await this.close()
+      const detail = this.stderr.trim().split('\n').slice(-2).join(' ')
+      throw new Error(`Could not start Chrome for viewport capture: ${detail || error.message}`)
+    }
+  }
+
+  async withPage({ url, viewport, waitMs = 300 }, fn) {
+    await this.ensureStarted()
+    const { targetId } = await this.pipe.send('Target.createTarget', { url: 'about:blank' })
+    const { sessionId } = await this.pipe.send('Target.attachToTarget', { targetId, flatten: true })
+    let unsubscribeRequests = null
+    try {
+      await this.pipe.send('Page.enable', {}, sessionId)
+      await this.pipe.send('Runtime.enable', {}, sessionId)
+      // The page is untrusted build output. Keep its network authority narrower
+      // than the lane sandbox: same preview origin only. This blocks internet,
+      // cloud metadata, and other localhost services while still allowing all
+      // JS/CSS/assets served from the selected build directory.
+      const allowedOrigin = new URL(url).origin
+      unsubscribeRequests = this.pipe.subscribe('Fetch.requestPaused', sessionId, (params) => {
+        let allowed = false
+        try { allowed = new URL(params.request?.url || '').origin === allowedOrigin } catch { allowed = false }
+        const method = allowed ? 'Fetch.continueRequest' : 'Fetch.failRequest'
+        const request = allowed
+          ? { requestId: params.requestId }
+          : { requestId: params.requestId, errorReason: 'BlockedByClient' }
+        void this.pipe.send(method, request, sessionId).catch(() => {})
+      })
+      await this.pipe.send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] }, sessionId)
+      await this.pipe.send('Network.setBypassServiceWorker', { bypass: true }, sessionId).catch(() => {})
+      await this.pipe.send('Emulation.setDeviceMetricsOverride', {
+        width: viewport.width, height: viewport.height, deviceScaleFactor: 1, mobile: false,
+        screenWidth: viewport.width, screenHeight: viewport.height,
+      }, sessionId)
+      const loaded = this.pipe.waitFor('Page.loadEventFired', sessionId)
+      const nav = await this.pipe.send('Page.navigate', { url }, sessionId)
+      if (nav.errorText) throw new Error(`Preview navigation failed: ${nav.errorText}`)
+      await loaded
+      await this.pipe.send('Runtime.evaluate', {
+        expression: 'document.fonts && document.fonts.ready', awaitPromise: true, returnByValue: true,
+      }, sessionId).catch(() => {})
+      const settle = Math.min(MAX_SETTLE_MS, Math.max(0, Number(waitMs) || 0))
+      if (settle) await new Promise((resolve) => setTimeout(resolve, settle))
+      return await fn({ pipe: this.pipe, sessionId })
+    } finally {
+      unsubscribeRequests?.()
+      await this.pipe.send('Target.closeTarget', { targetId }).catch(() => {})
+    }
+  }
+
+  async capture({ url, viewport, fullPage = true, waitMs = 300 }) {
+    return this.withPage({ url, viewport, waitMs }, async ({ pipe, sessionId }) => {
+      const metrics = await pipe.send('Page.getLayoutMetrics', {}, sessionId)
+      const contentHeight = Math.ceil(metrics.cssContentSize?.height || viewport.height)
+      const height = fullPage ? Math.min(MAX_CAPTURE_HEIGHT, Math.max(viewport.height, contentHeight)) : viewport.height
+      const result = await pipe.send('Page.captureScreenshot', {
+        format: 'png', fromSurface: true, captureBeyondViewport: true,
+        clip: { x: 0, y: 0, width: viewport.width, height, scale: 1 },
+      }, sessionId)
+      return { png: Buffer.from(result.data, 'base64'), width: viewport.width, height, contentHeight, capped: contentHeight > MAX_CAPTURE_HEIGHT }
+    })
+  }
+
+  async inspect({ url, viewport = DEFAULT_VIEWPORTS.mobile, selector, waitMs = 300 }) {
+    return this.withPage({ url, viewport, waitMs }, async ({ pipe, sessionId }) => {
+      const expression = `(() => {
+        const selector = ${JSON.stringify(selector || null)};
+        const el = selector ? document.querySelector(selector) : null;
+        const r = el && el.getBoundingClientRect();
+        return {
+          title: document.title, url: location.href,
+          viewport: { width: innerWidth, height: innerHeight, dpr: devicePixelRatio },
+          document: { width: Math.max(document.documentElement.scrollWidth, document.body?.scrollWidth || 0), height: Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight || 0) },
+          selector: selector ? { query: selector, found: !!el, tag: el?.tagName || null, text: el?.innerText?.slice(0, 2000) || '', rect: r ? { x:r.x, y:r.y, width:r.width, height:r.height } : null } : null,
+          text: document.body?.innerText?.slice(0, 12000) || ''
+        };
+      })()`
+      const result = await pipe.send('Runtime.evaluate', { expression, returnByValue: true }, sessionId)
+      if (result.exceptionDetails) throw new Error('DOM inspection failed in the preview page.')
+      return result.result?.value || {}
+    })
+  }
+
+  async close() {
+    const child = this.child
+    const pipe = this.pipe
+    this.child = null
+    this.pipe = null
+    if (pipe) await pipe.send('Browser.close').catch(() => {})
+    if (child && child.exitCode == null) { try { child.kill('SIGTERM') } catch { /* already gone */ } }
+    if (this.profileDir) await fsp.rm(this.profileDir, { recursive: true, force: true }).catch(() => {})
+    this.profileDir = null
+  }
+}
+
+export const sharedViewportBrowser = new CdpBrowser()
+
+export class ViewportManager {
+  constructor({ workspaceRoot, ownerId, outbox, browser = sharedViewportBrowser, startPreviewImpl = startPreview } = {}) {
+    this.workspaceRoot = path.resolve(workspaceRoot || process.cwd())
+    this.ownerId = ownerId || randomUUID()
+    this.outbox = outbox || path.join(os.tmpdir(), 'thinkpool-viewport-captures', this.ownerId)
+    this.browser = browser
+    this.startPreviewImpl = startPreviewImpl
+    this.previewId = `viewport:${this.ownerId}`
+    this.preview = null
+    this.root = null
+  }
+
+  async start({ root = 'dist' } = {}) {
+    const resolved = await resolveContainedRoot(this.workspaceRoot, root)
+    await this.stop()
+    const preview = await this.startPreviewImpl({ dir: resolved, host: '127.0.0.1', port: 0, id: this.previewId })
+    const parsed = new URL(preview.url)
+    if (parsed.hostname !== '127.0.0.1' && parsed.hostname !== 'localhost') {
+      await preview.stop?.()
+      throw new Error('Preview server did not bind to loopback.')
+    }
+    this.preview = preview
+    this.root = resolved
+    return { url: preview.url, root: resolved }
+  }
+
+  requirePreview() {
+    if (!this.preview?.url) throw new Error('No preview is running. Call preview_start after building the app.')
+    return this.preview
+  }
+
+  pageUrl(route) {
+    const preview = this.requirePreview()
+    return new URL(normalizeRoute(route), preview.url).href
+  }
+
+  async capture({ route = '/', viewports = 'both', title = 'Viewport capture', fullPage = true, waitMs = 300 } = {}) {
+    const url = this.pageUrl(route)
+    const names = viewports === 'both' ? ['desktop', 'mobile'] : [viewports]
+    if (names.some((name) => !DEFAULT_VIEWPORTS[name])) throw new Error('viewports must be "both", "desktop", or "mobile".')
+    await fsp.mkdir(this.outbox, { recursive: true })
+    const slug = `${safeSlug(title)}-${Date.now().toString(36)}`
+    const captures = {}
+    for (const name of names) {
+      const result = await this.browser.capture({ url, viewport: DEFAULT_VIEWPORTS[name], fullPage, waitMs })
+      const file = path.join(this.outbox, `${slug}--${name}.png`)
+      await fsp.writeFile(file, result.png)
+      captures[name] = { ...result, file }
+    }
+    const html = this.root && fs.existsSync(path.join(this.root, 'index.html')) ? path.join(this.root, 'index.html') : null
+    const manifest = {
+      slug, title: String(title || 'Viewport capture').slice(0, 120), html,
+      desktop: captures.desktop?.file || '', mobile: captures.mobile?.file || '', ts: Date.now(),
+    }
+    const manifestPath = path.join(this.outbox, `${slug}.json`)
+    const tmp = `${manifestPath}.tmp`
+    await fsp.writeFile(tmp, JSON.stringify(manifest))
+    await fsp.rename(tmp, manifestPath)
+    return { url, slug, manifestPath, captures }
+  }
+
+  inspect({ route = '/', viewport = 'mobile', selector, waitMs = 300 } = {}) {
+    if (!DEFAULT_VIEWPORTS[viewport]) throw new Error('viewport must be "desktop" or "mobile".')
+    return this.browser.inspect({ url: this.pageUrl(route), viewport: DEFAULT_VIEWPORTS[viewport], selector, waitMs })
+  }
+
+  async stop() {
+    const preview = this.preview || previews.get(this.previewId)
+    this.preview = null
+    this.root = null
+    if (preview?.stop) await preview.stop()
+  }
+}
+
+const textResult = (text) => ({ content: [{ type: 'text', text }] })
+const errorResult = (error) => textResult(`Viewport error: ${error?.message || error}`)
+
+export function createViewportTools({ tool, z, manager }) {
+  return [
+    tool(
+      'preview_start',
+      'Start a bridge-owned, read-only localhost preview for built files inside this lane workspace. Run the project build first. The default root is dist; pass another relative directory only when its index.html is the intended preview.',
+      { root: z.string().max(240).optional().describe('relative directory inside this lane workspace; default: dist') },
+      async (args) => {
+        try {
+          const started = await manager.start({ root: args?.root || 'dist' })
+          return textResult(`Preview ready from ${path.relative(manager.workspaceRoot, started.root) || '.'}. Use preview_capture to see desktop/mobile, or preview_inspect for DOM text and geometry.`)
+        } catch (error) { return errorResult(error) }
+      },
+    ),
+    tool(
+      'preview_capture',
+      'Capture this lane preview at exact desktop (1440×900) and mobile (390×844) CSS viewports. Defaults to both and full-page. Returns the PNGs to your vision context and also surfaces a mockup card in the ThinkPool room.',
+      {
+        path: z.string().max(500).optional().describe('route within the preview, e.g. / or /settings; never a full URL'),
+        viewports: z.enum(['both', 'desktop', 'mobile']).optional(),
+        title: z.string().max(120).optional(),
+        fullPage: z.boolean().optional(),
+        waitMs: z.number().int().min(0).max(MAX_SETTLE_MS).optional().describe('settle time after load, max 5000ms'),
+      },
+      async (args) => {
+        try {
+          const result = await manager.capture({
+            route: args?.path || '/', viewports: args?.viewports || 'both', title: args?.title || 'Viewport capture',
+            fullPage: args?.fullPage !== false, waitMs: args?.waitMs ?? 300,
+          })
+          const content = [{ type: 'text', text: `Captured ${Object.keys(result.captures).join(' + ')} for ${args?.path || '/'}. A room preview card is being delivered.` }]
+          for (const [name, capture] of Object.entries(result.captures)) {
+            content.push({ type: 'text', text: `${name}: ${capture.width}×${capture.height}${capture.capped ? ' (height capped)' : ''}` })
+            content.push({ type: 'image', data: capture.png.toString('base64'), mimeType: 'image/png' })
+          }
+          return { content }
+        } catch (error) { return errorResult(error) }
+      },
+    ),
+    tool(
+      'preview_inspect',
+      'Inspect rendered DOM state in this lane preview at an exact desktop or mobile viewport. Returns page text, document dimensions, and optional selector text/geometry without changing the page.',
+      {
+        path: z.string().max(500).optional().describe('route within the preview; never a full URL'),
+        viewport: z.enum(['desktop', 'mobile']).optional(),
+        selector: z.string().max(500).optional(),
+        waitMs: z.number().int().min(0).max(MAX_SETTLE_MS).optional(),
+      },
+      async (args) => {
+        try {
+          const result = await manager.inspect({ route: args?.path || '/', viewport: args?.viewport || 'mobile', selector: args?.selector, waitMs: args?.waitMs ?? 300 })
+          return textResult(JSON.stringify(result, null, 2))
+        } catch (error) { return errorResult(error) }
+      },
+    ),
+    tool(
+      'preview_stop',
+      'Stop this lane\'s bridge-owned preview server and release its port.',
+      {},
+      async () => {
+        try { await manager.stop(); return textResult('Preview stopped.') }
+        catch (error) { return errorResult(error) }
+      },
+    ),
+  ]
+}