rollberry 0.1.5

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+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.1.5] - 2026-03-18
+
+### Changed
+
+- Reduced default auto-scroll speed from 1800 px/s to 800 px/s for better
+  readability during capture.
+- Republished under new maintainer account.
+
+## [0.1.3] - 2026-03-15
+
+### Changed
+
+- README now includes a dedicated `Using With npx` section with version-pinned
+  examples and common usage patterns.
+
+## [0.1.2] - 2026-03-15
+
+### Added
+
+- `SECURITY.md`, `CONTRIBUTING.md`, GitHub issue forms, and a pull request
+  template.
+- Contact guidance pointing users to https://co-r-e.com/contact where private
+  contact is required.
+
+### Changed
+
+- MIT copyright holder is now `CORe Inc.`.
+- Branch protection policy now also covers `develop` and `release/*`, with
+  `mokuwaki` as the only bypass user.
+
+## [0.1.1] - 2026-03-15
+
+### Added
+
+- MIT license metadata and `LICENSE` file for open source distribution.
+- GitHub Actions trusted publishing workflow for npm releases on `v*` tags.
+- Maintainer release process documentation for `npx rollberry ...` distribution.
+
+### Changed
+
+- README rewritten around real `npx` usage, common capture examples, and
+  operational troubleshooting.
+- Package metadata now includes repository, homepage, bug tracker, and keywords.
+
+## [0.1.0] - 2026-03-15
+
+### Added
+
+- Initial public CLI release for smooth top-to-bottom page capture.
+- `localhost`, `127.0.0.1`, and self-signed `https://localhost` support.
+- Sidecar manifest and JSONL log output.
+- Regression suite runner and fixture-backed integration tests.

package/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to Rollberry
+
+Thank you for contributing to Rollberry.
+
+## Before You Start
+
+- Open an issue for bugs, feature requests, or larger changes before starting
+  implementation.
+- For security issues, do not open a public issue. Use
+  https://co-r-e.com/contact instead.
+- By contributing, you agree that your changes will be distributed under the
+  MIT license used by this repository.
+
+## Development Setup
+
+```bash
+corepack pnpm install
+corepack pnpm exec playwright install chromium
+corepack pnpm check
+corepack pnpm test
+```
+
+## Pull Request Expectations
+
+- Keep changes focused and avoid mixing unrelated work.
+- Update docs when CLI behavior or release/operational workflow changes.
+- Add or update tests when behavior changes.
+- Keep `README.md`, `CHANGELOG.md`, and sample config files aligned with the
+  code when relevant.
+
+## Branch Protection and Reviews
+
+The protected branches are:
+
+- `main`
+- `develop`
+- `release/*`
+
+For contributors other than `mokuwaki`:
+
+- direct push is not allowed on protected branches
+- merge requires at least one approval
+- the latest push must still be approved by someone else
+
+`mokuwaki` is the only configured bypass user for these protected branches.
+
+## Release Notes
+
+Rollberry remains on the `v0.x.x` line for now. Release prep should update:
+
+- `package.json`
+- `CHANGELOG.md`
+- any user-facing docs affected by the release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CORe Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# 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.
+
+Maintained by CORe Inc.
+
+## Quick Start
+
+Requirements:
+
+- Node.js `24.12.0+`
+- `ffmpeg` and `ffprobe` available on `PATH`
+
+Install nothing globally. Run it directly:
+
+```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'
+```
+
+On the first run, if Playwright Chromium is missing, Rollberry installs it
+automatically. `ffmpeg` is not auto-installed.
+
+## Using With npx
+
+The normal way to run Rollberry is `npx`.
+
+Use the latest published version:
+
+```bash
+npx rollberry capture http://localhost:3000 --out ./artifacts/demo.mp4
+```
+
+Pin a specific version:
+
+```bash
+npx rollberry@0.1.2 capture http://localhost:3000 --out ./artifacts/demo.mp4
+```
+
+Capture a local development server:
+
+```bash
+npx rollberry capture http://localhost:3000 \
+  --out ./artifacts/local.mp4 \
+  --wait-for selector:body
+```
+
+Capture a public page:
+
+```bash
+npx rollberry capture https://playwright.dev \
+  --out ./artifacts/playwright.mp4 \
+  --duration 8
+```
+
+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
+- if you want reproducible automation, pin the package version with
+  `npx rollberry@<version> ...`
+
+## What You Get
+
+Each run writes:
+
+- `video.mp4`: the rendered capture
+- `video.manifest.json`: environment, options, result, and failure details
+- `video.log.jsonl`: structured operational logs
+
+You can override the sidecar paths with `--manifest` and `--log-file`.
+
+## Common Examples
+
+Capture a development site:
+
+```bash
+npx rollberry capture http://localhost:3000 --out ./artifacts/local.mp4
+```
+
+Capture a public site at a fixed duration:
+
+```bash
+npx rollberry capture https://playwright.dev \
+  --out ./artifacts/playwright.mp4 \
+  --duration 8 \
+  --fps 60
+```
+
+Wait for a selector and hide overlays:
+
+```bash
+npx rollberry capture https://example.com \
+  --wait-for selector:main \
+  --hide-selector '#cookie-banner' \
+  --hide-selector '.intercom-lightweight-app'
+```
+
+Capture multiple pages into a single video:
+
+```bash
+npx rollberry capture \
+  https://example.com \
+  https://example.com/about \
+  https://example.com/contact \
+  --out ./artifacts/multi-page.mp4
+```
+
+Add a pause between pages (the last frame of each page is held):
+
+```bash
+npx rollberry capture \
+  https://example.com \
+  https://example.com/about \
+  --page-gap 1.5 \
+  --out ./artifacts/with-gap.mp4
+```
+
+Dump raw frames for debugging:
+
+```bash
+npx rollberry capture http://localhost:3000 \
+  --out ./artifacts/debug.mp4 \
+  --debug-frames-dir ./artifacts/debug-frames
+```
+
+## CLI Options
+
+```text
+rollberry capture <url...>
+
+--out <file>                Output MP4 path
+--viewport <WxH>            Viewport size, example: 1440x900
+--fps <n>                   Frames per second
+--duration <seconds|auto>   Explicit seconds or auto
+--motion <curve>            ease-in-out-sine | linear
+--timeout <ms>              Navigation timeout
+--wait-for <mode>           load | selector:<css> | ms:<n>
+--hide-selector <css>       Hide CSS selector before capture
+--page-gap <seconds>        Pause between pages (default: 0)
+--debug-frames-dir <dir>    Save raw PNG frames
+--manifest <file>           Manifest JSON output path
+--log-file <file>           Log JSONL output path
+```
+
+## Localhost Behavior
+
+- Supports `http://localhost:*`, `https://localhost:*`,
+  `http://127.0.0.1:*`, and `http://[::1]:*`
+- Retries connection-refused errors until `--timeout`
+- Accepts self-signed certificates for localhost targets only
+- Does not start your dev server for you
+
+## Troubleshooting
+
+If `ffmpeg` is missing:
+
+```bash
+brew install ffmpeg
+```
+
+If capture fails, inspect:
+
+- `*.manifest.json` for final status and error details
+- `*.log.jsonl` for per-step structured logs
+
+If a site keeps shifting during capture:
+
+- wait for a stable selector with `--wait-for selector:...`
+- hide chat widgets, cookie banners, and sticky overlays with `--hide-selector`
+- keep dynamic dev-only overlays out of the page when possible
+
+## Support and Contact
+
+- General contact: https://co-r-e.com/contact
+- Security issues: see [SECURITY.md](./SECURITY.md)
+- Contribution guide: see [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+## Local Development
+
+```bash
+corepack pnpm install
+corepack pnpm exec playwright install chromium
+corepack pnpm check
+corepack pnpm test
+corepack pnpm build
+```
+
+Run from the repository:
+
+```bash
+corepack pnpm dev -- capture http://localhost:3000 --out ./artifacts/demo.mp4
+```
+
+Run the regression suite:
+
+```bash
+cp regression.sample.json regression.sites.json
+corepack pnpm regression -- --config ./regression.sites.json
+```
+
+## Release Flow
+
+Rollberry stays on the `v0.x.x` line for now.
+
+1. Update `package.json` version and `CHANGELOG.md`
+2. Commit the release prep
+3. Create an annotated tag like `git tag -a v0.1.2 -m "Release v0.1.2"`
+4. Push `main` and the tag to GitHub
+5. GitHub Actions publishes to npm via trusted publishing
+
+Trusted publishing setup expected by this repo:
+
+- GitHub repository: `co-r-e/rollberry`
+- Workflow filename: `.github/workflows/publish.yml`
+- Trigger: push tag `v*`
+- In npm package settings, add a trusted publisher that matches the repository
+  and workflow above
+
+## License
+
+[MIT](./LICENSE)

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are provided for the latest published `v0.x.x` release and the
+current `main` branch on a best-effort basis.
+
+## Reporting a Vulnerability
+
+Do not open a public GitHub issue for suspected security vulnerabilities.
+
+Please contact us here instead:
+
+- https://co-r-e.com/contact
+
+Include as much detail as possible:
+
+- affected version
+- reproduction steps
+- impact assessment
+- proof of concept, if available
+
+We will review the report privately and respond through the contact channel.

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: options.urls.some(isLocalUrl),
+    });
+    const page = await context.newPage();
+    page.setDefaultTimeout(options.timeoutMs);
+    await page.addInitScript(() => {
+        history.scrollRestoration = 'manual';
+    });
+    return { browser, page };
+}
+export async function navigateWithRetry(page, url, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    const canRetry = isLocalUrl(url);
+    while (true) {
+        const remainingMs = Math.max(1, deadline - Date.now());
+        try {
+            await page.goto(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,167 @@
+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) {
+    if (options.urls.length === 0) {
+        throw new Error('少なくとも1つのURLを指定してください。');
+    }
+    await Promise.all([
+        ensureParentDirectory(options.outPath),
+        ensureParentDirectory(options.logFilePath),
+        ensureParentDirectory(options.manifestPath),
+        options.debugFramesDir
+            ? ensureDirectory(options.debugFramesDir)
+            : undefined,
+    ]);
+    const { browser, page } = await openBrowserSession(options, logger);
+    try {
+        const encoder = await createVideoEncoder({
+            fps: options.fps,
+            outPath: options.outPath,
+        });
+        const pages = [];
+        let totalFrameCount = 0;
+        let totalDurationSeconds = 0;
+        let frameOffset = 0;
+        let anyTruncated = false;
+        for (const [urlIndex, url] of options.urls.entries()) {
+            const { pageResult, lastFrame } = await capturePageFrames({
+                page,
+                url,
+                encoder,
+                options,
+                logger,
+                frameOffset,
+                urlIndex,
+            });
+            pages.push(pageResult);
+            totalFrameCount += pageResult.frameCount;
+            totalDurationSeconds += pageResult.durationSeconds;
+            frameOffset += pageResult.frameCount;
+            anyTruncated = anyTruncated || pageResult.truncated;
+            const isLastPage = urlIndex === options.urls.length - 1;
+            if (options.pageGapSeconds > 0 && !isLastPage) {
+                const gapFrameCount = await writeGapFrames({
+                    encoder,
+                    frame: lastFrame,
+                    fps: options.fps,
+                    gapSeconds: options.pageGapSeconds,
+                    debugFramesDir: options.debugFramesDir,
+                    frameOffset,
+                });
+                totalFrameCount += gapFrameCount;
+                totalDurationSeconds += gapFrameCount / options.fps;
+                frameOffset += gapFrameCount;
+            }
+        }
+        await encoder.finish();
+        await logger.info('encode.complete', 'Video encoding finished', {
+            outPath: options.outPath,
+        });
+        return {
+            outPath: options.outPath,
+            frameCount: totalFrameCount,
+            durationSeconds: totalDurationSeconds,
+            pages,
+            truncated: anyTruncated,
+        };
+    }
+    finally {
+        await browser.close();
+    }
+}
+async function capturePageFrames(input) {
+    const { page, url, encoder, options, logger, urlIndex } = input;
+    const { frameOffset } = input;
+    await logger.info('browser.open', `Opening page ${urlIndex + 1}`, {
+        url: url.toString(),
+        viewport: options.viewport,
+    });
+    await navigateWithRetry(page, url, options.timeoutMs);
+    await stabilizePage({
+        page,
+        waitFor: options.waitFor,
+        hideSelectors: options.hideSelectors,
+    });
+    const preflight = await preflightMeasurePage(page);
+    const plannedDurationSeconds = resolveDurationSeconds(options.duration, preflight.maxScroll);
+    const frames = buildScrollFrames({
+        fps: options.fps,
+        durationSeconds: plannedDurationSeconds,
+        maxScroll: preflight.maxScroll,
+        motion: options.motion,
+    });
+    const durationSeconds = frames.length / options.fps;
+    await logger.info('render.start', `Rendering frames for page ${urlIndex + 1}`, {
+        frameCount: frames.length,
+        fps: options.fps,
+        durationSeconds,
+        maxScroll: preflight.maxScroll,
+        url: url.toString(),
+    });
+    if (preflight.truncated) {
+        await logger.warn('preflight.truncated', 'Scroll height exceeded capture limit and was truncated', {
+            scrollHeight: preflight.scrollHeight,
+            url: url.toString(),
+        });
+    }
+    let lastFrame;
+    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',
+        });
+        lastFrame = frame;
+        if (options.debugFramesDir) {
+            const fileName = `${String(frameOffset + 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,
+                url: url.toString(),
+            });
+        }
+    }
+    if (!lastFrame) {
+        throw new Error(`ページのフレーム取得に失敗しました: ${url.toString()}`);
+    }
+    return {
+        pageResult: {
+            url: url.toString(),
+            frameCount: frames.length,
+            durationSeconds,
+            scrollHeight: preflight.scrollHeight,
+            truncated: preflight.truncated,
+        },
+        lastFrame,
+    };
+}
+async function writeGapFrames(input) {
+    const { encoder, frame, fps, gapSeconds, debugFramesDir, frameOffset } = input;
+    const gapFrameCount = Math.round(fps * gapSeconds);
+    if (gapFrameCount <= 0) {
+        return 0;
+    }
+    for (let i = 0; i < gapFrameCount; i++) {
+        if (debugFramesDir) {
+            const fileName = `${String(frameOffset + i).padStart(5, '0')}.png`;
+            await writeFile(`${debugFramesDir}/${fileName}`, frame);
+        }
+        await encoder.writeFrame(frame);
+    }
+    return gapFrameCount;
+}

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 = 800;
+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;