# Flowcorder Agent Context

Flowcorder is an installable CLI, local capture runner, and local Composer for making repeatable web app demo videos.

## Product Promise

Developers install Flowcorder beside their app, create flows in code, run those flows against the live app, and compose polished videos locally. No hosted editor is required for the core workflow.

## Install Flowcorder

```bash
pnpm add -D flowcorder
pnpm flowcorder init
pnpm flowcorder doctor
pnpm flowcorder run onboarding
pnpm flowcorder open
pnpm flowcorder compose onboarding-1778352213555
```

## CLI Surface

- `flowcorder init`: scaffold `flowcorder.config.ts`, `flowcorder/flows`, `flowcorder/auth`, and sample files.
- `flowcorder open`: start the local sidecar server and Studio UI with Composer.
- `flowcorder list`: list available flow definitions.
- `flowcorder doctor`: check config, app reachability, Playwright, FFmpeg, auth, fixtures, and output paths.
- `flowcorder run <flow-id>`: run a flow and write capture artifacts.
- `flowcorder compose <capture-id>`: render a capture into a polished video from the CLI.
- `flowcorder auth setup`: create or refresh authenticated browser state.
- `flowcorder docs`: print documentation and agent entrypoints.

## Consumer Project Contract

```text
my-app/
  flowcorder.config.ts
  flowcorder/
    auth/
      login.setup.ts
    fixtures/
      launch-demo.json
    flows/
      onboarding.flow.ts
  .flowcorder/
    onboarding-1778352213555/
      capture.json
      steps.json
      cursor-track.json
      recording.webm
      final.png
    composed/
      onboarding.mp4
```

`flowcorder/` is developer-authored source and should be committed. `.flowcorder/` is generated runtime state and usually should not be committed.

## Config Shape

```ts
import { defineConfig } from "flowcorder";

export default defineConfig({
  envFile: ".env",
  studioPort: 3888,
  app: {
    mode: "attach",
    baseUrl: "http://localhost:3000",
    readyUrl: "http://localhost:3000",
  },
  api: {
    baseUrl: "http://localhost:8080",
  },
  capture: {
    viewport: { width: 1280, height: 960 },
    deviceScaleFactor: 2,
    headless: true,
  },
  paths: {
    flows: "./flowcorder/flows",
    output: "./.flowcorder",
  },
  auth: {
    setup: "./flowcorder/auth/login.setup.ts",
  },
});
```

## Flow Shape

```ts
import { defineFlow } from "flowcorder";

export default defineFlow({
  id: "onboarding",
  name: "Onboarding Demo",
  description: "Show signup, dashboard, and first action.",
  estimatedDuration: "45s",
  async run({ page, app, step, pause }) {
    await step("open", "Open the app", async () => {
      await page.goto(app.url("/"), { waitUntil: "networkidle" });
      await pause(800);
    });

    await step("start", "Start onboarding", async () => {
      await page.getByRole("button", { name: /get started/i }).click();
      await pause(800);
    });
  },
});
```

## Agent Instructions

When asked to create a Flowcorder flow:

1. Inspect the app routes, authentication model, and stable selectors.
2. Create or update `flowcorder.config.ts`.
3. Add or update a flow under `flowcorder/flows`.
4. Prefer accessible selectors: role, label, placeholder, text, and test id.
5. Keep demo-specific data in `flowcorder/fixtures`.
6. Put auth setup in `flowcorder/auth/login.setup.ts`.
7. Run `flowcorder doctor`.
8. Run `flowcorder run <flow-id>`.
9. If capture succeeds, run `flowcorder compose <capture-id>` or ask the developer to open Composer with `flowcorder open`.
10. Report the capture id and generated files under `.flowcorder/`.

## Composer

Composer is Flowcorder's local timeline for editing capture output. It runs inside the local Studio launched by `flowcorder open`.

Composer should support:

- capture library
- timeline trimming
- scene ordering
- cursor track playback
- camera zooms and focus regions
- frames and backgrounds
- landscape and vertical presets
- local FFmpeg export

Composer must not require uploading captures to a hosted editor.