@t3lnet/sceneforge 1.0.8 → 1.0.10

package/context/templates/base/selectors-guide.md

@@ -0,0 +1,233 @@
+# SceneForge Selectors Guide
+
+## Selector Priority
+
+When targeting elements, use this priority order for reliability:
+
+1. **data-testid** - Most reliable, designed for testing
+2. **aria-label** - Good for accessibility-labeled elements
+3. **role + text** - Semantic matching for buttons, links
+4. **name attribute** - Form inputs
+5. **placeholder** - Input placeholders
+6. **text content** - Visible text (least stable)
+7. **CSS selector** - Last resort, most brittle
+
+## Target Types in SceneForge
+
+### Using `type: selector`
+
+Direct CSS selector - most flexible but requires maintenance.
+
+```yaml
+target:
+  type: selector
+  selector: "[data-testid='submit-button']"
+```
+
+**Good selectors:**
+```yaml
+# data-testid (best)
+selector: "[data-testid='save-btn']"
+
+# aria-label
+selector: "[aria-label='Close dialog']"
+
+# role with name
+selector: "button[name='submit']"
+
+# Unique ID
+selector: "#main-header"
+
+# Playwright-specific role selector
+selector: "button:has-text('Save')"
+selector: "role=button[name='Submit']"
+```
+
+**Avoid:**
+```yaml
+# Fragile class-based selectors
+selector: ".btn.btn-primary.mt-4"
+
+# Position-based
+selector: "div > div > button:first-child"
+
+# Generated class names
+selector: ".css-1a2b3c"
+```
+
+### Using `type: button`
+
+Match button elements by text, name, or selector.
+
+```yaml
+# By visible text
+target:
+  type: button
+  text: "Save Changes"
+
+# By name attribute
+target:
+  type: button
+  name: "submit"
+
+# By selector (fallback)
+target:
+  type: button
+  selector: "[data-testid='save']"
+```
+
+### Using `type: link`
+
+Match anchor elements.
+
+```yaml
+target:
+  type: link
+  text: "Learn More"
+```
+
+### Using `type: input`
+
+Match form input elements.
+
+```yaml
+# By name (most common)
+target:
+  type: input
+  name: "email"
+
+# By placeholder text
+target:
+  type: input
+  text: "Enter your email"
+
+# By selector
+target:
+  type: input
+  selector: "[data-testid='email-input']"
+```
+
+### Using `type: text`
+
+Match any element containing specific text.
+
+```yaml
+target:
+  type: text
+  text: "Welcome back!"
+```
+
+**Use for:**
+- Headings and labels
+- Menu items
+- Any element identified by its text content
+
+## Playwright Selector Syntax
+
+SceneForge uses Playwright under the hood. You can use Playwright's selector syntax:
+
+### Role Selectors
+```yaml
+selector: "role=button[name='Submit']"
+selector: "role=link[name='Dashboard']"
+selector: "role=textbox[name='Email']"
+```
+
+### Text Selectors
+```yaml
+selector: "text=Click here"
+selector: "text=/welcome/i"     # Regex, case-insensitive
+```
+
+### Has-text Selectors
+```yaml
+selector: "button:has-text('Save')"
+selector: "div:has-text('Loading')"
+```
+
+### Combining Selectors
+```yaml
+selector: ".modal >> button:has-text('Confirm')"
+selector: "[data-testid='form'] >> input[name='email']"
+```
+
+## Common Patterns
+
+### Dropdown/Select
+```yaml
+# Click to open dropdown
+- action: click
+  target:
+    type: selector
+    selector: "[data-testid='country-select']"
+
+# Click option
+- action: click
+  target:
+    type: text
+    text: "United States"
+```
+
+### Modal Dialog
+```yaml
+# Wait for modal
+- action: wait
+  waitFor:
+    type: selector
+    value: ".modal-content"
+
+# Click modal button
+- action: click
+  target:
+    type: selector
+    selector: ".modal-content >> button:has-text('Confirm')"
+```
+
+### Dynamic Content
+```yaml
+# Wait for async content
+- action: wait
+  waitFor:
+    type: selectorHidden
+    value: ".skeleton-loader"
+
+# Now interact with loaded content
+- action: click
+  target:
+    type: selector
+    selector: "[data-testid='data-row-1']"
+```
+
+### Form Inputs
+```yaml
+# Input with label
+target:
+  type: selector
+  selector: "label:has-text('Email') >> input"
+
+# Input by placeholder
+target:
+  type: selector
+  selector: "[placeholder='Enter email address']"
+```
+
+## Debugging Selectors
+
+Run the demo in headed mode to verify selectors:
+
+```bash
+sceneforge record --definition demo.yaml --headed
+```
+
+Use browser DevTools to:
+1. Inspect element attributes
+2. Test selectors in console: `document.querySelector('[data-testid="x"]')`
+3. Check for unique identifiers
+
+## Selector Stability Tips
+
+1. **Request data-testid**: Ask developers to add test IDs
+2. **Use aria-labels**: Good for accessibility anyway
+3. **Avoid CSS classes**: Often change with styling updates
+4. **Avoid deep nesting**: Use direct selectors when possible
+5. **Test after UI changes**: Re-verify selectors periodically

package/context/templates/base/yaml-schema.md

@@ -0,0 +1,210 @@
+# SceneForge YAML Schema Reference
+
+## Demo Definition Structure
+
+```yaml
+version: 1
+name: demo-name           # Identifier (used for output folders)
+title: "Demo Title"       # Display title
+description: "Optional description"
+steps:
+  - id: step-1
+    script: "Voiceover text for this step"
+    actions:
+      - action: navigate
+        path: /page-path
+      - action: click
+        target:
+          type: button
+          text: "Click Me"
+```
+
+## Root Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `version` | number | No | Schema version (default: 1) |
+| `name` | string | Yes | Demo identifier for output folders |
+| `title` | string | Yes | Display title for the demo |
+| `description` | string | No | Optional description |
+| `steps` | DemoStep[] | Yes | Array of demo steps |
+| `media` | MediaConfig | No | Intro/outro and music config |
+
+## DemoStep
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | string | Yes | Unique step identifier |
+| `script` | string | Yes | Voiceover text (can be empty string) |
+| `actions` | DemoAction[] | Yes | Array of actions to execute |
+
+## DemoAction Types
+
+### navigate
+Navigate to a URL path.
+```yaml
+- action: navigate
+  path: /dashboard
+  waitFor:              # Optional
+    type: idle
+```
+
+### click
+Click on an element.
+```yaml
+- action: click
+  target:
+    type: button
+    text: "Submit"
+  highlight: true       # Optional: visual highlight
+  waitFor:              # Optional
+    type: selector
+    value: ".success-message"
+```
+
+### type
+Type text into an input.
+```yaml
+- action: type
+  target:
+    type: input
+    name: email
+  text: "user@example.com"
+```
+
+### hover
+Hover over an element.
+```yaml
+- action: hover
+  target:
+    type: selector
+    selector: "[data-testid='menu']"
+```
+
+### scroll
+Scroll the page by duration.
+```yaml
+- action: scroll
+  duration: 1000        # Scroll for 1 second
+```
+
+### scrollTo
+Scroll to bring an element into view.
+```yaml
+- action: scrollTo
+  target:
+    type: text
+    text: "Section Title"
+```
+
+### wait
+Wait for duration or condition.
+```yaml
+# Wait for fixed duration
+- action: wait
+  duration: 2000        # 2 seconds
+
+# Wait for condition
+- action: wait
+  waitFor:
+    type: selector
+    value: ".loaded"
+    timeout: 10000      # Optional timeout
+```
+
+### upload
+Upload a file.
+```yaml
+- action: upload
+  file: ./assets/document.pdf
+  target:               # Optional: specific file input
+    type: selector
+    selector: "input[type='file']"
+```
+
+### drag
+Drag an element.
+```yaml
+- action: drag
+  target:
+    type: selector
+    selector: ".draggable"
+  drag:
+    deltaX: 100
+    deltaY: 50
+    steps: 10           # Optional: smoothness
+```
+
+## StepTarget Types
+
+| Type | Required Fields | Description |
+|------|-----------------|-------------|
+| `button` | `text`, `name`, or `selector` | Match a button element |
+| `link` | `text`, `name`, or `selector` | Match a link element |
+| `input` | `text`, `name`, or `selector` | Match an input element |
+| `text` | `text` | Match element containing text |
+| `selector` | `selector` | Match by CSS selector |
+
+### Target Examples
+```yaml
+# By visible text
+target:
+  type: button
+  text: "Save Changes"
+
+# By name attribute
+target:
+  type: input
+  name: "username"
+
+# By CSS selector
+target:
+  type: selector
+  selector: "[data-testid='submit-btn']"
+```
+
+## WaitCondition Types
+
+| Type | Requires Value | Description |
+|------|----------------|-------------|
+| `text` | Yes | Wait for text to appear |
+| `selector` | Yes | Wait for selector to match |
+| `textHidden` | Yes | Wait for text to disappear |
+| `selectorHidden` | Yes | Wait for selector to disappear |
+| `navigation` | No | Wait for page navigation |
+| `idle` | No | Wait for network idle |
+
+### WaitCondition Examples
+```yaml
+waitFor:
+  type: text
+  value: "Success!"
+  timeout: 5000
+
+waitFor:
+  type: selectorHidden
+  value: ".loading-spinner"
+```
+
+## Media Configuration
+
+```yaml
+media:
+  intro:
+    file: ./assets/intro.mp4
+    duration: 5           # Optional: trim to seconds
+    fade: true
+    fadeDuration: 0.5
+  outro:
+    file: ./assets/outro.mp4
+  backgroundMusic:
+    file: ./assets/music.mp3
+    volume: 0.15
+    loop: true
+    fadeIn: 2
+    fadeOut: 2
+    startAt:
+      type: afterIntro
+    endAt:
+      type: beforeOutro
+```

package/context/templates/skills/balance-timing.md

@@ -0,0 +1,136 @@
+# Skill: Balance Timing
+
+Analyze and balance the timing between script duration and action duration in a SceneForge demo.
+
+## Task
+
+Review timing data from the scripts JSON and suggest adjustments to achieve better synchronization.
+
+## Input Required
+
+Provide the following:
+- **Scripts JSON data**: Content from `output/<demo>/scripts/<demo>-scripts.json`
+- **Problem steps**: Steps with timing issues (optional)
+- **Constraints**: Any timing requirements (optional)
+
+## Analysis Process
+
+### Step 1: Calculate Timing Difference
+
+For each step:
+```
+difference = stepTimingMs - estimatedDurationMs
+```
+
+- **Positive**: Actions take longer than voiceover
+- **Negative**: Voiceover takes longer than actions
+
+### Step 2: Categorize Issues
+
+| Difference | Severity | Action Needed |
+|------------|----------|---------------|
+| ±500ms | Minor | Usually acceptable |
+| 500-1500ms | Moderate | Consider adjustment |
+| >1500ms | Significant | Must adjust |
+
+### Step 3: Recommend Solutions
+
+## Output Format
+
+Provide a timing analysis report with:
+1. Summary of all steps with issues
+2. Recommended adjustments per step
+3. Updated YAML snippets
+
+## Example Analysis
+
+### Input Data
+```json
+{
+  "steps": [
+    {
+      "stepId": "intro",
+      "estimatedDurationMs": 4800,
+      "stepTimingMs": 2000,
+      "wordCount": 12
+    },
+    {
+      "stepId": "fill-form",
+      "estimatedDurationMs": 3600,
+      "stepTimingMs": 6000,
+      "wordCount": 9
+    }
+  ]
+}
+```
+
+### Analysis Output
+
+```
+## Timing Analysis Report
+
+### Step: intro
+- Script duration: 4800ms (12 words)
+- Video duration: 2000ms
+- Difference: -2800ms (voiceover too long)
+
+**Recommendation:** Add wait action to extend step duration
+
+```yaml
+- id: intro
+  script: "Welcome to this demo..."
+  actions:
+    - action: wait
+      duration: 5000  # Extended from 2000ms
+```
+
+### Step: fill-form
+- Script duration: 3600ms (9 words)
+- Video duration: 6000ms
+- Difference: +2400ms (video has dead air)
+
+**Recommendation:** Expand script to fill time
+
+**Current script (9 words):**
+"Enter your details in the form below."
+
+**Suggested script (15 words):**
+"Enter your details in the form below. We'll add your name, email, and message."
+```
+
+## Adjustment Strategies
+
+### When Video > Script (Dead Air)
+
+**Option 1: Expand script**
+- Add more context or explanation
+- Describe what user should notice
+- Preview next step
+
+**Option 2: Split into multiple steps**
+- If step has distinct phases
+- Each gets focused narration
+
+### When Script > Video (Overlap Risk)
+
+**Option 1: Add wait action**
+```yaml
+actions:
+  - action: click
+    target: ...
+  - action: wait
+    duration: 2000  # Added padding
+```
+
+**Option 2: Shorten script**
+- Remove redundant words
+- Focus on essential information
+- Split long sentences
+
+## Checklist
+
+- [ ] All steps analyzed for timing variance
+- [ ] Significant issues identified
+- [ ] Solutions provided for each issue
+- [ ] Updated YAML snippets included
+- [ ] Total runtime remains reasonable