@t3lnet/sceneforge 1.0.22 → 1.0.24

package/README.md

@@ -119,15 +119,13 @@ npx sceneforge split --demo my-demo --crf 15
 
 ## Viewport Settings (Recording)
 
-Control output video resolution and content zoom:
+Control output video resolution:
 
 ```bash
 --viewport <WxH|preset>      # Video resolution (default: 1440x900)
                              # Presets: 720p, 1080p, 1440p, 4k
 --width <px>                 # Video width
 --height <px>                # Video height
---zoom <percent>             # Content zoom: 100, 150, 200 (default: 100)
-                             # Makes UI elements appear larger
 ```
 
 **Examples:**
@@ -136,13 +134,10 @@ Control output video resolution and content zoom:
 # Record at 1080p
 npx sceneforge record --definition demo.yaml --base-url http://localhost:5173 --viewport 1080p
 
-# Record at 1080p with zoomed content (UI appears 1.5x larger)
-npx sceneforge record --definition demo.yaml --base-url http://localhost:5173 \
-  --viewport 1080p --zoom 150
+# Record at 4K
+npx sceneforge record --definition demo.yaml --base-url http://localhost:5173 --viewport 4k
 ```
 
-**How zoom works:** `--viewport 1080p --zoom 150` records a 1920x1080 video where content appears 1.5x larger (browser viewport is actually 1280x720, scaled up to 1080p).
-
 ## Output Dimensions (Video Processing)
 
 Control final video resolution with support for different platforms and aspect ratios:
@@ -179,7 +174,7 @@ npx sceneforge concat --demo my-demo --output-size square
 
 # Full pipeline with all video options
 npx sceneforge pipeline --demo my-demo --base-url http://localhost:5173 \
-  --viewport 1080p --zoom 150 \
+  --viewport 1080p \
   --output-size 1080p \
   --quality high
 ```

package/cli/commands/add-audio-to-steps.js

@@ -5,10 +5,7 @@ import { getFlagValue, hasFlag } from "../utils/args.js";
 import { getOutputPaths, resolveRoot, readJson } from "../utils/paths.js";
 import { sanitizeFileSegment } from "../utils/sanitize.js";
 import {
-  getVideoEncodingArgs,
-  parseQualityArgs,
-  getQualityHelpText,
-  logQualitySettings,
+  getIntermediateEncodingArgs,
 } from "../utils/quality.js";
 import {
   parseOutputDimensions,
@@ -21,6 +18,9 @@ function printHelp() {
   console.log(`
 Add audio to individual video step clips
 
+Uses lossless encoding for intermediate files to preserve quality.
+Final compression is applied only at the concat step.
+
 Usage:
   sceneforge add-audio [options]
 
@@ -31,7 +31,6 @@ Options:
   --root <path>         Project root (defaults to cwd)
   --output-dir <path>   Output directory (defaults to e2e/output or output)
   --help, -h            Show this help message
-${getQualityHelpText()}
 ${getOutputDimensionsHelpText()}
 
 Output:
@@ -39,9 +38,8 @@ Output:
 
 Examples:
   sceneforge add-audio --demo create-quote
-  sceneforge add-audio --demo create-quote --quality high
   sceneforge add-audio --demo create-quote --output-size 1080p
-  sceneforge add-audio --all --codec libx265
+  sceneforge add-audio --all
 `);
 }
 
@@ -55,11 +53,12 @@ function buildScaleFilter(outputDimensions) {
   return `scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2:black`;
 }
 
-async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVideoPath, qualityOptions = {}, outputDimensions = null) {
+async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVideoPath, outputDimensions = null) {
   const videoDuration = await getMediaDuration(videoPath);
   const audioDuration = await getMediaDuration(audioPath);
   const targetDuration = audioDuration + padding;
-  const encodingArgs = getVideoEncodingArgs(qualityOptions);
+  // Use lossless encoding for intermediate files to prevent generation loss
+  const encodingArgs = getIntermediateEncodingArgs({ includeAudio: true });
   const scaleFilter = buildScaleFilter(outputDimensions);
 
   if (targetDuration <= videoDuration) {
@@ -142,9 +141,9 @@ async function addAudioToStep(videoPath, audioPath, outputPath, padding, nextVid
   ]);
 }
 
-async function processDemo(demoName, paths, padding, qualityOptions = {}, outputDimensions = null) {
-  console.log(`\n[audio] Processing: ${demoName}\n`);
-  logQualitySettings(qualityOptions, "[audio]");
+async function processDemo(demoName, paths, padding, outputDimensions = null) {
+  console.log(`\n[audio] Processing: ${demoName}`);
+  console.log("[audio] Using lossless encoding for intermediate files");
   logOutputDimensions(outputDimensions, "[audio]");
 
   const stepsManifestPath = path.join(paths.videosDir, demoName, "steps-manifest.json");
@@ -231,7 +230,7 @@ async function processDemo(demoName, paths, padding, qualityOptions = {}, output
     );
 
     try {
-      await addAudioToStep(step.videoFile, audioSegment.audioFile, outputPath, padding, nextVideoPath, qualityOptions, outputDimensions);
+      await addAudioToStep(step.videoFile, audioSegment.audioFile, outputPath, padding, nextVideoPath, outputDimensions);
       outputFiles.push(outputPath);
     } catch (error) {
       console.error(`[audio]   ${paddedIndex}. ${step.stepId}: ✗ Failed to process`);
@@ -264,7 +263,7 @@ async function processDemo(demoName, paths, padding, qualityOptions = {}, output
   console.log(`[audio]   Output: ${path.join(paths.videosDir, demoName)}`);
 }
 
-async function processAll(paths, padding, qualityOptions = {}, outputDimensions = null) {
+async function processAll(paths, padding, outputDimensions = null) {
   console.log("\n[audio] Processing all demos...\n");
 
   try {
@@ -295,7 +294,7 @@ async function processAll(paths, padding, qualityOptions = {}, outputDimensions
     console.log(`[audio] Found ${demosToProcess.length} demo(s) to process\n`);
 
     for (const demo of demosToProcess) {
-      await processDemo(demo, paths, padding, qualityOptions, outputDimensions);
+      await processDemo(demo, paths, padding, outputDimensions);
     }
 
     await fs.rm(paths.tempDir, { recursive: true, force: true });
@@ -328,17 +327,16 @@ export async function runAddAudioCommand(argv) {
 
   const rootDir = resolveRoot(root);
   const paths = await getOutputPaths(rootDir, outputDir);
-  const qualityOptions = parseQualityArgs(args, getFlagValue, hasFlag);
   const outputDimensions = parseOutputDimensions(args, getFlagValue);
 
   if (demo) {
-    await processDemo(demo, paths, padding, qualityOptions, outputDimensions);
+    await processDemo(demo, paths, padding, outputDimensions);
     await fs.rm(paths.tempDir, { recursive: true, force: true });
     return;
   }
 
   if (all) {
-    await processAll(paths, padding, qualityOptions, outputDimensions);
+    await processAll(paths, padding, outputDimensions);
     return;
   }
 

package/cli/commands/pipeline.js

@@ -5,6 +5,7 @@ import { getFlagValue, hasFlag } from "../utils/args.js";
 import { ensureDir, getOutputPaths, resolveRoot, toAbsolute } from "../utils/paths.js";
 import { getQualityHelpText } from "../utils/quality.js";
 import { getViewportHelpText, getOutputDimensionsHelpText } from "../utils/dimensions.js";
+import { getCDPRecordingHelpText } from "../utils/cdp-recorder.js";
 import { runRecordDemoCommand } from "./record-demo.js";
 import { runSplitVideoCommand } from "./split-video.js";
 import { runGenerateVoiceoverCommand } from "./generate-voiceover.js";
@@ -45,6 +46,7 @@ Media options (for final video):
 ${getQualityHelpText()}
 ${getViewportHelpText()}
 ${getOutputDimensionsHelpText()}
+${getCDPRecordingHelpText()}
 
   --help, -h             Show this help message
 
@@ -207,8 +209,6 @@ export async function runPipelineCommand(argv) {
   const viewport = getFlagValue(args, "--viewport");
   const viewportWidth = getFlagValue(args, "--width");
   const viewportHeight = getFlagValue(args, "--height");
-  const zoom = getFlagValue(args, "--zoom");
-  const deviceScaleFactor = getFlagValue(args, "--device-scale-factor");
 
   // Output dimension options (for video processing)
   const outputSize = getFlagValue(args, "--output-size");
@@ -261,13 +261,11 @@ export async function runPipelineCommand(argv) {
       if (crf) console.log(`  - CRF: ${crf}`);
       if (codec) console.log(`  - Codec: ${codec}`);
     }
-    if (viewport || viewportWidth || viewportHeight || zoom || deviceScaleFactor) {
+    if (viewport || viewportWidth || viewportHeight) {
       console.log("\nViewport options:");
       if (viewport) console.log(`  - Viewport: ${viewport}`);
       if (viewportWidth) console.log(`  - Width: ${viewportWidth}`);
       if (viewportHeight) console.log(`  - Height: ${viewportHeight}`);
-      if (zoom) console.log(`  - Zoom: ${zoom}%`);
-      if (deviceScaleFactor) console.log(`  - Device scale factor: ${deviceScaleFactor}`);
     }
     if (outputSize || outputWidth || outputHeight) {
       console.log("\nOutput dimension options:");
@@ -334,8 +332,9 @@ export async function runPipelineCommand(argv) {
     outputDimensionArgs.push("--output-height", outputHeight);
   }
 
+  // Split and add-audio use lossless encoding for intermediates (no quality args needed)
   await runStep("split", plan.split, () =>
-    runSplitVideoCommand(["--demo", demoName, ...sharedArgs, ...qualityArgs, ...outputDimensionArgs])
+    runSplitVideoCommand(["--demo", demoName, ...sharedArgs, ...outputDimensionArgs])
   );
 
   const voiceArgs = ["--demo", demoName, ...sharedArgs];
@@ -347,13 +346,14 @@ export async function runPipelineCommand(argv) {
   }
   await runStep("voiceover", plan.voiceover, () => runGenerateVoiceoverCommand(voiceArgs));
 
-  const audioArgs = ["--demo", demoName, ...sharedArgs, ...qualityArgs, ...outputDimensionArgs];
+  // Add-audio uses lossless encoding for intermediates (no quality args needed)
+  const audioArgs = ["--demo", demoName, ...sharedArgs, ...outputDimensionArgs];
   if (padding) {
     audioArgs.push("--padding", padding);
   }
   await runStep("add-audio", plan.addAudio, () => runAddAudioCommand(audioArgs));
 
-  // Build concat args with media options and quality settings
+  // Concat applies final compression - quality args are used here
   const concatArgs = ["--demo", demoName, ...sharedArgs, ...qualityArgs, ...outputDimensionArgs];
   if (intro) {
     concatArgs.push("--intro", intro);

package/cli/commands/record-demo.js

@@ -17,9 +17,9 @@ import {
 import { getMediaDuration } from "../utils/media.js";
 import {
   parseViewportArgs,
-  parseDeviceScaleFactor,
   getViewportHelpText,
 } from "../utils/dimensions.js";
+import { createCDPRecorder, getCDPRecordingHelpText } from "../utils/cdp-recorder.js";
 
 function printHelp() {
   console.log(`
@@ -45,11 +45,12 @@ Options:
   --no-video              Skip video recording
   --help, -h              Show this help message
 ${getViewportHelpText()}
+${getCDPRecordingHelpText()}
 
 Examples:
   sceneforge record --definition demo-definitions/create-quote.yaml --base-url http://localhost:5173
   sceneforge record --demo create-quote --definitions-dir examples --base-url http://localhost:5173
-  sceneforge record --demo create-quote --base-url http://localhost:5173 --viewport 1920x1080 --zoom 150
+  sceneforge record --demo create-quote --base-url http://localhost:5173 --viewport 1920x1080
 `);
 }
 
@@ -178,6 +179,9 @@ export async function runRecordDemoCommand(argv) {
   const headed = hasFlag(args, "--headed");
   const slowMo = getFlagValue(args, "--slowmo");
   const noVideo = hasFlag(args, "--no-video");
+  const hqVideo = hasFlag(args, "--hq-video");
+  const hqFormat = getFlagValue(args, "--hq-format") ?? "jpeg";
+  const hqQuality = parseInt(getFlagValue(args, "--hq-quality") ?? "100", 10);
 
   if (!baseUrl) {
     console.error("[error] --base-url is required");
@@ -213,24 +217,12 @@ export async function runRecordDemoCommand(argv) {
   await ensureDir(outputPaths.videosDir);
 
   const viewport = parseViewportArgs(args, getFlagValue);
-  const zoomFactor = parseDeviceScaleFactor(args, getFlagValue);
-
-  // To achieve "zoom", we use CSS zoom to make content appear larger.
-  // The viewport stays at the requested size, and we inject CSS zoom after page load.
-  // Example: --viewport 4k --zoom 200 means:
-  //   - Viewport is 3840x2160 (4K)
-  //   - CSS zoom: 2 makes content appear 2x larger
-  //   - User sees the equivalent of 1920x1080 content filling the 4K frame
-
-  // Log what's happening
-  if (zoomFactor !== 1) {
-    console.log(`[record] Viewport: ${viewport.width}x${viewport.height} with ${Math.round(zoomFactor * 100)}% CSS zoom`);
-  } else {
-    console.log(`[record] Viewport: ${viewport.width}x${viewport.height}`);
-  }
+
+  console.log(`[record] Viewport: ${viewport.width}x${viewport.height}`);
 
   const recordDir = path.join(outputPaths.videosDir, ".recordings", definition.name);
-  if (!noVideo) {
+  const framesDir = path.join(outputPaths.videosDir, ".frames", definition.name);
+  if (!noVideo && !hqVideo) {
     await ensureDir(recordDir);
   }
 
@@ -239,9 +231,12 @@ export async function runRecordDemoCommand(argv) {
     slowMo: slowMo ? Number(slowMo) : undefined,
   });
 
+  // When using HQ video, don't use Playwright's built-in recording
+  const usePlaywrightRecording = !noVideo && !hqVideo;
+
   const context = await browser.newContext({
     viewport,
-    recordVideo: noVideo ? undefined : { dir: recordDir, size: viewport },
+    recordVideo: usePlaywrightRecording ? { dir: recordDir, size: viewport } : undefined,
     storageState: storageState ? toAbsolute(rootDir, storageState) : undefined,
     locale: locale || undefined,
     extraHTTPHeaders: locale
@@ -252,32 +247,25 @@ export async function runRecordDemoCommand(argv) {
   });
 
   const page = await context.newPage();
+  const video = usePlaywrightRecording ? page.video() : null;
+  const videoRecordingStartTime = Date.now();
 
-  // Apply CSS zoom if requested (must be done before navigation to affect all content)
-  if (zoomFactor !== 1) {
-    await page.addInitScript((zoom) => {
-      document.addEventListener('DOMContentLoaded', () => {
-        document.documentElement.style.zoom = String(zoom);
-      });
-      // Also set immediately in case DOMContentLoaded already fired
-      if (document.documentElement) {
-        document.documentElement.style.zoom = String(zoom);
-      }
-    }, zoomFactor);
+  // Set up CDP recorder for high-quality video
+  let cdpRecorder = null;
+  if (hqVideo && !noVideo) {
+    cdpRecorder = createCDPRecorder(page, {
+      framesDir,
+      format: hqFormat,
+      quality: hqQuality,
+      maxWidth: viewport.width,
+      maxHeight: viewport.height,
+    });
+    await cdpRecorder.start();
   }
-
-  const video = page.video();
-  const videoRecordingStartTime = Date.now();
   const startUrl = resolveStartUrl(startPath, baseUrl);
 
   if (startUrl) {
     await page.goto(startUrl, { waitUntil: "networkidle" });
-    // Ensure zoom is applied after navigation
-    if (zoomFactor !== 1) {
-      await page.evaluate((zoom) => {
-        document.documentElement.style.zoom = String(zoom);
-      }, zoomFactor);
-    }
   }
   const result = await runDemo(
     definition,
@@ -294,10 +282,28 @@ export async function runRecordDemoCommand(argv) {
     }
   );
 
+  // Stop CDP recorder before closing context (if using HQ video)
+  if (cdpRecorder) {
+    await cdpRecorder.stop();
+  }
+
   await context.close();
   await browser.close();
 
-  if (video) {
+  // Handle video based on recording method
+  if (cdpRecorder) {
+    // Assemble CDP frames into video
+    const finalVideoPath = path.join(outputPaths.videosDir, `${definition.name}.webm`);
+    try {
+      await cdpRecorder.assembleVideo(finalVideoPath);
+      console.log(`[record] High-quality video saved: ${finalVideoPath}`);
+      if (result.scriptPath) {
+        await alignScriptToVideo(result.scriptPath, finalVideoPath, videoRecordingStartTime);
+      }
+    } finally {
+      await cdpRecorder.cleanup();
+    }
+  } else if (video) {
     const recordedPath = await video.path();
     const finalVideoPath = path.join(outputPaths.videosDir, `${definition.name}.webm`);
     await moveVideo(recordedPath, finalVideoPath);

package/cli/commands/split-video.js

@@ -5,10 +5,7 @@ import { getOutputPaths, readJson, resolveRoot } from "../utils/paths.js";
 import { getFlagValue, hasFlag } from "../utils/args.js";
 import { sanitizeFileSegment } from "../utils/sanitize.js";
 import {
-  getVideoEncodingArgs,
-  parseQualityArgs,
-  getQualityHelpText,
-  logQualitySettings,
+  getIntermediateEncodingArgs,
 } from "../utils/quality.js";
 import {
   parseOutputDimensions,
@@ -21,6 +18,9 @@ function printHelp() {
   console.log(`
 Split recorded demo video into per-step clips
 
+Uses lossless encoding for intermediate files to preserve quality.
+Final compression is applied only at the concat step.
+
 Usage:
   sceneforge split [options]
 
@@ -30,13 +30,10 @@ Options:
   --root <path>         Project root (defaults to cwd)
   --output-dir <path>   Output directory (defaults to e2e/output or output)
   --help, -h            Show this help message
-${getQualityHelpText()}
 ${getOutputDimensionsHelpText()}
 
 Examples:
   sceneforge split --demo create-quote
-  sceneforge split --demo create-quote --quality high
-  sceneforge split --demo create-quote --crf 15 --codec libx265
   sceneforge split --demo create-quote --output-size 1080p
   sceneforge split --all
 `);
@@ -71,9 +68,9 @@ async function findVideoFile(demoName, videosDir, testResultsDir) {
   return null;
 }
 
-async function splitDemo(demoName, paths, qualityOptions = {}, outputDimensions = null) {
-  console.log(`\n[split] Processing: ${demoName}\n`);
-  logQualitySettings(qualityOptions, "[split]");
+async function splitDemo(demoName, paths, outputDimensions = null) {
+  console.log(`\n[split] Processing: ${demoName}`);
+  console.log("[split] Using lossless encoding for intermediate files");
   logOutputDimensions(outputDimensions, "[split]");
 
   const scriptPath = path.join(paths.scriptsDir, `${demoName}.json`);
@@ -135,7 +132,8 @@ async function splitDemo(demoName, paths, qualityOptions = {}, outputDimensions
     );
 
     try {
-      const encodingArgs = getVideoEncodingArgs({ ...qualityOptions, includeAudio: false });
+      // Use lossless encoding for intermediate files to prevent generation loss
+      const encodingArgs = getIntermediateEncodingArgs({ includeAudio: false });
       const scaleArgs = getScaleFilterArgs(outputDimensions);
       await runFFmpeg([
         "-y",
@@ -192,7 +190,7 @@ async function splitDemo(demoName, paths, qualityOptions = {}, outputDimensions
   console.log(`[split]   Manifest: ${manifestPath}`);
 }
 
-async function splitAll(paths, qualityOptions = {}, outputDimensions = null) {
+async function splitAll(paths, outputDimensions = null) {
   console.log("\n[split] Processing all demos...\n");
 
   try {
@@ -210,7 +208,7 @@ async function splitAll(paths, qualityOptions = {}, outputDimensions = null) {
 
     for (const file of scriptFiles) {
       const demoName = path.basename(file, ".json");
-      await splitDemo(demoName, paths, qualityOptions, outputDimensions);
+      await splitDemo(demoName, paths, outputDimensions);
     }
 
     console.log("\n[split] All demos processed!");
@@ -240,16 +238,15 @@ export async function runSplitVideoCommand(argv) {
 
   const rootDir = resolveRoot(root);
   const paths = await getOutputPaths(rootDir, outputDir);
-  const qualityOptions = parseQualityArgs(args, getFlagValue, hasFlag);
   const outputDimensions = parseOutputDimensions(args, getFlagValue);
 
   if (demo) {
-    await splitDemo(demo, paths, qualityOptions, outputDimensions);
+    await splitDemo(demo, paths, outputDimensions);
     return;
   }
 
   if (all) {
-    await splitAll(paths, qualityOptions, outputDimensions);
+    await splitAll(paths, outputDimensions);
     return;
   }
 

package/cli/utils/cdp-recorder.js

@@ -0,0 +1,236 @@
+/**
+ * CDP-based high-quality screen recorder
+ *
+ * Uses Chrome DevTools Protocol screencast API to capture high-quality frames,
+ * then assembles them into a video using FFmpeg. This bypasses Playwright's
+ * hardcoded low-quality video settings.
+ *
+ * Benefits over Playwright's built-in recording:
+ * - Configurable quality (PNG lossless or high-quality JPEG)
+ * - No 1Mbps bitrate cap
+ * - Better compression settings via FFmpeg
+ */
+
+import * as fs from "fs/promises";
+import * as path from "path";
+import { runFFmpeg } from "./media.js";
+import { getIntermediateEncodingArgs } from "./quality.js";
+
+/**
+ * @typedef {Object} CDPRecorderOptions
+ * @property {string} framesDir - Directory to store captured frames
+ * @property {number} [quality=100] - JPEG quality (1-100), 100 = best quality
+ * @property {string} [format='jpeg'] - Frame format: 'jpeg' or 'png'
+ * @property {number} [maxWidth] - Max frame width (undefined = viewport width)
+ * @property {number} [maxHeight] - Max frame height (undefined = viewport height)
+ * @property {number} [everyNthFrame=1] - Capture every Nth frame (1 = all frames)
+ */
+
+/**
+ * @typedef {Object} CDPRecorder
+ * @property {Function} start - Start recording
+ * @property {Function} stop - Stop recording and return frame info
+ * @property {Function} assembleVideo - Assemble frames into video
+ */
+
+/**
+ * Create a CDP-based screen recorder for a Playwright page
+ *
+ * @param {import('@playwright/test').Page} page - Playwright page
+ * @param {CDPRecorderOptions} options - Recorder options
+ * @returns {CDPRecorder}
+ */
+export function createCDPRecorder(page, options) {
+  const {
+    framesDir,
+    quality = 100,
+    format = "jpeg",
+    maxWidth,
+    maxHeight,
+    everyNthFrame = 1,
+  } = options;
+
+  let cdpSession = null;
+  let frameCount = 0;
+  let frameTimestamps = [];
+  let isRecording = false;
+  let startTime = null;
+
+  const frameHandler = async (params) => {
+    if (!isRecording) return;
+
+    const { data, metadata, sessionId } = params;
+    frameCount += 1;
+
+    // Acknowledge the frame to continue receiving
+    try {
+      await cdpSession.send("Page.screencastFrameAck", { sessionId });
+    } catch {
+      // Session may be closed
+    }
+
+    // Skip frames based on everyNthFrame setting
+    if (everyNthFrame > 1 && frameCount % everyNthFrame !== 0) {
+      return;
+    }
+
+    const timestamp = metadata.timestamp;
+    const frameNumber = frameTimestamps.length;
+    const paddedNumber = String(frameNumber).padStart(8, "0");
+    const extension = format === "png" ? "png" : "jpg";
+    const framePath = path.join(framesDir, `frame_${paddedNumber}.${extension}`);
+
+    // Decode base64 and save frame
+    const buffer = Buffer.from(data, "base64");
+    await fs.writeFile(framePath, buffer);
+
+    frameTimestamps.push({
+      frameNumber,
+      timestamp,
+      path: framePath,
+    });
+  };
+
+  return {
+    /**
+     * Start recording frames via CDP screencast
+     */
+    async start() {
+      await fs.mkdir(framesDir, { recursive: true });
+
+      // Create CDP session for the page
+      cdpSession = await page.context().newCDPSession(page);
+
+      // Set up frame handler
+      cdpSession.on("Page.screencastFrame", frameHandler);
+
+      // Start screencast with high quality settings
+      // format: 'jpeg' or 'png'
+      // quality: 0-100 for jpeg (100 = best), ignored for png
+      // maxWidth/maxHeight: optional frame dimensions
+      // everyNthFrame: capture frequency (1 = every frame)
+      await cdpSession.send("Page.startScreencast", {
+        format,
+        quality,
+        maxWidth,
+        maxHeight,
+        everyNthFrame,
+      });
+
+      isRecording = true;
+      startTime = Date.now();
+      frameCount = 0;
+      frameTimestamps = [];
+
+      console.log("[cdp-recorder] Started high-quality screen capture");
+    },
+
+    /**
+     * Stop recording and return frame information
+     * @returns {Promise<{frameCount: number, duration: number, framesDir: string}>}
+     */
+    async stop() {
+      if (!isRecording || !cdpSession) {
+        return { frameCount: 0, duration: 0, framesDir };
+      }
+
+      isRecording = false;
+      const duration = Date.now() - startTime;
+
+      try {
+        await cdpSession.send("Page.stopScreencast");
+        cdpSession.off("Page.screencastFrame", frameHandler);
+        await cdpSession.detach();
+      } catch {
+        // Session may already be closed
+      }
+
+      console.log(
+        `[cdp-recorder] Captured ${frameTimestamps.length} frames in ${(duration / 1000).toFixed(2)}s`
+      );
+
+      return {
+        frameCount: frameTimestamps.length,
+        duration,
+        framesDir,
+        frameTimestamps,
+      };
+    },
+
+    /**
+     * Assemble captured frames into a video using FFmpeg
+     *
+     * @param {string} outputPath - Output video path
+     * @param {Object} [assembleOptions] - Assembly options
+     * @param {number} [assembleOptions.fps] - Output framerate (auto-detected if not specified)
+     * @returns {Promise<string>} - Path to assembled video
+     */
+    async assembleVideo(outputPath, assembleOptions = {}) {
+      const { fps: fpsOverride } = assembleOptions;
+
+      if (frameTimestamps.length === 0) {
+        throw new Error("No frames captured - cannot assemble video");
+      }
+
+      // Calculate actual FPS from captured frame timestamps
+      let fps = fpsOverride;
+      if (!fps && frameTimestamps.length > 1) {
+        const firstTimestamp = frameTimestamps[0].timestamp;
+        const lastTimestamp = frameTimestamps[frameTimestamps.length - 1].timestamp;
+        const durationSec = lastTimestamp - firstTimestamp;
+        if (durationSec > 0) {
+          fps = Math.round(frameTimestamps.length / durationSec);
+        }
+      }
+      fps = fps || 30; // Default to 30fps
+
+      console.log(`[cdp-recorder] Assembling video at ${fps} fps`);
+
+      const extension = format === "png" ? "png" : "jpg";
+      const framePattern = path.join(framesDir, `frame_%08d.${extension}`);
+
+      // Use lossless encoding for the assembled video (will be compressed at concat step)
+      const encodingArgs = getIntermediateEncodingArgs({ includeAudio: false });
+
+      await runFFmpeg([
+        "-y",
+        "-framerate",
+        String(fps),
+        "-i",
+        framePattern,
+        ...encodingArgs,
+        "-pix_fmt",
+        "yuv420p", // Ensure compatibility
+        outputPath,
+      ]);
+
+      console.log(`[cdp-recorder] Video assembled: ${outputPath}`);
+
+      return outputPath;
+    },
+
+    /**
+     * Clean up frame files
+     */
+    async cleanup() {
+      try {
+        await fs.rm(framesDir, { recursive: true, force: true });
+      } catch {
+        // Ignore cleanup errors
+      }
+    },
+  };
+}
+
+/**
+ * Get help text for CDP recording options
+ * @returns {string}
+ */
+export function getCDPRecordingHelpText() {
+  return `
+High-Quality Recording Options:
+  --hq-video              Use CDP-based high-quality recording instead of Playwright
+                          Captures frames at maximum quality and assembles with FFmpeg
+  --hq-format <format>    Frame format: jpeg (default) or png (lossless, larger files)
+  --hq-quality <1-100>    JPEG quality (default: 100, ignored for PNG)`;
+}

package/cli/utils/dimensions.js

@@ -3,7 +3,6 @@
  *
  * Browser Viewport:
  * - Controls the browser window size during recording
- * - Supports device scale factor (zoom) for high-DPI capture
  *
  * Output Dimensions:
  * - Controls the final video resolution after processing
@@ -35,7 +34,6 @@ export const OUTPUT_PRESETS = {
 };
 
 export const DEFAULT_VIEWPORT = { width: 1440, height: 900 };
-export const DEFAULT_DEVICE_SCALE_FACTOR = 1;
 
 /**
  * Parse a dimension string like "1920x1080" or a preset name like "1080p"
@@ -85,35 +83,6 @@ export function parseViewportArgs(args, getFlagValue) {
   return parseDimensions(viewportValue, VIEWPORT_PRESETS, DEFAULT_VIEWPORT);
 }
 
-/**
- * Parse device scale factor (zoom) from CLI arguments
- * @param {string[]} args - CLI arguments
- * @param {Function} getFlagValue - Function to get flag values
- * @returns {number} Device scale factor (1 = 100%, 1.5 = 150%, 2 = 200%)
- */
-export function parseDeviceScaleFactor(args, getFlagValue) {
-  const zoomValue = getFlagValue(args, "--zoom");
-  const scaleValue = getFlagValue(args, "--device-scale-factor");
-
-  // --zoom takes a percentage (100, 150, 200)
-  if (zoomValue !== null && zoomValue !== undefined) {
-    const zoom = Number(zoomValue);
-    if (Number.isFinite(zoom) && zoom > 0) {
-      return zoom / 100; // Convert percentage to scale factor
-    }
-  }
-
-  // --device-scale-factor takes the actual scale (1, 1.5, 2)
-  if (scaleValue !== null && scaleValue !== undefined) {
-    const scale = Number(scaleValue);
-    if (Number.isFinite(scale) && scale > 0) {
-      return scale;
-    }
-  }
-
-  return DEFAULT_DEVICE_SCALE_FACTOR;
-}
-
 /**
  * Parse output dimensions from CLI arguments
  * @param {string[]} args - CLI arguments
@@ -192,11 +161,7 @@ Viewport Options (Recording):
                            Presets: 720p, 1080p, 1440p, 4k
                            Example: --viewport 1920x1080 or --viewport 1080p
   --width <px>             Video width (overrides --viewport)
-  --height <px>            Video height (overrides --viewport)
-  --zoom <percent>         Content zoom level: 100, 150, 200 (default: 100)
-                           Makes UI elements appear larger in the video
-                           Example: --viewport 1080p --zoom 150 records at
-                           1920x1080 with content appearing 1.5x larger`;
+  --height <px>            Video height (overrides --viewport)`;
 }
 
 /**
@@ -217,28 +182,6 @@ Output Dimensions:
                               If not specified, keeps original recording dimensions`;
 }
 
-/**
- * Log viewport settings being used
- * @param {Object} viewport - { width, height }
- * @param {number} deviceScaleFactor - Scale factor
- * @param {string} prefix - Log prefix
- */
-export function logViewportSettings(viewport, deviceScaleFactor, prefix = "") {
-  const zoomPercent = Math.round(deviceScaleFactor * 100);
-  console.log(
-    `${prefix} Viewport: ${viewport.width}x${viewport.height} @ ${zoomPercent}% zoom`
-  );
-  if (deviceScaleFactor !== 1) {
-    const effectiveRes = {
-      width: Math.round(viewport.width * deviceScaleFactor),
-      height: Math.round(viewport.height * deviceScaleFactor),
-    };
-    console.log(
-      `${prefix} Effective capture resolution: ${effectiveRes.width}x${effectiveRes.height}`
-    );
-  }
-}
-
 /**
  * Log output dimension settings
  * @param {Object|null} dimensions - { width, height } or null

package/cli/utils/quality.js

@@ -47,6 +47,12 @@ export const DEFAULT_QUALITY = "medium";
 export const DEFAULT_AUDIO_CODEC = "aac";
 export const DEFAULT_AUDIO_BITRATE = "192k";
 
+// Lossless encoding for intermediate files to prevent generation loss
+// CRF 0 = mathematically lossless for x264/x265
+// Using "ultrafast" preset since these are temporary files and encoding speed matters
+export const INTERMEDIATE_CRF = 0;
+export const INTERMEDIATE_PRESET = "ultrafast";
+
 /**
  * Get video encoding arguments for FFmpeg
  * @param {Object} options
@@ -78,6 +84,36 @@ export function getVideoEncodingArgs(options = {}) {
   return args;
 }
 
+/**
+ * Get lossless encoding arguments for intermediate files.
+ * Uses CRF 0 (lossless) to prevent generation loss during multi-step processing.
+ * Final compression should be applied only at the last step (concat).
+ *
+ * @param {Object} options
+ * @param {string} [options.codec] - Video codec: libx264, libx265 (default: libx264)
+ * @param {boolean} [options.includeAudio] - Include audio encoding args
+ * @returns {string[]} FFmpeg arguments for lossless intermediate encoding
+ */
+export function getIntermediateEncodingArgs(options = {}) {
+  const {
+    codec = DEFAULT_CODEC,
+    includeAudio = true,
+  } = options;
+
+  const args = [
+    "-c:v", codec,
+    "-preset", INTERMEDIATE_PRESET,
+    "-crf", String(INTERMEDIATE_CRF),
+  ];
+
+  if (includeAudio) {
+    // Use high-quality audio for intermediates too
+    args.push("-c:a", DEFAULT_AUDIO_CODEC, "-b:a", DEFAULT_AUDIO_BITRATE);
+  }
+
+  return args;
+}
+
 /**
  * Parse quality-related CLI arguments
  * @param {string[]} args - CLI arguments

package/context/templates/base/cli-reference.md

@@ -28,7 +28,9 @@ sceneforge record --definition <path> [options]
 | `--viewport` | Target video resolution (preset or WxH, default: 1440x900) |
 | `--width` | Video width (overrides --viewport) |
 | `--height` | Video height (overrides --viewport) |
-| `--zoom` | Content zoom level: 100, 150, 200 (default: 100) - makes UI larger |
+| `--hq-video` | Use CDP-based high-quality recording |
+| `--hq-format` | Frame format: jpeg (default) or png (lossless) |
+| `--hq-quality` | JPEG quality 1-100 (default: 100) |
 
 **Viewport Presets:** 720p (1280x720), 1080p (1920x1080), 1440p (2560x1440), 4k (3840x2160)
 
@@ -46,8 +48,14 @@ sceneforge record -d demo.yaml -b http://localhost:3000 --storage ./auth.json
 # Record at 1080p resolution
 sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1080p
 
-# Record at 1080p with zoomed content (UI appears 1.5x larger)
-sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1080p --zoom 150
+# Record at 4K resolution
+sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 4k
+
+# High-quality CDP recording (bypasses Playwright's bitrate limits)
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video
+
+# HQ recording with lossless PNG frames
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video --hq-format png
 ```
 
 ### setup
@@ -94,10 +102,12 @@ sceneforge pipeline --definition <path> [options]
 | `--crf` | Override CRF value |
 | `--codec` | Video codec: libx264, libx265 |
 | `--viewport` | Target video resolution (preset or WxH) |
-| `--zoom` | Content zoom level: 100, 150, 200 (makes UI larger) |
 | `--output-size` | Final output dimensions (preset or WxH) |
 | `--output-width` | Output width (-1 for auto) |
 | `--output-height` | Output height (-1 for auto) |
+| `--hq-video` | Use CDP-based high-quality recording |
+| `--hq-format` | Frame format: jpeg (default) or png |
+| `--hq-quality` | JPEG quality 1-100 (default: 100) |
 
 **Examples:**
 ```bash
@@ -116,9 +126,9 @@ sceneforge pipeline -d demo.yaml -b http://localhost:3000 --quality high --outpu
 # TikTok/YouTube Shorts format
 sceneforge pipeline -d demo.yaml -b http://localhost:3000 --output-size tiktok --quality high
 
-# Full options: viewport + zoom + output scaling
+# Full options: viewport + output scaling
 sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
-  --viewport 1080p --zoom 150 \
+  --viewport 1080p \
   --output-size 1080p \
   --quality high
 ```
@@ -364,7 +374,7 @@ sceneforge split --demo my-demo --crf 15
 
 ## Viewport Settings
 
-Control output video resolution and content zoom during recording.
+Control output video resolution during recording.
 
 ### CLI Flags (record, pipeline)
 
@@ -372,7 +382,6 @@ Control output video resolution and content zoom during recording.
 --viewport <WxH|preset>      # Target video resolution (default: 1440x900)
 --width <px>                 # Video width (overrides --viewport)
 --height <px>                # Video height (overrides --viewport)
---zoom <percent>             # Content zoom: 100, 150, 200 (default: 100)
 ```
 
 ### Viewport Presets
@@ -384,16 +393,6 @@ Control output video resolution and content zoom during recording.
 | `1440p` | 2560x1440 |
 | `4k` | 3840x2160 |
 
-### How Zoom Works
-
-- `--viewport` sets the output video resolution (e.g., 1920x1080 for 1080p)
-- `--zoom` makes UI elements appear larger by using a smaller browser viewport
-- Example: `--viewport 1080p --zoom 150` records a 1920x1080 video
-  - Actual browser viewport: 1280x720 (1920/1.5 x 1080/1.5)
-  - Output video: 1920x1080
-  - Result: Content appears 1.5x larger/zoomed
-- Useful for demos where UI elements need to be more visible and readable
-
 ## Output Dimensions
 
 Control final video resolution after processing. Supports landscape, portrait, and square formats.
@@ -443,7 +442,76 @@ sceneforge concat --demo my-demo --output-size square
 
 # Full pipeline with all options
 sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
-  --viewport 1080p --zoom 150 \
+  --viewport 1080p \
   --output-size 1080p \
   --quality high
 ```
+
+## High-Quality Recording (CDP)
+
+SceneForge offers an alternative high-quality recording mode that bypasses Playwright's built-in video recording limitations.
+
+### Why Use HQ Recording?
+
+Playwright's built-in video recording uses hardcoded FFmpeg settings optimized for debugging rather than production quality:
+- **1Mbps bitrate cap** - Severely limits quality at higher resolutions
+- **Speed 8 encoding** - Prioritizes speed over quality
+- **Realtime deadline** - No time for quality optimization
+
+The CDP-based recorder captures frames directly from Chrome DevTools Protocol and assembles them with FFmpeg using our quality settings.
+
+### CLI Flags (record, pipeline)
+
+```bash
+--hq-video              # Enable CDP-based high-quality recording
+--hq-format <format>    # Frame format: jpeg (default) or png
+--hq-quality <1-100>    # JPEG quality (default: 100, ignored for PNG)
+```
+
+### Frame Formats
+
+| Format | Quality | File Size | Use Case |
+|--------|---------|-----------|----------|
+| `jpeg` | Very high (at quality 100) | Smaller | Default, good for most cases |
+| `png` | Lossless | Larger | Maximum quality, longer recordings |
+
+### How It Works
+
+1. **Frame Capture**: Uses Chrome's `Page.startScreencast` CDP method
+2. **Frame Storage**: Saves frames as JPEG (quality 100) or lossless PNG
+3. **Video Assembly**: FFmpeg assembles frames with lossless intermediate encoding
+4. **Final Output**: Quality settings applied at concat step
+
+### Examples
+
+```bash
+# High-quality recording with default settings
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video
+
+# Lossless PNG frames for maximum quality
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video --hq-format png
+
+# Full pipeline with HQ recording
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --hq-video --quality high
+
+# HQ recording at 4K
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
+  --hq-video \
+  --viewport 4k \
+  --output-size 1080p \
+  --quality high
+```
+
+### Trade-offs
+
+| Aspect | Standard Recording | HQ Recording |
+|--------|-------------------|--------------|
+| Quality | Limited by 1Mbps cap | Full quality frames |
+| Speed | Faster | Slower (frame-by-frame) |
+| Disk Usage | Moderate | Higher (temporary frames) |
+| Compatibility | Always works | Requires FFmpeg |
+
+### When to Use
+
+- **Use HQ Recording** when final video quality is critical
+- **Use Standard Recording** for quick drafts, debugging, or when disk space is limited

package/dist/templates/base/cli-reference.md

@@ -28,7 +28,9 @@ sceneforge record --definition <path> [options]
 | `--viewport` | Target video resolution (preset or WxH, default: 1440x900) |
 | `--width` | Video width (overrides --viewport) |
 | `--height` | Video height (overrides --viewport) |
-| `--zoom` | Content zoom level: 100, 150, 200 (default: 100) - makes UI larger |
+| `--hq-video` | Use CDP-based high-quality recording |
+| `--hq-format` | Frame format: jpeg (default) or png (lossless) |
+| `--hq-quality` | JPEG quality 1-100 (default: 100) |
 
 **Viewport Presets:** 720p (1280x720), 1080p (1920x1080), 1440p (2560x1440), 4k (3840x2160)
 
@@ -46,8 +48,14 @@ sceneforge record -d demo.yaml -b http://localhost:3000 --storage ./auth.json
 # Record at 1080p resolution
 sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1080p
 
-# Record at 1080p with zoomed content (UI appears 1.5x larger)
-sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1080p --zoom 150
+# Record at 4K resolution
+sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 4k
+
+# High-quality CDP recording (bypasses Playwright's bitrate limits)
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video
+
+# HQ recording with lossless PNG frames
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video --hq-format png
 ```
 
 ### setup
@@ -94,10 +102,12 @@ sceneforge pipeline --definition <path> [options]
 | `--crf` | Override CRF value |
 | `--codec` | Video codec: libx264, libx265 |
 | `--viewport` | Target video resolution (preset or WxH) |
-| `--zoom` | Content zoom level: 100, 150, 200 (makes UI larger) |
 | `--output-size` | Final output dimensions (preset or WxH) |
 | `--output-width` | Output width (-1 for auto) |
 | `--output-height` | Output height (-1 for auto) |
+| `--hq-video` | Use CDP-based high-quality recording |
+| `--hq-format` | Frame format: jpeg (default) or png |
+| `--hq-quality` | JPEG quality 1-100 (default: 100) |
 
 **Examples:**
 ```bash
@@ -116,9 +126,9 @@ sceneforge pipeline -d demo.yaml -b http://localhost:3000 --quality high --outpu
 # TikTok/YouTube Shorts format
 sceneforge pipeline -d demo.yaml -b http://localhost:3000 --output-size tiktok --quality high
 
-# Full options: viewport + zoom + output scaling
+# Full options: viewport + output scaling
 sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
-  --viewport 1080p --zoom 150 \
+  --viewport 1080p \
   --output-size 1080p \
   --quality high
 ```
@@ -364,7 +374,7 @@ sceneforge split --demo my-demo --crf 15
 
 ## Viewport Settings
 
-Control output video resolution and content zoom during recording.
+Control output video resolution during recording.
 
 ### CLI Flags (record, pipeline)
 
@@ -372,7 +382,6 @@ Control output video resolution and content zoom during recording.
 --viewport <WxH|preset>      # Target video resolution (default: 1440x900)
 --width <px>                 # Video width (overrides --viewport)
 --height <px>                # Video height (overrides --viewport)
---zoom <percent>             # Content zoom: 100, 150, 200 (default: 100)
 ```
 
 ### Viewport Presets
@@ -384,16 +393,6 @@ Control output video resolution and content zoom during recording.
 | `1440p` | 2560x1440 |
 | `4k` | 3840x2160 |
 
-### How Zoom Works
-
-- `--viewport` sets the output video resolution (e.g., 1920x1080 for 1080p)
-- `--zoom` makes UI elements appear larger by using a smaller browser viewport
-- Example: `--viewport 1080p --zoom 150` records a 1920x1080 video
-  - Actual browser viewport: 1280x720 (1920/1.5 x 1080/1.5)
-  - Output video: 1920x1080
-  - Result: Content appears 1.5x larger/zoomed
-- Useful for demos where UI elements need to be more visible and readable
-
 ## Output Dimensions
 
 Control final video resolution after processing. Supports landscape, portrait, and square formats.
@@ -443,7 +442,76 @@ sceneforge concat --demo my-demo --output-size square
 
 # Full pipeline with all options
 sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
-  --viewport 1080p --zoom 150 \
+  --viewport 1080p \
   --output-size 1080p \
   --quality high
 ```
+
+## High-Quality Recording (CDP)
+
+SceneForge offers an alternative high-quality recording mode that bypasses Playwright's built-in video recording limitations.
+
+### Why Use HQ Recording?
+
+Playwright's built-in video recording uses hardcoded FFmpeg settings optimized for debugging rather than production quality:
+- **1Mbps bitrate cap** - Severely limits quality at higher resolutions
+- **Speed 8 encoding** - Prioritizes speed over quality
+- **Realtime deadline** - No time for quality optimization
+
+The CDP-based recorder captures frames directly from Chrome DevTools Protocol and assembles them with FFmpeg using our quality settings.
+
+### CLI Flags (record, pipeline)
+
+```bash
+--hq-video              # Enable CDP-based high-quality recording
+--hq-format <format>    # Frame format: jpeg (default) or png
+--hq-quality <1-100>    # JPEG quality (default: 100, ignored for PNG)
+```
+
+### Frame Formats
+
+| Format | Quality | File Size | Use Case |
+|--------|---------|-----------|----------|
+| `jpeg` | Very high (at quality 100) | Smaller | Default, good for most cases |
+| `png` | Lossless | Larger | Maximum quality, longer recordings |
+
+### How It Works
+
+1. **Frame Capture**: Uses Chrome's `Page.startScreencast` CDP method
+2. **Frame Storage**: Saves frames as JPEG (quality 100) or lossless PNG
+3. **Video Assembly**: FFmpeg assembles frames with lossless intermediate encoding
+4. **Final Output**: Quality settings applied at concat step
+
+### Examples
+
+```bash
+# High-quality recording with default settings
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video
+
+# Lossless PNG frames for maximum quality
+sceneforge record -d demo.yaml -b http://localhost:3000 --hq-video --hq-format png
+
+# Full pipeline with HQ recording
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --hq-video --quality high
+
+# HQ recording at 4K
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 \
+  --hq-video \
+  --viewport 4k \
+  --output-size 1080p \
+  --quality high
+```
+
+### Trade-offs
+
+| Aspect | Standard Recording | HQ Recording |
+|--------|-------------------|--------------|
+| Quality | Limited by 1Mbps cap | Full quality frames |
+| Speed | Faster | Slower (frame-by-frame) |
+| Disk Usage | Moderate | Higher (temporary frames) |
+| Compatibility | Always works | Requires FFmpeg |
+
+### When to Use
+
+- **Use HQ Recording** when final video quality is critical
+- **Use Standard Recording** for quick drafts, debugging, or when disk space is limited

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t3lnet/sceneforge",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "description": "SceneForge runner and generation utilities for YAML-driven demos",
   "license": "MIT",
   "author": "T3LNET",