@t3lnet/sceneforge 1.0.8 → 1.0.10

package/context/templates/skills/write-step-script.md

@@ -0,0 +1,136 @@
+# Skill: Write Step Script
+
+Write voiceover script text for a SceneForge demo step.
+
+## Task
+
+Create engaging, clear voiceover script that explains the actions in a demo step.
+
+## Input Required
+
+Provide the following:
+- **Step ID**: The identifier of the step
+- **Actions**: The actions that will be performed
+- **Context**: What has happened before this step
+- **Target duration**: Approximate time (optional)
+
+## Output Format
+
+A single `script` field value suitable for voice synthesis:
+- Natural, conversational tone
+- Explains what's happening and why
+- Matches approximate action timing
+- Clean punctuation for speech synthesis
+
+## Writing Guidelines
+
+### Speaking Rate
+- Target: ~150 words per minute
+- 5 words ≈ 2 seconds
+- 15 words ≈ 6 seconds
+
+### Tone
+- Conversational, not robotic
+- Second person ("you") or first person plural ("we")
+- Action-oriented ("Click", "Enter", "Notice")
+
+### Structure
+- Start with action verb when possible
+- Explain purpose, not just mechanics
+- Add context for unfamiliar features
+
+## Examples
+
+### Simple Click Action
+
+**Actions:**
+```yaml
+- action: click
+  target:
+    type: button
+    text: "Save"
+```
+
+**Script:**
+```
+"Click Save to store your changes."
+```
+
+### Form Entry
+
+**Actions:**
+```yaml
+- action: type
+  target: { type: input, name: "email" }
+  text: "user@example.com"
+- action: type
+  target: { type: input, name: "password" }
+  text: "********"
+```
+
+**Script:**
+```
+"Enter your email address and password to sign in to your account."
+```
+
+### Feature Introduction
+
+**Actions:**
+```yaml
+- action: hover
+  target:
+    type: selector
+    selector: ".analytics-panel"
+- action: wait
+  duration: 2000
+```
+
+**Script:**
+```
+"The analytics panel provides real-time insights into your project's performance. You can see visitor counts, engagement metrics, and conversion rates at a glance."
+```
+
+### Navigation
+
+**Actions:**
+```yaml
+- action: click
+  target:
+    type: link
+    text: "Settings"
+- action: wait
+  waitFor:
+    type: idle
+```
+
+**Script:**
+```
+"Navigate to Settings to customize your preferences and configure your account options."
+```
+
+## Anti-Patterns to Avoid
+
+**Too mechanical:**
+```
+"Click the button that says Save."
+```
+
+**Too verbose:**
+```
+"Now what we're going to do is we're going to click on this Save button here to save all of the changes that we've made."
+```
+
+**Stating the obvious:**
+```
+"You can see there is a button. The button is blue. Click on it."
+```
+
+## Checklist
+
+Before finalizing:
+- [ ] Natural, conversational language
+- [ ] Appropriate length for action duration
+- [ ] Explains purpose, not just action
+- [ ] No filler words
+- [ ] Proper punctuation for speech
+- [ ] Consistent tone with other steps

package/context/templates/stages/stage1-actions.md

@@ -0,0 +1,236 @@
+# Stage 1: Action Generation
+
+This stage focuses on creating the action sequences that will be executed by Playwright to record the demo video.
+
+## Objectives
+
+1. Define clear, reliable action sequences
+2. Choose stable, maintainable selectors
+3. Add appropriate wait conditions
+4. Structure steps logically
+
+## Action Generation Guidelines
+
+### Step Structure
+
+Each step should represent a logical unit of the demo:
+
+```yaml
+- id: create-new-item
+  script: ""  # Leave empty for now, fill in Stage 2
+  actions:
+    - action: click
+      target:
+        type: button
+        text: "New Item"
+    - action: wait
+      waitFor:
+        type: selector
+        value: ".modal-content"
+    - action: type
+      target:
+        type: input
+        name: "item-name"
+      text: "My New Item"
+    - action: click
+      target:
+        type: button
+        text: "Create"
+```
+
+### Selector Selection Strategy
+
+**Priority Order:**
+1. `[data-testid="..."]` - Best stability
+2. `[aria-label="..."]` - Good for accessible UIs
+3. `role=button[name="..."]` - Semantic, readable
+4. `button:has-text("...")` - Text-based fallback
+5. CSS selectors - Last resort
+
+**Examples:**
+```yaml
+# Best: data-testid
+target:
+  type: selector
+  selector: "[data-testid='submit-btn']"
+
+# Good: aria-label
+target:
+  type: selector
+  selector: "[aria-label='Close dialog']"
+
+# Acceptable: role with text
+target:
+  type: button
+  text: "Submit"
+
+# Avoid: complex CSS paths
+target:
+  type: selector
+  selector: "div.container > form > div:nth-child(3) > button"
+```
+
+### Wait Conditions
+
+Always add wait conditions after actions that trigger:
+- Network requests
+- Animations/transitions
+- Modal dialogs
+- Dynamic content loading
+
+```yaml
+# After navigation
+- action: navigate
+  path: /dashboard
+  waitFor:
+    type: idle
+
+# After click that loads content
+- action: click
+  target:
+    type: button
+    text: "Load Data"
+  waitFor:
+    type: selector
+    value: ".data-table"
+
+# After click that opens modal
+- action: click
+  target:
+    type: button
+    text: "Settings"
+  waitFor:
+    type: selector
+    value: ".settings-modal"
+
+# Wait for spinner to disappear
+- action: wait
+  waitFor:
+    type: selectorHidden
+    value: ".loading-spinner"
+```
+
+## Common Patterns
+
+### Form Filling
+```yaml
+- id: fill-contact-form
+  script: ""
+  actions:
+    - action: type
+      target:
+        type: input
+        name: "name"
+      text: "John Smith"
+    - action: type
+      target:
+        type: input
+        name: "email"
+      text: "john@example.com"
+    - action: type
+      target:
+        type: selector
+        selector: "textarea[name='message']"
+      text: "Hello, I would like to inquire about..."
+    - action: click
+      target:
+        type: button
+        text: "Send Message"
+      waitFor:
+        type: text
+        value: "Message sent!"
+```
+
+### Dropdown Selection
+```yaml
+- id: select-country
+  script: ""
+  actions:
+    - action: click
+      target:
+        type: selector
+        selector: "[data-testid='country-dropdown']"
+    - action: wait
+      waitFor:
+        type: selector
+        value: ".dropdown-menu"
+    - action: click
+      target:
+        type: text
+        text: "United States"
+```
+
+### Modal Workflow
+```yaml
+- id: confirm-deletion
+  script: ""
+  actions:
+    - action: click
+      target:
+        type: button
+        text: "Delete"
+    - action: wait
+      waitFor:
+        type: selector
+        value: ".confirmation-modal"
+    - action: click
+      target:
+        type: selector
+        selector: ".confirmation-modal >> button:has-text('Confirm')"
+    - action: wait
+      waitFor:
+        type: selectorHidden
+        value: ".confirmation-modal"
+```
+
+### Async Content
+```yaml
+- id: load-report
+  script: ""
+  actions:
+    - action: click
+      target:
+        type: button
+        text: "Generate Report"
+    - action: wait
+      waitFor:
+        type: selectorHidden
+        value: ".generating-spinner"
+        timeout: 30000
+    - action: wait
+      waitFor:
+        type: selector
+        value: ".report-content"
+```
+
+## Testing Actions
+
+Run in headed mode to verify actions work correctly:
+
+```bash
+sceneforge record --definition demo.yaml --base-url http://localhost:3000 --headed
+```
+
+**Debugging tips:**
+- Add `--slowmo 500` to slow down execution
+- Watch for selector failures in the console
+- Check if wait conditions are adequate
+- Verify timing between actions
+
+## Step ID Conventions
+
+Use descriptive, kebab-case IDs:
+- `login-to-dashboard`
+- `create-new-project`
+- `upload-document`
+- `configure-settings`
+- `submit-and-confirm`
+
+## Checklist Before Stage 2
+
+- [ ] All actions execute without errors
+- [ ] Selectors are stable (use data-testid where possible)
+- [ ] Wait conditions prevent race conditions
+- [ ] Steps are logically grouped
+- [ ] Step IDs are descriptive
+- [ ] Demo completes successfully in headed mode

package/context/templates/stages/stage2-scripts.md

@@ -0,0 +1,197 @@
+# Stage 2: Script Writing
+
+This stage focuses on writing voiceover scripts that will be synthesized to speech and synchronized with the recorded actions.
+
+## Objectives
+
+1. Write clear, engaging voiceover scripts
+2. Match script duration to action timing
+3. Optimize for voice synthesis
+4. Create natural pacing
+
+## Script Writing Guidelines
+
+### Target Speaking Rate
+
+**~150 words per minute** is the ideal speaking rate for clarity.
+
+Quick estimation:
+- 5 words ≈ 2 seconds
+- 15 words ≈ 6 seconds
+- 30 words ≈ 12 seconds
+
+### Script Format
+
+```yaml
+steps:
+  - id: navigate-to-dashboard
+    script: "Let's start by navigating to the dashboard where we can see an overview of all our projects."
+    actions:
+      - action: navigate
+        path: /dashboard
+```
+
+### Writing Style
+
+**Do:**
+- Use conversational, natural language
+- Start sentences with action words ("Click", "Notice", "Let's")
+- Explain the purpose of actions
+- Add context for viewers unfamiliar with the app
+
+**Don't:**
+- Use overly technical jargon without explanation
+- Write long, complex sentences
+- Include filler words ("um", "uh", "basically")
+- Repeat obvious visual information
+
+### Script Examples
+
+**Good:**
+```yaml
+script: "Click the Create button to open the new project form. Here we'll enter the basic details for our project."
+```
+
+**Avoid:**
+```yaml
+script: "So basically what we're going to do now is we're going to click on this button here that says Create and that's going to open up a form."
+```
+
+### Timing Alignment
+
+Match script length to action complexity:
+
+**Short actions (click, hover):**
+```yaml
+- id: click-save
+  script: "Click Save to store your changes."
+  actions:
+    - action: click
+      target:
+        type: button
+        text: "Save"
+```
+
+**Longer actions (form filling):**
+```yaml
+- id: fill-user-details
+  script: "Enter the user's information in the form. We'll add their name, email address, and select their role from the dropdown menu."
+  actions:
+    - action: type
+      target: { type: input, name: "name" }
+      text: "Jane Smith"
+    - action: type
+      target: { type: input, name: "email" }
+      text: "jane@company.com"
+    - action: click
+      target: { type: selector, selector: "[data-testid='role-select']" }
+    - action: click
+      target: { type: text, text: "Administrator" }
+```
+
+### Voice Synthesis Considerations
+
+ElevenLabs handles most natural speech patterns, but consider:
+
+**Punctuation affects pacing:**
+- Periods (.) create full pauses
+- Commas (,) create brief pauses
+- Ellipsis (...) creates hesitation
+
+**Emphasis:**
+- Use sentence structure for emphasis
+- Place important words at sentence start/end
+
+**Numbers and abbreviations:**
+- Write out numbers for clarity: "three" not "3"
+- Spell out abbreviations: "API" → "A P I" or "application programming interface"
+
+## Common Patterns
+
+### Introduction Step
+```yaml
+- id: intro
+  script: "Welcome to this demo of the Project Management dashboard. I'll show you how to create a new project and assign team members."
+  actions:
+    - action: wait
+      duration: 2000
+```
+
+### Navigation Narration
+```yaml
+- id: go-to-settings
+  script: "Let's head over to the Settings page where we can configure our preferences."
+  actions:
+    - action: click
+      target:
+        type: link
+        text: "Settings"
+    - action: wait
+      waitFor:
+        type: idle
+```
+
+### Feature Highlight
+```yaml
+- id: show-filter
+  script: "Notice the filter panel on the left. This allows you to narrow down results by date, status, or category."
+  actions:
+    - action: hover
+      target:
+        type: selector
+        selector: ".filter-panel"
+      highlight: true
+    - action: wait
+      duration: 1500
+```
+
+### Form Walkthrough
+```yaml
+- id: complete-form
+  script: "Fill in the required fields. Start with the project name, then add a description. Finally, select a category from the dropdown."
+  actions:
+    - action: type
+      target: { type: input, name: "name" }
+      text: "Q1 Marketing Campaign"
+    - action: type
+      target: { type: selector, selector: "textarea[name='description']" }
+      text: "Campaign planning and execution for Q1 product launch."
+    - action: click
+      target: { type: selector, selector: "[data-testid='category-select']" }
+    - action: click
+      target: { type: text, text: "Marketing" }
+```
+
+### Conclusion Step
+```yaml
+- id: outro
+  script: "That completes our walkthrough. You've learned how to create projects, assign team members, and configure basic settings. For more tutorials, visit our documentation."
+  actions:
+    - action: wait
+      duration: 2000
+```
+
+## Duration Estimation
+
+Calculate approximate script duration:
+
+```
+word_count / 2.5 = seconds
+```
+
+Example: 25 words / 2.5 = 10 seconds
+
+Compare with expected action duration and adjust:
+- Add detail if actions take longer
+- Trim script if too long
+- Add `wait` actions for padding
+
+## Checklist Before Stage 3
+
+- [ ] All steps have scripts (none empty)
+- [ ] Scripts explain what's happening
+- [ ] Language is clear and conversational
+- [ ] Technical terms are explained
+- [ ] Script length roughly matches action duration
+- [ ] No spelling or grammar errors
+- [ ] Intro and outro provide context