rollberry 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# Rollberry
+
+Rollberry は、指定した Web ページを上から下まで滑らかにスクロールさせた MP4 を生成する CLI です。`localhost`、`127.0.0.1`、`[::1]` の開発中 URL にも対応します。
+
+## Requirements
+
+- Node.js `24.12.0+`
+- `ffmpeg` / `ffprobe`
+- macOS を優先サポート
+
+## Setup
+
+```bash
+corepack pnpm install
+corepack pnpm exec playwright install chromium
+```
+
+## Usage
+
+```bash
+npx rollberry capture http://localhost:3000 \
+  --out ./artifacts/demo.mp4 \
+  --viewport 1440x900 \
+  --fps 60 \
+  --duration auto \
+  --wait-for selector:body \
+  --hide-selector '#cookie-banner'
+```
+
+リポジトリ内で開発実行する場合は次です。
+
+```bash
+corepack pnpm dev -- capture http://localhost:3000 \
+  --out ./artifacts/demo.mp4 \
+  --viewport 1440x900 \
+  --fps 60 \
+  --duration auto \
+  --wait-for selector:body \
+  --hide-selector '#cookie-banner'
+```
+
+ビルド後は次でも実行できます。
+
+```bash
+node dist/cli.js capture https://example.com --out ./artifacts/example.mp4
+```
+
+初回の `npx rollberry ...` 実行時に Chromium が未導入なら、Rollberry が Playwright Chromium を自動インストールします。`ffmpeg` / `ffprobe` は自動導入しないので、事前に PATH 上で使える必要があります。
+
+## Sidecar Outputs
+
+各キャプチャのたびに次を出力します。
+
+- `video.mp4`: 本体動画
+- `video.manifest.json`: 実行結果、環境、オプション、失敗内容
+- `video.log.jsonl`: 1 行 1 JSON の運用ログ
+
+`--manifest` と `--log-file` で出力先を個別に上書きできます。
+
+## Localhost Behavior
+
+- `http://localhost:*`、`https://localhost:*`、`http://127.0.0.1:*`、`http://[::1]:*` を許可
+- `localhost` 系では接続拒否を `--timeout` まで 500ms 間隔で再試行
+- `https://localhost` 系では自己署名証明書を許可
+- dev server の自動起動はしません。URL は事前に起動済みである前提です
+
+## Recommended Operational Flow
+
+1. `regression.sample.json` をコピーして自分たちの `regression.sites.json` を作る
+2. 重要な 10〜20 URL を登録する
+3. リリース前に `corepack pnpm regression -- --config ./regression.sites.json` を実行する
+4. `artifacts/regression/summary.json` と各 manifest を確認する
+
+## Commands
+
+```bash
+corepack pnpm check
+corepack pnpm test
+corepack pnpm build
+corepack pnpm regression -- --config ./regression.sites.json
+```

package/dist/capture/browser-install.js

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { chromium } from 'playwright';
+const require = createRequire(import.meta.url);
+export async function ensureChromiumInstalled(logger) {
+    const executablePath = chromium.executablePath();
+    if (await hasExecutable(executablePath)) {
+        return;
+    }
+    await logger.warn('browser.install.start', 'Chromium was not found. Installing Playwright Chromium.', { executablePath });
+    await installPlaywrightChromium(resolvePlaywrightCliPath());
+    if (!(await hasExecutable(executablePath))) {
+        throw new Error(`Chromium のインストール後も実行ファイルが見つかりません: ${executablePath}`);
+    }
+    await logger.info('browser.install.complete', 'Playwright Chromium installation finished.', { executablePath });
+}
+export function resolvePlaywrightCliPath() {
+    return join(dirname(require.resolve('playwright/package.json')), 'cli.js');
+}
+async function hasExecutable(path) {
+    try {
+        await access(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function installPlaywrightChromium(cliPath) {
+    const child = spawn(process.execPath, [cliPath, 'install', 'chromium'], {
+        env: process.env,
+        stdio: 'inherit',
+    });
+    await new Promise((resolve, reject) => {
+        child.once('error', (error) => {
+            reject(error);
+        });
+        child.once('close', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`Playwright Chromium install failed with exit code ${code ?? 'null'}.`));
+        });
+    });
+}

package/dist/capture/browser.js

@@ -0,0 +1,54 @@
+import { chromium } from 'playwright';
+import { ensureChromiumInstalled } from './browser-install.js';
+import { LOCALHOST_RETRY_INTERVAL_MS } from './constants.js';
+import { delay, isLocalUrl } from './utils.js';
+export async function openBrowserSession(options, logger) {
+    await ensureChromiumInstalled(logger);
+    const browser = await chromium.launch({
+        headless: true,
+    });
+    const context = await browser.newContext({
+        viewport: options.viewport,
+        ignoreHTTPSErrors: isLocalUrl(options.url),
+    });
+    const page = await context.newPage();
+    page.setDefaultTimeout(options.timeoutMs);
+    await page.addInitScript(() => {
+        history.scrollRestoration = 'manual';
+    });
+    return { browser, page };
+}
+export async function navigateWithRetry(page, options) {
+    const deadline = Date.now() + options.timeoutMs;
+    const canRetry = isLocalUrl(options.url);
+    while (true) {
+        const remainingMs = Math.max(1, deadline - Date.now());
+        try {
+            await page.goto(options.url.toString(), {
+                waitUntil: 'domcontentloaded',
+                timeout: remainingMs,
+            });
+            return;
+        }
+        catch (error) {
+            if (!canRetry ||
+                Date.now() + LOCALHOST_RETRY_INTERVAL_MS >= deadline ||
+                !isRetryableNavigationError(error)) {
+                throw error;
+            }
+            await delay(LOCALHOST_RETRY_INTERVAL_MS);
+        }
+    }
+}
+function isRetryableNavigationError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return [
+        'ERR_CONNECTION_REFUSED',
+        'ERR_EMPTY_RESPONSE',
+        'ERR_CONNECTION_RESET',
+        'ECONNREFUSED',
+        'ECONNRESET',
+    ].some((token) => error.message.includes(token));
+}

package/dist/capture/capture.js

@@ -0,0 +1,89 @@
+import { writeFile } from 'node:fs/promises';
+import { navigateWithRetry, openBrowserSession } from './browser.js';
+import { createVideoEncoder } from './ffmpeg.js';
+import { preflightMeasurePage } from './preflight.js';
+import { buildScrollFrames, resolveDurationSeconds } from './scroll-plan.js';
+import { stabilizePage } from './stabilize.js';
+import { ensureDirectory, ensureParentDirectory, waitForAnimationFrames, } from './utils.js';
+export async function captureVideo(options, logger) {
+    await ensureParentDirectory(options.outPath);
+    await ensureParentDirectory(options.logFilePath);
+    await ensureParentDirectory(options.manifestPath);
+    if (options.debugFramesDir) {
+        await ensureDirectory(options.debugFramesDir);
+    }
+    const { browser, page } = await openBrowserSession(options, logger);
+    try {
+        await logger.info('browser.open', 'Opening page', {
+            url: options.url.toString(),
+            viewport: options.viewport,
+        });
+        await navigateWithRetry(page, options);
+        await stabilizePage({
+            page,
+            waitFor: options.waitFor,
+            hideSelectors: options.hideSelectors,
+        });
+        const preflight = await preflightMeasurePage(page);
+        const durationSeconds = resolveDurationSeconds(options.duration, preflight.maxScroll);
+        const frames = buildScrollFrames({
+            fps: options.fps,
+            durationSeconds,
+            maxScroll: preflight.maxScroll,
+            motion: options.motion,
+        });
+        const encoder = await createVideoEncoder({
+            fps: options.fps,
+            outPath: options.outPath,
+        });
+        await logger.info('render.start', 'Rendering frames', {
+            frameCount: frames.length,
+            fps: options.fps,
+            durationSeconds,
+            maxScroll: preflight.maxScroll,
+        });
+        if (preflight.truncated) {
+            await logger.warn('preflight.truncated', 'Scroll height exceeded capture limit and was truncated', {
+                scrollHeight: preflight.scrollHeight,
+            });
+        }
+        for (const [index, scrollTop] of frames.entries()) {
+            await page.evaluate((nextScrollTop) => {
+                window.scrollTo({ top: nextScrollTop, behavior: 'auto' });
+            }, scrollTop);
+            await waitForAnimationFrames(page);
+            const frame = await page.screenshot({
+                type: 'png',
+                scale: 'css',
+                animations: 'disabled',
+                caret: 'hide',
+            });
+            if (options.debugFramesDir) {
+                const fileName = `${String(index).padStart(5, '0')}.png`;
+                await writeFile(`${options.debugFramesDir}/${fileName}`, frame);
+            }
+            await encoder.writeFrame(frame);
+            if ((index + 1) % Math.max(1, Math.floor(frames.length / 10)) === 0) {
+                await logger.info('render.progress', 'Rendered frame batch', {
+                    renderedFrames: index + 1,
+                    totalFrames: frames.length,
+                    scrollTop,
+                });
+            }
+        }
+        await encoder.finish();
+        await logger.info('encode.complete', 'Video encoding finished', {
+            outPath: options.outPath,
+        });
+        return {
+            outPath: options.outPath,
+            frameCount: frames.length,
+            durationSeconds,
+            finalScrollHeight: preflight.scrollHeight,
+            truncated: preflight.truncated,
+        };
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/capture/constants.js

@@ -0,0 +1,8 @@
+export const AUTO_DURATION_MIN_SECONDS = 4;
+export const AUTO_DURATION_MAX_SECONDS = 40;
+export const AUTO_DURATION_PIXELS_PER_SECOND = 1800;
+export const LOCALHOST_RETRY_INTERVAL_MS = 500;
+export const STABILIZE_DELAY_MS = 500;
+export const PREFLIGHT_STEP_DELAY_MS = 120;
+export const PREFLIGHT_STABLE_ROUNDS = 3;
+export const PREFLIGHT_MAX_SCROLL_HEIGHT = 30_000;

package/dist/capture/ffmpeg.js

@@ -0,0 +1,80 @@
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+export async function createVideoEncoder(options) {
+    const ffmpeg = spawn('ffmpeg', [
+        '-hide_banner',
+        '-loglevel',
+        'error',
+        '-y',
+        '-f',
+        'image2pipe',
+        '-framerate',
+        String(options.fps),
+        '-c:v',
+        'png',
+        '-i',
+        'pipe:0',
+        '-an',
+        '-c:v',
+        'libx264',
+        '-pix_fmt',
+        'yuv420p',
+        '-preset',
+        'slow',
+        '-crf',
+        '18',
+        '-movflags',
+        '+faststart',
+        '-vf',
+        'pad=ceil(iw/2)*2:ceil(ih/2)*2',
+        options.outPath,
+    ], {
+        stdio: ['pipe', 'ignore', 'pipe'],
+    });
+    let spawnError;
+    let stderr = '';
+    ffmpeg.on('error', (error) => {
+        spawnError = error;
+    });
+    ffmpeg.stderr.setEncoding('utf8');
+    ffmpeg.stderr.on('data', (chunk) => {
+        stderr += chunk;
+    });
+    return {
+        async writeFrame(frame) {
+            if (spawnError) {
+                throw createEncoderError(spawnError, stderr);
+            }
+            const stdin = ffmpeg.stdin;
+            if (stdin.destroyed) {
+                throw createEncoderError(new Error('FFmpeg の標準入力が閉じています。'), stderr);
+            }
+            await new Promise((resolve, reject) => {
+                stdin.write(frame, (error) => {
+                    if (error) {
+                        reject(createEncoderError(error, stderr));
+                        return;
+                    }
+                    resolve();
+                });
+            });
+        },
+        async finish() {
+            if (spawnError) {
+                throw createEncoderError(spawnError, stderr);
+            }
+            ffmpeg.stdin.end();
+            const [exitCode] = (await once(ffmpeg, 'close'));
+            if (exitCode !== 0) {
+                throw createEncoderError(new Error(`FFmpeg が異常終了しました (exit code: ${exitCode ?? 'null'})`), stderr);
+            }
+        },
+    };
+}
+function createEncoderError(error, stderr) {
+    if ('code' in error && error.code === 'ENOENT') {
+        return new Error('FFmpeg が見つかりません。PATH に ffmpeg を追加してください。');
+    }
+    const detail = stderr.trim();
+    return new Error(detail ? `${error.message}\n${detail}` : error.message);
+}

package/dist/capture/logger.js

@@ -0,0 +1,30 @@
+import { appendFile } from 'node:fs/promises';
+export function createCaptureLogger(logFilePath) {
+    let queue = Promise.resolve();
+    const write = async (level, event, message, data) => {
+        const logEvent = {
+            timestamp: new Date().toISOString(),
+            level,
+            event,
+            message,
+            data,
+        };
+        process.stderr.write(`${logEvent.timestamp} [${level.toUpperCase()}] ${message}\n`);
+        queue = queue.then(() => appendFile(logFilePath, `${JSON.stringify(logEvent)}\n`, 'utf8'));
+        await queue;
+    };
+    return {
+        info(event, message, data) {
+            return write('info', event, message, data);
+        },
+        warn(event, message, data) {
+            return write('warn', event, message, data);
+        },
+        error(event, message, data) {
+            return write('error', event, message, data);
+        },
+        close() {
+            return queue;
+        },
+    };
+}

package/dist/capture/preflight.js

@@ -0,0 +1,40 @@
+import { PREFLIGHT_MAX_SCROLL_HEIGHT, PREFLIGHT_STABLE_ROUNDS, PREFLIGHT_STEP_DELAY_MS, } from './constants.js';
+import { delay, measurePage, waitForAnimationFrames } from './utils.js';
+export async function preflightMeasurePage(page) {
+    let metrics = await measurePage(page);
+    let truncated = metrics.scrollHeight > PREFLIGHT_MAX_SCROLL_HEIGHT;
+    let stableRounds = metrics.maxScroll === 0 ? PREFLIGHT_STABLE_ROUNDS : 0;
+    while (!truncated && stableRounds < PREFLIGHT_STABLE_ROUNDS) {
+        let position = 0;
+        while (position < metrics.maxScroll) {
+            position = Math.min(position + metrics.viewportHeight, metrics.maxScroll);
+            await page.evaluate((scrollTop) => {
+                window.scrollTo({ top: scrollTop, behavior: 'auto' });
+            }, position);
+            await waitForAnimationFrames(page);
+            await delay(PREFLIGHT_STEP_DELAY_MS);
+        }
+        await delay(PREFLIGHT_STEP_DELAY_MS);
+        const nextMetrics = await measurePage(page);
+        truncated = nextMetrics.scrollHeight > PREFLIGHT_MAX_SCROLL_HEIGHT;
+        if (nextMetrics.scrollHeight > metrics.scrollHeight) {
+            metrics = nextMetrics;
+            stableRounds = nextMetrics.maxScroll === 0 ? PREFLIGHT_STABLE_ROUNDS : 0;
+        }
+        else {
+            metrics = nextMetrics;
+            stableRounds += 1;
+        }
+    }
+    await page.evaluate(() => {
+        window.scrollTo({ top: 0, behavior: 'auto' });
+    });
+    await waitForAnimationFrames(page);
+    const clampedScrollHeight = Math.min(metrics.scrollHeight, PREFLIGHT_MAX_SCROLL_HEIGHT);
+    return {
+        scrollHeight: clampedScrollHeight,
+        viewportHeight: metrics.viewportHeight,
+        maxScroll: Math.max(0, clampedScrollHeight - metrics.viewportHeight),
+        truncated,
+    };
+}

package/dist/capture/scroll-plan.js

@@ -0,0 +1,22 @@
+import { AUTO_DURATION_MAX_SECONDS, AUTO_DURATION_MIN_SECONDS, AUTO_DURATION_PIXELS_PER_SECOND, } from './constants.js';
+import { clamp } from './utils.js';
+export function resolveDurationSeconds(requestedDuration, maxScroll) {
+    if (requestedDuration !== 'auto') {
+        return requestedDuration;
+    }
+    return clamp(maxScroll / AUTO_DURATION_PIXELS_PER_SECOND, AUTO_DURATION_MIN_SECONDS, AUTO_DURATION_MAX_SECONDS);
+}
+export function buildScrollFrames(options) {
+    const frameCount = Math.max(1, Math.ceil(options.durationSeconds * options.fps));
+    if (frameCount === 1) {
+        return [0];
+    }
+    return Array.from({ length: frameCount }, (_, index) => {
+        const progress = index / (frameCount - 1);
+        const easedProgress = options.motion === 'linear' ? progress : easeInOutSine(progress);
+        return Number((options.maxScroll * easedProgress).toFixed(3));
+    });
+}
+function easeInOutSine(value) {
+    return -(Math.cos(Math.PI * value) - 1) / 2;
+}

package/dist/capture/stabilize.js

@@ -0,0 +1,56 @@
+import { STABILIZE_DELAY_MS } from './constants.js';
+import { delay, waitForAnimationFrames } from './utils.js';
+export async function stabilizePage(options) {
+    await options.page.addStyleTag({
+        content: buildStabilizingCss(options.hideSelectors),
+    });
+    await waitForRequestedCondition(options.page, options.waitFor);
+    await waitForFonts(options.page);
+    await delay(STABILIZE_DELAY_MS);
+    await options.page.evaluate(() => {
+        window.scrollTo({ top: 0, behavior: 'auto' });
+    });
+    await waitForAnimationFrames(options.page);
+}
+function buildStabilizingCss(hideSelectors) {
+    const hiddenSelectorBlock = hideSelectors.length > 0
+        ? `${hideSelectors.join(', ')} { display: none !important; visibility: hidden !important; }\n`
+        : '';
+    return `
+    html {
+      scroll-behavior: auto !important;
+      caret-color: transparent !important;
+      scroll-snap-type: none !important;
+    }
+
+    *, *::before, *::after {
+      animation: none !important;
+      transition: none !important;
+      scroll-behavior: auto !important;
+      caret-color: transparent !important;
+    }
+
+    ${hiddenSelectorBlock}
+  `;
+}
+async function waitForRequestedCondition(page, waitFor) {
+    if (waitFor.kind === 'load') {
+        await page.waitForLoadState('load');
+        return;
+    }
+    if (waitFor.kind === 'selector') {
+        await page.waitForSelector(waitFor.selector, {
+            state: 'attached',
+        });
+        return;
+    }
+    await delay(waitFor.ms);
+}
+async function waitForFonts(page) {
+    await page.evaluate(async () => {
+        if (!('fonts' in document)) {
+            return;
+        }
+        await document.fonts.ready;
+    });
+}

package/dist/capture/types.js

@@ -0,0 +1 @@
+export {};

package/dist/capture/utils.js

@@ -0,0 +1,55 @@
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+const LOCALHOST_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+export function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+export function isLocalUrl(url) {
+    return LOCALHOST_HOSTS.has(url.hostname);
+}
+export function parseCaptureUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new Error(`無効なURLです: ${rawUrl}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`サポート対象外のURLです: ${rawUrl} (http/https のみ対応)`);
+    }
+    return url;
+}
+export async function ensureParentDirectory(filePath) {
+    await mkdir(dirname(filePath), { recursive: true });
+}
+export async function ensureDirectory(path) {
+    await mkdir(path, { recursive: true });
+}
+export async function delay(ms) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export async function waitForAnimationFrames(page, frameCount = 2) {
+    await page.evaluate(async (count) => {
+        for (let index = 0; index < count; index += 1) {
+            await new Promise((resolve) => {
+                requestAnimationFrame(() => resolve());
+            });
+        }
+    }, frameCount);
+}
+export async function measurePage(page) {
+    return page.evaluate(() => {
+        const body = document.body;
+        const root = document.documentElement;
+        const scrollHeight = Math.max(body?.scrollHeight ?? 0, body?.offsetHeight ?? 0, root.scrollHeight, root.offsetHeight, root.clientHeight);
+        const viewportHeight = window.innerHeight || root.clientHeight;
+        return {
+            scrollHeight,
+            viewportHeight,
+            maxScroll: Math.max(0, scrollHeight - viewportHeight),
+        };
+    });
+}

package/dist/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { CliError, formatUsage, parseCliArgs } from './options.js';
+import { runCaptureCommand } from './run-capture.js';
+async function main() {
+    try {
+        const options = parseCliArgs();
+        const result = await runCaptureCommand(options);
+        process.stdout.write(`${result.capture.outPath}\n`);
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            process.stderr.write(`${error.message}\n`);
+            if (error.showUsage) {
+                process.stderr.write(`\n${formatUsage()}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        process.stderr.write(`${error instanceof Error ? error.message : '予期しないエラーが発生しました。'}\n`);
+        process.exitCode = 1;
+    }
+}
+await main();

package/dist/options.js

@@ -0,0 +1,192 @@
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { parseCaptureUrl } from './capture/utils.js';
+const DEFAULT_OUT_FILE = 'rollberry.mp4';
+const DEFAULT_VIEWPORT = '1440x900';
+const DEFAULT_FPS = 60;
+const DEFAULT_DURATION = 'auto';
+const DEFAULT_MOTION = 'ease-in-out-sine';
+const DEFAULT_TIMEOUT_MS = 30_000;
+export class CliError extends Error {
+    showUsage;
+    constructor(message, showUsage = false) {
+        super(message);
+        this.showUsage = showUsage;
+        this.name = 'CliError';
+    }
+}
+export function parseCliArgs(argv = process.argv.slice(2)) {
+    const [command, ...rest] = argv;
+    if (!command) {
+        throw new CliError('サブコマンドが必要です。', true);
+    }
+    if (command !== 'capture') {
+        throw new CliError(`未知のサブコマンドです: ${command}`, true);
+    }
+    const parsed = parseArgs({
+        args: rest,
+        allowPositionals: true,
+        options: {
+            out: {
+                type: 'string',
+            },
+            viewport: {
+                type: 'string',
+            },
+            fps: {
+                type: 'string',
+            },
+            duration: {
+                type: 'string',
+            },
+            motion: {
+                type: 'string',
+            },
+            timeout: {
+                type: 'string',
+            },
+            'wait-for': {
+                type: 'string',
+            },
+            'hide-selector': {
+                type: 'string',
+                multiple: true,
+            },
+            'debug-frames-dir': {
+                type: 'string',
+            },
+            manifest: {
+                type: 'string',
+            },
+            'log-file': {
+                type: 'string',
+            },
+        },
+        strict: true,
+    });
+    const rawUrl = parsed.positionals[0];
+    if (!rawUrl) {
+        throw new CliError('capture にはURLが必要です。', true);
+    }
+    const durationOption = parsed.values.duration ?? DEFAULT_DURATION;
+    if (durationOption !== 'auto' && Number.isNaN(Number(durationOption))) {
+        throw new CliError(`--duration は "auto" または数値で指定してください: ${durationOption}`);
+    }
+    const outPath = resolveOutPath(parsed.values.out ?? DEFAULT_OUT_FILE);
+    return {
+        url: parseWithCliError(rawUrl, parseCaptureUrl),
+        outPath,
+        manifestPath: parsed.values.manifest
+            ? resolveOutPath(parsed.values.manifest)
+            : deriveSidecarPath(outPath, '.manifest.json'),
+        logFilePath: parsed.values['log-file']
+            ? resolveOutPath(parsed.values['log-file'])
+            : deriveSidecarPath(outPath, '.log.jsonl'),
+        viewport: parseWithCliError(parsed.values.viewport ?? DEFAULT_VIEWPORT, parseViewport),
+        fps: parseWithCliError(parsed.values.fps ?? String(DEFAULT_FPS), parsePositiveInt),
+        duration: durationOption === 'auto'
+            ? 'auto'
+            : parseWithCliError(durationOption, parsePositiveNumber),
+        motion: parseWithCliError(parsed.values.motion ?? DEFAULT_MOTION, parseMotion),
+        timeoutMs: parseWithCliError(parsed.values.timeout ?? String(DEFAULT_TIMEOUT_MS), parsePositiveInt),
+        waitFor: parseWithCliError(parsed.values['wait-for'] ?? 'load', parseWaitFor),
+        hideSelectors: parsed.values['hide-selector'] ?? [],
+        debugFramesDir: parsed.values['debug-frames-dir']
+            ? resolveOutPath(parsed.values['debug-frames-dir'])
+            : undefined,
+    };
+}
+export function formatUsage() {
+    return [
+        'Usage:',
+        '  rollberry capture <url> [options]',
+        '',
+        'Options:',
+        '  --out <file>                Output MP4 path (default: ./rollberry.mp4)',
+        '  --viewport <WxH>           Viewport size (default: 1440x900)',
+        '  --fps <n>                  Frames per second (default: 60)',
+        '  --duration <seconds|auto>  Capture duration (default: auto)',
+        '  --motion <curve>           ease-in-out-sine | linear',
+        '  --timeout <ms>             Navigation timeout (default: 30000)',
+        '  --wait-for <mode>          load | selector:<css> | ms:<n>',
+        '  --hide-selector <css>      Hide CSS selector before capture',
+        '  --debug-frames-dir <dir>   Save raw PNG frames for debugging',
+        '  --manifest <file>          Manifest JSON path (default: <out>.manifest.json)',
+        '  --log-file <file>          Log JSONL path (default: <out>.log.jsonl)',
+    ].join('\n');
+}
+function parseWithCliError(rawValue, parser) {
+    try {
+        return parser(rawValue);
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            throw error;
+        }
+        throw new CliError(error instanceof Error ? error.message : '引数の解析に失敗しました。');
+    }
+}
+function resolveOutPath(path) {
+    return resolve(process.cwd(), path);
+}
+function deriveSidecarPath(path, suffix) {
+    const extension = /\.([^.]+)$/u.exec(path);
+    if (!extension) {
+        return `${path}${suffix}`;
+    }
+    return path.slice(0, -extension[0].length) + suffix;
+}
+function parseViewport(rawViewport) {
+    const match = /^(?<width>\d+)x(?<height>\d+)$/u.exec(rawViewport);
+    if (!match?.groups) {
+        throw new Error(`--viewport は "1440x900" の形式で指定してください: ${rawViewport}`);
+    }
+    const width = Number(match.groups.width);
+    const height = Number(match.groups.height);
+    if (width <= 0 || height <= 0) {
+        throw new Error(`--viewport の値が不正です: ${rawViewport}`);
+    }
+    return { width, height };
+}
+function parsePositiveInt(rawValue) {
+    const value = Number(rawValue);
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`正の整数を指定してください: ${rawValue}`);
+    }
+    return value;
+}
+function parsePositiveNumber(rawValue) {
+    const value = Number(rawValue);
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`正の数値を指定してください: ${rawValue}`);
+    }
+    return value;
+}
+function parseMotion(rawMotion) {
+    if (rawMotion === 'ease-in-out-sine' || rawMotion === 'linear') {
+        return rawMotion;
+    }
+    throw new Error(`--motion は ease-in-out-sine または linear です: ${rawMotion}`);
+}
+function parseWaitFor(rawWaitFor) {
+    if (rawWaitFor === 'load') {
+        return { kind: 'load' };
+    }
+    if (rawWaitFor.startsWith('selector:')) {
+        const selector = rawWaitFor.slice('selector:'.length).trim();
+        if (!selector) {
+            throw new Error('--wait-for selector:<css> の CSS セレクタが空です。');
+        }
+        return {
+            kind: 'selector',
+            selector,
+        };
+    }
+    if (rawWaitFor.startsWith('ms:')) {
+        return {
+            kind: 'delay',
+            ms: parsePositiveInt(rawWaitFor.slice('ms:'.length)),
+        };
+    }
+    throw new Error(`--wait-for は load / selector:<css> / ms:<n> のいずれかです: ${rawWaitFor}`);
+}

package/dist/run-capture.js

@@ -0,0 +1,115 @@
+import { writeFile } from 'node:fs/promises';
+import { captureVideo } from './capture/capture.js';
+import { createCaptureLogger } from './capture/logger.js';
+import { ensureParentDirectory } from './capture/utils.js';
+export async function runCaptureCommand(options) {
+    await ensureParentDirectory(options.outPath);
+    await ensureParentDirectory(options.manifestPath);
+    await ensureParentDirectory(options.logFilePath);
+    const logger = createCaptureLogger(options.logFilePath);
+    const startedAt = new Date();
+    await logger.info('capture.start', 'Capture started', {
+        url: options.url.toString(),
+        outPath: options.outPath,
+        manifestPath: options.manifestPath,
+        logFilePath: options.logFilePath,
+    });
+    try {
+        const capture = await captureVideo(options, logger);
+        const finishedAt = new Date();
+        const warnings = capture.truncated ? ['scroll_height_truncated'] : [];
+        const manifest = buildManifest({
+            status: 'succeeded',
+            options,
+            startedAt,
+            finishedAt,
+            warnings,
+            videoCreated: true,
+            result: capture,
+        });
+        await writeManifest(options.manifestPath, manifest);
+        await logger.info('capture.complete', 'Capture finished', {
+            outPath: capture.outPath,
+            frameCount: capture.frameCount,
+            durationSeconds: capture.durationSeconds,
+            manifestPath: options.manifestPath,
+        });
+        return {
+            capture,
+            manifestPath: options.manifestPath,
+            logFilePath: options.logFilePath,
+        };
+    }
+    catch (error) {
+        const finishedAt = new Date();
+        const manifest = buildManifest({
+            status: 'failed',
+            options,
+            startedAt,
+            finishedAt,
+            warnings: [],
+            videoCreated: false,
+            error,
+        });
+        await logger.error('capture.failed', 'Capture failed', {
+            name: manifest.error?.name,
+            message: manifest.error?.message,
+            manifestPath: options.manifestPath,
+        });
+        await writeManifest(options.manifestPath, manifest);
+        throw error;
+    }
+    finally {
+        await logger.close();
+    }
+}
+async function writeManifest(manifestPath, manifest) {
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+function buildManifest(input) {
+    return {
+        schemaVersion: 1,
+        status: input.status,
+        startedAt: input.startedAt.toISOString(),
+        finishedAt: input.finishedAt.toISOString(),
+        durationMs: input.finishedAt.getTime() - input.startedAt.getTime(),
+        environment: {
+            nodeVersion: process.version,
+            platform: process.platform,
+            arch: process.arch,
+        },
+        options: {
+            url: input.options.url.toString(),
+            viewport: input.options.viewport,
+            fps: input.options.fps,
+            duration: input.options.duration,
+            motion: input.options.motion,
+            timeoutMs: input.options.timeoutMs,
+            waitFor: input.options.waitFor,
+            hideSelectors: input.options.hideSelectors,
+        },
+        artifacts: {
+            videoPath: input.options.outPath,
+            manifestPath: input.options.manifestPath,
+            logFilePath: input.options.logFilePath,
+            debugFramesDir: input.options.debugFramesDir,
+            videoCreated: input.videoCreated,
+        },
+        result: input.result,
+        warnings: input.warnings,
+        error: input.error ? serializeError(input.error) : undefined,
+    };
+}
+function serializeError(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+        };
+    }
+    return {
+        name: 'Error',
+        message: typeof error === 'string' ? error : 'Unknown error',
+    };
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "rollberry",
+  "version": "0.1.0",
+  "description": "CLI to capture smooth top-to-bottom scroll videos from web pages, including localhost URLs.",
+  "type": "module",
+  "packageManager": "pnpm@10.15.0",
+  "files": [
+    "dist",
+    "README.md",
+    "regression.sample.json"
+  ],
+  "bin": {
+    "rollberry": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=24.12.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "biome check . && tsc -p tsconfig.json --noEmit",
+    "dev": "tsx src/cli.ts",
+    "browsers:install": "playwright install chromium",
+    "prepack": "npm run build",
+    "regression": "tsx scripts/run-regression-suite.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "playwright": "1.58.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.7",
+    "@types/node": "25.5.0",
+    "selfsigned": "5.5.0",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "vitest": "4.1.0"
+  }
+}

package/regression.sample.json

@@ -0,0 +1,22 @@
+{
+  "outputDir": "./artifacts/regression",
+  "cases": [
+    {
+      "name": "local-homepage",
+      "url": "http://localhost:3000",
+      "viewport": "1440x900",
+      "fps": 60,
+      "duration": "auto",
+      "waitFor": "selector:body",
+      "hideSelectors": ["#cookie-banner", ".intercom-lightweight-app"]
+    },
+    {
+      "name": "playwright-docs",
+      "url": "https://playwright.dev/",
+      "viewport": "1440x900",
+      "fps": 60,
+      "duration": 8,
+      "waitFor": "selector:main"
+    }
+  ]
+}