@t3lnet/sceneforge 1.0.8 → 1.0.10

package/context/templates/skills/debug-selector.md

@@ -0,0 +1,193 @@
+# Skill: Debug Selector
+
+Help diagnose and fix selector issues in SceneForge demo actions.
+
+## Task
+
+Analyze a failing selector and provide working alternatives.
+
+## Input Required
+
+Provide the following:
+- **Current selector**: The selector that's not working
+- **Target element description**: What element you're trying to select
+- **Error message**: Error from Playwright (if available)
+- **Page context**: What page/feature contains the element
+
+## Debugging Process
+
+### Step 1: Identify the Problem
+
+Common selector issues:
+- **Element not found**: Selector doesn't match anything
+- **Multiple matches**: Selector is too broad
+- **Timing issue**: Element not ready when selector runs
+- **Dynamic content**: Element changes between loads
+
+### Step 2: Analyze Current Selector
+
+Evaluate the selector:
+- Is it using stable attributes?
+- Is it too specific or too broad?
+- Does it depend on DOM structure?
+
+### Step 3: Provide Alternatives
+
+Generate multiple alternatives ordered by reliability.
+
+## Output Format
+
+```markdown
+## Selector Debug Report
+
+### Current Selector
+`[selector]`
+
+### Problem Analysis
+[Description of why it's failing]
+
+### Alternative Selectors (Best to Worst)
+
+1. **Best: data-testid**
+   ```yaml
+   selector: "[data-testid='element-id']"
+   ```
+   Stability: High | Reason: Direct test identifier
+
+2. **Good: aria-label**
+   ```yaml
+   selector: "[aria-label='Button description']"
+   ```
+   Stability: Good | Reason: Accessibility attribute
+
+3. **Acceptable: role + text**
+   ```yaml
+   selector: "button:has-text('Click Me')"
+   ```
+   Stability: Medium | Reason: Text may change
+
+### Recommended Wait Condition
+[If timing is the issue]
+
+### Implementation
+[Complete YAML action with recommended selector]
+```
+
+## Common Issues and Solutions
+
+### Issue: Element Not Found
+
+**Cause**: Selector doesn't match element attributes
+
+**Solution**: Inspect element in DevTools and find stable attributes
+
+```yaml
+# Instead of
+selector: ".btn-submit"
+
+# Use
+selector: "[data-testid='submit-form']"
+# or
+selector: "button:has-text('Submit')"
+```
+
+### Issue: Multiple Elements Match
+
+**Cause**: Selector too broad
+
+**Solution**: Add context or use more specific selector
+
+```yaml
+# Instead of
+selector: "button"
+
+# Use
+selector: ".modal-dialog >> button:has-text('Confirm')"
+# or
+selector: "[data-testid='modal-confirm-btn']"
+```
+
+### Issue: Timing/Race Condition
+
+**Cause**: Element not yet in DOM when selector runs
+
+**Solution**: Add wait condition before action
+
+```yaml
+# Add wait before the problematic action
+- action: wait
+  waitFor:
+    type: selector
+    value: ".content-loaded"
+    timeout: 10000
+
+- action: click
+  target:
+    type: selector
+    selector: "[data-testid='element']"
+```
+
+### Issue: Dynamic ID/Classes
+
+**Cause**: IDs like `element-abc123` change on each load
+
+**Solution**: Use attribute starts-with or contains
+
+```yaml
+# Instead of
+selector: "#user-abc123"
+
+# Use
+selector: "[id^='user-']"
+# or find a stable attribute
+selector: "[data-user-id]"
+```
+
+### Issue: Element Inside Shadow DOM
+
+**Cause**: Element in web component shadow root
+
+**Solution**: Use Playwright's pierce selector
+
+```yaml
+selector: "pierce/#shadow-element"
+```
+
+### Issue: Element in iframe
+
+**Cause**: Element inside frame
+
+**Solution**: Handle frames in Playwright
+
+```yaml
+# Note: May require code changes
+# Consider if action can be restructured
+selector: "iframe[name='frame'] >> [data-testid='element']"
+```
+
+## Selector Testing Commands
+
+Test selectors in browser DevTools:
+
+```javascript
+// Test CSS selector
+document.querySelector('[data-testid="element"]')
+
+// Test multiple matches
+document.querySelectorAll('button').length
+
+// Test Playwright-style selector (conceptual)
+// button:has-text('Submit')
+Array.from(document.querySelectorAll('button'))
+  .filter(b => b.textContent.includes('Submit'))
+```
+
+## Checklist
+
+- [ ] Element exists in DOM (check DevTools)
+- [ ] Selector syntax is valid
+- [ ] No typos in attribute names/values
+- [ ] Element is visible (not display:none)
+- [ ] Element is not inside iframe
+- [ ] Timing is adequate (add wait if needed)
+- [ ] Selected correct element (not duplicate)

package/context/templates/skills/generate-actions.md

@@ -0,0 +1,94 @@
+# Skill: Generate Demo Actions
+
+Generate SceneForge demo actions for a web page or workflow.
+
+## Task
+
+Create a complete set of demo actions for the specified page or user workflow.
+
+## Input Required
+
+Provide the following information:
+- **Page URL or description**: What page/feature are we demoing?
+- **User goal**: What should the user accomplish?
+- **Key interactions**: What elements will be clicked/typed?
+- **Expected outcome**: What happens when the workflow completes?
+
+## Output Format
+
+Generate a YAML steps array with:
+- Logical step groupings
+- Descriptive step IDs
+- Empty script fields (to be filled later)
+- Reliable selectors
+- Appropriate wait conditions
+
+## Process
+
+1. **Analyze the workflow**: Break into logical steps
+2. **Identify elements**: Determine selectors for each interaction
+3. **Add wait conditions**: Ensure stability between actions
+4. **Structure output**: Create valid YAML
+
+## Example Output
+
+```yaml
+steps:
+  - id: navigate-to-form
+    script: ""
+    actions:
+      - action: navigate
+        path: /contact
+        waitFor:
+          type: idle
+
+  - 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: "I'm interested in learning more about your services."
+
+  - id: submit-form
+    script: ""
+    actions:
+      - action: click
+        target:
+          type: button
+          text: "Send Message"
+        highlight: true
+        waitFor:
+          type: text
+          value: "Thank you"
+```
+
+## Selector Guidelines
+
+Use this priority when choosing selectors:
+1. `[data-testid="..."]` - Most reliable
+2. `[aria-label="..."]` - Accessibility labels
+3. `role=button[name="..."]` - Semantic roles
+4. `input[name="..."]` - Form inputs by name
+5. `button:has-text("...")` - Text fallback
+
+## Checklist
+
+Before finalizing, verify:
+- [ ] All user interactions are captured
+- [ ] Steps are logically grouped
+- [ ] IDs are descriptive (kebab-case)
+- [ ] Wait conditions prevent race conditions
+- [ ] Selectors are as stable as possible
+- [ ] YAML syntax is valid

package/context/templates/skills/optimize-demo.md

@@ -0,0 +1,218 @@
+# Skill: Optimize Demo
+
+Optimize a SceneForge demo for better flow, reliability, and viewer experience.
+
+## Task
+
+Review and optimize a demo definition for:
+- Smoother transitions
+- Better pacing
+- Improved reliability
+- Enhanced viewer experience
+
+## Input Required
+
+Provide the following:
+- **Demo YAML content**: The full demo definition
+- **Problem areas**: Known issues with flow/pacing (optional)
+- **Target duration**: Desired total runtime (optional)
+- **Audience**: Who will watch this demo (optional)
+
+## Optimization Areas
+
+### 1. Pacing Optimization
+- Step duration balance
+- Transition timing
+- Information density
+
+### 2. Visual Flow
+- Highlights for key actions
+- Hover states for context
+- Scroll to show content
+
+### 3. Reliability
+- Selector stability
+- Wait condition coverage
+- Error resilience
+
+### 4. Narrative Flow
+- Script coherence
+- Logical progression
+- Clear purpose
+
+## Output Format
+
+```markdown
+## Demo Optimization Report
+
+### Overview
+- Current duration: ~Xm Xs
+- Recommended duration: ~Ym Ys
+- Optimization potential: High/Medium/Low
+
+### Pacing Issues
+[List of pacing problems]
+
+### Flow Improvements
+[Suggested improvements]
+
+### Reliability Enhancements
+[Stability improvements]
+
+### Optimized YAML
+[Updated demo definition]
+```
+
+## Optimization Techniques
+
+### Improve Transitions
+
+**Add smooth navigation waits:**
+```yaml
+# Before
+- action: click
+  target: { type: link, text: "Dashboard" }
+
+# After
+- action: click
+  target: { type: link, text: "Dashboard" }
+  waitFor:
+    type: idle
+- action: wait
+  duration: 500  # Let page settle
+```
+
+### Add Visual Emphasis
+
+**Highlight important clicks:**
+```yaml
+- action: click
+  target:
+    type: button
+    text: "Create Project"
+  highlight: true  # Visual indicator for viewers
+```
+
+**Add hover for context:**
+```yaml
+# Before click, hover to draw attention
+- action: hover
+  target:
+    type: selector
+    selector: "[data-testid='important-button']"
+- action: wait
+  duration: 500
+- action: click
+  target:
+    type: selector
+    selector: "[data-testid='important-button']"
+```
+
+### Optimize Step Grouping
+
+**Split complex steps:**
+```yaml
+# Before: One step with 8 actions
+- id: complete-form
+  script: "Fill out the entire form."
+  actions: [... 8 actions ...]
+
+# After: Logical groupings
+- id: fill-personal-info
+  script: "Start by entering your personal information."
+  actions:
+    - action: type
+      target: { type: input, name: "name" }
+      text: "John Smith"
+    - action: type
+      target: { type: input, name: "email" }
+      text: "john@example.com"
+
+- id: fill-company-info
+  script: "Next, add your company details."
+  actions:
+    - action: type
+      target: { type: input, name: "company" }
+      text: "Acme Corp"
+    - action: type
+      target: { type: input, name: "role" }
+      text: "Developer"
+```
+
+### Add Breathing Room
+
+**Pause between major sections:**
+```yaml
+- id: section-transition
+  script: "Now let's look at the reporting features."
+  actions:
+    - action: wait
+      duration: 1500
+    - action: click
+      target: { type: link, text: "Reports" }
+```
+
+### Improve Script Flow
+
+**Connect steps narratively:**
+```yaml
+# Step 1 ending
+script: "...and that completes the basic setup."
+
+# Step 2 beginning (flows from step 1)
+script: "With the foundation in place, we can now configure advanced options."
+```
+
+### Add Recovery Points
+
+**Ensure stable states:**
+```yaml
+# After potentially flaky operations
+- action: click
+  target: { type: button, text: "Process" }
+  waitFor:
+    type: selectorHidden
+    value: ".processing-spinner"
+    timeout: 30000  # Generous timeout
+- action: wait
+  waitFor:
+    type: selector
+    value: ".success-indicator"
+```
+
+## Pacing Guidelines
+
+| Step Type | Recommended Duration |
+|-----------|---------------------|
+| Intro | 5-10 seconds |
+| Simple action | 3-5 seconds |
+| Form entry | 8-15 seconds |
+| Feature explanation | 10-20 seconds |
+| Transition | 2-4 seconds |
+| Outro | 5-10 seconds |
+
+## Optimization Checklist
+
+### Pacing
+- [ ] No rushed steps (< 2 seconds)
+- [ ] No overly long steps (> 30 seconds)
+- [ ] Smooth transitions between sections
+- [ ] Adequate intro and outro
+
+### Visual
+- [ ] Key actions have highlights
+- [ ] Complex UI has hover indicators
+- [ ] Content scrolled into view
+- [ ] No jarring jumps
+
+### Reliability
+- [ ] All async operations have waits
+- [ ] Timeouts are reasonable
+- [ ] Selectors are stable
+- [ ] Error states considered
+
+### Narrative
+- [ ] Scripts connect logically
+- [ ] Purpose is clear throughout
+- [ ] Technical terms explained
+- [ ] Conclusion summarizes value

package/context/templates/skills/review-demo-yaml.md

@@ -0,0 +1,164 @@
+# Skill: Review Demo YAML
+
+Review and improve a SceneForge demo definition for quality, reliability, and best practices.
+
+## Task
+
+Analyze a demo YAML file and provide feedback on:
+- Action reliability
+- Selector stability
+- Script quality
+- Timing considerations
+- Overall structure
+
+## Input Required
+
+Provide the following:
+- **Demo YAML content**: The full demo definition
+- **Issues encountered**: Any known problems (optional)
+- **Focus areas**: Specific aspects to review (optional)
+
+## Review Categories
+
+### 1. Schema Compliance
+- Valid YAML syntax
+- Required fields present
+- Correct action types
+- Valid target types
+
+### 2. Selector Quality
+- Stability score (data-testid > aria-label > text)
+- Specificity (not too broad or narrow)
+- Brittleness risk
+
+### 3. Wait Conditions
+- Present after async operations
+- Appropriate condition types
+- Reasonable timeouts
+
+### 4. Script Quality
+- Clarity and tone
+- Length vs. action duration
+- Grammar and punctuation
+
+### 5. Step Organization
+- Logical groupings
+- Descriptive IDs
+- Appropriate granularity
+
+## Output Format
+
+```markdown
+## Demo Review: [demo-name]
+
+### Summary
+- Overall quality: Good/Needs Work/Poor
+- Critical issues: X
+- Warnings: Y
+- Suggestions: Z
+
+### Critical Issues
+[List of must-fix problems]
+
+### Warnings
+[List of should-fix problems]
+
+### Suggestions
+[List of nice-to-have improvements]
+
+### Detailed Review
+
+#### Step: [step-id]
+- Actions: [assessment]
+- Selectors: [assessment]
+- Script: [assessment]
+- Recommendations: [list]
+
+[Repeat for each step]
+
+### Recommended Changes
+[YAML snippets with improvements]
+```
+
+## Review Checklist
+
+### Schema
+- [ ] Version field present
+- [ ] Name follows naming convention
+- [ ] Title is descriptive
+- [ ] All steps have IDs
+- [ ] All steps have script field
+- [ ] All steps have actions array
+
+### Selectors
+- [ ] No fragile CSS class selectors
+- [ ] No position-based selectors
+- [ ] Uses data-testid where available
+- [ ] Fallbacks use semantic selectors
+
+### Wait Conditions
+- [ ] Navigation actions have waitFor
+- [ ] Clicks that trigger async have waitFor
+- [ ] Timeouts are reasonable (not too short)
+
+### Scripts
+- [ ] All steps have non-empty scripts (or intentionally empty)
+- [ ] Language is clear and natural
+- [ ] No spelling/grammar errors
+- [ ] Appropriate length for actions
+
+### Structure
+- [ ] Steps grouped logically
+- [ ] IDs are descriptive
+- [ ] Not too many actions per step
+- [ ] Intro/outro provide context
+
+## Example Review
+
+```markdown
+## Demo Review: onboarding-flow
+
+### Summary
+- Overall quality: Needs Work
+- Critical issues: 2
+- Warnings: 3
+- Suggestions: 4
+
+### Critical Issues
+
+1. **Step "click-button" uses fragile selector**
+   ```yaml
+   # Current
+   selector: ".btn.btn-primary.mt-4"
+
+   # Recommended
+   selector: "[data-testid='submit-btn']"
+   ```
+
+2. **Step "load-data" missing wait condition**
+   ```yaml
+   # Current
+   - action: click
+     target: { type: button, text: "Load" }
+
+   # Recommended
+   - action: click
+     target: { type: button, text: "Load" }
+     waitFor:
+       type: selector
+       value: ".data-table"
+   ```
+
+### Warnings
+
+1. Script in step "intro" may be too short for video duration
+2. Step IDs not descriptive: "step1", "step2"
+3. No timeout on slow API wait condition
+
+### Suggestions
+
+1. Add highlight to key click actions
+2. Consider splitting "fill-large-form" into multiple steps
+3. Add brief pause after modal opens
+4. Include conclusion step
+```