# Integrate ScreenCI

> Turn a flow in your app into a polished, narrated product video that you regenerate whenever the UI changes.

You are an AI agent integrating ScreenCI into this project. Work through the steps below in order.

## 0. Use npm throughout

This brief uses **npm** commands (lockfile: `package-lock.json`). Use npm for **every** command below, including CI. Do not mix package managers.

If the project's root lockfile shows a different manager, follow that manager's brief instead: `/integrate.md` (npm), `/integrate-pnpm.md` (pnpm), or `/integrate-yarn.md` (yarn).

## 1. Scaffold the project (do this first)

Run this in the repository root before anything else. Always pass `--yes`; without it the command blocks on prompts and hangs. No account or setup token is needed.

```bash
npm init screenci@latest -- --yes
```

- init generates `.github/workflows/screenci.yaml`, scaffolds `screenci.config.ts` and `recordings/`, and installs the **`screenci` agent skill** at the repository root so you can author videos. The project name defaults to the repository root directory name.
- If the user already has a `SCREENCI_SECRET` from an existing account (shared across their org's projects), pass it as the first argument so recordings upload straight to their organization: `npm init screenci@latest PASTE_YOUR_SCREENCI_SECRET_HERE -- --yes`. Otherwise `record` (step 4) uploads under a local, anonymous trial session with no sign-in.

## 2. Wire up the app server (if recording a local app)

If the videos navigate to this project's own app, configure `screenci/screenci.config.ts` with a CI-aware `webServer` before authoring. Skip this step if the videos only navigate to a remote URL (staging, production).

```ts
webServer: {
  command: process.env.CI ? 'npm run preview' : 'npm run dev',
  cwd: '..', // path from screenci/ to the project root
  url: process.env.CI ? 'http://localhost:4173' : 'http://localhost:5173',
  reuseExistingServer: !process.env.CI,
  timeout: 120_000,
},
use: {
  baseURL: process.env.CI ? 'http://localhost:4173' : 'http://localhost:5173',
},
```

To also build this project's app in CI, uncomment the "Install app dependencies" / "Build app" hints in the generated `.github/workflows/screenci.yaml` and add the root lockfile to its `cache-dependency-path` (the file shows where). Do not hand-write the workflow. Match ports and build commands to the framework, and keep `webServer.command` on npm.

## 3. Author a video for the requested flow

The installed `screenci` skill guides authoring. Create one video for the feature or files the user pointed you at:

- Add `recordings/<flow>.screenci.ts` and remove the starter `recordings/example.screenci.ts`.
- Read the referenced source files and pages to learn the real routes, selectors, and flow. If you only have a live URL (or this brief's URL carried a `?live` flag), use the `playwright-cli` skill to explore it first.
- Every video must include narration via `video.narration({ en: { ... } })` and open by stating its purpose.
- Wrap setup (auth, initial navigation, loading) in `hide()`, then move through the demo with visible clicks.
- When the requested flow includes app-managed copy, background music / sound effects, or reusable ScreenCI-made intros / outros, use the matching fixtures instead of hard-coding around them: `video.values(...)`, `video.audio(...)`, and `selected(name, options)` render dependencies.

## 4. Verify, then record it yourself

Run both commands yourself once tests pass. Do not stop after authoring and ask the user to record.

```bash
npx screenci test    # run until green; fix selectors/flow and rerun
npx screenci record  # capture the final video once tests pass
```

`record` uploads immediately either way. Without a `SCREENCI_SECRET` it uploads under an anonymous trial; with one, straight to the user's organization. Renders without a secret, and free-tier renders, include a ScreenCI watermark. Mention that signing up (or upgrading) removes it.

Then report the URL `record` printed (it starts with the app's domain, e.g. `https://app.screenci.com/record/...`) so the user can open it. Without a `SCREENCI_SECRET`, this is also how they view and claim the anonymous trial recording.

## Full documentation

Every documentation page is also available as raw markdown by appending `.md` to its URL (for example `https://screenci.com/docs/video-script-basics.md`).

### Getting Started

- [Overview](/docs.md): How ScreenCI works: record locally, render in the service, and serve from a CDN. The service never sees your source code, and the CLI is open source.
- [Agent Integration](/docs/agent-integration.md): The recommended path: point a coding agent at the integration brief so it scaffolds ScreenCI, authors a video for your flow, and records it.
- [Manual Setup & First Video](/docs/manual-setup.md): Wire ScreenCI up by hand: initialize a project, run the starter video locally, and record your first final video.
- [Video Script Basics](/docs/video-script-basics.md): Author .screenci.ts files with Playwright-like APIs, ScreenCI narration and camera helpers, and workflow-aware pacing.
- [CI Setup](/docs/ci-setup.md): Understand the generated GitHub Actions workflow, required secrets, and how to keep CI recordings deterministic.

### Fixtures

- [Narration](/docs/guides/narration.md): Attach spoken cues to a video, overlap narration with visible UI motion, choose voices, use speech markup, and connect ElevenLabs for custom voices.
- [Overlays](/docs/guides/overlays.md): Add intro clips, corner logos, transitions, and timed overlays to ScreenCI recordings from files, HTML, or React.
- [Render Dependencies](/docs/guides/dependencies.md): Reuse another ScreenCI video or screenshot with selected(...): embed its currently selected output, inherit its audio, optionally carry subtitles, and keep dependents updated when the source render changes.
- [Languages](/docs/guides/languages.md): Record per-language video versions from one script: set browser locale automatically, localize narration, values, overlays, and audio, and control the recording mode.

### Guides

- [Animated Interactions](/docs/guides/animated-interactions.md): Understand how ScreenCI instruments the Playwright page so visible actions like clicks, typing, mouse movement, and scrolling are animated.
- [Camera and Zooming](/docs/guides/camera-and-zooming.md): Choose between autoZoom and manual framing, and use camera direction to guide attention without making the video frantic.
- [Screenshots](/docs/guides/screenshots.md): Capture branded still screenshots with the screenshot() fixture: crop to a component, set quality and dark mode, and frame the shot on a background with overlays.
- [Editor](/docs/guides/editor.md): Remix render options, narration text, voices, overlays, and languages from the web app. Everything is editable by default: arrays declare blank editor-owned names, and code values stay editable in the web editor.
- [Public URLs and Embeds](/docs/guides/public-urls-and-embeds.md): Enable public delivery for a video, understand stable language-specific URLs, and embed ScreenCI outputs in other sites.
- [Redact Sensitive Content](/docs/guides/redact.md): Keep secrets out of a recording with redact: mask locators, typed values, and always-secret elements in the page before the frame is captured, so they are never uploaded.
- [Screen Audio](/docs/guides/screen-audio.md): Capture system audio alongside the screen recording and mix it into the rendered video. Linux only, with an automatic, isolated per-worker capture sink.
- [Update ScreenCI](/docs/guides/update-screenci.md): Upgrade the screenci package, refresh Playwright when needed, and verify that existing videos still behave as expected.
- [Version History](/docs/guides/version-history.md): Every render is kept as a version. Select which one a public URL serves, roll back to an earlier render, and understand per-language retention. Paid feature.
- [Organisation & SSO](/docs/guides/organisation.md): Manage organisation members and roles, and enforce single sign-on with SAML through your own identity provider. SSO and member management are a Business feature.
- [Anonymous Trial](/docs/guides/anonymous-trial.md): Record without an account: what the anonymous trial allows (including a preview of expressive narration and multiple languages), its limits, and what happens to that content after you sign up.

### Reference

- [CLI](/docs/reference/cli.md): Command reference for screenci init, test, record, project info, and public delivery commands.
- [Configuration](/docs/reference/configuration.md): Configure project identity, file locations, rendering defaults, upload behavior, and Playwright integration in screenci.config.ts.
- [Public Delivery API](/docs/reference/public-delivery-api.md): Technical reference for the unauthenticated endpoints that serve published videos, thumbnails, subtitles, and metadata.