@t3lnet/sceneforge 1.0.20 → 1.0.22

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

@@ -212,33 +212,19 @@ export async function runRecordDemoCommand(argv) {
   await ensureDir(outputPaths.outputDir);
   await ensureDir(outputPaths.videosDir);
 
-  const requestedViewport = parseViewportArgs(args, getFlagValue);
+  const viewport = 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: requestedViewport.width,
-    height: requestedViewport.height,
-  };
+  // 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} (zoomed ${Math.round(zoomFactor * 100)}%)`);
-    console.log(`[record] Output video: ${recordVideoSize.width}x${recordVideoSize.height}`);
+    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}`);
   }
@@ -255,9 +241,7 @@ export async function runRecordDemoCommand(argv) {
 
   const context = await browser.newContext({
     viewport,
-    // 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 },
+    recordVideo: noVideo ? undefined : { dir: recordDir, size: viewport },
     storageState: storageState ? toAbsolute(rootDir, storageState) : undefined,
     locale: locale || undefined,
     extraHTTPHeaders: locale
@@ -268,12 +252,32 @@ export async function runRecordDemoCommand(argv) {
   });
 
   const page = await context.newPage();
+
+  // 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);
+  }
+
   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,

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.20",
+  "version": "1.0.22",
   "description": "SceneForge runner and generation utilities for YAML-driven demos",
   "license": "MIT",
   "author": "T3LNET",