feat(screenshot): full-page capture, wait-for-selector, and --timeout

Adds three no-dependency options to the WebView screenshot helper + CLI:
- fullPage / --full-page: measures the document scrollHeight via WebView.evaluate
  and re-renders at full height (WebView has no resize), so long pages
  (dashboards, docs) are captured whole instead of clipped to the viewport.
- waitSelector / --wait-selector: polls the page until a CSS selector exists
  before capturing (client-rendered content, hydration, font swaps).
- --timeout: exposes the existing timeoutMs navigation cap on the CLI.
Dimensions clamp to WebView's 16384px ceiling. Tests cover full-page
(PNG height > 3x viewport) and wait-selector.

Author: chrisbbreuer

packages/stx/bin/cli.ts

@@ -2209,6 +2209,9 @@ catch (error) {
     .option('--width <px>', 'Viewport width', { default: '1440' })
     .option('--height <px>', 'Viewport height', { default: '2200' })
     .option('--wait <ms>', 'Settle time after navigation before capture', { default: '800' })
+    .option('--timeout <ms>', 'Hard cap on waiting for navigation', { default: '15000' })
+    .option('--full-page', 'Capture the entire scrollable page, not just the viewport')
+    .option('--wait-selector <sel>', 'Wait until a CSS selector exists before capturing')
     .option('--format <fmt>', 'Image format: png | jpeg | webp', { default: 'png' })
     .option('--backend <name>', 'WebView backend: webkit (macOS, default) | chrome')
     .action(async (input: string | undefined, options: any) => {
@@ -2219,6 +2222,9 @@ catch (error) {
           width: Number.parseInt(options.width, 10),
           height: Number.parseInt(options.height, 10),
           waitMs: Number.parseInt(options.wait, 10),
+          timeoutMs: Number.parseInt(options.timeout, 10),
+          fullPage: Boolean(options.fullPage),
+          waitSelector: options.waitSelector,
           format: options.format,
           backend: options.backend,
         })

packages/stx/src/screenshot.ts

@@ -12,6 +12,9 @@ import { WebView } from 'bun'
 import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs'
 import path from 'node:path'
 
+/** WebView viewport dimensions are clamped to [1, 16384] by Bun. */
+const MAX_DIMENSION = 16384
+
 export interface ScreenshotOptions {
   /** Viewport width in CSS px. @default 1440 */
   width?: number
@@ -25,6 +28,19 @@ export interface ScreenshotOptions {
   format?: 'png' | 'jpeg' | 'webp'
   /** WebView backend. macOS defaults to system WebKit; elsewhere use 'chrome'. */
   backend?: 'webkit' | 'chrome'
+  /**
+   * Capture the entire scrollable page rather than just the viewport. The page
+   * is measured (`scrollHeight`) and re-rendered at its full height so nothing
+   * is cut off — ideal for long pages (dashboards, docs). Clamped to WebView's
+   * 16384px ceiling. @default false
+   */
+  fullPage?: boolean
+  /**
+   * Wait until this CSS selector is present in the DOM before capturing (polls
+   * the page via `evaluate`). Use for content that renders after load (data
+   * fetched client-side, hydration, fonts swapped in).
+   */
+  waitSelector?: string
 }
 
 export interface ShotResult {
@@ -40,37 +56,88 @@ function toUrl(input: string): string {
   return `file://${path.resolve(input)}`
 }
 
+/** Resolve once navigation completes (+ a short settle), with a timeout fallback. */
+function waitForNavigation(view: any, waitMs: number, timeoutMs: number): Promise<void> {
+  return new Promise<void>((resolve) => {
+    let settled = false
+    const finish = (): void => {
+      if (!settled) {
+        settled = true
+        resolve()
+      }
+    }
+    view.onNavigated = () => setTimeout(finish, waitMs)
+    setTimeout(finish, timeoutMs)
+  })
+}
+
+/** Poll the page until `selector` exists, or `timeoutMs` elapses (best-effort). */
+async function waitForSelector(view: any, selector: string, timeoutMs: number): Promise<void> {
+  const expr = `!!document.querySelector(${JSON.stringify(selector)})`
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    try {
+      if (await view.evaluate(expr))
+        return
+    }
+    catch {
+      // Navigation may still be settling; keep polling until the deadline.
+    }
+    await new Promise(r => setTimeout(r, 100))
+  }
+}
+
+/** Measure the full scrollable document height in CSS px (0 on failure). */
+async function measureFullHeight(view: any): Promise<number> {
+  try {
+    const h = await view.evaluate(
+      'Math.ceil(Math.max('
+      + 'document.documentElement.scrollHeight, document.documentElement.offsetHeight, '
+      + 'document.body ? document.body.scrollHeight : 0, document.body ? document.body.offsetHeight : 0))',
+    )
+    return typeof h === 'number' && Number.isFinite(h) && h > 0 ? Math.min(h, MAX_DIMENSION) : 0
+  }
+  catch {
+    return 0
+  }
+}
+
 /** Capture a single page to `output` using Bun's headless WebView. */
 export async function captureScreenshot(input: string, output: string, opts: ScreenshotOptions = {}): Promise<ShotResult> {
-  const width = opts.width ?? 1440
-  const height = opts.height ?? 2200
+  const width = Math.min(opts.width ?? 1440, MAX_DIMENSION)
+  const height = Math.min(opts.height ?? 2200, MAX_DIMENSION)
   const waitMs = opts.waitMs ?? 800
   const timeoutMs = opts.timeoutMs ?? 15000
   const format = opts.format ?? 'png'
+  const url = toUrl(input)
 
-  const view = new WebView({
-    url: toUrl(input),
+  const open = (h: number): any => new WebView({
+    url,
     width,
-    height,
+    height: h,
     headless: true,
     ...(opts.backend ? { backend: opts.backend } : {}),
   } as any)
 
+  let view = open(height)
   try {
-    // Resolve once navigation completes (+ a short settle), with a timeout
-    // fallback in case onNavigated never fires.
-    await new Promise<void>((resolve) => {
-      let settled = false
-      const finish = (): void => {
-        if (!settled) {
-          settled = true
-          resolve()
-        }
+    await waitForNavigation(view, waitMs, timeoutMs)
+    if (opts.waitSelector)
+      await waitForSelector(view, opts.waitSelector, timeoutMs)
+
+    // Full-page: WebView has no resize(), so measure the document and re-render
+    // at its full height. Only re-render when the page is actually taller than
+    // the current viewport (a no-op otherwise).
+    if (opts.fullPage) {
+      const full = await measureFullHeight(view)
+      if (full > height) {
+        view.close()
+        view = open(full)
+        await waitForNavigation(view, waitMs, timeoutMs)
+        if (opts.waitSelector)
+          await waitForSelector(view, opts.waitSelector, timeoutMs)
       }
-      const v = view as any
-      v.onNavigated = () => setTimeout(finish, waitMs)
-      setTimeout(finish, timeoutMs)
-    })
+    }
 
     const buf = await view.screenshot({ encoding: 'buffer', format } as any)
     mkdirSync(path.dirname(path.resolve(output)), { recursive: true })

packages/stx/test/screenshot.test.ts

@@ -42,4 +42,44 @@ describe('screenshot (Bun WebView)', () => {
       rmSync(dir, { recursive: true, force: true })
     }
   })
+
+  it('full-page captures the whole scrollable document, not just the viewport', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'stx-shot-full-'))
+    // A page far taller than the viewport (a tall column).
+    const tall = join(dir, 'tall.html')
+    writeFileSync(tall, '<!doctype html><html><body style="margin:0"><div style="height:3000px;background:#0b1020"></div></body></html>')
+    const viewportOut = join(dir, 'viewport.png')
+    const fullOut = join(dir, 'full.png')
+    try {
+      await captureScreenshot(tall, viewportOut, { width: 400, height: 300, waitMs: 300 })
+      await captureScreenshot(tall, fullOut, { width: 400, height: 300, waitMs: 300, fullPage: true })
+      // PNG height lives in bytes 20-23 (big-endian) of the IHDR chunk.
+      const pngHeight = async (p: string): Promise<number> => {
+        const b = await Bun.file(p).bytes()
+        return (b[20] << 24) | (b[21] << 16) | (b[22] << 8) | b[23]
+      }
+      const vh = await pngHeight(viewportOut)
+      const fh = await pngHeight(fullOut)
+      // The full-page shot is much taller than the 300px viewport capture.
+      expect(fh).toBeGreaterThan(vh * 3)
+    }
+    finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('wait-selector resolves and still captures when the selector exists', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'stx-shot-sel-'))
+    const file = join(dir, 'sel.html')
+    writeFileSync(file, '<!doctype html><html><body><div id="ready">ok</div></body></html>')
+    const out = join(dir, 'sel.png')
+    try {
+      const r = await captureScreenshot(file, out, { width: 400, height: 300, waitMs: 200, waitSelector: '#ready', timeoutMs: 5000 })
+      expect(existsSync(out)).toBe(true)
+      expect(r.bytes).toBeGreaterThan(0)
+    }
+    finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
 })