rollberry 0.1.9 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on Keep a Changelog and the project stays on the `v0.x.x`
 line until the CLI surface and capture behavior settle.
 
+## [0.2.0] - 2026-03-22
+
+### Added
+
+- `render <project.json>` command for project-based multi-scene rendering.
+- Project config support for `scenes`, `outputs`, reusable defaults, and
+  project-level summary manifests.
+- Scene `actions` and mid-capture `timeline` segments including `pause`,
+  `scroll`, `click`, `hover`, `press`, `type`, and `scroll-to`.
+- Multi-output rendering with per-output viewport, audio, subtitles,
+  transitions, and encoder settings.
+- Node library exports for project loading, render planning, and render
+  execution.
+- JSON Schema and sample project config for editor validation and onboarding.
+- Scene-to-scene `crossfade` transitions.
+- Subtitle support for both soft and burn-in modes with `.srt`, `.vtt`, and
+  `.webvtt` inputs.
+- `finalVideo` encoder controls for final `mp4` and `webm` outputs.
+- `intermediateArtifact` profiles for scene clip generation.
+
+### Changed
+
+- Render orchestration now uses an explicit render-plan layer that separates
+  scene capture from final composition.
+- Render manifests now use schema version `2` and separate `captureMetrics`
+  from `artifactMetrics`.
+- Probe handling now records explicit status and warnings, and fails fast when
+  precise clip timing is required by composition capabilities such as
+  `crossfade`.
+
 ## [0.1.9] - 2026-03-20
 
 ### Added

package/README.md

@@ -1,9 +1,11 @@
 # Rollberry
 
-Rollberry is an MIT-licensed open source CLI for turning web pages into
-smooth top-to-bottom scroll videos. It captures one or more URLs into a single
-MP4. It is built for real browser capture, works with normal URLs and
-`localhost`, and is published for direct `npx` usage.
+Rollberry is an MIT-licensed open source CLI and Node API for turning web
+pages into smooth top-to-bottom scroll videos. It can capture one or more
+URLs into a single MP4, or render a project JSON file into multiple output
+variants such as desktop and mobile. It is built for real browser capture,
+works with normal URLs and `localhost`, and is published for direct `npx`
+usage.
 
 Maintained by CORe Inc.
 
@@ -12,7 +14,7 @@ Maintained by CORe Inc.
 Requirements:
 
 - Node.js `24.12.0+`
-- `ffmpeg` and `ffprobe` available on `PATH`
+- `ffmpeg` available on `PATH`
 
 Install nothing globally. Run it directly:
 
@@ -29,6 +31,13 @@ npx rollberry capture http://localhost:3000 \
 On the first run, if Playwright Chromium is missing, Rollberry installs it
 automatically. `ffmpeg` is not auto-installed.
 
+For project-based rendering, start from the bundled sample:
+
+```bash
+cp rollberry.project.sample.json rollberry.project.json
+npx rollberry render ./rollberry.project.json
+```
+
 ## Using With npx
 
 The normal way to run Rollberry is `npx`.
@@ -61,11 +70,17 @@ npx rollberry capture https://playwright.dev \
   --duration 8
 ```
 
+Render a project file with multiple outputs:
+
+```bash
+npx rollberry render ./rollberry.project.json
+```
+
 Notes:
 
 - `npx` downloads the published CLI package automatically
 - on the first run, Rollberry installs Playwright Chromium if needed
-- `ffmpeg` and `ffprobe` must already be available on your machine
+- `ffmpeg` must already be available on your machine
 - if you want reproducible automation, pin the package version with
   `npx rollberry@<version> ...`
 
@@ -74,10 +89,12 @@ Notes:
 Each run writes:
 
 - `video.mp4`: the rendered capture
-- `video.manifest.json`: environment, options, result, and failure details
+- `video.manifest.json`: environment, scene definitions, capture metrics, artifact metrics, and failure details
 - `video.log.jsonl`: structured operational logs
 
 You can override the sidecar paths with `--manifest` and `--log-file`.
+Project renders write the same sidecars for each configured output, plus a
+project-level `*.render-summary.json`.
 
 ## Common Examples
 
@@ -133,10 +150,162 @@ npx rollberry capture http://localhost:3000 \
   --debug-frames-dir ./artifacts/debug-frames
 ```
 
+Render a project file into desktop and mobile outputs:
+
+```bash
+npx rollberry render ./rollberry.project.json
+```
+
+Render only one named output from a project:
+
+```bash
+npx rollberry render ./rollberry.project.json --output mobile
+```
+
+## Project Rendering
+
+Use `render` when you want scene-by-scene control and multiple outputs from one
+config file. `actions` run before capture as setup. `timeline` runs during the
+capture itself and lets you interleave scroll, pause, and interactions inside
+one scene.
+
+```json
+{
+  "$schema": "./rollberry.project.schema.json",
+  "schemaVersion": 1,
+  "summaryManifest": "./artifacts/demo.render-summary.json",
+  "defaults": {
+    "fps": 60,
+    "viewport": "1440x900",
+    "waitFor": "selector:body",
+    "hideSelectors": ["#cookie-banner"]
+  },
+  "scenes": [
+    {
+      "name": "home",
+      "url": "http://localhost:3000",
+      "actions": [
+        { "type": "click", "selector": "[data-open-menu]" },
+        { "type": "wait", "ms": 300 }
+      ],
+      "timeline": [
+        { "type": "pause", "duration": 0.4 },
+        {
+          "type": "click",
+          "selector": "[data-open-menu]",
+          "holdAfterSeconds": 0.4
+        },
+        { "type": "scroll", "toSelector": "#pricing", "duration": 1.4 },
+        { "type": "scroll", "to": "bottom", "duration": "auto" }
+      ],
+      "holdAfterSeconds": 0.75
+    },
+    {
+      "name": "pricing",
+      "url": "http://localhost:3000/pricing"
+    }
+  ],
+  "outputs": [
+    {
+      "name": "desktop",
+      "viewport": "1440x900",
+      "out": "./artifacts/demo-desktop.mp4",
+      "audio": {
+        "path": "./assets/demo-narration.wav",
+        "volume": 0.8,
+        "loop": true
+      },
+      "subtitles": {
+        "path": "./assets/demo-captions.vtt",
+        "mode": "burn-in"
+      },
+      "transition": {
+        "type": "crossfade",
+        "duration": 0.25
+      },
+      "intermediateArtifact": {
+        "format": "mp4",
+        "preset": "veryfast",
+        "crf": 20
+      },
+      "finalVideo": {
+        "preset": "medium",
+        "crf": 19
+      }
+    },
+    {
+      "name": "mobile",
+      "viewport": "430x932",
+      "out": "./artifacts/demo-mobile.webm",
+      "format": "webm",
+      "subtitles": {
+        "path": "./assets/demo-captions.vtt",
+        "mode": "soft"
+      },
+      "transition": {
+        "type": "crossfade",
+        "duration": 0.25
+      },
+      "intermediateArtifact": {
+        "format": "mp4",
+        "preset": "fast",
+        "crf": 22
+      },
+      "finalVideo": {
+        "deadline": "best",
+        "crf": 30
+      }
+    }
+  ]
+}
+```
+
+Supported setup actions:
+
+- `wait`
+- `click`
+- `hover`
+- `press`
+- `type`
+- `scroll-to`
+
+Supported timeline segments:
+
+- `pause`
+- `wait`
+- `scroll`
+- `click`
+- `hover`
+- `press`
+- `type`
+- `scroll-to`
+
+Supported output extensions:
+
+- `mp4`
+- `webm`
+
+Supported media extensions:
+
+- output-level background audio via `audio.path`
+- output-level subtitles via `subtitles.path`
+- `subtitles.mode: "soft"` for `mp4` and `webm`
+- `subtitles.mode: "burn-in"` for `mp4` and `webm`
+- `.srt`, `.vtt`, and `.webvtt` subtitle inputs
+- output-level `transition.type: "fade-in"`
+- output-level `transition.type: "crossfade"` between adjacent scenes
+- output-level `intermediateArtifact.format` / `preset` / `crf` for scene clip profiles
+- output-level `finalVideo.preset` / `finalVideo.crf` for `mp4` encode control
+- output-level `finalVideo.deadline` / `finalVideo.crf` for `webm` encode control
+- project-level summary manifest via `summaryManifest`
+- render manifest separates `captureMetrics` and `artifactMetrics`
+- `crossfade` uses `ffprobe`-backed clip timing when available and fails fast if scene clip probing is unavailable
+
 ## CLI Options
 
 ```text
 rollberry capture <url...>
+rollberry render <project.json>
 
 --out <file>                Output MP4 path
 --viewport <WxH>            Viewport size, example: 1440x900
@@ -150,6 +319,10 @@ rollberry capture <url...>
 --debug-frames-dir <dir>    Save raw PNG frames
 --manifest <file>           Manifest JSON output path
 --log-file <file>           Log JSONL output path
+
+render:
+--output <name>             Render only the named output (repeatable)
+--force                     Overwrite configured output files
 ```
 
 ## Localhost Behavior
@@ -168,6 +341,9 @@ If `ffmpeg` is missing:
 brew install ffmpeg
 ```
 
+If you are running the test suite, `ffprobe` may also be used for extra video
+verification. Most FFmpeg installs include it alongside `ffmpeg`.
+
 If capture fails, inspect:
 
 - `*.manifest.json` for final status and error details
@@ -187,6 +363,11 @@ If a site keeps shifting during capture:
 
 ## Local Development
 
+For local CLI usage and captures, Rollberry requires `ffmpeg` on `PATH`.
+When running `pnpm test`, the integration suite uses `ffprobe` when available
+to inspect generated videos, but falls back to basic file validation if it is
+missing.
+
 ```bash
 corepack pnpm install
 corepack pnpm exec playwright install chromium
@@ -199,6 +380,7 @@ Run from the repository:
 
 ```bash
 corepack pnpm dev -- capture http://localhost:3000 --out ./artifacts/demo.mp4
+corepack pnpm dev -- render ./rollberry.project.sample.json
 ```
 
 Run the regression suite:

package/dist/capture/actions.d.ts

@@ -0,0 +1,11 @@
+import type { Page } from 'playwright';
+import type { CaptureAction } from './types.js';
+export declare function executeSceneActions(options: {
+    page: Page;
+    actions: CaptureAction[];
+    timeoutMs: number;
+    onActionStart?: (action: CaptureAction, index: number) => Promise<void> | void;
+    onActionComplete?: (action: CaptureAction, index: number) => Promise<void> | void;
+}): Promise<void>;
+export declare function executeCaptureAction(page: Page, action: CaptureAction, timeoutMs: number): Promise<void>;
+export declare function resetScrollPosition(page: Page): Promise<void>;

package/dist/capture/actions.js

@@ -0,0 +1,81 @@
+import { delay, waitForAnimationFrames } from './utils.js';
+const ACTION_SETTLE_DELAY_MS = 75;
+export async function executeSceneActions(options) {
+    const { page, actions, timeoutMs, onActionStart, onActionComplete } = options;
+    for (const [index, action] of actions.entries()) {
+        await onActionStart?.(action, index);
+        await executeCaptureAction(page, action, timeoutMs);
+        await onActionComplete?.(action, index);
+    }
+}
+export async function executeCaptureAction(page, action, timeoutMs) {
+    switch (action.kind) {
+        case 'wait':
+            await delay(action.ms);
+            break;
+        case 'click':
+            await page.waitForSelector(action.selector, {
+                state: 'visible',
+                timeout: timeoutMs,
+            });
+            await page.locator(action.selector).click();
+            await settlePage(page);
+            break;
+        case 'hover':
+            await page.waitForSelector(action.selector, {
+                state: 'visible',
+                timeout: timeoutMs,
+            });
+            await page.locator(action.selector).hover();
+            await settlePage(page);
+            break;
+        case 'press':
+            await page.keyboard.press(action.key);
+            await settlePage(page);
+            break;
+        case 'type':
+            await page.waitForSelector(action.selector, {
+                state: 'visible',
+                timeout: timeoutMs,
+            });
+            if (action.clear) {
+                await page.locator(action.selector).fill(action.text);
+            }
+            else {
+                await page.locator(action.selector).type(action.text);
+            }
+            await settlePage(page);
+            break;
+        case 'scroll-to':
+            await page.waitForSelector(action.selector, {
+                state: 'attached',
+                timeout: timeoutMs,
+            });
+            await page.evaluate(({ selector, block }) => {
+                const element = document.querySelector(selector);
+                if (!element) {
+                    throw new Error(`Selector not found for scroll action: ${selector}`);
+                }
+                element.scrollIntoView({
+                    block,
+                    behavior: 'auto',
+                    inline: 'nearest',
+                });
+            }, {
+                selector: action.selector,
+                block: action.block,
+            });
+            await settlePage(page);
+            break;
+    }
+}
+export async function resetScrollPosition(page) {
+    await page.evaluate(() => {
+        window.scrollTo({ top: 0, behavior: 'auto' });
+    });
+    await waitForAnimationFrames(page);
+}
+async function settlePage(page) {
+    await waitForAnimationFrames(page);
+    await delay(ACTION_SETTLE_DELAY_MS);
+}

package/dist/capture/browser-install.d.ts

@@ -0,0 +1,3 @@
+import type { CaptureLogger } from './logger.js';
+export declare function ensureChromiumInstalled(logger: CaptureLogger): Promise<void>;
+export declare function resolvePlaywrightCliPath(): string;

package/dist/capture/browser.d.ts

@@ -0,0 +1,13 @@
+import { chromium, type Page } from 'playwright';
+import type { CaptureLogger } from './logger.js';
+import type { Viewport } from './types.js';
+export interface BrowserSession {
+    browser: Awaited<ReturnType<typeof chromium.launch>>;
+    page: Page;
+}
+export declare function openBrowserSession(options: {
+    viewport: Viewport;
+    timeoutMs: number;
+    urls: URL[];
+}, logger: CaptureLogger): Promise<BrowserSession>;
+export declare function navigateWithRetry(page: Page, url: URL, timeoutMs: number): Promise<void>;

package/dist/capture/capture.d.ts

@@ -0,0 +1,8 @@
+import type { CaptureLogger } from './logger.js';
+import type { ProgressReporter } from './progress.js';
+import type { CaptureJob, CaptureOptions, CaptureResult } from './types.js';
+export declare function captureVideo(options: CaptureOptions, logger: CaptureLogger, progress?: ProgressReporter, signal?: AbortSignal): Promise<CaptureResult>;
+export declare function captureSceneVideo(job: CaptureJob, logger: CaptureLogger, progress?: ProgressReporter, signal?: AbortSignal): Promise<CaptureResult>;
+export declare class AbortError extends Error {
+    constructor();
+}