@a1knowhow/demo-maker 0.1.0

package/docs/getting-started.md

@@ -0,0 +1,220 @@
+# Getting started
+
+Purpose: Step-by-step from install to a first recorded MP4.
+
+## Step 1 — Install prerequisites
+
+**Goal:** Node, Chromium, and ffmpeg available.
+
+```bash
+node -v          # need 20+
+brew install ffmpeg   # macOS; or apt/winget on Linux/Windows
+```
+
+**Clone and install** (from the repo root):
+
+```bash
+npm install
+npx playwright install chromium
+```
+
+Or as a dependency in your project:
+
+```bash
+npm install -D @a1knowhow/demo-maker
+npx playwright install chromium
+```
+
+**Expected:** `npx demo-maker --help` prints usage.
+
+**Common failure:** `ffmpeg: command not found` — install ffmpeg before using `.mp4`, `cut_video`, or background audio.
+
+---
+
+## Step 2 — Run the smoke example
+
+**Goal:** Prove the CLI drives a browser.
+
+```bash
+npx demo-maker run examples/smoke.yaml --headless --fast
+```
+
+**Expected:** Scenario completes successfully (opens example.com, asserts “Example Domain”).
+
+**Common failure:** Playwright browser missing → re-run `npx playwright install chromium`.
+
+For a public docs tour (getting-started → actions → locators):
+
+```bash
+npx demo-maker run examples/demo1-introduction.yaml --headless --fast
+```
+
+For a richer GitHub Actions UI walkthrough:
+
+```bash
+npx demo-maker run examples/demo2-github-actions.yaml --headless --fast
+```
+
+---
+
+## Step 3 — Point at your app
+
+**Goal:** A minimal scenario against your product.
+
+1. Copy `examples/smoke.yaml` to e.g. `scenarios/my-app.yaml`.
+2. Set `base_url` to your app (e.g. `http://localhost:3000`).
+3. Replace steps with `navigate` / `click` / `type` / `expect_visible` for a short happy path.
+
+```yaml
+name: my-app-smoke
+description: First walkthrough
+base_url: http://localhost:3000/
+steps:
+  - action: navigate
+    url: "/"
+  - action: expect_visible
+    locator: { role: heading, name: /Welcome/i }
+  - action: wait
+    timeout_ms: 1500
+```
+
+```bash
+npx demo-maker run scenarios/my-app.yaml --headless --fast
+```
+
+**Expected:** Steps pass against your running app.
+
+**Common failure:** Locator not found → see [Locators](./locators.md) and [Repairing scenarios](./repairing-scenarios.md). Prefer `role`/`label`/`text` over CSS.
+
+---
+
+## Step 4 — Env file and auth (when needed)
+
+**Goal:** Credentials and `{{ VAR }}` without hardcoding secrets in YAML.
+
+Create `scenarios/u2.env` (do not commit secrets):
+
+```dotenv
+E2E_TEST_USER_EMAIL=you@example.com
+E2E_TEST_USER_PASSWORD=secret
+BASE_URL=http://localhost:3000/
+DEMO_WORKSPACE1=Acme Corp
+```
+
+If the scenario includes an `auth:` block, those env vars are required. Otherwise empty auth is allowed (as in smoke).
+
+```yaml
+auth:
+  email_env: E2E_TEST_USER_EMAIL
+  password_env: E2E_TEST_USER_PASSWORD
+steps:
+  - action: type
+    locator: { role: textbox, name: /email/i }
+    value: "{{ auth.email }}"
+```
+
+```bash
+npx demo-maker run scenarios/login.yaml --env-file scenarios/u2.env --fast
+```
+
+**Save session** after login for later runs:
+
+```bash
+npx demo-maker run scenarios/login.yaml --env-file scenarios/u2.env \
+  --save-storage-state=scenarios/session.json
+
+npx demo-maker run scenarios/app.yaml --env-file scenarios/u2.env \
+  --storage-state=scenarios/session.json --fast
+```
+
+---
+
+## Step 5 — Record a video (MP4)
+
+**Goal:** Polished output for demos.
+
+```yaml
+video:
+  enabled: true
+  dir: output/videos
+  filename: demo-[date:"YYYY-MM-DD-HHmm"].mp4
+  size: { width: 1920, height: 1080 }
+  viewport: { width: 1440, height: 810 }   # optional; fit laptop screen when headed
+```
+
+```bash
+npx demo-maker run scenarios/my-app.yaml --env-file scenarios/u2.env
+```
+
+**Expected:** MP4 under `output/videos/` plus a sibling `*.timing.json`.
+
+**Common failure:** `.mp4` without ffmpeg → runner keeps WebM and warns. Install ffmpeg and re-run.
+
+Details: [Video and pacing](./video-and-pacing.md).
+
+---
+
+## Step 6 — Record interactions instead of writing YAML by hand
+
+**Goal:** Capture real clicks as steps.
+
+```bash
+demo-maker record \
+  --save-to scenarios/recorded.yaml \
+  --url http://localhost:3000/ \
+  --env-file scenarios/u2.env
+```
+
+Interact in the browser, then **Ctrl+C** to save. Edit captions and locators, then `npx demo-maker run`.
+
+Continue from an existing prefix (e.g. login):
+
+```bash
+demo-maker record \
+  --continue-from scenarios/01.login.yaml \
+  --save-to scenarios/recorded-segment.yaml \
+  --fast --env-file scenarios/u2.env
+```
+
+Details: [Recording](./recording.md).
+
+---
+
+## Step 7 — Reuse fragments with imports
+
+**Goal:** Don’t copy-paste login into every scenario.
+
+```yaml
+# scenarios/full-demo.yaml
+name: full-demo
+base_url: http://localhost:3000/
+steps:
+  - import: 01.login.yaml
+  - action: click
+    locator: { role: link, name: Dashboard }
+  - import: fragments/create-item.yaml
+```
+
+Details: [Imports and fragments](./imports-and-fragments.md).
+
+---
+
+## Step 8 — YouTube chapters
+
+**Goal:** Paste chapter timestamps into a video description.
+
+```bash
+demo-maker export-chapters output/videos
+# or: demo-maker export-chapters output/videos/demo-….timing.json
+```
+
+Use `action: log` with `── Scene N: …` markers and/or step `caption:` for chapter labels.
+
+---
+
+## Next reading
+
+- Full action list: [Actions](./actions.md)
+- Locator guide: [Locators](./locators.md)
+- After UI breaks demos: [Repairing scenarios](./repairing-scenarios.md)
+- All flags: [CLI](./cli.md)

package/docs/imports-and-fragments.md

@@ -0,0 +1,78 @@
+# Imports and fragments
+
+Purpose: Compose reusable YAML without duplicating steps.
+
+## Two forms
+
+1. **Top-level `imports:`** — paths relative to the entry file; their steps run **first**, in order, then local `steps`.
+2. **Step-level `- import: path.yaml`** — expanded **in place** so you can interleave fragments.
+
+Nested imports are allowed. Circular imports error.
+
+**Metadata:** Only the **entry** file’s `name`, `base_url`, `video`, pacing, `auth`, etc. apply. Imported files contribute steps only.
+
+Paths resolve relative to the YAML file that contains the reference.
+
+## Fragment example
+
+```yaml
+# fragments/login.yaml
+name: login
+base_url: http://localhost:3000/
+steps:
+  - action: navigate
+    url: /login
+  - action: type
+    locator: { role: textbox, name: /email/i }
+    value: "{{ auth.email }}"
+  - action: type
+    locator: { role: textbox, name: /password/i }
+    value: "{{ auth.password }}"
+  - action: click
+    locator: { role: button, name: /Sign in/i }
+```
+
+## Step-level composition
+
+```yaml
+name: full-demo
+base_url: http://localhost:3000/
+steps:
+  - import: fragments/login.yaml
+  - action: click
+    locator: { role: link, name: Dashboard }
+  - import: fragments/create-item.yaml
+  - action: wait
+    timeout_ms: 2000
+```
+
+Order: login steps → click Dashboard → create-item steps → wait.
+
+## Top-level imports only
+
+```yaml
+name: full-demo
+base_url: http://localhost:3000/
+imports:
+  - fragments/login.yaml
+  - fragments/create-item.yaml
+steps:
+  - action: click
+    locator: { role: link, name: folder }
+```
+
+Order: login → create-item → click folder.
+
+## Continue-from recordings
+
+When you `demo-maker record --continue-from 01.login.yaml --save-to recorded.yaml`, the saved file typically has:
+
+```yaml
+name: recorded-…
+imports:
+  - 01.login.yaml
+steps:
+  # only newly recorded steps
+```
+
+See [Recording](./recording.md).

package/docs/library-api.md

@@ -0,0 +1,64 @@
+# Library API
+
+Purpose: Use demo-maker from TypeScript instead of the CLI.
+
+Package entry: `@a1knowhow/demo-maker` (see `src/index.ts`).
+
+```ts
+import {
+  loadScenario,
+  runScenario,
+  createDemoLogger,
+  createRegexUrlCapture,
+  type RunContext,
+} from "@a1knowhow/demo-maker";
+
+const scenario = loadScenario("./scenarios/demo.yaml", { cwd: process.cwd() });
+
+const context: RunContext = {
+  auth: {
+    email: process.env.E2E_TEST_USER_EMAIL ?? "",
+    password: process.env.E2E_TEST_USER_PASSWORD ?? "",
+  },
+  // Prefer explicit keys or an env file — avoid spreading all of process.env
+  variables: {
+    BASE_URL: scenario.base_url,
+    ...(process.env.DEMO_WORKSPACE1
+      ? { DEMO_WORKSPACE1: process.env.DEMO_WORKSPACE1 }
+      : {}),
+  },
+};
+
+const result = await runScenario(scenario, context, {
+  logger: createDemoLogger("info"),
+  headless: true,
+  cwd: process.cwd(),
+  urlCaptureHooks: [
+    createRegexUrlCapture([
+      { variable: "workspace_id", pattern: String.raw`/workspace/([^/]+)` },
+    ]),
+  ],
+});
+
+if (!result.success) {
+  throw new Error(result.error);
+}
+```
+
+## Useful exports
+
+| Export | Role |
+|--------|------|
+| `loadScenario` / `parseScenario` | YAML → scenario |
+| `runScenario` / `runScenarioOnExistingPage` | Execute |
+| `sliceScenarioByEndStep` | Truncate steps |
+| `resolveVariables` | `{{ }}` helper |
+| `formatYouTubeChapters` | Timing → chapter text |
+| `createRegexUrlCapture` / `buildUrlCaptureHooks` | URL → variable capture |
+| Types | `DemoScenario`, `DemoStep`, `Locator`, `RunContext`, `UrlCaptureRule`, … |
+
+## Options highlights
+
+`RunScenarioOptions`: `logger`, `headless`, `cwd`, `storageStatePath`, `saveStorageStatePath`, `failFast`, `endStep`, `pauseAtEnd`, `debugDir`, `urlCaptureHooks`.
+
+Relative paths in YAML (`video.dir`, file uploads) resolve against `cwd` (default `process.cwd()`).

package/docs/locators.md

@@ -0,0 +1,119 @@
+# Locators
+
+Purpose: How to target UI elements in YAML (`locator:`). Prefer accessibility over CSS.
+
+## Locator kinds
+
+Each `locator:` object uses **exactly one** shape:
+
+| Kind | YAML shape | Playwright | When to use |
+|------|------------|------------|-------------|
+| **role** | `{ role: button, name: Submit }` | `getByRole` | Buttons, links, headings, dialogs, comboboxes |
+| **label** | `{ label: Email address }` | `getByLabel` | Fields with `<label>` or `aria-label` |
+| **text** | `{ text: Acme Corp }` | `getByText` | Visible copy (substring); plain string only |
+| **placeholder** | `{ placeholder: Search… }` | `getByPlaceholder` | Inputs by placeholder |
+| **title** | `{ title: Close dialog }` | `getByTitle` | `title` attribute |
+| **selector** | `{ selector: "#id" }` | `page.locator` | **Last resort** CSS |
+
+Common roles: `button`, `textbox`, `link`, `heading`, `main`, `dialog`, `combobox`, `menuitem`, `checkbox`, `option`.
+
+## Matching rules
+
+- **Role + string `name`** — **exact** accessible name (`exact: true`)
+- **Role + regex `name`** — `/Sign in/i` for case-insensitive / partial
+- **`label`** — string or regex
+- **`text`** — substring match; **no** regex on `text` (use `role`+regex or `selector: 'text=/…/i'` as last resort)
+- **`settle_until: { text: "…" }`** — **exact** text (unlike step `locator: { text }`)
+
+## Regex in YAML
+
+Write JS-style regex as strings the parser understands:
+
+```yaml
+locator: { role: button, name: /Sign in/i }
+locator: { label: /email address/i }
+```
+
+Supported flags: `g`, `i`, `m`, `s`, `u`, `y`.
+
+**`{{ variables }}` do not work inside regex.** `/{{ DEMO_NAME }}/i` is literal. Use string fields:
+
+```yaml
+locator: { text: "{{ DEMO_NAME }}" }
+locator: { role: link, name: "{{ DEMO_NAME }}" }
+```
+
+## Variables in locators
+
+`{{ VAR }}` resolves at **run time** for string fields only (`text`, string `name`/`label`/`placeholder`/`title`/`selector`).
+
+## Prefer stable kinds
+
+`label` / `role`+`name` > `text` > `placeholder` > `selector`
+
+## Examples
+
+```yaml
+# Login button
+- action: click
+  locator: { role: button, name: /Sign in/i }
+
+# Form field
+- action: type
+  locator: { label: Email }
+  value: "{{ auth.email }}"
+
+# List row by visible name
+- action: click
+  locator: { text: "{{ DEMO_WORKSPACE1 }}" }
+
+# Search then pick option
+- action: type
+  locator: { placeholder: Search… }
+  value: Acme
+- action: click
+  locator: { role: option, name: /Acme/i }
+
+# File upload (often no a11y hook)
+- action: type
+  locator: { selector: 'input[type="file"]' }
+  value: /absolute/path/to/file.pdf
+```
+
+## Anti-patterns
+
+```yaml
+# wrong: "text" is not an ARIA role; {{ }} inside /…/i is literal
+locator:
+  role: text
+  name: /{{ DEMO_NAME }}/i
+
+# right
+locator:
+  text: "{{ DEMO_NAME }}"
+```
+
+## When a step fails
+
+1. Note step number and Playwright error (`not found`, `strict mode violation`)
+2. Isolate: `--end-step=N-1 --pause-at-end` and inspect Accessibility tree
+3. Fix locator or add unique `aria-label` in the app
+4. Or re-record a segment (`demo-maker record --continue-from …`) and transplant locators only
+
+| Problem | Fix |
+|---------|-----|
+| Button renamed | Update `name` or `/partial/i` |
+| Strict mode (2+ matches) | Exact name, unique `aria-label`, tighter regex |
+| Custom editor (no role) | Add `aria-label` → `{ label: … }` or `{ role: textbox, name: … }` |
+| Dynamic row | `{ text: "{{ VAR }}" }` |
+| Recorder wrote `(recorded)` | Fix a11y; re-record or hand-write |
+
+## Accessibility tip (for app authors)
+
+Add unique `aria-label` on inputs, editors, and buttons. In loops, suffix with index or entity name so each instance is uniquely addressable. Dialogs need `aria-label` or `aria-labelledby` on the root.
+
+## Recorder mapping
+
+When recording/importing, priority is roughly: `aria-label`/`label=` → Playwright `getBy*` code → internal selector parse → fallback `text` or `(recorded)`.
+
+See [Recording](./recording.md) and [Repairing scenarios](./repairing-scenarios.md).

package/docs/recording.md

@@ -0,0 +1,59 @@
+# Recording
+
+Purpose: Capture browser actions into YAML (or import from JSON).
+
+## Live record
+
+Uses Playwright’s recorder API (codegen without the Inspector UI). Actions stream to the CLI; **Ctrl+C** writes YAML.
+
+```bash
+demo-maker record \
+  --save-to scenarios/recorded.yaml \
+  --save-json scenarios/recording.json \
+  --url http://localhost:3000/ \
+  --base-url http://localhost:3000/
+```
+
+- `--save-to` — required output YAML
+- `--save-json` — optional raw JSON for later `--from` / `import`
+- Refuses to overwrite an existing `--save-to` on a fresh live record (delete/rename first)
+
+Edit captions, variables, and locators after saving, then `npx demo-maker run`.
+
+## Continue from existing YAML
+
+Replay a prefix scenario, then record additional steps (e.g. login once, then capture a new flow).
+
+```bash
+demo-maker record \
+  --continue-from scenarios/01.login.yaml \
+  --save-to scenarios/recorded-segment.yaml \
+  --fast \
+  --env-file scenarios/u2.env
+```
+
+- On Ctrl+C, saved YAML contains **only newly recorded steps** plus top-level `imports` pointing at the continue-from file (relative path).
+- Overwrite of `--save-to` is allowed with `--continue-from`.
+- `--end-step=N` limits replay to steps 1..N before recording starts.
+- If replay fails, the process exits and does **not** start recording.
+
+## Import from JSON
+
+Convert demo-maker recorder JSON or Chrome DevTools Recorder (Puppeteer Replay) JSON:
+
+```bash
+demo-maker record --from recording.json --save-to scenario.yaml --base-url http://localhost:3000/
+# or
+demo-maker import recording.json -o scenario.yaml --base-url http://localhost:3000/
+```
+
+## After recording
+
+1. Replace brittle selectors with `role` / `label` / `text` where possible ([Locators](./locators.md))
+2. Add `caption:` sparingly (scene titles, not every click)
+3. Wire `{{ auth.* }}` / env vars ([Variables](./variables.md))
+4. Enable `video:` when ready ([Video and pacing](./video-and-pacing.md))
+
+## Repair loop
+
+See [Repairing scenarios](./repairing-scenarios.md) for detect → isolate → continue-from → transplant locators → verify.

package/docs/repairing-scenarios.md

@@ -0,0 +1,73 @@
+# Repairing scenarios
+
+Purpose: YAML is valid but fails at runtime after UI changes. This is a **runtime** smoke loop, not schema validation.
+
+## 1. Detect drift
+
+```bash
+demo-maker check scenarios/02.create.yaml \
+  --env-file scenarios/u2.env \
+  --storage-state=scenarios/session.json
+```
+
+`check` = `run --fail-fast --fast`. Note the failing **step number** and Playwright message. Treat the browser + error as source of truth.
+
+Optional failure screenshot:
+
+```bash
+demo-maker check scenarios/02.create.yaml \
+  --env-file scenarios/u2.env \
+  --debug-dir=output/demo-debug
+```
+
+## 2. Isolate
+
+Replay only the prefix, then pause headed:
+
+```bash
+npx demo-maker run scenarios/02.create.yaml \
+  --env-file scenarios/u2.env \
+  --storage-state=scenarios/session.json \
+  --fast --end-step=7 --pause-at-end
+```
+
+Inspect the Accessibility tree (role, name, label) for the next control.
+
+## 3. Re-capture
+
+```bash
+demo-maker record \
+  --continue-from scenarios/02.create.yaml \
+  --end-step=7 \
+  --save-to _repair/segment.yaml \
+  --save-json _repair/segment.json \
+  --fast --env-file scenarios/u2.env
+```
+
+Perform the corrected path, **Ctrl+C**. Do **not** blindly overwrite the canonical YAML — transplant changed `locator` values and steps; keep `caption`, `video`, pacing, and `metadata`.
+
+## 4. Verify
+
+```bash
+demo-maker check scenarios/02.create.yaml \
+  --env-file scenarios/u2.env \
+  --storage-state=scenarios/session.json
+```
+
+Then re-run your full demo / project smoke targets if you have them.
+
+## Flags used in the loop
+
+| Flag | Purpose |
+|------|---------|
+| `--fail-fast` / `check` | Stop on first failure |
+| `--end-step=N` | Run or replay only 1..N |
+| `--pause-at-end` | Keep browser open |
+| `--debug-dir=PATH` | PNG on failure |
+| `--continue-from` | Replay then record |
+
+See [CLI](./cli.md), [Locators](./locators.md), [Recording](./recording.md).
+
+## Prefer fixing a11y
+
+When locators break, prefer adding unique `aria-label` (and dialog names) in the app over brittle CSS. Then update YAML to `{ role, name }` / `{ label }`.

package/docs/scenario-schema.md

@@ -0,0 +1,80 @@
+# Scenario schema
+
+Purpose: Top-level YAML fields for an entry scenario. Typed definitions: [`src/types.ts`](../src/types.ts).
+
+**Metadata rule:** Only the **entry** file (the path you pass to `npx demo-maker run`) supplies `name`, `base_url`, `video`, pacing, `auth`, etc. Imported files contribute **steps only**.
+
+## Required / common fields
+
+```yaml
+name: string                    # required
+description: string             # optional (may be empty)
+base_url: string                # default http://localhost:2000/
+imports: [path, ...]            # optional; prepended steps from other files
+metadata: { ... }               # optional; arbitrary (e.g. YouTube paste); ignored by runner
+auth:
+  email_env: ENV_VAR_NAME
+  password_env: ENV_VAR_NAME
+steps: []                       # required array of steps or { import: path }
+```
+
+## Pacing (optional, milliseconds)
+
+| Field | Role |
+|-------|------|
+| `step_delay_ms` | Delay after each step |
+| `slow_mo_ms` | Playwright slowMo after every browser action |
+| `typing_delay_ms` | Delay between keystrokes for `type` (per-step override allowed) |
+| `post_click_delay_ms` | Hold after click (after settle) |
+| `navigate_hold_ms` | Hold after navigate (after DOM settle) |
+| `pre_action_delay_ms` | Delay before navigate/click |
+| `action_timeout_ms` | Default Playwright action timeout (default 10000) |
+
+`--fast` overrides pacing to near-zero for smoke runs.
+
+## Video / audio / screenshots
+
+See [Video and pacing](./video-and-pacing.md).
+
+```yaml
+video:
+  enabled: true
+  dir: output/videos
+  filename: demo-[date:"YYYY-MM-DD-HHmm"].mp4
+  size: { width: 1920, height: 1080 }
+  viewport: { width: 1440, height: 810 }
+  start_step: 3
+  end_step: 20
+  caption_parallel: true
+  playback_speed: 1.0
+
+audio:
+  background: path/to/track.mp3   # mixed into final MP4 via ffmpeg
+
+screenshots:
+  dir: output/screenshots
+
+device_scale_factor: 2             # optional; crisp PNG screenshots
+```
+
+## Storage state
+
+```yaml
+storage_state: session.json       # load
+save_storage_state: session.json  # save after run
+
+url_capture:                      # optional; see docs/url-capture.md
+  - variable: workspace_id
+    pattern: "/workspace/([^/]+)"
+```
+
+CLI `--storage-state` / `--save-storage-state` override these.
+
+## Steps
+
+Each item is either:
+
+- A normal step with `action: …` (see [Actions](./actions.md)), or
+- `{ import: "relative/path.yaml" }` (see [Imports](./imports-and-fragments.md))
+
+Any step may include optional `caption:`, `timeout_ms:`, `video_exclude: true`, and action-specific fields.