screenci 0.0.43 → 0.0.45

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScreenCI Ltd
+
+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

@@ -2,94 +2,85 @@
 
 Your UI changed. Your demo videos didn't. screenci fixes that.
 
-Record product walkthroughs as code. When the UI ships, run `screenci record` and your videos regenerate. No clicky re-recordings, no stale screenshots, no passive-aggressive Slack messages from the docs team.
+Record product walkthroughs as code. When the UI ships, run
+`npx screenci record` and your videos regenerate.
 
-## Install
+ScreenCI keeps the Playwright mental model, but the output is a maintainable
+product video instead of a test report.
+
+## Install and scaffold
 
 ```bash
-npm install screenci
+npx screenci@latest init
 ```
 
-## Init a new project
+`init` creates a ready-to-run project in the current directory, installs
+dependencies, and installs Chromium by default.
 
-```bash
-npx screenci init "My Project"
-cd screenci
-npm install
+```text
+screenci.config.ts
+package.json
+tsconfig.json
+README.md
+.gitignore
+.env
+videos/
+  example.video.ts
+.github/workflows/screenci.yaml
 ```
 
-This scaffolds a ready-to-run project:
+Docs:
 
-```
-screenci/
-  screenci.config.ts     ← video settings
-  videos/
-    example.video.ts     ← your first video script
-  package.json
-  .gitignore
-```
+- Getting started: `https://screenci.com/docs`
+- Writing scripts: `https://screenci.com/docs/write-video-scripts`
+- CLI reference: `https://screenci.com/docs/reference/cli`
 
 ## Write a video
 
-Video scripts are Playwright test files with a `.video.ts` extension. If you already know Playwright, you already know 90% of this.
+Video scripts are Playwright-style files with a `.video.ts` extension. If you
+already know Playwright locators, navigation, and waiting, you already know
+most of the automation layer.
 
 ```ts
 // videos/onboarding.video.ts
-import { video } from 'screenci'
+import { hide, video } from 'screenci'
 
 video('Onboarding flow', async ({ page }) => {
-  await page.goto('https://app.example.com/signup')
-  await page.fill('input[name="email"]', 'jane@example.com')
-  await page.click('button[type="submit"]')
-  await page.waitForURL('**/dashboard')
+  await hide(async () => {
+    await page.goto('https://app.example.com/signup')
+  })
+
+  await page.getByLabel('Email').fill('jane@example.com')
+  await page.getByRole('button', { name: 'Create account' }).click()
+  await page.getByRole('heading', { name: 'Dashboard' }).waitFor()
 })
 ```
 
-Each `video()` call → one `.mp4`. The title becomes the filename.
-
-> **Full reference:** [Writing Video Tests](http://localhost:4321/reference/video-tests)
-
-### `ScreenCIPage` — animated interactions
-
-Inside `video()`, `page` is a `ScreenCIPage` — a Playwright `Page` with animated cursor and typing. You don't need to change anything; the animations happen automatically:
+Each `video()` call becomes one output video. The title becomes the filename
+and the remote video identity.
 
-| Method          | Behaviour                                       |
-| --------------- | ----------------------------------------------- |
-| `click()`       | Bezier-curve cursor move, then click            |
-| `fill()`        | Character-by-character typing                   |
-| `hover()`       | Animated cursor move                            |
-| `dragTo()`      | Animated move → mouseDown → drag → mouseUp      |
-| `page.mouse`    | Smooth bezier moves instead of instant teleport |
-| Everything else | Standard Playwright — unchanged                 |
+Inside `video()`, `page` is a `ScreenCIPage`: a Playwright `Page` with animated
+cursor movement and visible typing layered on top of normal Playwright
+behavior.
 
-All standard `page` methods (`goto`, `waitForURL`, `waitForLoadState`, `waitForTimeout`, `keyboard`, `screenshot`, `expect`, …) work exactly as documented in [Playwright's API](https://playwright.dev/docs/api/class-page).
-
-`fill()` already moves to the field, clicks it, and types, so you do not need a separate `click()` first:
-
-```ts
-const searchBox = page.getByPlaceholder('Search')
-
-await searchBox.fill('Item 1')
-```
-
-## Run it
+## Run locally
 
 ```bash
-# Dry-run: opens Playwright UI so you can verify selectors and pacing
+npx screenci test
 npx screenci test --ui
-
-# Record: captures the screen and writes .screenci/<name>/recording.mp4
-npx screenci record
 ```
 
-Or via the package scripts scaffolded by `init`:
+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
-npm run test    # → npx screenci test
-npm run record  # → npx screenci record
+npx screenci record
 ```
 
-Recordings land in `.screenci/<video-name>/recording.mp4` alongside a `data.json` with all the interaction events.
+`record` writes local artifacts into `.screenci/<video-name>/` and uploads them
+when `SCREENCI_SECRET` is configured.
 
 ## Configure
 
@@ -99,159 +90,47 @@ import { defineConfig } from 'screenci'
 
 export default defineConfig({
   projectName: 'my-project',
+  envFile: '.env',
   videoDir: './videos',
   use: {
     baseURL: 'https://app.example.com',
     recordOptions: {
-      aspectRatio: '16:9', // '16:9' | '9:16' | '1:1' | '4:3' | ...
-      quality: '1080p', // '720p' | '1080p' | '1440p' | '2160p'
-      fps: 30, // 24 | 30 | 60
-    },
-  },
-})
-```
-
-screenci enforces `workers: 1`, `retries: 0`, and `fullyParallel: false` so each generated video has one deterministic timeline. Don't fight it.
-
-## AI narration
-
-`createNarration()` maps keys to narration text (or audio files). Define it once near the top of the file, then call `await narration.key()` for the common case where the full line should run before moving on. Use `await narration.key.start()` when narration should overlap with the next actions, and `await narration.key.end()` only to close that same active cue later.
-
-```ts
-import { video, createNarration, voices } from 'screenci'
-
-const narration = createNarration({
-  voice: { name: voices.Aria },
-  languages: {
-    en: {
-      cues: {
-        intro: 'Welcome to the dashboard.',
-        addButton: 'Click here to create a new project.',
-      },
-    },
-  },
-})
-
-video('Dashboard walkthrough', async ({ page }) => {
-  await page.goto('/dashboard')
-
-  await narration.intro()
-  await page.locator('#reports').click()
-
-  await narration.addButton()
-  await page.locator('#new-project').click()
-})
-```
-
-Use this pattern:
-
-```ts
-const narration = createNarration({ ... })
-
-video('Example', async ({ page }) => {
-  await narration.intro.start() // starts narration now
-  await page.click('#filters') // runs while intro audio is still playing
-
-  await narration.details.start() // auto-ends intro, then starts details
-  await narration.details.end() // use this before navigation or the next gated action
-  await page.click('#confirm')
-})
-```
-
-### Multi-language (type-safe)
-
-TypeScript enforces that every language has the same keys. Missing a translation is a compile error.
-
-```ts
-import { createNarration, voices } from 'screenci'
-
-const narration = createNarration({
-  voice: { name: voices.Ava },
-  languages: {
-    en: {
-      cues: {
-        intro: 'Welcome to the dashboard.',
-        addButton: 'Click here to create a new project.',
-      },
-    },
-    fi: {
-      voice: { name: voices.Nora },
-      cues: {
-        intro: 'Tervetuloa hallintapaneeliin.',
-        addButton: 'Klikkaa tästä luodaksesi uuden projektin.',
-      },
+      aspectRatio: '16:9',
+      quality: '1080p',
+      fps: 60,
     },
+    trace: 'retain-on-failure',
   },
+  projects: [{ name: 'chromium' }],
 })
 ```
 
-## Hide the boring parts
+ScreenCI manages `testDir`, `testMatch`, and `retries` for you. Most other
+Playwright config still passes through.
 
-`hide()` cuts a section from the final video. Use it for logins, especially the initial page load, cookie banner dismissal, and other setup the viewer should not see.
+## Authoring helpers
 
-```ts
-import { video, hide } from 'screenci'
-
-video('Dashboard demo', async ({ page }) => {
-  await hide(async () => {
-    // viewer never sees this
-    await page.goto('/login')
-    await page.fill('input[name="email"]', 'admin@example.com')
-    await page.fill('input[name="password"]', 'hunter2')
-    await page.click('button[type="submit"]')
-    await page.waitForURL('**/dashboard')
-  })
-
-  // video starts here — dashboard is already open
-  await page.locator('#reports').click()
-})
-```
-
-## Zoom the camera
-
-`autoZoom()` follows interactions with a smooth camera pan. Wrap a form or a page section, not individual clicks.
-
-```ts
-import { video, autoZoom } from 'screenci'
-
-video('Profile settings', async ({ page }) => {
-  await page.goto('/settings/profile')
-
-  await autoZoom(
-    async () => {
-      await page.locator('#name').fill('Jane Doe')
-      await page.locator('#bio').fill('Engineer')
-      await page.locator('button[type="submit"]').click()
-    },
-    { duration: 400, amount: 0.4, easing: 'ease-in-out' }
-  )
-})
-```
-
-## API
-
-| Export            | What it does                                                       |
-| ----------------- | ------------------------------------------------------------------ |
-| `defineConfig`    | Wraps Playwright config with screenci defaults                     |
-| `video`           | Declares a video recording test                                    |
-| `createNarration` | Creates typed narration controllers with AI-generated audio        |
-| `hide`            | Cuts a section from the final video                                |
-| `autoZoom`        | Smooth camera pan that follows interactions                        |
-| `voices`          | Available voice constants (`voices.Ava`, `voices.elevenlabs(...)`) |
-
-The `page` fixture inside `video()` is a `ScreenCIPage` — a Playwright `Page` with animated cursor support wired in on all locator methods.
+| 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         |
+| `createAssets`    | Inserts timed media overlays into the recording timeline |
+| `voices`          | Available voice constants such as `voices.Ava`           |
+| `languageRegions` | Region constants such as `languageRegions.en.US`         |
 
 ## Output
 
-```
+```text
 .screenci/
   <video-name>/
-    recording.mp4   ← the raw screen capture
-    data.json       ← interaction events + cue metadata
+    recording.mp4
+    data.json
 ```
 
-Upload to screenci.com for rendering, narration generation, and the permanent embed link:
-
-```bash
-npm run retry
-```
+When `SCREENCI_SECRET` is configured, `screenci record` uploads the output to
+ScreenCI for rendering, narration generation, and hosted delivery.

package/dist/cli.d.ts

@@ -1,5 +1,14 @@
 import type { RecordingCustomVoiceRef, RecordingData } from './src/events.js';
 import type { VoiceKey } from './src/voices.js';
+import type { RecordUploadPolicy } from './src/types.js';
+type PlaywrightListReportSuite = {
+    title?: string;
+    specs?: Array<{
+        title: string;
+    }>;
+    suites?: PlaywrightListReportSuite[];
+};
+export declare function collectPlaywrightListTitles(suites: readonly PlaywrightListReportSuite[]): string[];
 type PreparedUploadAsset = {
     fileHash: string;
     path: string;
@@ -13,11 +22,21 @@ export declare function stripVoicePath(voice: VoiceKey | RecordingCustomVoiceRef
 export declare function annotateRecordingDataWithAssetHashes(data: RecordingData, assets: PreparedUploadAsset[]): RecordingData;
 export declare function formatUploadStartFailureMessage(videoName: string, status: number, responseText: string, secret: string): string;
 export declare function printUploadStartFailureMessage(videoName: string, status: number, responseText: string, secret: string): void;
+export declare function uploadRecordings(screenciDir: string, projectName: string, apiUrl: string, secret: string, specificEntry?: string, verbose?: boolean): Promise<{
+    projectId: string | null;
+    hadFailures: boolean;
+    failedVideoNames: string[];
+    failedVideoMessages: Array<{
+        videoName: string;
+        message: string;
+    }>;
+}>;
 export declare function getDevBackendUrl(): string;
 export declare function getDevFrontendUrl(): string;
 export declare function extractConfigStringLiteral(configSource: string, property: 'projectName' | 'envFile'): string | undefined;
+export declare function extractRecordUploadPolicyLiteral(configSource: string): RecordUploadPolicy | undefined;
 export declare function getConfigModuleSpecifier(resolvedConfigPath: string): string;
-export declare function ensureScreenciSecret(): Promise<string | undefined>;
+export declare function ensureScreenciSecret(resolvedConfigPath?: string): Promise<string | undefined>;
 export declare function main(): Promise<void>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,uBAAuB,EACvB,aAAa,EAEd,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AA4D/C,KAAK,mBAAmB,GAAG;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAiBD,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,GAAG,KAAK,GAAG,OAAO,CAAC,EACtD,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,GACxC,MAAM,IAAI,CAiBZ;AA0ZD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,QAAQ,GAAG,uBAAuB,GACxC,QAAQ,GAAG,uBAAuB,CAKpC;AAED,wBAAgB,oCAAoC,CAClD,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,mBAAmB,EAAE,GAC5B,aAAa,CAqEf;AAQD,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,MAAM,CAeR;AAED,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,IAAI,CAcN;AAgRD,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C;AAqID,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,aAAa,GAAG,SAAS,GAClC,MAAM,GAAG,SAAS,CAepB;AAsBD,wBAAgB,wBAAwB,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAS3E;AA2dD,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAwBxE;AAwMD,wBAAsB,IAAI,kBAiOzB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,uBAAuB,EACvB,aAAa,EAEd,MAAM,iBAAiB,CAAA;AAMxB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAkB,MAAM,gBAAgB,CAAA;AAuBxE,KAAK,yBAAyB,GAAG;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAChC,MAAM,CAAC,EAAE,yBAAyB,EAAE,CAAA;CACrC,CAAA;AAMD,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,SAAS,yBAAyB,EAAE,GAC3C,MAAM,EAAE,CAiBV;AAuJD,KAAK,mBAAmB,GAAG;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAuSD,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,GAAG,KAAK,GAAG,OAAO,CAAC,EACtD,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,GACxC,MAAM,IAAI,CAiBZ;AAiZD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,QAAQ,GAAG,uBAAuB,GACxC,QAAQ,GAAG,uBAAuB,CAKpC;AAED,wBAAgB,oCAAoC,CAClD,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,mBAAmB,EAAE,GAC5B,aAAa,CAqEf;AAQD,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,MAAM,CAeR;AAED,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,IAAI,CAcN;AA4FD,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,EACtB,OAAO,UAAQ,GACd,OAAO,CAAC;IACT,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,WAAW,EAAE,OAAO,CAAA;IACpB,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,mBAAmB,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACnE,CAAC,CAmFD;AAeD,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C;AA6FD,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,aAAa,GAAG,SAAS,GAClC,MAAM,GAAG,SAAS,CAepB;AAED,wBAAgB,gCAAgC,CAC9C,YAAY,EAAE,MAAM,GACnB,kBAAkB,GAAG,SAAS,CAmBhC;AA+BD,wBAAgB,wBAAwB,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAS3E;AA4cD,wBAAsB,oBAAoB,CACxC,kBAAkB,CAAC,EAAE,MAAM,GAC1B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA2B7B;AAiLD,wBAAsB,IAAI,kBAyRzB"}