@t3lnet/sceneforge 1.0.19 → 1.0.21

package/README.md

@@ -119,15 +119,15 @@ npx sceneforge split --demo my-demo --crf 15
 
 ## Viewport Settings (Recording)
 
-Control browser viewport size and zoom level during recording:
+Control output video resolution and content zoom:
 
 ```bash
---viewport <WxH|preset>      # Viewport size (default: 1440x900)
+--viewport <WxH|preset>      # Video resolution (default: 1440x900)
                              # Presets: 720p, 1080p, 1440p, 4k
---width <px>                 # Viewport width
---height <px>                # Viewport height
---zoom <percent>             # Browser zoom: 100, 150, 200 (default: 100)
---device-scale-factor <n>    # Device pixel ratio: 1, 1.5, 2
+--width <px>                 # Video width
+--height <px>                # Video height
+--zoom <percent>             # Content zoom: 100, 150, 200 (default: 100)
+                             # Makes UI elements appear larger
 ```
 
 **Examples:**
@@ -136,11 +136,13 @@ Control browser viewport size and zoom level during recording:
 # Record at 1080p
 npx sceneforge record --definition demo.yaml --base-url http://localhost:5173 --viewport 1080p
 
-# Record with zoom for extra detail
+# Record at 1080p with zoomed content (UI appears 1.5x larger)
 npx sceneforge record --definition demo.yaml --base-url http://localhost:5173 \
-  --viewport 1920x1080 --zoom 150
+  --viewport 1080p --zoom 150
 ```
 
+**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:

package/cli/commands/record-demo.js

@@ -19,7 +19,6 @@ import {
   parseViewportArgs,
   parseDeviceScaleFactor,
   getViewportHelpText,
-  logViewportSettings,
 } from "../utils/dimensions.js";
 
 function printHelp() {
@@ -213,17 +212,37 @@ export async function runRecordDemoCommand(argv) {
   await ensureDir(outputPaths.outputDir);
   await ensureDir(outputPaths.videosDir);
 
-  const viewport = parseViewportArgs(args, getFlagValue);
-  const deviceScaleFactor = parseDeviceScaleFactor(args, getFlagValue);
-
-  logViewportSettings(viewport, deviceScaleFactor, "[record]");
-
-  // Calculate video recording size (viewport * scale factor for high-DPI capture)
+  const requestedViewport = parseViewportArgs(args, getFlagValue);
+  const zoomFactor = parseDeviceScaleFactor(args, getFlagValue);
+
+  // To achieve "zoom", we use a smaller viewport but record at the requested resolution.
+  // This makes content appear larger (zoomed in) in the final video.
+  // Example: --viewport 1080p --zoom 150 means:
+  //   - User wants 1920x1080 output video
+  //   - Content should appear 1.5x larger (zoomed)
+  //   - So we set viewport to 1280x720 (1920/1.5 x 1080/1.5)
+  //   - Record at 1920x1080
+  const viewport = zoomFactor !== 1
+    ? {
+        width: Math.round(requestedViewport.width / zoomFactor),
+        height: Math.round(requestedViewport.height / zoomFactor),
+      }
+    : requestedViewport;
+
+  // Recording size is the requested viewport (the final video dimensions)
   const recordVideoSize = {
-    width: Math.round(viewport.width * deviceScaleFactor),
-    height: Math.round(viewport.height * deviceScaleFactor),
+    width: requestedViewport.width,
+    height: requestedViewport.height,
   };
 
+  // Log what's happening
+  if (zoomFactor !== 1) {
+    console.log(`[record] Viewport: ${viewport.width}x${viewport.height} (zoomed ${Math.round(zoomFactor * 100)}%)`);
+    console.log(`[record] Output video: ${recordVideoSize.width}x${recordVideoSize.height}`);
+  } else {
+    console.log(`[record] Viewport: ${viewport.width}x${viewport.height}`);
+  }
+
   const recordDir = path.join(outputPaths.videosDir, ".recordings", definition.name);
   if (!noVideo) {
     await ensureDir(recordDir);
@@ -236,7 +255,8 @@ export async function runRecordDemoCommand(argv) {
 
   const context = await browser.newContext({
     viewport,
-    deviceScaleFactor,
+    // Note: we achieve "zoom" by using a smaller viewport, not deviceScaleFactor
+    // deviceScaleFactor only affects pixel density, not content size
     recordVideo: noVideo ? undefined : { dir: recordDir, size: recordVideoSize },
     storageState: storageState ? toAbsolute(rootDir, storageState) : undefined,
     locale: locale || undefined,

package/cli/utils/dimensions.js

@@ -188,13 +188,15 @@ export function getScaleFilterArgs(dimensions) {
 export function getViewportHelpText() {
   return `
 Viewport Options (Recording):
-  --viewport <WxH|preset>  Browser viewport size (default: 1440x900)
+  --viewport <WxH|preset>  Target video resolution (default: 1440x900)
                            Presets: 720p, 1080p, 1440p, 4k
                            Example: --viewport 1920x1080 or --viewport 1080p
-  --width <px>             Viewport width (overrides --viewport)
-  --height <px>            Viewport height (overrides --viewport)
-  --zoom <percent>         Browser zoom level: 100, 150, 200 (default: 100)
-  --device-scale-factor <n> Device pixel ratio: 1, 1.5, 2 (alternative to --zoom)`;
+  --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`;
 }
 
 /**

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

@@ -25,11 +25,10 @@ sceneforge record --definition <path> [options]
 | `--storage` | Path to storage state JSON |
 | `--slowmo` | Slow down actions by ms |
 | `--env-file` | Path to .env file |
-| `--viewport` | Browser viewport size (preset or WxH, default: 1440x900) |
-| `--width` | Viewport width (overrides --viewport) |
-| `--height` | Viewport height (overrides --viewport) |
-| `--zoom` | Browser zoom level: 100, 150, 200 (default: 100) |
-| `--device-scale-factor` | Device pixel ratio: 1, 1.5, 2 |
+| `--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 |
 
 **Viewport Presets:** 720p (1280x720), 1080p (1920x1080), 1440p (2560x1440), 4k (3840x2160)
 
@@ -44,11 +43,11 @@ sceneforge record -d demo.yaml -b http://localhost:3000 --headed
 # With auth state
 sceneforge record -d demo.yaml -b http://localhost:3000 --storage ./auth.json
 
-# Record at 1080p viewport
+# Record at 1080p resolution
 sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1080p
 
-# Record with zoom for extra detail
-sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1920x1080 --zoom 150
+# Record at 1080p with zoomed content (UI appears 1.5x larger)
+sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1080p --zoom 150
 ```
 
 ### setup
@@ -94,9 +93,9 @@ sceneforge pipeline --definition <path> [options]
 | `--quality` | Quality preset: low, medium, high |
 | `--crf` | Override CRF value |
 | `--codec` | Video codec: libx264, libx265 |
-| `--viewport` | Browser viewport size (preset or WxH) |
-| `--zoom` | Browser zoom level: 100, 150, 200 |
-| `--output-size` | Output video dimensions (preset or WxH) |
+| `--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) |
 
@@ -365,16 +364,15 @@ sceneforge split --demo my-demo --crf 15
 
 ## Viewport Settings
 
-Control browser viewport size and zoom during recording for high-DPI capture.
+Control output video resolution and content zoom during recording.
 
 ### CLI Flags (record, pipeline)
 
 ```bash
---viewport <WxH|preset>      # Browser viewport size (default: 1440x900)
---width <px>                 # Viewport width (overrides --viewport)
---height <px>                # Viewport height (overrides --viewport)
---zoom <percent>             # Browser zoom: 100, 150, 200 (default: 100)
---device-scale-factor <n>    # Device pixel ratio: 1, 1.5, 2
+--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
@@ -386,12 +384,15 @@ Control browser viewport size and zoom during recording for high-DPI capture.
 | `1440p` | 2560x1440 |
 | `4k` | 3840x2160 |
 
-### Why Viewport Settings Matter
+### How Zoom Works
 
-- Larger viewports capture more UI detail and clarity
-- Zoom (device scale factor) increases effective pixel density
-- A 1080p viewport at 150% zoom captures at 2880x1620 effective pixels
-- Useful for creating videos that look sharp on retina displays
+- `--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
 

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

@@ -25,11 +25,10 @@ sceneforge record --definition <path> [options]
 | `--storage` | Path to storage state JSON |
 | `--slowmo` | Slow down actions by ms |
 | `--env-file` | Path to .env file |
-| `--viewport` | Browser viewport size (preset or WxH, default: 1440x900) |
-| `--width` | Viewport width (overrides --viewport) |
-| `--height` | Viewport height (overrides --viewport) |
-| `--zoom` | Browser zoom level: 100, 150, 200 (default: 100) |
-| `--device-scale-factor` | Device pixel ratio: 1, 1.5, 2 |
+| `--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 |
 
 **Viewport Presets:** 720p (1280x720), 1080p (1920x1080), 1440p (2560x1440), 4k (3840x2160)
 
@@ -44,11 +43,11 @@ sceneforge record -d demo.yaml -b http://localhost:3000 --headed
 # With auth state
 sceneforge record -d demo.yaml -b http://localhost:3000 --storage ./auth.json
 
-# Record at 1080p viewport
+# Record at 1080p resolution
 sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1080p
 
-# Record with zoom for extra detail
-sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1920x1080 --zoom 150
+# Record at 1080p with zoomed content (UI appears 1.5x larger)
+sceneforge record -d demo.yaml -b http://localhost:3000 --viewport 1080p --zoom 150
 ```
 
 ### setup
@@ -94,9 +93,9 @@ sceneforge pipeline --definition <path> [options]
 | `--quality` | Quality preset: low, medium, high |
 | `--crf` | Override CRF value |
 | `--codec` | Video codec: libx264, libx265 |
-| `--viewport` | Browser viewport size (preset or WxH) |
-| `--zoom` | Browser zoom level: 100, 150, 200 |
-| `--output-size` | Output video dimensions (preset or WxH) |
+| `--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) |
 
@@ -365,16 +364,15 @@ sceneforge split --demo my-demo --crf 15
 
 ## Viewport Settings
 
-Control browser viewport size and zoom during recording for high-DPI capture.
+Control output video resolution and content zoom during recording.
 
 ### CLI Flags (record, pipeline)
 
 ```bash
---viewport <WxH|preset>      # Browser viewport size (default: 1440x900)
---width <px>                 # Viewport width (overrides --viewport)
---height <px>                # Viewport height (overrides --viewport)
---zoom <percent>             # Browser zoom: 100, 150, 200 (default: 100)
---device-scale-factor <n>    # Device pixel ratio: 1, 1.5, 2
+--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
@@ -386,12 +384,15 @@ Control browser viewport size and zoom during recording for high-DPI capture.
 | `1440p` | 2560x1440 |
 | `4k` | 3840x2160 |
 
-### Why Viewport Settings Matter
+### How Zoom Works
 
-- Larger viewports capture more UI detail and clarity
-- Zoom (device scale factor) increases effective pixel density
-- A 1080p viewport at 150% zoom captures at 2880x1620 effective pixels
-- Useful for creating videos that look sharp on retina displays
+- `--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
 

package/package.json

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