@milkstraw/traceframe 0.2.0 → 0.3.0

package/README.md

@@ -57,7 +57,9 @@ Both presets use a 1280×800 CSS viewport. `draft` produces 1280×800 at 30 FPS;
 
 The cursor and click pulses are always drawn at the full frame rate. Chromium may capture page changes, such as scrolling and animations, at a lower rate at 2560×1600, depending on the machine. The video repeats the last page frame until the next one arrives.
 
-Use `--run-dir .traceframe/runs/name` (`runDirectory` in the API) to keep the raw capture and FFmpeg filter file, including a partial capture if the flow fails during recording. Keep that directory out of Git, because the raw capture shows everything the page showed.
+Use `--run-dir .traceframe/runs/name` (`runDirectory` in the API) to keep the raw capture and FFmpeg filter file, including a partial capture if the flow fails during recording. On a preparation or recording failure, Traceframe also tries to save a viewport screenshot as `failure.png`. Keep that directory out of Git, because captures and screenshots can contain private page data.
+
+When available, failure output includes the error code, flow-file locations, elapsed recording time, and paths to artifacts saved for that attempt. Without `--run-dir`, temporary captures are removed and no failure screenshot is saved. See [diagnosing a failed take](docs/recording-flows.md#diagnose-a-failed-take).
 
 ## Write a flow
 
@@ -143,10 +145,23 @@ await record({
 })
 ```
 
-Traceframe's own errors are `TraceframeError` instances (exported by the package) with a `code`, such as `READY_FAILED` or `FLOW_TARGET_OBSCURED`.
+Traceframe's own errors are `TraceframeError` instances (exported by the package) with a `code`, such as `READY_FAILED` or `FLOW_TARGET_OBSCURED`. Other exceptions thrown by the flow become `FLOW_FAILED`, with the original thrown value in `cause`; existing Traceframe error codes and causes are preserved.
+
+When available, `error.diagnostics` contains:
+
+| Field | Meaning |
+| --- | --- |
+| `flowLocations` | Locations in the supplied flow file, as `{ file, line, column }` objects with an absolute path and 1-based line/column. Empty when the error stack has no matching frame. |
+| `recordingTime` | Elapsed seconds from the first captured frame for a capture-stage failure, measured before collecting failure artifacts. Omitted before the first frame and for later rendering failures. |
+| `capturePath` | Absolute path to the retained raw capture, only when `runDirectory` was supplied and saving succeeded. |
+| `screenshotPath` | Absolute path to the saved failure screenshot, only when `runDirectory` was supplied and the screenshot succeeded. |
+
+A flow timeout may have no flow location because it is raised outside the blocked operation. Screenshots are best effort and have a five-second collection budget. Partial captures are saved before browser shutdown, with no fixed time limit so slower encoders can finish. Diagnostic failures do not replace the original error.
 
 Pass `signal` to stop a recording early. Traceframe closes the browser, stops FFmpeg, and removes its temporary files before rejecting with the signal's reason. When you pass a signal, Traceframe leaves Ctrl-C and other termination signals to you. The CLI does this for you: the first Ctrl-C stops and cleans up, and a second one exits at once.
 
+A stuck recording encoder can delay saving and cancellation indefinitely. A second Ctrl-C forces the CLI to exit and can discard the unfinished capture. API callers that need a hard shutdown deadline should run recording in a separate process they can terminate.
+
 ## Sample output
 
 The committed sample is generated from the [repository's fixture flow](examples/fixture-flow.mjs) with the `standard` preset (2560×1600 at 60 FPS) and is about 12 seconds long:

package/docs/recording-flows.md

@@ -58,6 +58,42 @@ Before a follow-up, wait for the application to show that the current step is co
 
 Set a Playwright timeout explicitly when an individual operation may exceed its usual 30 seconds, such as `await newReply.waitFor({ timeout: 60_000 })`. Use Traceframe's `wait(seconds)` for reading time. Each helper wait is limited to 30 seconds, and the whole flow has a 120-second timeout that `--flow-timeout` (`flowTimeout` in the API) raises.
 
+## Add captions and reading time
+
+For a review video, explain what the viewer should notice. Show the caption, pause before moving the pointer, perform the action, then hold the result. Start with about 12 characters per second and a 2.5-second minimum for reading, followed by a 2.5–4 second result hold.
+
+Use Playwright's [`page.screencast.showOverlay()`](https://playwright.dev/docs/api/class-screencast#screencast-show-overlay) inside the flow. Keep the caption compact, centered, and clear of the controls and results being shown. Traceframe's covered-click check ignores this pointer-transparent caption; use `top: 32px` instead of `bottom: 32px` when it would hide controls or results near the bottom. Keep its handle and dispose of it after the result hold:
+
+```js
+const text = 'Open Actions to inspect the available options.'
+const caption = await page.screencast.showOverlay(`
+  <div style="position: fixed; left: 24px; right: 24px; bottom: 32px;
+    display: flex; justify-content: center; pointer-events: none;">
+    <div dir="auto" style="max-width: 720px; padding: 12px 20px; border-radius: 10px;
+      background: #18181b; color: #fff;
+      box-shadow: 0 4px 16px rgba(0, 0, 0, 0.16);
+      font: 500 20px/1.45 system-ui, sans-serif;
+      text-align: center; text-wrap: balance;">
+      ${text}
+    </div>
+  </div>
+`)
+try {
+  await wait(Math.max(2.5, Array.from(text).length / 12))
+  await click(page.getByRole('button', { name: 'Actions', exact: true }))
+  await page.getByRole('menu').waitFor()
+  await wait(3)
+} finally {
+  await caption.dispose()
+}
+```
+
+Omit `duration` when actions should happen while the caption is visible. Playwright uses milliseconds for `duration`: awaiting `showOverlay(html, { duration: 3000 })` waits until the overlay is removed. The example uses fixed text; escape dynamic text before inserting it into HTML.
+
+Playwright restores overlays after a full-page navigation, but they can briefly disappear while the new document loads. Opening a native modal `<dialog>` can also briefly cover an existing caption. For a clean caption transition, finish the reading pause and dispose of the current caption before the action that navigates or opens the dialog, then show the next caption after the destination or dialog is ready.
+
+Keep captions short. Split longer text into separate captions so each reading pause stays within the helper's 30-second limit. Reading pauses and result holds count toward the flow timeout; for a longer video, raise it with, for example, `--flow-timeout 240` (seconds).
+
 ## Optional startup settings
 
 `page.emulateMedia({ colorScheme: 'dark' })` in `ready` updates CSS themes that follow the browser's color scheme. If the app reads the setting only at startup, set it before opening the app, as below.
@@ -83,7 +119,7 @@ The two `Emulation` calls set the locale that `navigator.language`, `Intl`, and
 
 Use `--preset draft` while writing the flow and the default preset for the final video.
 
-While writing the flow, pass `--run-dir` with an ignored folder, such as `.traceframe/runs/demo`. A failed take then keeps its partial `capture.webm`, which has no cursor overlay and stops where the flow failed.
+While writing the flow, pass `--run-dir` with an ignored folder, such as `.traceframe/runs/demo`. Use a separate directory for each take. A failed take keeps its partial `capture.webm` when saving succeeds and attempts a viewport screenshot, `failure.png`. The raw capture has no added cursor overlay and may include repeated final frames after the failure time.
 
 A failed take may already have submitted real jobs, so reset demo data before recording again. Check the important transitions and the final result. You can also check the file for decode errors:
 
@@ -91,6 +127,22 @@ A failed take may already have submitted real jobs, so reset demo data before re
 ffmpeg -v error -xerror -i ./recording.mp4 -f null -
 ```
 
+## Diagnose a failed take
+
+The CLI keeps the original error message and adds available context on standard error. For example:
+
+```text
+traceframe: [FLOW_FAILED] Expected the Saved status.
+  Flow: /project/review.mjs:18:9
+  Recording time: 12.35 s
+  Capture: /project/.traceframe/runs/demo/capture.webm
+  Screenshot: /project/.traceframe/runs/demo/failure.png
+```
+
+Inspect the reported screenshot, then the capture near the reported time if needed. The time is measured from the first captured frame before diagnostic collection; it is not the raw file's duration. Correct the locator or application check and reset demo data before retrying.
+
+Only paths saved for the current attempt are reported. A closed or unresponsive page may prevent a screenshot or capture from being saved. Errors before the first frame have no recording time, and a flow timeout may have no source location. Without `--run-dir`, flow locations and timing are still reported when available, but temporary captures are removed and no failure screenshot is saved. The API exposes the same context through [`error.diagnostics`](../README.md#programmatic-usage).
+
 ## Edit the finished video
 
 Edit the finished MP4 with FFmpeg rather than changing the flow. Editing finished frames keeps the page and cursor together. Keep the original, and say when a clip's pacing was edited.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milkstraw/traceframe",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Record scripted browser flows and render smooth cursor overlays into video.",
   "keywords": [
     "playwright",

package/src/capture.mjs

@@ -1,13 +1,16 @@
 import { addAbortListener } from 'node:events'
+import { writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { setTimeout as delay } from 'node:timers/promises'
 import { chromium } from 'playwright'
 
 import { TraceframeError } from './errors.mjs'
+import { addDiagnostics, retainedFile } from './diagnostics.mjs'
 import { createFlowApi } from './flow.mjs'
 
 const PLAYWRIGHT_DEFAULT_TIMEOUT = 30_000
 const FIRST_FRAME_TIMEOUT = 10_000
+const FAILURE_SCREENSHOT_TIMEOUT = 5_000
 
 export async function captureFlow({ config, flow, directory, signal: callerSignal }) {
   const signal = callerSignal ?? new AbortController().signal
@@ -17,6 +20,9 @@ export async function captureFlow({ config, flow, directory, signal: callerSigna
   signal.throwIfAborted()
   const browser = await launchBrowser(config, { handleSignals: !callerSignal })
   let page
+  let clock
+  let recording = false
+  let failed = false
   try {
     page = await browser.newPage({ viewport: config.viewport, deviceScaleFactor: config.scale, storageState: config.storageState })
     await raceAbort(waitForReady(page, flow, config, signal), signal)
@@ -24,28 +30,60 @@ export async function captureFlow({ config, flow, directory, signal: callerSigna
 
     const firstFrame = Promise.withResolvers()
     await startScreencast(page, rawPath, config, ({ timestamp }) => firstFrame.resolve(timestamp))
-    const clock = await withDeadline(
+    recording = true
+    clock = await withDeadline(
       () => firstFrame.promise,
       FIRST_FRAME_TIMEOUT,
       new TraceframeError(`No screencast frame arrived within ${FIRST_FRAME_TIMEOUT / 1000} seconds.`, { code: 'FIRST_FRAME_TIMEOUT' }),
       signal,
     )
-    await withDeadline(
-      (flowSignal) => flow.run({ page, signal: flowSignal, ...createFlowApi({ page, trace, clock, viewport: config.viewport, signal: flowSignal }) }),
-      config.flowTimeout * 1000,
-      new TraceframeError(`Flow exceeded the ${config.flowTimeout}-second flow timeout. Raise it with the flowTimeout option, or --flow-timeout.`, { code: 'FLOW_TOO_LONG' }),
-      signal,
-    )
+    try {
+      await withDeadline(
+        (flowSignal) => flow.run({ page, signal: flowSignal, ...createFlowApi({ page, trace, clock, viewport: config.viewport, signal: flowSignal }) }),
+        config.flowTimeout * 1000,
+        new TraceframeError(`Flow exceeded the ${config.flowTimeout}-second flow timeout. Raise it with the flowTimeout option, or --flow-timeout.`, { code: 'FLOW_TOO_LONG' }),
+        signal,
+      )
+    } catch (error) {
+      if (signal.aborted || error instanceof TraceframeError) throw error
+      throw new TraceframeError(error instanceof Error ? error.message : String(error), { code: 'FLOW_FAILED', cause: error })
+    }
     trace.end = (Date.now() - clock) / 1000
     await delay(config.postRoll * 1000, undefined, { signal })
+    // A failed stop must not be retried: Playwright may still be waiting to finish its artifact.
+    recording = false
     await page.screencast.stop()
     return { rawPath, trace }
   } catch (error) {
-    // Closing the browser alone discards the screencast. Stop it so a run directory keeps what was recorded.
-    await page?.screencast.stop().catch(() => {})
-    throw error
+    failed = true
+    const recordingTime = clock === undefined ? undefined : Math.max(0, (Date.now() - clock) / 1000)
+    // Let the encoder finish saving before closing the browser, including on slower machines.
+    const [capturePath, screenshotPath] = await Promise.all([
+      recording ? page.screencast.stop()
+        .then(() => config.runDirectory ? retainedFile(rawPath) : undefined)
+        .catch(() => undefined) : undefined,
+      config.runDirectory && page && !signal.aborted ? saveFailureScreenshot(page, directory, signal) : undefined,
+    ])
+    if (signal.aborted) throw error
+    throw await addDiagnostics(error, { flow: config.flow, recordingTime, capturePath, screenshotPath })
   } finally {
-    await browser.close()
+    // A shutdown error must not hide the flow failure.
+    if (failed) await browser.close().catch(() => {})
+    else await browser.close()
+  }
+}
+
+async function saveFailureScreenshot(page, directory, signal) {
+  try {
+    return await withDeadline(async (diagnosticSignal) => {
+      const screenshot = await page.screenshot({ timeout: FAILURE_SCREENSHOT_TIMEOUT })
+      diagnosticSignal.throwIfAborted()
+      const path = join(directory, 'failure.png')
+      await writeFile(path, screenshot, { signal: diagnosticSignal })
+      return path
+    }, FAILURE_SCREENSHOT_TIMEOUT, new Error('Failure screenshot timed out.'), signal)
+  } catch {
+    return undefined
   }
 }
 

package/src/cli.mjs

@@ -4,6 +4,7 @@ import { createRequire } from 'node:module'
 import { parseArgs } from 'node:util'
 
 import { LIMITS } from './flow.mjs'
+import { formatFailure } from './diagnostics.mjs'
 import { record } from './record.mjs'
 
 const { version: VERSION } = createRequire(import.meta.url)('../package.json')
@@ -44,7 +45,7 @@ Options:
   --post-roll <seconds>        Tail after the flow (default: 0.3)
   --ready-timeout <seconds>    Playwright default timeout during navigation and ready() (default: 30)
   --flow-timeout <seconds>     Time limit for the flow, including waits (default: 120)
-  --run-dir <path>             Keep the raw capture and FFmpeg filter in this directory
+  --run-dir <path>             Keep the raw capture, failure screenshot and FFmpeg filter
   -h, --help                   Show this help
   -v, --version                Show the version
 
@@ -74,7 +75,7 @@ try {
     process.stderr.write('traceframe: Recording was interrupted.\n')
     process.exitCode = SIGNAL_EXIT_CODES[interruptedBy]
   } else {
-    process.stderr.write(`traceframe: ${error instanceof Error ? error.message : String(error)}\n`)
+    process.stderr.write(formatFailure(error))
     process.exitCode = 1
   }
 }

package/src/diagnostics.mjs

@@ -0,0 +1,50 @@
+import { realpath, stat } from 'node:fs/promises'
+import { pathToFileURL } from 'node:url'
+
+import { TraceframeError } from './errors.mjs'
+
+// Only report the supplied flow's locations, never the rest of a stack or error object.
+export async function addDiagnostics(error, { flow, ...details }) {
+  if (!(error instanceof Error)) return error
+  try {
+    const paths = new Set([flow, await realpath(flow).catch(() => flow)])
+    const names = [...paths].flatMap((path) => [path, pathToFileURL(path).href])
+    const escaped = names.map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    const location = new RegExp(`^\\s+at (?:async )?(?:.+ \\()?(${escaped.join('|')}):(\\d+):(\\d+)\\)?$`)
+    const flowLocations = []
+    const seenErrors = new Set()
+    const seenLocations = new Set()
+    for (let current = error; current instanceof Error && !seenErrors.has(current); current = current.cause) {
+      seenErrors.add(current)
+      for (const frame of String(current.stack ?? '').split('\n')) {
+        const match = frame.match(location)
+        if (!match || seenLocations.has(`${match[2]}:${match[3]}`)) continue
+        seenLocations.add(`${match[2]}:${match[3]}`)
+        flowLocations.push({ file: flow, line: Number(match[2]), column: Number(match[3]) })
+      }
+    }
+    error.diagnostics = { flowLocations, ...Object.fromEntries(Object.entries(details).filter(([, value]) => value !== undefined)) }
+  } catch {
+    // A frozen error or an unavailable stack must not replace the original failure.
+  }
+  return error
+}
+
+export async function retainedFile(path) {
+  const info = await stat(path).catch(() => undefined)
+  return info?.isFile() && info.size > 0 ? path : undefined
+}
+
+export function formatFailure(error) {
+  const message = error instanceof Error ? error.message : String(error)
+  const code = error instanceof TraceframeError && error.code ? `[${error.code}] ` : ''
+  const lines = [`traceframe: ${code}${message.trimEnd()}`]
+  const diagnostics = error?.diagnostics
+  for (const { file, line, column } of diagnostics?.flowLocations ?? []) {
+    lines.push(`  Flow: ${file}:${line}:${column}`)
+  }
+  if (Number.isFinite(diagnostics?.recordingTime)) lines.push(`  Recording time: ${diagnostics.recordingTime.toFixed(2)} s`)
+  if (diagnostics?.capturePath) lines.push(`  Capture: ${diagnostics.capturePath}`)
+  if (diagnostics?.screenshotPath) lines.push(`  Screenshot: ${diagnostics.screenshotPath}`)
+  return `${lines.join('\n')}\n`
+}

package/src/record.mjs

@@ -4,6 +4,7 @@ import { dirname, join } from 'node:path'
 
 import { createConfig } from './config.mjs'
 import { captureFlow } from './capture.mjs'
+import { addDiagnostics, retainedFile } from './diagnostics.mjs'
 import { probeFfmpeg } from './ffmpeg.mjs'
 import { loadFlow } from './flow.mjs'
 import { renderVideo } from './render.mjs'
@@ -13,13 +14,18 @@ export async function record(options = {}) {
   signal?.throwIfAborted()
   const config = createConfig(options)
   const ffmpeg = await probeFfmpeg()
-  const flow = await loadFlow(config.flow, config.viewport)
+  const flow = await loadFlow(config.flow, config.viewport).catch(async (error) => {
+    throw await addDiagnostics(error, { flow: config.flow })
+  })
   await mkdir(dirname(config.output), { recursive: true })
   const directory = config.runDirectory ?? await mkdtemp(join(tmpdir(), 'traceframe-'))
   await mkdir(directory, { recursive: true })
 
+  let capture
+  let failed = false
   try {
-    const { rawPath, trace } = await captureFlow({ config, flow, directory, signal })
+    capture = await captureFlow({ config, flow, directory, signal })
+    const { rawPath, trace } = capture
     const duration = await renderVideo({ rawPath, trace, directory, config, ffmpeg, signal })
     return {
       output: config.output,
@@ -32,8 +38,17 @@ export async function record(options = {}) {
       runDirectory: config.runDirectory,
     }
   } catch (error) {
+    failed = true
+    if (signal?.aborted) throw signal.reason
+    if (capture && config.runDirectory) {
+      await addDiagnostics(error, { flow: config.flow, capturePath: await retainedFile(capture.rawPath) })
+    }
     throw signal?.aborted ? signal.reason : error
   } finally {
-    if (!config.runDirectory) await rm(directory, { recursive: true, force: true })
+    if (!config.runDirectory) {
+      const cleanup = rm(directory, { recursive: true, force: true })
+      if (failed) await cleanup.catch(() => {})
+      else await cleanup
+    }
   }
 }