@t3lnet/sceneforge 1.0.9 → 1.0.11

package/context/templates/base/actions-reference.md

@@ -0,0 +1,299 @@
+# SceneForge Actions Reference
+
+## Action Type Summary
+
+| Action | Purpose | Required Fields |
+|--------|---------|-----------------|
+| `navigate` | Go to URL | `path` |
+| `click` | Click element | `target` |
+| `type` | Enter text | `target`, `text` |
+| `hover` | Hover element | `target` |
+| `scroll` | Scroll page | `duration` |
+| `scrollTo` | Scroll to element | `target` |
+| `wait` | Pause execution | `duration` or `waitFor` |
+| `upload` | Upload file | `file` |
+| `drag` | Drag element | `target`, `drag` |
+
+## Detailed Action Reference
+
+### navigate
+
+Navigate the browser to a URL path. The path is appended to the base URL.
+
+```yaml
+- action: navigate
+  path: /dashboard
+```
+
+**Fields:**
+- `path` (required): URL path to navigate to
+- `waitFor` (optional): Condition to wait for after navigation
+
+**Common patterns:**
+```yaml
+# Navigate and wait for network idle
+- action: navigate
+  path: /settings
+  waitFor:
+    type: idle
+
+# Navigate and wait for specific element
+- action: navigate
+  path: /users
+  waitFor:
+    type: selector
+    value: ".user-list"
+```
+
+### click
+
+Click on an element identified by target.
+
+```yaml
+- action: click
+  target:
+    type: button
+    text: "Submit"
+```
+
+**Fields:**
+- `target` (required): Element to click
+- `highlight` (optional): Show visual highlight before click
+- `waitFor` (optional): Condition to wait for after click
+
+**Common patterns:**
+```yaml
+# Click button with highlight
+- action: click
+  target:
+    type: button
+    text: "Save"
+  highlight: true
+
+# Click and wait for result
+- action: click
+  target:
+    type: selector
+    selector: "[data-testid='submit']"
+  waitFor:
+    type: text
+    value: "Saved successfully"
+
+# Click dropdown option
+- action: click
+  target:
+    type: text
+    text: "Option 1"
+```
+
+### type
+
+Type text into an input field. Clears existing content first.
+
+```yaml
+- action: type
+  target:
+    type: input
+    name: "email"
+  text: "user@example.com"
+```
+
+**Fields:**
+- `target` (required): Input element to type into
+- `text` (required): Text to enter
+- `waitFor` (optional): Condition to wait for after typing
+
+**Common patterns:**
+```yaml
+# Type into named input
+- action: type
+  target:
+    type: input
+    name: "search"
+  text: "query term"
+
+# Type into input by placeholder
+- action: type
+  target:
+    type: selector
+    selector: "[placeholder='Enter email']"
+  text: "test@example.com"
+
+# Type and wait for autocomplete
+- action: type
+  target:
+    type: input
+    name: "city"
+  text: "New York"
+  waitFor:
+    type: selector
+    value: ".autocomplete-dropdown"
+```
+
+### hover
+
+Move cursor to hover over an element. Useful for triggering hover states, tooltips, or dropdown menus.
+
+```yaml
+- action: hover
+  target:
+    type: selector
+    selector: "[data-testid='menu']"
+```
+
+**Fields:**
+- `target` (required): Element to hover over
+- `waitFor` (optional): Condition to wait for after hover
+
+**Common patterns:**
+```yaml
+# Hover to show tooltip
+- action: hover
+  target:
+    type: selector
+    selector: ".info-icon"
+  waitFor:
+    type: selector
+    value: ".tooltip"
+
+# Hover to open dropdown menu
+- action: hover
+  target:
+    type: text
+    text: "Products"
+  waitFor:
+    type: selector
+    value: ".dropdown-menu"
+```
+
+### scroll
+
+Scroll the page for a specified duration. Creates smooth scrolling animation.
+
+```yaml
+- action: scroll
+  duration: 1500
+```
+
+**Fields:**
+- `duration` (required): Scroll duration in milliseconds
+- `waitFor` (optional): Condition to wait for after scrolling
+
+### scrollTo
+
+Scroll the page to bring an element into view.
+
+```yaml
+- action: scrollTo
+  target:
+    type: text
+    text: "Contact Section"
+```
+
+**Fields:**
+- `target` (required): Element to scroll to
+- `waitFor` (optional): Condition to wait for after scrolling
+
+### wait
+
+Pause demo execution for a duration or until a condition is met.
+
+```yaml
+# Fixed duration wait
+- action: wait
+  duration: 2000
+
+# Conditional wait
+- action: wait
+  waitFor:
+    type: selector
+    value: ".data-loaded"
+```
+
+**Fields:**
+- `duration` (optional): Wait time in milliseconds
+- `waitFor` (optional): Condition to wait for
+
+**Note:** Either `duration` or `waitFor` must be specified.
+
+**Common patterns:**
+```yaml
+# Wait for loading to complete
+- action: wait
+  waitFor:
+    type: selectorHidden
+    value: ".spinner"
+
+# Wait for text to appear
+- action: wait
+  waitFor:
+    type: text
+    value: "Data loaded"
+    timeout: 10000
+
+# Add padding between actions
+- action: wait
+  duration: 500
+```
+
+### upload
+
+Upload a file using a file input.
+
+```yaml
+- action: upload
+  file: ./assets/image.png
+```
+
+**Fields:**
+- `file` (required): Path to file (relative to YAML or absolute)
+- `target` (optional): Specific file input element
+- `waitFor` (optional): Condition to wait for after upload
+
+**Common patterns:**
+```yaml
+# Upload to specific input
+- action: upload
+  file: ./documents/report.pdf
+  target:
+    type: selector
+    selector: "#document-upload"
+
+# Upload and wait for preview
+- action: upload
+  file: ./images/photo.jpg
+  waitFor:
+    type: selector
+    value: ".preview-image"
+```
+
+### drag
+
+Drag an element by specified delta.
+
+```yaml
+- action: drag
+  target:
+    type: selector
+    selector: ".slider-handle"
+  drag:
+    deltaX: 100
+    deltaY: 0
+    steps: 20
+```
+
+**Fields:**
+- `target` (required): Element to drag
+- `drag` (required): Drag configuration
+  - `deltaX`: Horizontal movement in pixels
+  - `deltaY`: Vertical movement in pixels
+  - `steps` (optional): Number of intermediate positions for smooth animation
+- `waitFor` (optional): Condition to wait for after drag
+
+## Best Practices
+
+1. **Use specific selectors**: Prefer `data-testid` or unique attributes
+2. **Add waitFor conditions**: Ensure UI is ready before next action
+3. **Use highlight for important clicks**: Makes demos easier to follow
+4. **Group related actions**: Keep logical operations in the same step
+5. **Add wait actions for timing**: Control pacing of the demo

package/context/templates/base/cli-reference.md

@@ -0,0 +1,236 @@
+# SceneForge CLI Reference
+
+## Overview
+
+```bash
+sceneforge <command> [options]
+```
+
+## Commands
+
+### record
+Execute a demo definition and record video.
+
+```bash
+sceneforge record --definition <path> [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--definition`, `-d` | Path to demo YAML file |
+| `--base-url`, `-b` | Base URL for the application |
+| `--output`, `-o` | Output directory (default: ./output) |
+| `--headed` | Run browser in headed mode (visible) |
+| `--storage` | Path to storage state JSON |
+| `--slowmo` | Slow down actions by ms |
+| `--env-file` | Path to .env file |
+
+**Examples:**
+```bash
+# Basic recording
+sceneforge record -d demo.yaml -b http://localhost:3000
+
+# Headed mode for debugging
+sceneforge record -d demo.yaml -b http://localhost:3000 --headed
+
+# With auth state
+sceneforge record -d demo.yaml -b http://localhost:3000 --storage ./auth.json
+```
+
+### setup
+Run a setup definition to create authentication state.
+
+```bash
+sceneforge setup --definition <path> [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--definition`, `-d` | Path to setup YAML file |
+| `--base-url`, `-b` | Base URL for the application |
+| `--output`, `-o` | Output path for storage state |
+| `--headed` | Run browser in headed mode |
+
+**Example:**
+```bash
+sceneforge setup -d login-setup.yaml -b http://localhost:3000 -o ./auth.json
+```
+
+### pipeline
+Run the complete demo pipeline (record + voiceover + video processing).
+
+```bash
+sceneforge pipeline --definition <path> [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--definition`, `-d` | Path to demo YAML file |
+| `--base-url`, `-b` | Base URL for the application |
+| `--output`, `-o` | Output directory |
+| `--clean` | Clean output directory before running |
+| `--headed` | Run browser in headed mode |
+| `--storage` | Path to storage state JSON |
+| `--skip-record` | Skip recording step |
+| `--skip-voiceover` | Skip voiceover generation |
+| `--skip-concat` | Skip final concatenation |
+| `--resume` | Resume from last successful step |
+
+**Examples:**
+```bash
+# Full pipeline with clean output
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --clean
+
+# Resume after fixing issues
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --resume
+
+# Skip recording (use existing videos)
+sceneforge pipeline -d demo.yaml --skip-record
+```
+
+### split
+Split recorded video into per-step clips.
+
+```bash
+sceneforge split --demo <name> [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--demo` | Demo name (folder in output) |
+| `--output`, `-o` | Output directory |
+
+### voiceover
+Generate voiceover audio from scripts.
+
+```bash
+sceneforge voiceover --demo <name> [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--demo` | Demo name |
+| `--output`, `-o` | Output directory |
+| `--voice-id` | ElevenLabs voice ID |
+| `--no-cache` | Disable voice cache |
+
+**Environment Variables:**
+- `ELEVENLABS_API_KEY` - Your ElevenLabs API key
+- `ELEVENLABS_VOICE_ID` - Default voice ID
+
+### add-audio
+Merge audio tracks with video clips.
+
+```bash
+sceneforge add-audio --demo <name> [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--demo` | Demo name |
+| `--output`, `-o` | Output directory |
+
+### concat
+Concatenate step clips into final video.
+
+```bash
+sceneforge concat --demo <name> [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--demo` | Demo name |
+| `--output`, `-o` | Output directory |
+
+### doctor
+Run environment diagnostics.
+
+```bash
+sceneforge doctor [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--root` | Project root directory |
+| `--env-file` | Environment file path |
+| `--json` | Output as JSON |
+
+**Checks:**
+- ffmpeg installation
+- ffprobe installation
+- Environment variables (ELEVENLABS_API_KEY, etc.)
+
+### context
+Manage LLM context files for AI coding assistants.
+
+```bash
+sceneforge context <subcommand> [options]
+```
+
+**Subcommands:**
+- `deploy` - Deploy context files
+- `list` - List deployed context
+- `remove` - Remove context files
+- `preview` - Preview context content
+- `skill` - Manage skills
+
+See dedicated context documentation for details.
+
+## Output Structure
+
+```
+output/
+  <demo-name>/
+    videos/           # Raw step recordings
+    scripts/          # Generated script JSON
+    audio/            # Synthesized voiceover
+    final/            # Concatenated output
+    test-results/     # Playwright artifacts
+```
+
+## Common Workflows
+
+### First-time Demo Creation
+
+```bash
+# 1. Create auth state if needed
+sceneforge setup -d setup.yaml -b http://localhost:3000 -o auth.json
+
+# 2. Record demo
+sceneforge record -d demo.yaml -b http://localhost:3000 --storage auth.json --headed
+
+# 3. Generate voiceover
+sceneforge voiceover --demo my-demo
+
+# 4. Process video
+sceneforge add-audio --demo my-demo
+sceneforge concat --demo my-demo
+```
+
+### Using Pipeline
+
+```bash
+# Full automated pipeline
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --clean
+
+# After making script changes
+sceneforge pipeline -d demo.yaml -b http://localhost:3000 --skip-record
+```
+
+### Debugging
+
+```bash
+# Run diagnostics
+sceneforge doctor
+
+# Record in headed mode with slow motion
+sceneforge record -d demo.yaml -b http://localhost:3000 --headed --slowmo 500
+```

package/context/templates/base/project-overview.md

@@ -0,0 +1,58 @@
+# SceneForge Project Overview
+
+SceneForge is a toolkit for creating automated browser demo videos with voiceover narration. It uses YAML definitions to describe demo workflows that are executed via Playwright, then processes the recordings into polished video content with synthesized voice narration.
+
+## Core Concepts
+
+### Demo Definition
+A YAML file that describes a complete demo workflow. It contains:
+- **Metadata**: name, title, description
+- **Steps**: logical groupings of actions with voiceover scripts
+- **Media config** (optional): intro/outro videos, background music
+
+### Demo Step
+A logical unit within a demo. Each step contains:
+- **id**: Unique identifier for the step
+- **script**: Voiceover text that will be synthesized to speech
+- **actions**: Array of browser interactions to execute
+
+### Demo Action
+A single browser interaction within a step:
+- **navigate**: Go to a URL
+- **click**: Click an element
+- **type**: Enter text into an input
+- **hover**: Hover over an element
+- **scroll/scrollTo**: Scroll the page or to an element
+- **wait**: Pause for duration or condition
+- **upload**: Upload a file
+- **drag**: Drag and drop interaction
+
+## Project Architecture
+
+```
+packages/
+  sceneforge/       # Main CLI and runtime library
+    cli/            # CLI commands
+    context/        # LLM context generation (this module)
+    src/            # Public API exports
+  shared/           # Shared types and schemas
+  playwright/       # Playwright demo runner
+  generation/       # Voice synthesis and script generation
+  extension/        # Chrome extension for recording
+```
+
+## Typical Workflow
+
+1. **Define demo** - Create a YAML file with steps and actions
+2. **Record** - Run `sceneforge record` to execute actions and capture video
+3. **Generate voiceover** - Run `sceneforge voiceover` to synthesize speech
+4. **Process video** - Run `sceneforge pipeline` for the full process
+5. **Iterate** - Adjust timing, scripts, and actions as needed
+
+## Key Files
+
+- `*.yaml` - Demo definition files
+- `output/videos/` - Recorded video clips per step
+- `output/audio/` - Synthesized voiceover audio
+- `output/scripts/` - Generated script JSON with timing data
+- `output/final/` - Final concatenated video output