screenci 0.0.69 → 0.0.71

package/README.md

@@ -3,53 +3,45 @@
 Your UI changed. Your demo videos didn't. screenci fixes that.
 
 Record product walkthroughs as code. When the UI ships, run
-`npx screenci record` and your videos regenerate.
+`npx screenci record` and your videos regenerate. You keep the Playwright
+mental model, but the output is a maintainable product video instead of a
+test report.
 
-ScreenCI keeps the Playwright mental model, but the output is a maintainable
-product video instead of a test report.
+Learn more at [screenci.com](https://screenci.com).
 
-## Install and scaffold
+## Get started
 
 ```bash
 npm init screenci@latest
+# or
 pnpm create screenci
 ```
 
-`init` creates a ready-to-run, self-contained `screenci/` directory ("the
-island") with its own dependencies, and installs Chromium by default. The
-island is deliberately isolated from any surrounding workspace, which makes
-installation reliable inside complex monorepos. When using `npm init`, pass
-extra initializer flags after `--`, for example
-`npm init screenci@latest -- --yes --package-manager pnpm`.
-
-```text
-screenci/
-  screenci.config.ts
-  package.json
-  package-lock.json        # or pnpm-lock.yaml / yarn.lock
-  .gitignore
-  videos/
-    example.video.ts
-.github/workflows/screenci.yaml   # at the repo root, scoped to screenci/
-```
+This scaffolds a self-contained `screenci/` directory with its own
+dependencies and installs Chromium. The directory is isolated from the
+surrounding workspace, which keeps installation reliable inside monorepos.
+
+Then write a video, run it locally, and record the final output:
 
-`screenci test` and `screenci record` work both from inside `screenci/` and
-from the repository root.
+```bash
+npx screenci test      # author the video
+npx screenci record    # render and upload the final video
+```
 
-Docs:
+Full docs:
 
-- Getting started: `https://screenci.com/docs`
-- Writing scripts: `https://screenci.com/docs/write-video-scripts`
-- CLI reference: `https://screenci.com/docs/reference/cli`
+- [Getting started](https://screenci.com/docs)
+- [Writing scripts](https://screenci.com/docs/video-script-basics)
+- [CLI reference](https://screenci.com/docs/reference/cli)
 
 ## Write a video
 
-Video scripts are Playwright-style files with a `.video.ts` extension. If you
+Video scripts are Playwright-style files with a `.screenci.ts` extension. If you
 already know Playwright locators, navigation, and waiting, you already know
 most of the automation layer.
 
 ```ts
-// videos/onboarding.video.ts
+// videos/onboarding.screenci.ts
 import { hide, speed, time, video } from 'screenci'
 
 video('Onboarding flow', async ({ page }) => {
@@ -70,101 +62,32 @@ video('Onboarding flow', async ({ page }) => {
 ```
 
 Each `video()` call becomes one output video. The title becomes the filename
-and the remote video identity.
-
-Inside `video()`, `page` is a `ScreenCIPage`: a Playwright `Page` with animated
-cursor movement and visible typing layered on top of normal Playwright
-behavior.
+and the remote video identity. Inside `video()`, `page` is a `ScreenCIPage`: a
+Playwright `Page` with animated cursor movement and visible typing layered on
+top of normal Playwright behavior.
 
 `hide()` removes setup entirely. `speed()` and `time()` keep a section visible
-but remap its rendered duration. Narration cue audio keeps its original
-playback speed.
-
-## Run locally
-
-```bash
-npx screenci test
-npx screenci test --ui
-```
-
-Use `test` for the normal authoring loop. It runs the video scripts through
-Playwright without starting the final recording and upload path.
-
-## Record the final output
-
-```bash
-npx screenci record
-```
-
-On the first run without `SCREENCI_SECRET` in an interactive terminal, `record`
-prints a one-time ScreenCI link, waits for you to finish sign-in in the browser,
-saves the secret into the project env file, and then continues. In a
-non-interactive session (no terminal, or `SCREENCI_NONINTERACTIVE=1`) `record`
-does not wait: it prints the sign-in link and exits, so you can open the link,
-sign in, choose a plan, and rerun `record`, which then detects the completed
-session and continues. Set `SCREENCI_SECRET` ahead of time to skip sign-in
-entirely. Pending auth state is cached in `.screenci/link-session.json`, so
-rerunning `record` reuses the same link until it expires or completes. Recorded
-artifacts still live in `.screenci/<video-name>/`.
-
-## Configure
-
-```ts
-// screenci.config.ts
-import { defineConfig } from 'screenci'
-
-export default defineConfig({
-  projectName: 'my-project',
-  envFile: '.env',
-  videoDir: './videos',
-  use: {
-    baseURL: 'https://app.example.com',
-    recordOptions: {
-      aspectRatio: '16:9',
-      quality: '1080p',
-      fps: 60,
-    },
-    trace: 'retain-on-failure',
-  },
-  projects: [{ name: 'chromium' }],
-})
-```
-
-ScreenCI manages `testDir`, `testMatch`, and `retries` for you. Most other
-Playwright config still passes through.
-
-If you keep local runtime secrets in an env file, point `envFile` at it or use
-the project `.env`. ScreenCI loads that file automatically for CLI commands.
-That is also the right place for BYOK-style secrets such as
-`ELEVENLABS_API_KEY`. ScreenCI does not store raw API keys from your env file.
+but remap its rendered duration.
 
 ## Authoring helpers
 
-| Export            | What it does                                              |
-| ----------------- | --------------------------------------------------------- |
-| `defineConfig`    | Wraps Playwright config with ScreenCI defaults            |
-| `video`           | Declares a video recording test                           |
-| `createNarration` | Creates typed narration controllers                       |
-| `hide`            | Cuts setup or cleanup out of the visible recording        |
-| `autoZoom`        | Smooth camera follow for an interaction block             |
-| `zoomTo`          | Manual camera framing for a locator or point              |
-| `resetZoom`       | Returns from manual framing to the full viewport          |
-| `createOverlays`  | Inserts timed media overlays into the recording timeline  |
-| `voices`          | Available voice constants such as `voices.Ava`            |
-| `modelTypes`      | Narration model constants such as `modelTypes.consistent` |
-
-## Output
-
-```text
-.screenci/
-  <video-name>/
-    recording.mp4
-    data.json
-```
-
-When `SCREENCI_SECRET` is configured, `screenci record` uploads the output to
-ScreenCI for rendering, narration generation, and hosted delivery.
-
-For narration authoring, keep cues short and usually one sentence at a time.
-That makes overlap timing easier to manage and should reduce TTS regeneration
-cost when only one line changes.
+| Export            | What it does                                             |
+| ----------------- | -------------------------------------------------------- |
+| `defineConfig`    | Wraps Playwright config with ScreenCI defaults           |
+| `video`           | Declares a video recording test                          |
+| `createNarration` | Creates typed narration controllers                      |
+| `hide`            | Cuts setup or cleanup out of the visible recording       |
+| `autoZoom`        | Smooth camera follow for an interaction block            |
+| `zoomTo`          | Manual camera framing for a locator or point             |
+| `resetZoom`       | Returns from manual framing to the full viewport         |
+| `createOverlays`  | Inserts timed media overlays into the recording timeline |
+| `voices`          | Available voice constants such as `voices.Ava`           |
+| `modelTypes`      | Narration model constants                                |
+
+See the [docs](https://screenci.com/docs) for configuration, narration,
+camera, and CI setup.
+
+## Community
+
+Questions, ideas, or want to show off your videos? Join us on
+[Discord](https://discord.gg/DyjSRFzeBc).

package/dist/cli.d.ts

@@ -69,6 +69,7 @@ export declare function extractConfigStringLiteral(configSource: string, propert
 export declare function extractRecordUploadPolicyLiteral(configSource: string): RecordUploadPolicy | undefined;
 export declare function extractMockRecordLiteral(configSource: string): boolean | undefined;
 export declare function getConfigModuleSpecifier(resolvedConfigPath: string): string;
+export declare function extractGrep(args: string[]): string | undefined;
 export declare function ensureScreenciSecret(resolvedConfigPath?: string, opts?: {
     interactive?: boolean;
     pollAuth?: boolean;

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -342,7 +342,15 @@ async function uploadRecordingCandidate(candidate, screenciDir, projectName, api
     let plan = null;
     try {
         uploadAbort.throwIfAborted();
-        const recordingPath = resolve(screenciDir, entry, 'recording.mp4');
+        // A screenshot recording uploads its raw page capture (always a PNG) through
+        // the same recording endpoint a video uses; the renderer reads those bytes as
+        // the capture. Videos upload recording.mp4. Output kind defaults to 'video'.
+        const isScreenshot = data.output === 'screenshot';
+        const recordingFileName = isScreenshot
+            ? (data.screenshot?.path ?? 'screenshot.png')
+            : 'recording.mp4';
+        const recordingContentType = isScreenshot ? 'image/png' : 'video/mp4';
+        const recordingPath = resolve(screenciDir, entry, recordingFileName);
         if (!existsSync(recordingPath)) {
             progressReporter.complete(progressIndex, 'failure');
             return {
@@ -350,7 +358,7 @@ async function uploadRecordingCandidate(candidate, screenciDir, projectName, api
                 videoId: null,
                 hadFailure: true,
                 videoName,
-                failureMessage: `Missing recording.mp4 for "${videoName}"`,
+                failureMessage: `Missing ${recordingFileName} for "${videoName}"`,
                 recordId,
             };
         }
@@ -408,7 +416,7 @@ async function uploadRecordingCandidate(candidate, screenciDir, projectName, api
         uploadAbort.throwIfAborted();
         const fileStat = await stat(recordingPath);
         if (verbose) {
-            logger.info(`Uploading recording.mp4 size=${(fileStat.size / 1024 / 1024).toFixed(1)}MB`);
+            logger.info(`Uploading ${recordingFileName} size=${(fileStat.size / 1024 / 1024).toFixed(1)}MB`);
         }
         const recordingResponse = await withUploadRetry(async () => {
             const stream = createReadStream(recordingPath);
@@ -420,7 +428,7 @@ async function uploadRecordingCandidate(candidate, screenciDir, projectName, api
                 return await fetch(`${apiUrl}/cli/upload/${recordingId}/recording`, {
                     method: 'PUT',
                     headers: {
-                        'Content-Type': 'video/mp4',
+                        'Content-Type': recordingContentType,
                         'Content-Length': String(fileStat.size),
                         'X-ScreenCI-Secret': secret,
                         ...(elevenLabsApiKey
@@ -1417,6 +1425,49 @@ async function updateVideoVisibility(videoId, isPublic, configPath) {
     }
     logger.info(`${isPublic ? 'Made public' : 'Made private'}: ${videoId}`);
 }
+// Extract a `--grep <value>` / `--grep=<value>` from the pass-through args so a
+// remote trigger can forward it as a filter (records only matching videos).
+export function extractGrep(args) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === '--grep' || arg === '-g') {
+            return args[i + 1];
+        }
+        if (arg.startsWith('--grep=')) {
+            return arg.slice('--grep='.length);
+        }
+    }
+    return undefined;
+}
+// `screenci record --remote` triggers the project's GitHub Actions recording
+// workflow instead of recording locally. The project is resolved from the
+// existing SCREENCI_SECRET + config `projectName`, exactly like the other
+// authenticated commands; the backend dispatches the workflow using the GitHub
+// token stored for the project. An optional `--grep` records only matching
+// videos/screenshots.
+async function triggerRemoteRun(configPath, grep) {
+    const { screenciConfig, secret, apiUrl } = await requireScreenCISecret(configPath, { interactive: detectInteractiveSession() });
+    const res = await fetch(`${apiUrl}/cli/trigger-run`, {
+        method: 'POST',
+        headers: {
+            'X-ScreenCI-Secret': secret,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            projectName: screenciConfig.projectName,
+            ...(grep ? { grep } : {}),
+        }),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Failed to trigger remote run: ${res.status} ${text}${hint401(res.status, secret)}`);
+    }
+    logger.info(grep
+        ? `Triggered the remote recording workflow for "${screenciConfig.projectName}" (filter: ${grep}).`
+        : `Triggered the remote recording workflow for "${screenciConfig.projectName}".`);
+}
 function getLastRecordFilePath(screenciDir) {
     return resolve(screenciDir, SCREENCI_LAST_RECORD_FILE);
 }
@@ -1669,9 +1720,17 @@ export async function main() {
         .description('Record videos using Playwright')
         .option('-v, --verbose', 'verbose output')
         .option('--poll-auth', 'wait for sign-in to complete (polling every 5s, up to 5 minutes) instead of exiting, then continue recording')
+        .option('--remote', 'trigger the GitHub Actions recording workflow for this project remotely instead of recording locally')
         .allowUnknownOption(true)
         .action(async () => {
         const parsed = parseRecordCliArgs(getSubcommandArgv('record'));
+        // `--remote` is a pure dispatch: it fires the project's GitHub Actions
+        // recording workflow and exits, so there is no local Playwright run. A
+        // pass-through `--grep` becomes the remote recording filter.
+        if (parsed.remote) {
+            await triggerRemoteRun(parsed.configPath, extractGrep(parsed.otherArgs));
+            return;
+        }
         let playwrightFailure = null;
         try {
             await run('record', parsed.otherArgs, parsed.configPath, parsed.verbose, false, parsed.pollAuth);
@@ -1911,6 +1970,7 @@ function parseRecordCliArgs(args) {
     let configPath;
     let verbose = false;
     let pollAuth = false;
+    let remote = false;
     const otherArgs = [];
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -1931,6 +1991,9 @@ function parseRecordCliArgs(args) {
         else if (arg === '--poll-auth') {
             pollAuth = true;
         }
+        else if (arg === '--remote') {
+            remote = true;
+        }
         else {
             otherArgs.push(arg);
         }
@@ -1939,6 +2002,7 @@ function parseRecordCliArgs(args) {
         configPath,
         verbose,
         pollAuth,
+        remote,
         otherArgs,
     };
 }