From 3dd3f09e22062997b97d1e39a8e0053c4aa6aff2 Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Sun, 8 Mar 2026 23:23:25 -0400
Subject: [PATCH 01/14] feat(sim): add playback speed control, edge animation,
 and template scenarios

Add simulation playback polish with three major features:

1. Edge animation: animated signal/particle traverses edges using SMIL
   animateMotion with multi-layered energy bead (Catppuccin green).
   Pre-computed trace snapshots give O(1) highlight lookups per step.

2. Playback speed control: 0.5x-4x speed selector in SimulationPanel
   with interval scaling for auto-play and particle duration.

3. Template scenarios: 26 example scenarios across 10 templates with
   prefilled input, fixtures, and embedded rules data. Switch fixture
   support added to engine for label-based case matching.
---
 packages/app/src/App.tsx                      |  14 +
 .../app/src/components/SimulationPanel.tsx    | 112 ++-
 .../app/src/data/template-scenarios.test.ts   | 110 +++
 packages/app/src/data/template-scenarios.ts   | 836 ++++++++++++++++++
 packages/app/src/hooks/useSimulation.test.ts  | 134 +++
 packages/app/src/hooks/useSimulation.ts       | 122 ++-
 .../editor/src/components/FlowprintEditor.tsx |  25 +-
 .../src/contexts/SimulationContext.test.tsx   |  74 +-
 .../editor/src/contexts/SimulationContext.tsx |  36 +
 packages/editor/src/edges/ConditionalEdge.tsx |   2 +
 .../src/edges/EdgeSimulationOverlay.tsx       | 144 +++
 packages/editor/src/edges/ErrorEdge.tsx       |   2 +
 packages/editor/src/edges/SmoothstepEdge.tsx  |   2 +
 packages/editor/src/index.ts                  |  17 +-
 packages/editor/src/styles/edges.css          |   2 +
 packages/editor/src/styles/nodes.css          |  19 +-
 .../engine/src/__tests__/simulator.test.ts    | 101 ++-
 packages/engine/src/simulator/simulator.ts    |  45 +-
 18 files changed, 1772 insertions(+), 25 deletions(-)
 create mode 100644 packages/app/src/data/template-scenarios.test.ts
 create mode 100644 packages/app/src/data/template-scenarios.ts
 create mode 100644 packages/editor/src/edges/EdgeSimulationOverlay.tsx

diff --git a/packages/app/src/App.tsx b/packages/app/src/App.tsx
index 2804c6f..8fdf58a 100644
--- a/packages/app/src/App.tsx
+++ b/packages/app/src/App.tsx
@@ -9,6 +9,8 @@ import { WelcomeScreen } from './components/WelcomeScreen'
 import { NewBlueprintWizard } from './components/NewBlueprintWizard'
 import { SettingsDialog } from './components/SettingsDialog'
 import { SimulationPanel } from './components/SimulationPanel'
+import { getScenarios } from './data/template-scenarios'
+import type { TemplateScenario } from './data/template-scenarios'
 import { UnsavedChangesGuard } from './components/UnsavedChangesGuard'
 import { useFileManager } from './hooks/useFileManager'
 import { useProjectDirectory } from './hooks/useProjectDirectory'
@@ -36,6 +38,14 @@ export function App() {
   })
 
   const simulation = useSimulation(doc, rulesDataMap)
+  const scenarios = doc ? getScenarios(doc.name) : []
+
+  const handleSelectScenario = useCallback(
+    (scenario: TemplateScenario | null) => {
+      setRulesDataMap(scenario?.rulesData ?? {})
+    },
+    [],
+  )
 
   // Review #5: gate on doc !== null only, not on rules presence
   const canSimulate = doc !== null
@@ -231,6 +241,8 @@ export function App() {
               symbolSearch={symbolSearch ?? undefined}
               rulesDataMap={rulesDataMap}
               nodeHighlights={simulation.nodeHighlights}
+              edgeHighlights={simulation.edgeHighlights}
+              simulationAnimation={simulation.simulationAnimation}
               showYamlPreview
               showExportButton
               style={{ width: '100%', height: '100%' }}
@@ -245,6 +257,8 @@ export function App() {
                   setShowSimPanel(false)
                 },
               }}
+              scenarios={scenarios}
+              onSelectScenario={handleSelectScenario}
             />
           )}
         </>
diff --git a/packages/app/src/components/SimulationPanel.tsx b/packages/app/src/components/SimulationPanel.tsx
index 53376b9..60ff095 100644
--- a/packages/app/src/components/SimulationPanel.tsx
+++ b/packages/app/src/components/SimulationPanel.tsx
@@ -1,8 +1,11 @@
 import { useState, useCallback, useEffect } from 'react'
 import type { UseSimulationReturn } from '../hooks/useSimulation'
+import type { TemplateScenario } from '../data/template-scenarios'
 
 export interface SimulationPanelProps {
   simulation: UseSimulationReturn
+  scenarios?: TemplateScenario[]
+  onSelectScenario?: (scenario: TemplateScenario | null) => void
 }
 
 const panelStyle: React.CSSProperties = {
@@ -114,12 +117,73 @@ function buildCumulativeContext(
   return ctx
 }
 
-export function SimulationPanel({ simulation }: SimulationPanelProps) {
+const selectStyle: React.CSSProperties = {
+  width: '100%',
+  padding: '6px 8px',
+  fontSize: 12,
+  fontFamily: 'var(--fp-font-sans, system-ui, sans-serif)',
+  background: '#1C1B25',
+  color: '#E8E7F4',
+  border: '1px solid #2E2D3D',
+  borderRadius: 6,
+  cursor: 'pointer',
+}
+
+export function SimulationPanel({ simulation, scenarios, onSelectScenario }: SimulationPanelProps) {
   const [inputText, setInputText] = useState('{}')
   const [fixturesText, setFixturesText] = useState('')
   const [showFixtures, setShowFixtures] = useState(false)
   const [showContext, setShowContext] = useState(false)
   const [inputError, setInputError] = useState<string | null>(null)
+  const [selectedScenarioId, setSelectedScenarioId] = useState<string | null>(null)
+
+  const hasScenarios = scenarios && scenarios.length > 0
+  const selectedScenario = hasScenarios
+    ? scenarios.find((s) => s.id === selectedScenarioId) ?? null
+    : null
+
+  const handleSelectScenario = useCallback(
+    (scenarioId: string) => {
+      if (scenarioId === '') {
+        setSelectedScenarioId(null)
+        onSelectScenario?.(null)
+        return
+      }
+      const scenario = scenarios?.find((s) => s.id === scenarioId)
+      if (!scenario) return
+      setSelectedScenarioId(scenarioId)
+      setInputText(JSON.stringify(scenario.input, null, 2))
+      setFixturesText(JSON.stringify(scenario.fixtures ?? {}, null, 2))
+      if (scenario.fixtures && Object.keys(scenario.fixtures).length > 0) {
+        setShowFixtures(true)
+      }
+      setInputError(null)
+      onSelectScenario?.(scenario)
+    },
+    [scenarios, onSelectScenario],
+  )
+
+  const handleInputChange = useCallback(
+    (value: string) => {
+      setInputText(value)
+      if (selectedScenarioId) {
+        setSelectedScenarioId(null)
+        onSelectScenario?.(null)
+      }
+    },
+    [selectedScenarioId, onSelectScenario],
+  )
+
+  const handleFixturesChange = useCallback(
+    (value: string) => {
+      setFixturesText(value)
+      if (selectedScenarioId) {
+        setSelectedScenarioId(null)
+        onSelectScenario?.(null)
+      }
+    },
+    [selectedScenarioId, onSelectScenario],
+  )
 
   const {
     isActive,
@@ -136,6 +200,8 @@ export function SimulationPanel({ simulation }: SimulationPanelProps) {
     reset,
     setAutoPlay,
     isAutoPlaying,
+    playbackSpeed,
+    setPlaybackSpeed,
   } = simulation
 
   const handleRun = useCallback(() => {
@@ -207,13 +273,38 @@ export function SimulationPanel({ simulation }: SimulationPanelProps) {
           </button>
         </div>
 
+        {hasScenarios && (
+          <div style={inputAreaStyle}>
+            <label style={{ display: 'block', fontSize: 11, marginBottom: 4, color: '#8887A5' }}>
+              Example Scenario
+            </label>
+            <select
+              value={selectedScenarioId ?? ''}
+              onChange={(e) => { handleSelectScenario(e.target.value) }}
+              style={selectStyle}
+            >
+              <option value="">Custom input</option>
+              {scenarios.map((s) => (
+                <option key={s.id} value={s.id}>
+                  {s.name}
+                </option>
+              ))}
+            </select>
+            {selectedScenario && (
+              <div style={{ fontSize: 11, color: '#8887A5', marginTop: 4 }}>
+                {selectedScenario.description}
+              </div>
+            )}
+          </div>
+        )}
+
         <div style={inputAreaStyle}>
           <label style={{ display: 'block', fontSize: 11, marginBottom: 4, color: '#8887A5' }}>
             Input JSON
           </label>
           <textarea
             value={inputText}
-            onChange={(e) => { setInputText(e.target.value) }}
+            onChange={(e) => { handleInputChange(e.target.value) }}
             style={textareaStyle}
             placeholder='{"key": "value"}'
           />
@@ -236,7 +327,7 @@ export function SimulationPanel({ simulation }: SimulationPanelProps) {
             </label>
             <textarea
               value={fixturesText}
-              onChange={(e) => { setFixturesText(e.target.value) }}
+              onChange={(e) => { handleFixturesChange(e.target.value) }}
               style={textareaStyle}
               placeholder='{"wait_node_id": {"event": "data"}}'
             />
@@ -306,6 +397,21 @@ export function SimulationPanel({ simulation }: SimulationPanelProps) {
         >
           {isAutoPlaying ? 'Pause' : 'Play'}
         </button>
+
+        {/* Speed buttons */}
+        <span style={{ color: '#8887A5', fontSize: 10, marginLeft: 4 }}>Speed:</span>
+        {[0.5, 1, 2, 4].map((speed) => (
+          <button
+            key={speed}
+            type="button"
+            onClick={() => { setPlaybackSpeed(speed) }}
+            style={playbackSpeed === speed ? btnActiveStyle : btnStyle}
+            title={`${String(speed)}x speed`}
+          >
+            {speed}x
+          </button>
+        ))}
+
         <button type="button" onClick={stop} style={{ ...btnStyle, color: '#f38ba8' }}>
           Stop
         </button>
diff --git a/packages/app/src/data/template-scenarios.test.ts b/packages/app/src/data/template-scenarios.test.ts
new file mode 100644
index 0000000..262e4a1
--- /dev/null
+++ b/packages/app/src/data/template-scenarios.test.ts
@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest'
+import { getScenarios } from './template-scenarios'
+
+const TEMPLATE_NAMES = [
+  'hello_world',
+  'request_response',
+  'approval_workflow',
+  'order_routing',
+  'parallel_pipeline',
+  'ci_cd_pipeline',
+  'patient_intake',
+  'subscription_billing',
+  'e_commerce_fulfillment',
+  'insurance_claims',
+]
+
+// Load templates via the public API
+import { getTemplates, loadTemplate } from './templates'
+
+describe('template-scenarios', () => {
+  it('every template has at least one scenario', () => {
+    for (const name of TEMPLATE_NAMES) {
+      const scenarios = getScenarios(name)
+      expect(scenarios.length, `${name} should have scenarios`).toBeGreaterThanOrEqual(1)
+    }
+  })
+
+  it('scenario IDs are unique within each template', () => {
+    for (const name of TEMPLATE_NAMES) {
+      const scenarios = getScenarios(name)
+      const ids = scenarios.map((s) => s.id)
+      expect(new Set(ids).size, `${name} has duplicate scenario IDs`).toBe(ids.length)
+    }
+  })
+
+  it('every scenario has a valid input object', () => {
+    for (const name of TEMPLATE_NAMES) {
+      for (const scenario of getScenarios(name)) {
+        expect(
+          typeof scenario.input,
+          `${name}/${scenario.id} input should be an object`,
+        ).toBe('object')
+        expect(scenario.input, `${name}/${scenario.id} input should not be null`).not.toBeNull()
+      }
+    }
+  })
+
+  it('returns empty array for unknown template', () => {
+    expect(getScenarios('nonexistent_template')).toEqual([])
+  })
+
+  describe('rules file references match template YAML', () => {
+    const templates = getTemplates()
+
+    for (const tmpl of templates) {
+      const doc = loadTemplate(tmpl.id)
+      const docName = doc.name
+
+      // Collect rules file refs from the template
+      const rulesRefs = new Set<string>()
+      for (const node of Object.values(doc.nodes)) {
+        if ('rules' in node && node.rules && typeof node.rules === 'object' && 'file' in node.rules) {
+          rulesRefs.add((node.rules as { file: string }).file)
+        }
+      }
+
+      if (rulesRefs.size === 0) continue
+
+      it(`${docName}: scenarios with rulesData cover all rules file refs`, () => {
+        const scenarios = getScenarios(docName)
+        // At least one scenario should provide rulesData for templates that use rules
+        const scenariosWithRules = scenarios.filter((s) => s.rulesData && Object.keys(s.rulesData).length > 0)
+        expect(
+          scenariosWithRules.length,
+          `${docName} should have at least one scenario with rulesData`,
+        ).toBeGreaterThanOrEqual(1)
+
+        // Check that all rules refs are covered by at least one scenario
+        for (const ref of rulesRefs) {
+          const covered = scenariosWithRules.some((s) => s.rulesData?.[ref])
+          expect(covered, `${docName}: rules ref "${ref}" should be covered by a scenario`).toBe(true)
+        }
+      })
+    }
+  })
+
+  describe('fixture node IDs reference real nodes in template', () => {
+    const templates = getTemplates()
+
+    for (const tmpl of templates) {
+      const doc = loadTemplate(tmpl.id)
+      const docName = doc.name
+      const nodeIds = new Set(Object.keys(doc.nodes))
+      const scenarios = getScenarios(docName)
+
+      for (const scenario of scenarios) {
+        if (!scenario.fixtures) continue
+
+        it(`${docName}/${scenario.id}: fixture keys are valid node IDs`, () => {
+          for (const fixtureKey of Object.keys(scenario.fixtures ?? {})) {
+            expect(
+              nodeIds.has(fixtureKey),
+              `${docName}/${scenario.id}: fixture key "${fixtureKey}" is not a node in the template`,
+            ).toBe(true)
+          }
+        })
+      }
+    }
+  })
+})
diff --git a/packages/app/src/data/template-scenarios.ts b/packages/app/src/data/template-scenarios.ts
new file mode 100644
index 0000000..93911f2
--- /dev/null
+++ b/packages/app/src/data/template-scenarios.ts
@@ -0,0 +1,836 @@
+import type { RulesDataMap } from '@ruminaider/flowprint-editor'
+
+export interface TemplateScenario {
+  id: string
+  name: string
+  description: string
+  input: Record<string, unknown>
+  fixtures?: Record<string, unknown>
+  rulesData?: RulesDataMap
+}
+
+const TEMPLATE_SCENARIOS: Record<string, TemplateScenario[]> = {
+  // ── Hello World ──────────────────────────────────────
+  hello_world: [
+    {
+      id: 'greeting',
+      name: 'Simple Greeting',
+      description: 'A user sends their name and receives a greeting',
+      input: { name: 'Alice' },
+      fixtures: {
+        greet_user: { message: 'Hello, Alice!' },
+      },
+    },
+  ],
+
+  // ── Request / Response ───────────────────────────────
+  request_response: [
+    {
+      id: 'success',
+      name: 'Successful Request',
+      description: 'A GET request is received, processed, and returns a 200 response',
+      input: { method: 'GET', path: '/api/users', params: { id: 42 } },
+      fixtures: {
+        receive_request: { validated: true, requestId: 'req-001' },
+        process_request: { users: [{ id: 42, name: 'Alice' }] },
+        send_response: { status: 200, body: { id: 42, name: 'Alice' } },
+      },
+    },
+    {
+      id: 'large-payload',
+      name: 'Large Payload',
+      description: 'A POST request with a large payload is processed successfully',
+      input: { method: 'POST', path: '/api/import', payload: { records: 500 } },
+      fixtures: {
+        receive_request: { validated: true, requestId: 'req-002', size: '1.2MB' },
+        process_request: { imported: 500, skipped: 0 },
+        send_response: { status: 201, body: { imported: 500 } },
+      },
+    },
+  ],
+
+  // ── Approval Workflow ────────────────────────────────
+  approval_workflow: [
+    {
+      id: 'approved',
+      name: 'Request Approved',
+      description: 'A purchase request is submitted and approved by the reviewer',
+      input: { request: { type: 'purchase', amount: 500, requester: 'Alice' } },
+      fixtures: {
+        submit_request: { requestId: 'REQ-001', submitted: true },
+        review_request: { decision: 'Approved', reviewer: 'Bob' },
+        check_approval: 'Approved',
+        process_approval: { processed: true, orderId: 'ORD-001' },
+      },
+    },
+    {
+      id: 'rejected',
+      name: 'Request Rejected',
+      description: 'A purchase request is submitted but rejected by the reviewer',
+      input: { request: { type: 'purchase', amount: 50_000, requester: 'Charlie' } },
+      fixtures: {
+        submit_request: { requestId: 'REQ-002', submitted: true },
+        review_request: { decision: 'Rejected', reviewer: 'Bob', reason: 'Over budget' },
+        check_approval: 'Rejected',
+        notify_rejection: { notified: true, reason: 'Over budget' },
+      },
+    },
+  ],
+
+  // ── Order Routing ────────────────────────────────────
+  order_routing: [
+    {
+      id: 'express-order',
+      name: 'Express Order ($500)',
+      description: 'A high-value order routed through express fulfillment',
+      input: { order: { id: 'ORD-001', total_amount: 500, customer: 'Alice' } },
+      fixtures: {
+        receive_order: { orderId: 'ORD-001', validated: true },
+        route_order: 'Express',
+        fulfill_express: { shipped: true, method: 'overnight' },
+        confirm_order: { confirmed: true, eta: '1 business day' },
+      },
+      rulesData: {
+        'rules/routing.rules.yaml': {
+          data: {
+
+            hit_policy: 'first',
+            inputs: ['order.total_amount'],
+            rules: [
+              {
+                when: { 'order.total_amount': { gte: 200 } },
+                then: { classification: 'Express' },
+              },
+              {
+                when: { 'order.total_amount': { gte: 50 } },
+                then: { classification: 'Standard' },
+              },
+              { then: { classification: 'Manual Review' } },
+            ],
+          },
+        },
+      },
+    },
+    {
+      id: 'standard-order',
+      name: 'Standard Order ($75)',
+      description: 'A regular order routed through standard fulfillment',
+      input: { order: { id: 'ORD-002', total_amount: 75, customer: 'Bob' } },
+      fixtures: {
+        receive_order: { orderId: 'ORD-002', validated: true },
+        route_order: 'Standard',
+        fulfill_standard: { shipped: true, method: 'ground' },
+        confirm_order: { confirmed: true, eta: '5-7 business days' },
+      },
+      rulesData: {
+        'rules/routing.rules.yaml': {
+          data: {
+
+            hit_policy: 'first',
+            inputs: ['order.total_amount'],
+            rules: [
+              {
+                when: { 'order.total_amount': { gte: 200 } },
+                then: { classification: 'Express' },
+              },
+              {
+                when: { 'order.total_amount': { gte: 50 } },
+                then: { classification: 'Standard' },
+              },
+              { then: { classification: 'Manual Review' } },
+            ],
+          },
+        },
+      },
+    },
+    {
+      id: 'manual-review',
+      name: 'Manual Review ($10)',
+      description: 'A low-value order flagged for manual review',
+      input: { order: { id: 'ORD-003', total_amount: 10, customer: 'Charlie' } },
+      fixtures: {
+        receive_order: { orderId: 'ORD-003', validated: true },
+        route_order: 'Manual Review',
+        flag_for_review: { flagged: true, reason: 'Low value order' },
+        confirm_order: { confirmed: true, eta: 'Pending review' },
+      },
+      rulesData: {
+        'rules/routing.rules.yaml': {
+          data: {
+
+            hit_policy: 'first',
+            inputs: ['order.total_amount'],
+            rules: [
+              {
+                when: { 'order.total_amount': { gte: 200 } },
+                then: { classification: 'Express' },
+              },
+              {
+                when: { 'order.total_amount': { gte: 50 } },
+                then: { classification: 'Standard' },
+              },
+              { then: { classification: 'Manual Review' } },
+            ],
+          },
+        },
+      },
+    },
+  ],
+
+  // ── Parallel Pipeline ────────────────────────────────
+  parallel_pipeline: [
+    {
+      id: 'default-processing',
+      name: 'Default Processing',
+      description: 'Data flows through all three parallel branches and aggregates',
+      input: { data: { records: [{ id: 1 }, { id: 2 }], source: 'api' } },
+      fixtures: {
+        receive_data: { parsed: true, recordCount: 2 },
+        enrich_data: { enriched: true, externalRefs: 2 },
+        validate_data: { valid: true, errors: 0 },
+        transform_data: { transformed: true, format: 'canonical' },
+        aggregate_results: { merged: true, totalRecords: 2 },
+      },
+    },
+    {
+      id: 'with-enrichment',
+      name: 'With External Enrichment',
+      description: 'Processing with rich external data augmentation',
+      input: { data: { records: [{ id: 1, sku: 'ABC-123' }], source: 'warehouse' } },
+      fixtures: {
+        receive_data: { parsed: true, recordCount: 1 },
+        enrich_data: { enriched: true, supplier: 'ACME Corp', price: 29.99 },
+        validate_data: { valid: true, warnings: ['Missing category'] },
+        transform_data: { transformed: true, format: 'warehouse-v2' },
+        aggregate_results: { merged: true, totalRecords: 1, warnings: 1 },
+      },
+    },
+  ],
+
+  // ── CI/CD Pipeline ───────────────────────────────────
+  ci_cd_pipeline: [
+    {
+      id: 'all-pass',
+      name: 'All Checks Pass',
+      description: 'Code is pushed, all tests pass, deployed to staging, approved, and released',
+      input: { commit: { sha: 'abc1234', branch: 'main', author: 'Alice' } },
+      fixtures: {
+        push_code: { sha: 'abc1234', branch: 'main' },
+        install_dependencies: { cached: true, packages: 142 },
+        build_project: { success: true, duration: '45s', artifacts: 3 },
+        run_unit_tests: { passed: 48, failed: 0, coverage: 94.2 },
+        run_integration_tests: { passed: 12, failed: 0 },
+        run_e2e_tests: { passed: 8, failed: 0 },
+        quality_gate: 'All checks pass',
+        deploy_staging: { url: 'https://staging.example.com', healthy: true },
+        await_approval: { approver: 'Bob', approved: true },
+        deploy_production: { url: 'https://example.com', strategy: 'blue-green' },
+      },
+    },
+    {
+      id: 'build-failure',
+      name: 'Build Failure',
+      description: 'Code is pushed but the build step fails, triggering the error handler',
+      input: { commit: { sha: 'def5678', branch: 'feature/broken', author: 'Charlie' } },
+      fixtures: {
+        push_code: { sha: 'def5678', branch: 'feature/broken' },
+        install_dependencies: { cached: false, packages: 142 },
+        build_project: { success: false, error: 'TypeScript compilation failed' },
+      },
+    },
+    {
+      id: 'checks-fail',
+      name: 'Quality Checks Fail',
+      description: 'Build succeeds but test failures cause the quality gate to reject the pipeline',
+      input: { commit: { sha: 'ghi9012', branch: 'feature/flaky', author: 'Dave' } },
+      fixtures: {
+        push_code: { sha: 'ghi9012', branch: 'feature/flaky' },
+        install_dependencies: { cached: true, packages: 142 },
+        build_project: { success: true, duration: '50s' },
+        run_unit_tests: { passed: 45, failed: 3, coverage: 88.1 },
+        run_integration_tests: { passed: 10, failed: 2 },
+        run_e2e_tests: { passed: 6, failed: 2 },
+        quality_gate: 'Checks fail',
+        reject_pipeline: { notified: true, failureCount: 7 },
+      },
+    },
+  ],
+
+  // ── Patient Intake ───────────────────────────────────
+  patient_intake: [
+    {
+      id: 'existing-routine',
+      name: 'Existing Patient, Routine Visit',
+      description: 'An existing patient with full coverage arrives for a routine appointment',
+      input: {
+        patient: { id: 'PT-001', name: 'Alice Smith', dob: '1985-03-15' },
+        visit: { type: 'routine', reason: 'Annual checkup' },
+      },
+      fixtures: {
+        patient_arrives: { checkedIn: true, method: 'kiosk' },
+        verify_identity: { verified: true, photoMatch: true },
+        check_existing_record: 'Existing patient',
+        update_demographics: { updated: true, changedFields: ['phone'] },
+        collect_insurance_info: { memberId: 'INS-12345', group: 'GRP-100' },
+        verify_insurance_coverage: 'Fully covered',
+        triage_assessment: 'Routine',
+        assign_provider: { provider: 'Dr. Johnson', specialty: 'General' },
+        schedule_appointment: { slot: '10:30 AM', room: 'B-204' },
+      },
+      rulesData: {
+        'rules/provider-assignment.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['visit.type'],
+            rules: [
+              {
+                when: { 'visit.type': { eq: 'routine' } },
+                then: { provider: 'Dr. Johnson', specialty: 'General' },
+              },
+              {
+                when: { 'visit.type': { eq: 'urgent' } },
+                then: { provider: 'Dr. Chen', specialty: 'Emergency' },
+              },
+            ],
+          },
+        },
+        'rules/scheduling.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['visit.type'],
+            rules: [
+              {
+                when: { 'visit.type': { eq: 'routine' } },
+                then: { priority: 'normal', maxWait: '30min' },
+              },
+              {
+                when: { 'visit.type': { eq: 'urgent' } },
+                then: { priority: 'high', maxWait: '10min' },
+              },
+            ],
+          },
+        },
+      },
+    },
+    {
+      id: 'new-emergency',
+      name: 'New Patient, Emergency',
+      description: 'A new patient arrives with emergency symptoms and is escalated',
+      input: {
+        patient: { name: 'Bob Jones', dob: '1990-07-22' },
+        visit: { type: 'emergency', reason: 'Chest pain' },
+      },
+      fixtures: {
+        patient_arrives: { checkedIn: true, method: 'walk-in' },
+        verify_identity: { verified: true, photoMatch: true },
+        check_existing_record: 'New patient',
+        create_patient_record: { patientId: 'PT-NEW-001', created: true },
+        collect_insurance_info: { memberId: 'INS-67890', group: 'GRP-200' },
+        verify_insurance_coverage: 'Fully covered',
+        triage_assessment: 'Emergency',
+        escalate_emergency: { transferred: true, department: 'ER', notified: 'Dr. Chen' },
+      },
+    },
+    {
+      id: 'partial-coverage-urgent',
+      name: 'Partial Coverage, Urgent',
+      description: 'An existing patient with partial insurance coverage needs urgent care',
+      input: {
+        patient: { id: 'PT-003', name: 'Carol Davis', dob: '1975-11-30' },
+        visit: { type: 'urgent', reason: 'Severe migraine' },
+      },
+      fixtures: {
+        patient_arrives: { checkedIn: true, method: 'front-desk' },
+        verify_identity: { verified: true },
+        check_existing_record: 'Existing patient',
+        update_demographics: { updated: false, noChanges: true },
+        collect_insurance_info: { memberId: 'INS-33333', group: 'GRP-150' },
+        verify_insurance_coverage: 'Partial coverage',
+        collect_copay: { amount: 50, method: 'card', processed: true },
+        triage_assessment: 'Urgent',
+        assign_provider: { provider: 'Dr. Chen', specialty: 'Emergency' },
+        schedule_appointment: { slot: 'Next available', room: 'A-101', priority: 'high' },
+      },
+      rulesData: {
+        'rules/provider-assignment.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['visit.type'],
+            rules: [
+              {
+                when: { 'visit.type': { eq: 'routine' } },
+                then: { provider: 'Dr. Johnson', specialty: 'General' },
+              },
+              {
+                when: { 'visit.type': { eq: 'urgent' } },
+                then: { provider: 'Dr. Chen', specialty: 'Emergency' },
+              },
+            ],
+          },
+        },
+        'rules/scheduling.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['visit.type'],
+            rules: [
+              {
+                when: { 'visit.type': { eq: 'routine' } },
+                then: { priority: 'normal', maxWait: '30min' },
+              },
+              {
+                when: { 'visit.type': { eq: 'urgent' } },
+                then: { priority: 'high', maxWait: '10min' },
+              },
+            ],
+          },
+        },
+      },
+    },
+  ],
+
+  // ── Subscription Billing ─────────────────────────────
+  subscription_billing: [
+    {
+      id: 'billing-success',
+      name: 'Standard Billing Success',
+      description: 'A Pro plan subscription is billed successfully with discount and tax',
+      input: {
+        account: { id: 'ACC-001', plan: 'Pro', tenure_months: 14 },
+        billing: { period: 'monthly', region: 'US-CA' },
+      },
+      fixtures: {
+        initiate_billing: { accountId: 'ACC-001', plan: 'Pro', cycle: 'March 2025' },
+        generate_invoice: {
+          invoiceId: 'INV-001',
+          base: 49.99,
+          discount: -5.0,
+          tax: 3.82,
+          total: 48.81,
+        },
+        process_payment: { charged: true, method: 'Visa *4242', transactionId: 'TXN-001' },
+        check_payment_result: 'Payment Succeeded',
+        send_receipt: { emailed: true, to: 'alice@example.com' },
+      },
+      rulesData: {
+        'rules/pricing.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['account.plan'],
+            rules: [
+              {
+                when: { 'account.plan': { eq: 'Pro' } },
+                then: { base_price: 49.99, currency: 'USD' },
+              },
+              {
+                when: { 'account.plan': { eq: 'Enterprise' } },
+                then: { base_price: 199.99, currency: 'USD' },
+              },
+              { then: { base_price: 9.99, currency: 'USD' } },
+            ],
+          },
+        },
+        'rules/discount.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['account.tenure_months'],
+            rules: [
+              {
+                when: { 'account.tenure_months': { gte: 12 } },
+                then: { discount_pct: 10, reason: 'Loyalty discount' },
+              },
+              { then: { discount_pct: 0 } },
+            ],
+          },
+        },
+        'rules/tax.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['billing.region'],
+            rules: [
+              {
+                when: { 'billing.region': { eq: 'US-CA' } },
+                then: { tax_rate: 8.5, jurisdiction: 'California' },
+              },
+              {
+                when: { 'billing.region': { eq: 'US-NY' } },
+                then: { tax_rate: 8.875, jurisdiction: 'New York' },
+              },
+              { then: { tax_rate: 0, jurisdiction: 'Tax-exempt' } },
+            ],
+          },
+        },
+      },
+    },
+    {
+      id: 'payment-declined',
+      name: 'Payment Declined',
+      description: 'Billing proceeds normally but the payment is declined, entering the dunning flow',
+      input: {
+        account: { id: 'ACC-002', plan: 'Pro', tenure_months: 3 },
+        billing: { period: 'monthly', region: 'US-NY' },
+      },
+      fixtures: {
+        initiate_billing: { accountId: 'ACC-002', plan: 'Pro', cycle: 'March 2025' },
+        generate_invoice: { invoiceId: 'INV-002', base: 49.99, discount: 0, tax: 4.44, total: 54.43 },
+        process_payment: { charged: false, error: 'Card declined' },
+        check_payment_result: 'Payment Declined',
+        notify_customer: { emailed: true, to: 'bob@example.com', dunningStep: 1 },
+      },
+      rulesData: {
+        'rules/pricing.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['account.plan'],
+            rules: [
+              {
+                when: { 'account.plan': { eq: 'Pro' } },
+                then: { base_price: 49.99, currency: 'USD' },
+              },
+              { then: { base_price: 9.99, currency: 'USD' } },
+            ],
+          },
+        },
+        'rules/discount.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['account.tenure_months'],
+            rules: [
+              {
+                when: { 'account.tenure_months': { gte: 12 } },
+                then: { discount_pct: 10, reason: 'Loyalty discount' },
+              },
+              { then: { discount_pct: 0 } },
+            ],
+          },
+        },
+        'rules/tax.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['billing.region'],
+            rules: [
+              {
+                when: { 'billing.region': { eq: 'US-NY' } },
+                then: { tax_rate: 8.875, jurisdiction: 'New York' },
+              },
+              { then: { tax_rate: 0, jurisdiction: 'Tax-exempt' } },
+            ],
+          },
+        },
+      },
+    },
+  ],
+
+  // ── E-Commerce Fulfillment ───────────────────────────
+  e_commerce_fulfillment: [
+    {
+      id: 'in-stock-standard',
+      name: 'In-Stock, Standard Shipping',
+      description: 'Order placed, payment clears fraud check, in-stock items shipped via standard',
+      input: {
+        order: { id: 'ORD-E001', items: [{ sku: 'WIDGET-A', qty: 2 }], total: 59.98 },
+        customer: { id: 'CUST-001', name: 'Alice', tier: 'Gold' },
+      },
+      fixtures: {
+        receive_order: { orderId: 'ORD-E001', validated: true },
+        validate_payment: { authorized: true, holdAmount: 59.98 },
+        check_fraud: 'Approved',
+        confirm_order: { confirmed: true, confirmationEmail: true },
+        check_inventory: 'In stock',
+        pick_and_pack: { packed: true, weight: '2.3 lbs', boxes: 1 },
+        select_carrier: 'Standard shipping',
+        ship_order: { tracking: 'TRK-123456', carrier: 'UPS Ground' },
+        track_delivery: { delivered: true, signedBy: 'Alice' },
+        capture_payment: { captured: true, amount: 59.98 },
+        check_return_request: 'No return',
+      },
+      rulesData: {
+        'rules/loyalty-rewards.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['customer.tier', 'order.total'],
+            rules: [
+              {
+                when: { 'customer.tier': { eq: 'Gold' } },
+                then: { points_multiplier: 2, bonus_points: 100 },
+              },
+              {
+                when: { 'order.total': { gte: 100 } },
+                then: { points_multiplier: 1.5, bonus_points: 50 },
+              },
+              { then: { points_multiplier: 1, bonus_points: 0 } },
+            ],
+          },
+        },
+      },
+    },
+    {
+      id: 'fraud-flagged',
+      name: 'Fraud Flagged for Review',
+      description: 'Payment is flagged for manual fraud review, then cleared and fulfilled',
+      input: {
+        order: { id: 'ORD-E002', items: [{ sku: 'LAPTOP-X', qty: 1 }], total: 1299.99 },
+        customer: { id: 'CUST-NEW', name: 'Unknown', tier: 'Basic' },
+      },
+      fixtures: {
+        receive_order: { orderId: 'ORD-E002', validated: true },
+        validate_payment: { authorized: true, holdAmount: 1299.99 },
+        check_fraud: 'Flagged for review',
+        manual_fraud_review: { cleared: true, analyst: 'Fraud Team', notes: 'Verified with customer' },
+        confirm_order: { confirmed: true },
+        check_inventory: 'In stock',
+        pick_and_pack: { packed: true, weight: '5.1 lbs', boxes: 1 },
+        select_carrier: 'Express shipping',
+        ship_order: { tracking: 'TRK-789012', carrier: 'FedEx Express' },
+        track_delivery: { delivered: true },
+        capture_payment: { captured: true, amount: 1299.99 },
+        check_return_request: 'No return',
+      },
+      rulesData: {
+        'rules/loyalty-rewards.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['customer.tier'],
+            rules: [
+              { then: { points_multiplier: 1, bonus_points: 0 } },
+            ],
+          },
+        },
+      },
+    },
+    {
+      id: 'return-requested',
+      name: 'Return Requested',
+      description: 'Order is delivered but customer requests a return and receives a refund',
+      input: {
+        order: { id: 'ORD-E003', items: [{ sku: 'SHOES-M', qty: 1 }], total: 89.99 },
+        customer: { id: 'CUST-003', name: 'Carol', tier: 'Silver' },
+      },
+      fixtures: {
+        receive_order: { orderId: 'ORD-E003', validated: true },
+        validate_payment: { authorized: true, holdAmount: 89.99 },
+        check_fraud: 'Approved',
+        confirm_order: { confirmed: true },
+        check_inventory: 'In stock',
+        pick_and_pack: { packed: true, weight: '1.8 lbs' },
+        select_carrier: 'Standard shipping',
+        ship_order: { tracking: 'TRK-345678', carrier: 'USPS' },
+        track_delivery: { delivered: true },
+        capture_payment: { captured: true, amount: 89.99 },
+        check_return_request: 'Return requested',
+        process_return: { received: true, condition: 'Like new', restocked: true },
+        issue_refund: { refunded: true, amount: 89.99, method: 'Original payment' },
+      },
+      rulesData: {
+        'rules/loyalty-rewards.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['customer.tier'],
+            rules: [
+              {
+                when: { 'customer.tier': { eq: 'Silver' } },
+                then: { points_multiplier: 1.5, bonus_points: 25 },
+              },
+              { then: { points_multiplier: 1, bonus_points: 0 } },
+            ],
+          },
+        },
+      },
+    },
+  ],
+
+  // ── Insurance Claims ─────────────────────────────────
+  insurance_claims: [
+    {
+      id: 'auto-approved',
+      name: 'Auto-Approved Claim',
+      description: 'A simple auto claim is filed, auto-approved, and settled with payment',
+      input: {
+        claim: { type: 'auto', amount: 3500, incident: 'Fender bender', date: '2025-02-15' },
+        claimant: { id: 'CLT-001', name: 'Alice', policyNumber: 'POL-A100' },
+      },
+      fixtures: {
+        file_claim: { claimNumber: 'CLM-001', filed: true },
+        acknowledge_claim: { acknowledged: true, assignedTo: 'Agent Smith' },
+        classify_claim: 'Auto',
+        check_auto_adjudication: 'Auto-approve',
+        evaluate_claim: { assessed: true, liability: 'clear', damageEstimate: 3500 },
+        check_escalation: 'Standard processing',
+        present_offer: { amount: 3200, breakdown: { repair: 2800, rental: 400 } },
+        await_claimant_response: { response: 'accept' },
+        check_claimant_decision: 'Accepted',
+        process_payment: { paid: true, amount: 3200, method: 'direct deposit' },
+      },
+      rulesData: {
+        'rules/escalation.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['claim.amount'],
+            rules: [
+              {
+                when: { 'claim.amount': { gte: 50000 } },
+                then: { level: 'senior', reason: 'High value claim' },
+              },
+              { then: { level: 'standard' } },
+            ],
+          },
+        },
+        'rules/reserve-setting.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['claim.type', 'claim.amount'],
+            rules: [
+              {
+                when: { 'claim.type': { eq: 'auto' } },
+                then: { reserve: 5000, category: 'auto-collision' },
+              },
+              { then: { reserve: 10000, category: 'general' } },
+            ],
+          },
+        },
+        'rules/settlement-calculation.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['claim.amount'],
+            rules: [
+              {
+                when: { 'claim.amount': { lte: 10000 } },
+                then: { deductible: 500, settlement_pct: 90 },
+              },
+              { then: { deductible: 1000, settlement_pct: 85 } },
+            ],
+          },
+        },
+      },
+    },
+    {
+      id: 'fraud-investigation',
+      name: 'Fraud Investigation',
+      description: 'A suspicious health claim triggers fraud detection and SIU investigation',
+      input: {
+        claim: { type: 'health', amount: 25000, incident: 'Surgery claim', date: '2025-01-20' },
+        claimant: { id: 'CLT-002', name: 'Bob', policyNumber: 'POL-H200' },
+      },
+      fixtures: {
+        file_claim: { claimNumber: 'CLM-002', filed: true },
+        acknowledge_claim: { acknowledged: true },
+        classify_claim: 'Health',
+        check_auto_adjudication: 'Requires review',
+        run_fraud_detection: 'Suspicious',
+        escalate_to_siu: { referralId: 'SIU-001', priority: 'high' },
+        await_investigation: { result: 'cleared', investigator: 'Agent Martinez', weeks: 3 },
+        check_investigation_result: 'Cleared',
+        evaluate_claim: { assessed: true, liability: 'valid', medicalReview: true },
+        check_escalation: 'Standard processing',
+        present_offer: { amount: 22000 },
+        await_claimant_response: { response: 'accept' },
+        check_claimant_decision: 'Accepted',
+        process_payment: { paid: true, amount: 22000 },
+      },
+      rulesData: {
+        'rules/escalation.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['claim.amount'],
+            rules: [
+              { then: { level: 'standard' } },
+            ],
+          },
+        },
+        'rules/reserve-setting.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['claim.type'],
+            rules: [
+              {
+                when: { 'claim.type': { eq: 'health' } },
+                then: { reserve: 30000, category: 'health-surgical' },
+              },
+              { then: { reserve: 10000, category: 'general' } },
+            ],
+          },
+        },
+        'rules/settlement-calculation.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['claim.amount'],
+            rules: [
+              {
+                when: { 'claim.amount': { gte: 10000 } },
+                then: { deductible: 1000, settlement_pct: 85 },
+              },
+              { then: { deductible: 500, settlement_pct: 90 } },
+            ],
+          },
+        },
+      },
+    },
+    {
+      id: 'counter-offer',
+      name: 'Counter-Offer Negotiation',
+      description: 'A property claim where the claimant counter-offers, leading to re-evaluation',
+      input: {
+        claim: { type: 'property', amount: 75000, incident: 'Storm damage', date: '2025-03-01' },
+        claimant: { id: 'CLT-003', name: 'Carol', policyNumber: 'POL-P300' },
+      },
+      fixtures: {
+        file_claim: { claimNumber: 'CLM-003', filed: true },
+        acknowledge_claim: { acknowledged: true },
+        classify_claim: 'Property',
+        check_auto_adjudication: 'Requires review',
+        run_fraud_detection: 'Clear',
+        evaluate_claim: { assessed: true, damageEstimate: 68000, liability: 'covered' },
+        check_escalation: 'Escalate to senior',
+        senior_adjuster_review: { reviewed: true, recommendation: 65000 },
+        calculate_settlement: { amount: 62000 },
+        present_offer: { amount: 62000 },
+        await_claimant_response: { response: 'counter', requestedAmount: 70000 },
+        check_claimant_decision: 'Counter-offer',
+      },
+      rulesData: {
+        'rules/escalation.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['claim.amount'],
+            rules: [
+              {
+                when: { 'claim.amount': { gte: 50000 } },
+                then: { level: 'senior', reason: 'High value claim' },
+              },
+              { then: { level: 'standard' } },
+            ],
+          },
+        },
+        'rules/reserve-setting.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['claim.type'],
+            rules: [
+              {
+                when: { 'claim.type': { eq: 'property' } },
+                then: { reserve: 100000, category: 'property-damage' },
+              },
+              { then: { reserve: 10000, category: 'general' } },
+            ],
+          },
+        },
+        'rules/settlement-calculation.rules.yaml': {
+          data: {
+            hit_policy: 'first',
+            inputs: ['claim.amount'],
+            rules: [
+              {
+                when: { 'claim.amount': { gte: 50000 } },
+                then: { deductible: 2500, settlement_pct: 80 },
+              },
+              { then: { deductible: 500, settlement_pct: 90 } },
+            ],
+          },
+        },
+      },
+    },
+  ],
+}
+
+export function getScenarios(docName: string): TemplateScenario[] {
+  return TEMPLATE_SCENARIOS[docName] ?? []
+}
diff --git a/packages/app/src/hooks/useSimulation.test.ts b/packages/app/src/hooks/useSimulation.test.ts
index 9557e58..acd4b86 100644
--- a/packages/app/src/hooks/useSimulation.test.ts
+++ b/packages/app/src/hooks/useSimulation.test.ts
@@ -35,6 +35,18 @@ const mockTrace = {
   ],
 }
 
+const threeNodeDoc: FlowprintDocument = {
+  schema: 'flowprint/1.0',
+  name: 'test-3',
+  version: '0.1.0',
+  lanes: { main: { label: 'Main' } },
+  nodes: {
+    a: { type: 'action', lane: 'main', label: 'A', next: 'b' },
+    b: { type: 'action', lane: 'main', label: 'B', next: 'c' },
+    c: { type: 'terminal', lane: 'main', label: 'C', outcome: 'success' },
+  },
+}
+
 const threeStepTrace = {
   status: 'success' as const,
   duration_ms: 15,
@@ -355,4 +367,126 @@ describe('useSimulation', () => {
     expect(mockSimulateGraph).not.toHaveBeenCalled()
     expect(result.current.isActive).toBe(false)
   })
+
+  it('playbackSpeed defaults to 1 and can be changed', () => {
+    const { result } = renderHook(() => useSimulation(minimalDoc, emptyRules))
+    expect(result.current.playbackSpeed).toBe(1)
+
+    act(() => {
+      result.current.setPlaybackSpeed(4)
+    })
+    expect(result.current.playbackSpeed).toBe(4)
+  })
+
+  it('stop() resets playbackSpeed to 1', async () => {
+    mockSimulateGraph.mockResolvedValue(mockTrace)
+    const { result } = renderHook(() => useSimulation(minimalDoc, emptyRules))
+
+    await act(async () => {
+      result.current.start({})
+      await vi.runAllTimersAsync()
+    })
+
+    act(() => {
+      result.current.setPlaybackSpeed(4)
+    })
+    expect(result.current.playbackSpeed).toBe(4)
+
+    act(() => {
+      result.current.stop()
+    })
+    expect(result.current.playbackSpeed).toBe(1)
+  })
+
+  it('auto-play speed scales with playbackSpeed', async () => {
+    mockSimulateGraph.mockResolvedValue(threeStepTrace)
+    const { result } = renderHook(() => useSimulation(threeNodeDoc, emptyRules))
+
+    await act(async () => {
+      result.current.start({})
+      await vi.runAllTimersAsync()
+    })
+
+    act(() => {
+      result.current.setPlaybackSpeed(2)
+      result.current.setAutoPlay(true)
+    })
+
+    // At 2x speed, interval = 1500/2 = 750ms
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(750)
+    })
+    expect(result.current.currentStep).toBe(1)
+  })
+
+  it('edgeHighlights computed correctly at each step', async () => {
+    mockSimulateGraph.mockResolvedValue(threeStepTrace)
+    const { result } = renderHook(() => useSimulation(threeNodeDoc, emptyRules))
+
+    await act(async () => {
+      result.current.start({})
+      await vi.runAllTimersAsync()
+    })
+
+    // Step 0 (node a): no incoming edge (first node)
+    expect(result.current.edgeHighlights).toEqual({})
+
+    // Step 1 (node b): incoming edge a->b is traversing
+    act(() => {
+      result.current.stepForward()
+    })
+    expect(result.current.edgeHighlights).toHaveProperty('e-a-b-0', 'traversing')
+
+    // Step 2 (node c): incoming edge b->c is traversing
+    act(() => {
+      result.current.stepForward()
+    })
+    expect(result.current.edgeHighlights).toHaveProperty('e-b-c-1', 'traversing')
+    // a->b is no longer highlighted
+    expect(result.current.edgeHighlights).not.toHaveProperty('e-a-b-0')
+  })
+
+  it('simulationAnimation tracks forward/backward steps', async () => {
+    mockSimulateGraph.mockResolvedValue(threeStepTrace)
+    const { result } = renderHook(() => useSimulation(threeNodeDoc, emptyRules))
+
+    await act(async () => {
+      result.current.start({})
+      await vi.runAllTimersAsync()
+    })
+
+    // Initial state after start(): isForwardStep is false (no animation until user steps)
+    expect(result.current.simulationAnimation.isForwardStep).toBe(false)
+
+    // Step forward: 1 > 0 = true
+    act(() => {
+      result.current.stepForward()
+    })
+    expect(result.current.simulationAnimation.isForwardStep).toBe(true)
+
+    // Step back: 0 > 1 = false
+    act(() => {
+      result.current.stepBack()
+    })
+    expect(result.current.simulationAnimation.isForwardStep).toBe(false)
+  })
+
+  it('particleDurationMs scales with playbackSpeed', async () => {
+    mockSimulateGraph.mockResolvedValue(mockTrace)
+    const { result } = renderHook(() => useSimulation(minimalDoc, emptyRules))
+
+    await act(async () => {
+      result.current.start({})
+      await vi.runAllTimersAsync()
+    })
+
+    // At 1x: max(400, 1200/1) = 1200
+    expect(result.current.simulationAnimation.particleDurationMs).toBe(1200)
+
+    act(() => {
+      result.current.setPlaybackSpeed(4)
+    })
+    // At 4x: max(400, 1200/4) = 400
+    expect(result.current.simulationAnimation.particleDurationMs).toBe(400)
+  })
 })
diff --git a/packages/app/src/hooks/useSimulation.ts b/packages/app/src/hooks/useSimulation.ts
index 2494ae5..8cb69bc 100644
--- a/packages/app/src/hooks/useSimulation.ts
+++ b/packages/app/src/hooks/useSimulation.ts
@@ -7,7 +7,9 @@ import type {
   RulesDocument,
 } from '@ruminaider/flowprint-engine/browser'
 import type { FlowprintDocument } from '@ruminaider/flowprint-schema'
+import { getEdges } from '@ruminaider/flowprint-schema'
 import type { NodeHighlightMap } from '@ruminaider/flowprint-editor'
+import type { EdgeHighlightMap, SimulationAnimationConfig } from '@ruminaider/flowprint-editor'
 import type { RulesDataMap } from '@ruminaider/flowprint-editor'
 
 export interface UseSimulationReturn {
@@ -28,20 +30,48 @@ export interface UseSimulationReturn {
   reset: () => void
   setAutoPlay: (enabled: boolean) => void
   isAutoPlaying: boolean
+  playbackSpeed: number
+  setPlaybackSpeed: (speed: number) => void
+  edgeHighlights: EdgeHighlightMap
+  simulationAnimation: SimulationAnimationConfig
 }
 
 interface TraceSnapshots {
   highlights: NodeHighlightMap[]
+  edgeHighlights: EdgeHighlightMap[]
   contexts: Record<string, unknown>[]
 }
 
+/**
+ * Build a lookup from "source->target" to React Flow edge ID.
+ * Mirrors the ID pattern in layout-engine.ts: `e-${source}-${target}-${index}`
+ */
+function buildEdgeLookup(doc: FlowprintDocument): Map<string, string> {
+  const schemaEdges = getEdges(doc)
+  const lookup = new Map<string, string>()
+  for (let i = 0; i < schemaEdges.length; i++) {
+    const edge = schemaEdges[i]
+    if (!edge) continue
+    const key = `${edge.source}->${edge.target}`
+    // First occurrence wins (matches computeEdges index ordering)
+    if (!lookup.has(key)) {
+      lookup.set(key, `e-${edge.source}-${edge.target}-${String(i)}`)
+    }
+  }
+  return lookup
+}
+
 /**
  * Pre-compute highlight and context snapshots for every step index.
  * One-time O(n) pass when trace arrives, then O(1) access per step.
  * Each entry is a point-in-time snapshot (Review #36).
  */
-function buildTraceSnapshots(steps: SimulationStep[]): TraceSnapshots {
+function buildTraceSnapshots(
+  steps: SimulationStep[],
+  edgeLookup: Map<string, string>,
+): TraceSnapshots {
   const highlights: NodeHighlightMap[] = []
+  const edgeHighlights: EdgeHighlightMap[] = []
   const contexts: Record<string, unknown>[] = []
   const cumulativeCtx: Record<string, unknown> = {}
 
@@ -49,6 +79,7 @@ function buildTraceSnapshots(steps: SimulationStep[]): TraceSnapshots {
     const step = steps[i]
     if (!step) continue
     const snapshot: NodeHighlightMap = {}
+    const edgeSnapshot: EdgeHighlightMap = {}
 
     // Mark all previously visited nodes
     for (let j = 0; j < i; j++) {
@@ -57,10 +88,44 @@ function buildTraceSnapshots(steps: SimulationStep[]): TraceSnapshots {
       snapshot[prev.node_id] = prev.status === 'error' ? 'error' : 'visited'
     }
 
+    // Mark the incoming edge (previous → current) as traversing.
+    // This shows the signal arriving at the active node rather than
+    // departing, which naturally means step 0 has no edge animation
+    // and parallel branches find their edge from the hub node.
+    if (i > 0) {
+      const prevStep = steps[i - 1]
+      if (prevStep) {
+        // Strategy 1: direct edge from previous step
+        let edgeId = edgeLookup.get(`${prevStep.node_id}->${step.node_id}`)
+
+        // Strategy 2: edge via previous step's routing target
+        // (handles parallel hub skipping: build_project.next=run_tests → run_tests→run_unit_tests)
+        if (!edgeId && prevStep.next && prevStep.next !== step.node_id) {
+          edgeId = edgeLookup.get(`${prevStep.next}->${step.node_id}`)
+        }
+
+        // Strategy 3: find any edge targeting this node in the schema
+        // (handles 2nd+ parallel branches where prev step is a sibling branch)
+        if (!edgeId) {
+          for (const [key, eid] of edgeLookup.entries()) {
+            if (key.endsWith(`->${step.node_id}`)) {
+              edgeId = eid
+              break
+            }
+          }
+        }
+
+        if (edgeId) {
+          edgeSnapshot[edgeId] = 'traversing'
+        }
+      }
+    }
+
     // Mark current node
     snapshot[step.node_id] = step.status === 'error' ? 'error' : 'active'
 
     highlights.push(snapshot)
+    edgeHighlights.push(edgeSnapshot)
 
     // Build cumulative context
     if (step.stepOutput) {
@@ -69,7 +134,7 @@ function buildTraceSnapshots(steps: SimulationStep[]): TraceSnapshots {
     contexts.push({ ...cumulativeCtx })
   }
 
-  return { highlights, contexts }
+  return { highlights, edgeHighlights, contexts }
 }
 
 /**
@@ -86,6 +151,7 @@ function convertRulesData(map: RulesDataMap): Record<string, RulesDocument> {
 }
 
 const emptyHighlights: NodeHighlightMap = {}
+const emptyEdgeHighlightsMap: EdgeHighlightMap = {}
 
 export function useSimulation(
   doc: FlowprintDocument | null,
@@ -95,22 +161,40 @@ export function useSimulation(
   const [currentStep, setCurrentStep] = useState(0)
   const [isAutoPlaying, setIsAutoPlayingState] = useState(false)
   const [error, setError] = useState<string | null>(null)
+  const [playbackSpeed, setPlaybackSpeed] = useState(1)
   const autoPlayRef = useRef(false)
+  const playbackSpeedRef = useRef(1)
 
   const isActive = trace !== null
   const totalSteps = trace?.steps.length ?? 0
   const currentStepData = trace?.steps[currentStep]
   const currentNodeId = currentStepData?.node_id
 
+  // Build edge lookup once when doc changes
+  const edgeLookup = useMemo(() => (doc ? buildEdgeLookup(doc) : new Map<string, string>()), [doc])
+
   // Pre-compute snapshots once when trace changes (Review #19/#25/#34)
   const snapshots = useMemo<TraceSnapshots | null>(() => {
     if (!trace) return null
-    return buildTraceSnapshots(trace.steps)
-  }, [trace])
+    return buildTraceSnapshots(trace.steps, edgeLookup)
+  }, [trace, edgeLookup])
 
   // O(1) lookup per step (Review #19)
   const nodeHighlights = snapshots?.highlights[currentStep] ?? emptyHighlights
 
+  // Track step direction for particle animation
+  const [isForwardStep, setIsForwardStep] = useState(false)
+
+  const edgeHighlights: EdgeHighlightMap =
+    snapshots?.edgeHighlights[currentStep] ?? emptyEdgeHighlightsMap
+  const simulationAnimation: SimulationAnimationConfig = useMemo(
+    () => ({
+      isForwardStep,
+      particleDurationMs: Math.max(400, 1200 / playbackSpeed),
+    }),
+    [isForwardStep, playbackSpeed],
+  )
+
   const start = useCallback(
     (input: unknown, fixtures?: Record<string, unknown>) => {
       if (!doc) return
@@ -142,25 +226,35 @@ export function useSimulation(
     setCurrentStep(0)
     setIsAutoPlayingState(false)
     autoPlayRef.current = false
+    setPlaybackSpeed(1)
+    playbackSpeedRef.current = 1
+    setIsForwardStep(false)
     setError(null)
   }, [])
 
   const stepForward = useCallback(() => {
+    setIsForwardStep(true)
     setCurrentStep((prev) => Math.min(prev + 1, totalSteps - 1))
   }, [totalSteps])
 
   const stepBack = useCallback(() => {
+    setIsForwardStep(false)
     setCurrentStep((prev) => Math.max(prev - 1, 0))
   }, [])
 
   const goToStep = useCallback(
     (step: number) => {
-      setCurrentStep(Math.max(0, Math.min(step, totalSteps - 1)))
+      setCurrentStep((prev) => {
+        const clamped = Math.max(0, Math.min(step, totalSteps - 1))
+        setIsForwardStep(clamped > prev)
+        return clamped
+      })
     },
     [totalSteps],
   )
 
   const reset = useCallback(() => {
+    setIsForwardStep(false)
     setCurrentStep(0)
     setIsAutoPlayingState(false)
     autoPlayRef.current = false
@@ -171,6 +265,11 @@ export function useSimulation(
     autoPlayRef.current = enabled
   }, [])
 
+  const handleSetPlaybackSpeed = useCallback((speed: number) => {
+    setPlaybackSpeed(speed)
+    playbackSpeedRef.current = speed
+  }, [])
+
   // Review #22: chained setTimeout instead of setInterval for auto-play
   useEffect(() => {
     if (!isAutoPlaying || !trace) return
@@ -179,6 +278,7 @@ export function useSimulation(
     const stepsLength = trace.steps.length
 
     function tick() {
+      setIsForwardStep(true)
       setCurrentStep((prev) => {
         const next = prev + 1
         if (next >= stepsLength) {
@@ -186,18 +286,18 @@ export function useSimulation(
           autoPlayRef.current = false
           return prev
         }
-        // Schedule next tick after completing this one
-        timeoutId = setTimeout(tick, 1500)
+        // Schedule next tick — reads current speed via ref
+        timeoutId = setTimeout(tick, 1500 / playbackSpeedRef.current)
         return next
       })
     }
 
-    timeoutId = setTimeout(tick, 1500)
+    timeoutId = setTimeout(tick, 1500 / playbackSpeedRef.current)
 
     return () => {
       clearTimeout(timeoutId)
     }
-  }, [isAutoPlaying, trace])
+  }, [isAutoPlaying, trace, playbackSpeed])
 
   return {
     isActive,
@@ -216,5 +316,9 @@ export function useSimulation(
     reset,
     setAutoPlay,
     isAutoPlaying,
+    playbackSpeed,
+    setPlaybackSpeed: handleSetPlaybackSpeed,
+    edgeHighlights,
+    simulationAnimation,
   }
 }
diff --git a/packages/editor/src/components/FlowprintEditor.tsx b/packages/editor/src/components/FlowprintEditor.tsx
index 0dd8eef..8c13984 100644
--- a/packages/editor/src/components/FlowprintEditor.tsx
+++ b/packages/editor/src/components/FlowprintEditor.tsx
@@ -54,8 +54,16 @@ import type { ThemeMode } from '../hooks/useTheme'
 import type { SymbolSearchProvider } from '../symbols/types'
 import { RulesDataProvider } from '../contexts/RulesDataContext'
 import type { RulesDataMap } from '../contexts/RulesDataContext'
-import { SimulationProvider } from '../contexts/SimulationContext'
-import type { NodeHighlightMap } from '../contexts/SimulationContext'
+import {
+  SimulationProvider,
+  EdgeSimulationProvider,
+  SimulationAnimationProvider,
+} from '../contexts/SimulationContext'
+import type {
+  NodeHighlightMap,
+  EdgeHighlightMap,
+  SimulationAnimationConfig,
+} from '../contexts/SimulationContext'
 
 // ---------------------------------------------------------------------------
 // Types
@@ -75,10 +83,17 @@ export interface FlowprintEditorProps {
   showExportButton?: boolean
   rulesDataMap?: RulesDataMap
   nodeHighlights?: NodeHighlightMap
+  edgeHighlights?: EdgeHighlightMap
+  simulationAnimation?: SimulationAnimationConfig
 }
 
 const emptyRulesDataMap: RulesDataMap = {}
 const emptyHighlights: NodeHighlightMap = {}
+const emptyEdgeHighlights: EdgeHighlightMap = {}
+const defaultAnimationConfig: SimulationAnimationConfig = {
+  isForwardStep: true,
+  particleDurationMs: 600,
+}
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -209,6 +224,8 @@ export function FlowprintEditor({
   theme = 'system',
   rulesDataMap,
   nodeHighlights,
+  edgeHighlights,
+  simulationAnimation,
 }: FlowprintEditorProps) {
   const resolvedTheme = useTheme(theme)
   const state = useFlowprintState({ initialDoc: value, onChange })
@@ -552,6 +569,8 @@ export function FlowprintEditor({
     <ErrorBoundary doc={state.doc}>
       <RulesDataProvider value={rulesDataMap ?? emptyRulesDataMap}>
       <SimulationProvider value={nodeHighlights ?? emptyHighlights}>
+      <EdgeSimulationProvider value={edgeHighlights ?? emptyEdgeHighlights}>
+      <SimulationAnimationProvider value={simulationAnimation ?? defaultAnimationConfig}>
       <ReactFlowProvider>
         <div
           className={`fp-editor${className ? ` ${className}` : ''}`}
@@ -701,6 +720,8 @@ export function FlowprintEditor({
           )}
         </div>
       </ReactFlowProvider>
+      </SimulationAnimationProvider>
+      </EdgeSimulationProvider>
       </SimulationProvider>
       </RulesDataProvider>
     </ErrorBoundary>
diff --git a/packages/editor/src/contexts/SimulationContext.test.tsx b/packages/editor/src/contexts/SimulationContext.test.tsx
index d0a3276..d915a14 100644
--- a/packages/editor/src/contexts/SimulationContext.test.tsx
+++ b/packages/editor/src/contexts/SimulationContext.test.tsx
@@ -1,8 +1,19 @@
 import { describe, it, expect } from 'vitest'
 import { renderHook } from '@testing-library/react'
 import type { ReactNode } from 'react'
-import { SimulationProvider, useNodeHighlight } from './SimulationContext'
-import type { NodeHighlightMap } from './SimulationContext'
+import {
+  SimulationProvider,
+  useNodeHighlight,
+  EdgeSimulationProvider,
+  useEdgeHighlight,
+  SimulationAnimationProvider,
+  useSimulationAnimation,
+} from './SimulationContext'
+import type {
+  NodeHighlightMap,
+  EdgeHighlightMap,
+  SimulationAnimationConfig,
+} from './SimulationContext'
 
 describe('useNodeHighlight', () => {
   it('returns undefined with no provider', () => {
@@ -46,3 +57,62 @@ describe('useNodeHighlight', () => {
     expect(result.current).toBe('visited')
   })
 })
+
+describe('useEdgeHighlight', () => {
+  it('returns undefined with no provider', () => {
+    const { result } = renderHook(() => useEdgeHighlight('e-a-b-0'))
+    expect(result.current).toBeUndefined()
+  })
+
+  it('returns traversing state', () => {
+    const edges: EdgeHighlightMap = { 'e-a-b-0': 'traversing' }
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <EdgeSimulationProvider value={edges}>{children}</EdgeSimulationProvider>
+    )
+    const { result } = renderHook(() => useEdgeHighlight('e-a-b-0'), { wrapper })
+    expect(result.current).toBe('traversing')
+  })
+
+  it('returns traversed state', () => {
+    const edges: EdgeHighlightMap = { 'e-a-b-0': 'traversed' }
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <EdgeSimulationProvider value={edges}>{children}</EdgeSimulationProvider>
+    )
+    const { result } = renderHook(() => useEdgeHighlight('e-a-b-0'), { wrapper })
+    expect(result.current).toBe('traversed')
+  })
+
+  it('returns undefined for unknown edge ID', () => {
+    const edges: EdgeHighlightMap = { 'e-a-b-0': 'traversing' }
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <EdgeSimulationProvider value={edges}>{children}</EdgeSimulationProvider>
+    )
+    const { result } = renderHook(() => useEdgeHighlight('e-x-y-0'), { wrapper })
+    expect(result.current).toBeUndefined()
+  })
+})
+
+describe('useSimulationAnimation', () => {
+  it('returns default config with no provider', () => {
+    const { result } = renderHook(() => useSimulationAnimation())
+    expect(result.current).toEqual({
+      isForwardStep: true,
+      particleDurationMs: 600,
+    })
+  })
+
+  it('returns provided config', () => {
+    const config: SimulationAnimationConfig = {
+      isForwardStep: false,
+      particleDurationMs: 300,
+    }
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <SimulationAnimationProvider value={config}>{children}</SimulationAnimationProvider>
+    )
+    const { result } = renderHook(() => useSimulationAnimation(), { wrapper })
+    expect(result.current).toEqual({
+      isForwardStep: false,
+      particleDurationMs: 300,
+    })
+  })
+})
diff --git a/packages/editor/src/contexts/SimulationContext.tsx b/packages/editor/src/contexts/SimulationContext.tsx
index d5bb487..f322a18 100644
--- a/packages/editor/src/contexts/SimulationContext.tsx
+++ b/packages/editor/src/contexts/SimulationContext.tsx
@@ -1,5 +1,7 @@
 import { createContext, useContext } from 'react'
 
+// ── Node highlights (existing) ──────────────────
+
 export type NodeHighlightState = 'active' | 'visited' | 'error'
 export type NodeHighlightMap = Record<string, NodeHighlightState>
 
@@ -11,3 +13,37 @@ export function useNodeHighlight(nodeId: string): NodeHighlightState | undefined
   const map = useContext(SimulationContext)
   return map[nodeId]
 }
+
+// ── Edge highlights ─────────────────────────────
+
+export type EdgeHighlightState = 'traversing' | 'traversed'
+export type EdgeHighlightMap = Record<string, EdgeHighlightState>
+
+const EdgeSimulationContext = createContext<EdgeHighlightMap>({})
+
+export const EdgeSimulationProvider = EdgeSimulationContext.Provider
+
+export function useEdgeHighlight(edgeId: string): EdgeHighlightState | undefined {
+  const map = useContext(EdgeSimulationContext)
+  return map[edgeId]
+}
+
+// ── Animation config ────────────────────────────
+
+export interface SimulationAnimationConfig {
+  isForwardStep: boolean
+  particleDurationMs: number
+}
+
+const defaultAnimationConfig: SimulationAnimationConfig = {
+  isForwardStep: true,
+  particleDurationMs: 600,
+}
+
+const SimulationAnimationContext = createContext<SimulationAnimationConfig>(defaultAnimationConfig)
+
+export const SimulationAnimationProvider = SimulationAnimationContext.Provider
+
+export function useSimulationAnimation(): SimulationAnimationConfig {
+  return useContext(SimulationAnimationContext)
+}
diff --git a/packages/editor/src/edges/ConditionalEdge.tsx b/packages/editor/src/edges/ConditionalEdge.tsx
index 2bb4681..5792011 100644
--- a/packages/editor/src/edges/ConditionalEdge.tsx
+++ b/packages/editor/src/edges/ConditionalEdge.tsx
@@ -5,6 +5,7 @@ import {
   getSmoothStepPath,
   type EdgeProps,
 } from '@xyflow/react'
+import { EdgeSimulationOverlay } from './EdgeSimulationOverlay'
 
 function ConditionalEdge({
   id,
@@ -59,6 +60,7 @@ function ConditionalEdge({
           pointerEvents: 'none',
         }}
       />
+      <EdgeSimulationOverlay edgeId={id} edgePath={edgePath} />
       <EdgeLabelRenderer>
         {label && (
           <div
diff --git a/packages/editor/src/edges/EdgeSimulationOverlay.tsx b/packages/editor/src/edges/EdgeSimulationOverlay.tsx
new file mode 100644
index 0000000..7a32412
--- /dev/null
+++ b/packages/editor/src/edges/EdgeSimulationOverlay.tsx
@@ -0,0 +1,144 @@
+import { useEffect, useId, useRef } from 'react'
+import { useEdgeHighlight, useSimulationAnimation } from '../contexts/SimulationContext'
+
+interface EdgeSimulationOverlayProps {
+  edgeId: string
+  edgePath: string
+}
+
+export function EdgeSimulationOverlay({ edgeId, edgePath }: EdgeSimulationOverlayProps) {
+  const highlight = useEdgeHighlight(edgeId)
+  const animation = useSimulationAnimation()
+  const uniqueId = useId()
+  const pathId = `fp-sim-path-${uniqueId}`
+  const filterId = `fp-sim-glow-${uniqueId}`
+  const groupRef = useRef<SVGGElement>(null)
+  // Track which edge animation we've already started so re-renders
+  // don't restart the SMIL animation mid-flight.
+  const startedForRef = useRef<string | null>(null)
+  // Store rAF ID in a ref so re-renders don't cancel it via cleanup.
+  // Only cancelled on unmount.
+  const rafRef = useRef<number>(0)
+
+  // Cancel pending rAF only on unmount
+  useEffect(() => {
+    return () => {
+      cancelAnimationFrame(rafRef.current)
+    }
+  }, [])
+
+  useEffect(() => {
+    const g = groupRef.current
+    if (!g) {
+      // Component returned null — reset so next mount triggers animation
+      startedForRef.current = null
+      return
+    }
+    // Already started for this edge — don't restart
+    if (startedForRef.current === edgeId) return
+    startedForRef.current = edgeId
+
+    // The browser's SVG engine needs one frame to register newly inserted
+    // SMIL elements before beginElement() can activate them.
+    rafRef.current = requestAnimationFrame(() => {
+      const smilElements = g.querySelectorAll('animate, animateMotion')
+      smilElements.forEach((el) => {
+        try {
+          ;(el as SVGAnimationElement).beginElement()
+        } catch {
+          // Ignore if element was removed before this frame
+        }
+      })
+    })
+  })
+
+  if (!highlight) return null
+
+  if (highlight === 'traversed') {
+    return null
+  }
+
+  // highlight === 'traversing'
+  // Only show the animation on forward steps.
+  // Backward nav / initial render before first step: nothing to show.
+  if (!animation.isForwardStep) return null
+
+  const durSeconds = (animation.particleDurationMs / 1000).toFixed(2)
+  const dur = `${durSeconds}s`
+
+  return (
+    <g ref={groupRef}>
+      {/* SVG filter for energy bead glow */}
+      <defs>
+        <filter id={filterId} x="-200%" y="-200%" width="500%" height="500%">
+          <feGaussianBlur in="SourceGraphic" stdDeviation="4" result="blur" />
+          <feComposite in="SourceGraphic" in2="blur" operator="over" />
+        </filter>
+      </defs>
+
+      {/* Hidden reference path for animateMotion */}
+      <path id={pathId} d={edgePath} fill="none" stroke="none" />
+
+      {/* Dim base path — shows the route before signal arrives */}
+      <path
+        d={edgePath}
+        stroke="#a6e3a1"
+        strokeWidth={2}
+        strokeOpacity={0.15}
+        fill="none"
+        pointerEvents="none"
+      />
+
+      {/* Progressive trail — draws itself behind the particle */}
+      <path
+        d={edgePath}
+        pathLength={1}
+        stroke="#a6e3a1"
+        strokeWidth={3}
+        strokeDasharray="1"
+        strokeDashoffset="1"
+        fill="none"
+        pointerEvents="none"
+        style={{ filter: 'drop-shadow(0 0 4px rgba(166, 227, 161, 0.6))' }}
+        key={`trail-${edgeId}`}
+      >
+        <animate
+          attributeName="stroke-dashoffset"
+          from="1"
+          to="0"
+          dur={dur}
+          fill="freeze"
+          begin="indefinite"
+        />
+      </path>
+
+      {/* Energy bead — multi-layered particle */}
+      <g filter={`url(#${filterId})`} key={`bead-${edgeId}`}>
+        {/* Outer halo */}
+        <circle r={10} fill="rgba(166, 227, 161, 0.15)">
+          <animateMotion dur={dur} fill="freeze" begin="indefinite">
+            <mpath href={`#${pathId}`} />
+          </animateMotion>
+        </circle>
+        {/* Mid glow */}
+        <circle r={6} fill="rgba(166, 227, 161, 0.35)">
+          <animateMotion dur={dur} fill="freeze" begin="indefinite">
+            <mpath href={`#${pathId}`} />
+          </animateMotion>
+        </circle>
+        {/* Core */}
+        <circle r={4} fill="#a6e3a1">
+          <animateMotion dur={dur} fill="freeze" begin="indefinite">
+            <mpath href={`#${pathId}`} />
+          </animateMotion>
+        </circle>
+        {/* Hot center */}
+        <circle r={1.5} fill="#fff">
+          <animateMotion dur={dur} fill="freeze" begin="indefinite">
+            <mpath href={`#${pathId}`} />
+          </animateMotion>
+        </circle>
+      </g>
+    </g>
+  )
+}
diff --git a/packages/editor/src/edges/ErrorEdge.tsx b/packages/editor/src/edges/ErrorEdge.tsx
index ccc76c3..e974614 100644
--- a/packages/editor/src/edges/ErrorEdge.tsx
+++ b/packages/editor/src/edges/ErrorEdge.tsx
@@ -5,6 +5,7 @@ import {
   getSmoothStepPath,
   type EdgeProps,
 } from '@xyflow/react'
+import { EdgeSimulationOverlay } from './EdgeSimulationOverlay'
 
 function ErrorEdge({
   id,
@@ -53,6 +54,7 @@ function ErrorEdge({
           pointerEvents: 'none',
         }}
       />
+      <EdgeSimulationOverlay edgeId={id} edgePath={edgePath} />
       <EdgeLabelRenderer>
         <button
           type="button"
diff --git a/packages/editor/src/edges/SmoothstepEdge.tsx b/packages/editor/src/edges/SmoothstepEdge.tsx
index 523c05e..8e48a6f 100644
--- a/packages/editor/src/edges/SmoothstepEdge.tsx
+++ b/packages/editor/src/edges/SmoothstepEdge.tsx
@@ -5,6 +5,7 @@ import {
   getSmoothStepPath,
   type EdgeProps,
 } from '@xyflow/react'
+import { EdgeSimulationOverlay } from './EdgeSimulationOverlay'
 
 function SmoothstepEdge({
   id,
@@ -56,6 +57,7 @@ function SmoothstepEdge({
           pointerEvents: 'none',
         }}
       />
+      <EdgeSimulationOverlay edgeId={id} edgePath={edgePath} />
       <EdgeLabelRenderer>
         <button
           type="button"
diff --git a/packages/editor/src/index.ts b/packages/editor/src/index.ts
index e3da6e6..dd34abd 100644
--- a/packages/editor/src/index.ts
+++ b/packages/editor/src/index.ts
@@ -63,8 +63,21 @@ export { RulesDataProvider, useRulesData } from './contexts/RulesDataContext'
 export type { RulesDataMap, RulesDataEntry } from './contexts/RulesDataContext'
 
 // Simulation context
-export { SimulationProvider, useNodeHighlight } from './contexts/SimulationContext'
-export type { NodeHighlightState, NodeHighlightMap } from './contexts/SimulationContext'
+export {
+  SimulationProvider,
+  useNodeHighlight,
+  EdgeSimulationProvider,
+  useEdgeHighlight,
+  SimulationAnimationProvider,
+  useSimulationAnimation,
+} from './contexts/SimulationContext'
+export type {
+  NodeHighlightState,
+  NodeHighlightMap,
+  EdgeHighlightState,
+  EdgeHighlightMap,
+  SimulationAnimationConfig,
+} from './contexts/SimulationContext'
 
 // Theme
 export { useTheme } from './hooks/useTheme'
diff --git a/packages/editor/src/styles/edges.css b/packages/editor/src/styles/edges.css
index 44d3ddd..213464a 100644
--- a/packages/editor/src/styles/edges.css
+++ b/packages/editor/src/styles/edges.css
@@ -46,3 +46,5 @@
   color: var(--fp-text-primary);
   border-color: var(--fp-border-strong);
 }
+
+
diff --git a/packages/editor/src/styles/nodes.css b/packages/editor/src/styles/nodes.css
index 56e471f..a6052d7 100644
--- a/packages/editor/src/styles/nodes.css
+++ b/packages/editor/src/styles/nodes.css
@@ -100,6 +100,21 @@
   }
 }
 
+@keyframes fp-sim-entrance {
+  0% {
+    transform: scale(0.95);
+    opacity: 0.7;
+  }
+  60% {
+    transform: scale(1.02);
+    opacity: 1;
+  }
+  100% {
+    transform: scale(1);
+    opacity: 1;
+  }
+}
+
 .fp-node--sim-active {
   --fp-sim-glow: rgba(166, 227, 161, 0.5);
   background: rgba(166, 227, 161, 0.15);
@@ -108,7 +123,9 @@
   box-shadow:
     0 0 0 3px rgba(166, 227, 161, 0.3),
     0 0 12px rgba(166, 227, 161, 0.2);
-  animation: fp-sim-pulse 1.5s ease-in-out infinite;
+  animation:
+    fp-sim-entrance 0.3s ease-out,
+    fp-sim-pulse 1.5s ease-in-out 0.3s infinite;
 }
 
 .fp-node--sim-visited {
diff --git a/packages/engine/src/__tests__/simulator.test.ts b/packages/engine/src/__tests__/simulator.test.ts
index 5be9d8d..75e5cba 100644
--- a/packages/engine/src/__tests__/simulator.test.ts
+++ b/packages/engine/src/__tests__/simulator.test.ts
@@ -200,8 +200,9 @@ describe('simulateGraph', () => {
 
       const trace = await simulateGraph(doc, makeOptions())
 
-      expect(trace.steps[0]?.status).toBe('error')
-      expect(trace.steps[0]?.error).toContain('not found in rulesData')
+      // Missing rules are skipped gracefully — node completes with empty output
+      expect(trace.steps[0]?.status).toBe('completed')
+      expect(trace.steps).toHaveLength(2) // proceeds to 'done' terminal
     })
   })
 
@@ -249,6 +250,102 @@ describe('simulateGraph', () => {
     })
   })
 
+  describe('switch fixture data', () => {
+    it('matches fixture string against case.when labels', async () => {
+      const doc = makeDoc({
+        check: {
+          type: 'switch',
+          lane: 'default',
+          label: 'Check',
+          cases: [
+            { when: 'Approved', next: 'approve' },
+            { when: 'Rejected', next: 'reject' },
+          ],
+          default: 'fallback',
+        },
+        approve: { type: 'terminal', lane: 'default', label: 'Approve', outcome: 'success' },
+        reject: { type: 'terminal', lane: 'default', label: 'Reject', outcome: 'failure' },
+        fallback: { type: 'terminal', lane: 'default', label: 'Fallback', outcome: 'success' },
+      })
+
+      const trace = await simulateGraph(doc, makeOptions({
+        fixtures: { check: 'Approved' },
+      }))
+
+      expect(trace.steps.map((s) => s.node_id)).toEqual(['check', 'approve'])
+      expect(trace.steps[0]?.status).toBe('matched')
+      expect(trace.steps[0]?.matched_case).toBe(0)
+      expect(trace.steps[0]?.stepOutput).toEqual({ nodeId: 'check', value: 'Approved' })
+    })
+
+    it('routes to default when fixture is "default"', async () => {
+      const doc = makeDoc({
+        check: {
+          type: 'switch',
+          lane: 'default',
+          label: 'Check',
+          cases: [{ when: 'Express', next: 'fast' }],
+          default: 'slow',
+        },
+        fast: { type: 'terminal', lane: 'default', label: 'Fast', outcome: 'success' },
+        slow: { type: 'terminal', lane: 'default', label: 'Slow', outcome: 'success' },
+      })
+
+      const trace = await simulateGraph(doc, makeOptions({
+        fixtures: { check: 'default' },
+      }))
+
+      expect(trace.steps.map((s) => s.node_id)).toEqual(['check', 'slow'])
+      expect(trace.steps[0]?.status).toBe('default')
+    })
+
+    it('falls through to expression evaluation when fixture does not match any label', async () => {
+      const doc = makeDoc({
+        check: {
+          type: 'switch',
+          lane: 'default',
+          label: 'Check',
+          cases: [
+            { when: 'input.amount > 100', next: 'high' },
+          ],
+          default: 'low',
+        },
+        high: { type: 'terminal', lane: 'default', label: 'High', outcome: 'success' },
+        low: { type: 'terminal', lane: 'default', label: 'Low', outcome: 'success' },
+      })
+
+      const trace = await simulateGraph(doc, makeOptions({
+        input: { amount: 200 },
+        fixtures: { check: 'NoMatch' },
+      }))
+
+      // Fixture "NoMatch" doesn't match any case label, so falls through to expression eval
+      expect(trace.steps.map((s) => s.node_id)).toEqual(['check', 'high'])
+    })
+
+    it('does not interfere when no fixture provided', async () => {
+      const doc = makeDoc({
+        check: {
+          type: 'switch',
+          lane: 'default',
+          label: 'Check',
+          cases: [
+            { when: 'Approved', next: 'approve' },
+          ],
+          default: 'fallback',
+        },
+        approve: { type: 'terminal', lane: 'default', label: 'Approve', outcome: 'success' },
+        fallback: { type: 'terminal', lane: 'default', label: 'Fallback', outcome: 'success' },
+      })
+
+      // Label-style when values are not valid expressions, so falls through to default
+      const trace = await simulateGraph(doc, makeOptions())
+
+      expect(trace.steps.map((s) => s.node_id)).toEqual(['check', 'fallback'])
+      expect(trace.steps[0]?.status).toBe('default')
+    })
+  })
+
   describe('fixture data', () => {
     it('uses fixture for entry-point action', async () => {
       const doc = makeDoc({
diff --git a/packages/engine/src/simulator/simulator.ts b/packages/engine/src/simulator/simulator.ts
index b2e9a3c..67b676d 100644
--- a/packages/engine/src/simulator/simulator.ts
+++ b/packages/engine/src/simulator/simulator.ts
@@ -59,11 +59,17 @@ export async function simulateGraph(
     }
     const rulesDoc = options.rulesData[rulesRef.file]
     if (!rulesDoc) {
+      // Missing rules: continue simulation with empty output instead of halting.
+      // This allows templates to be simulated without providing rules files.
+      ctx.results.set(nodeId, {})
       return {
-        node_id: nodeId,
-        type: 'action',
-        status: 'error',
-        error: `Rules file "${rulesRef.file}" not found in rulesData`,
+        detail: {
+          file: rulesRef.file,
+          hitPolicy: 'none',
+          matchedCount: 0,
+          output: {},
+        },
+        output: {},
       }
     }
     const execCtx: ExecutionContext = { input: options.input, results: ctx.results }
@@ -109,6 +115,37 @@ export async function simulateGraph(
     },
 
     onSwitch(nodeId, node, ctx) {
+      // Switch fixture support: match fixture string against case labels
+      const switchFixture = options.fixtures?.[nodeId]
+      if (switchFixture != null && typeof switchFixture === 'string') {
+        for (let i = 0; i < (node.cases?.length ?? 0); i++) {
+          const c = node.cases?.[i]
+          if (!c) continue
+          if (c.when === switchFixture) {
+            ctx.results.set(nodeId, switchFixture)
+            return {
+              node_id: nodeId,
+              type: 'switch',
+              status: 'matched',
+              matched_case: i,
+              next: c.next,
+              stepOutput: { nodeId, value: switchFixture },
+            }
+          }
+        }
+        if (switchFixture === 'default' && node.default) {
+          ctx.results.set(nodeId, switchFixture)
+          return {
+            node_id: nodeId,
+            type: 'switch',
+            status: 'default',
+            next: node.default,
+            stepOutput: { nodeId, value: switchFixture },
+          }
+        }
+        // No label match → fall through to normal rules/expression evaluation
+      }
+
       if (node.rules) {
         const rulesResult = evaluateNodeRules(nodeId, node.rules, ctx)
         if ('node_id' in rulesResult) {

From db6e1bdc76004d7c04c0476d169e63232d106114 Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Mon, 9 Mar 2026 08:16:11 -0400
Subject: [PATCH 02/14] fix(sim): delay node active glow until edge particle
 arrives

The active node now stays visually neutral during the particle transit,
then lights up when the animation completes. Uses CSS animation-delay
with animation-fill-mode:both to hold the pre-animation state.
---
 packages/editor/src/nodes/NodeShell.tsx | 10 +++++++++-
 packages/editor/src/styles/nodes.css    | 24 ++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/packages/editor/src/nodes/NodeShell.tsx b/packages/editor/src/nodes/NodeShell.tsx
index 57c85c6..cf13bce 100644
--- a/packages/editor/src/nodes/NodeShell.tsx
+++ b/packages/editor/src/nodes/NodeShell.tsx
@@ -1,7 +1,7 @@
 import type { ComponentType, ReactNode } from 'react'
 import { Handle, Position } from '@xyflow/react'
 import { MoreHorizontal } from 'lucide-react'
-import { useNodeHighlight } from '../contexts/SimulationContext'
+import { useNodeHighlight, useSimulationAnimation } from '../contexts/SimulationContext'
 
 export interface NodeShellProps {
   nodeId: string
@@ -31,6 +31,10 @@ export function NodeShell({
   children,
 }: NodeShellProps) {
   const simState = useNodeHighlight(nodeId)
+  const simAnimation = useSimulationAnimation()
+
+  // When stepping forward, delay the "active" glow until the particle arrives
+  const isDelayedActive = simState === 'active' && simAnimation.isForwardStep
 
   const classNames = [
     'fp-node',
@@ -38,6 +42,7 @@ export function NodeShell({
     isUnassigned && 'fp-node--unassigned',
     hasError && 'fp-node--error',
     simState === 'active' && 'fp-node--sim-active',
+    isDelayedActive && 'fp-node--sim-active-delayed',
     simState === 'visited' && 'fp-node--sim-visited',
     simState === 'error' && 'fp-node--sim-error',
   ]
@@ -52,6 +57,9 @@ export function NodeShell({
       style={{
         '--node-accent': `var(${colorVar})`,
         '--node-accent-subtle': `var(${colorVar}-subtle)`,
+        ...(isDelayedActive && {
+          '--fp-sim-particle-dur': `${String(simAnimation.particleDurationMs)}ms`,
+        }),
       } as React.CSSProperties}
     >
       <Handle type="target" position={Position.Left} />
diff --git a/packages/editor/src/styles/nodes.css b/packages/editor/src/styles/nodes.css
index a6052d7..f7fdddc 100644
--- a/packages/editor/src/styles/nodes.css
+++ b/packages/editor/src/styles/nodes.css
@@ -128,6 +128,30 @@
     fp-sim-pulse 1.5s ease-in-out 0.3s infinite;
 }
 
+/* Delay the active glow until the edge particle arrives */
+@keyframes fp-sim-delayed-entrance {
+  0% {
+    background: transparent;
+    border-color: var(--fp-border-default);
+    box-shadow: none;
+    opacity: 1;
+  }
+  100% {
+    background: rgba(166, 227, 161, 0.15);
+    border-color: #a6e3a1;
+    box-shadow:
+      0 0 0 3px rgba(166, 227, 161, 0.3),
+      0 0 12px rgba(166, 227, 161, 0.2);
+    opacity: 1;
+  }
+}
+
+.fp-node--sim-active.fp-node--sim-active-delayed {
+  animation:
+    fp-sim-delayed-entrance 0.3s ease-out var(--fp-sim-particle-dur, 0ms) both,
+    fp-sim-pulse 1.5s ease-in-out calc(var(--fp-sim-particle-dur, 0ms) + 0.3s) infinite;
+}
+
 .fp-node--sim-visited {
   background: rgba(180, 190, 254, 0.1);
   border-color: #b4befe;

From b98655ad9b3ac82e0f9517d5b80c80c8de5bd449 Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Mon, 9 Mar 2026 08:22:41 -0400
Subject: [PATCH 03/14] fix(sim): keep node's normal appearance during edge
 particle transit

Use var(--fp-bg-node) and var(--fp-border-default) at keyframe 0%
so the node looks unchanged during the delay, not transparent.
---
 packages/editor/src/styles/nodes.css | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/editor/src/styles/nodes.css b/packages/editor/src/styles/nodes.css
index f7fdddc..b5ff7b8 100644
--- a/packages/editor/src/styles/nodes.css
+++ b/packages/editor/src/styles/nodes.css
@@ -128,13 +128,14 @@
     fp-sim-pulse 1.5s ease-in-out 0.3s infinite;
 }
 
-/* Delay the active glow until the edge particle arrives */
+/* Delay the active glow until the edge particle arrives.
+ * animation-fill-mode:both holds the 0% (normal) look during the delay,
+ * then transitions to 100% (active glow) over 0.3s. */
 @keyframes fp-sim-delayed-entrance {
   0% {
-    background: transparent;
+    background: var(--fp-bg-node);
     border-color: var(--fp-border-default);
     box-shadow: none;
-    opacity: 1;
   }
   100% {
     background: rgba(166, 227, 161, 0.15);
@@ -142,7 +143,6 @@
     box-shadow:
       0 0 0 3px rgba(166, 227, 161, 0.3),
       0 0 12px rgba(166, 227, 161, 0.2);
-    opacity: 1;
   }
 }
 

From d9de56c28553e9b8843770d5b429cb5fabe86888 Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Mon, 9 Mar 2026 08:43:08 -0400
Subject: [PATCH 04/14] fix(sim): add error.catch routing and fix broken
 scenarios
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The simulator's onAction handler always routed to node.next, ignoring
error.catch. This meant templates with error handlers (CI/CD, insurance)
never took the error path. Added _error fixture convention to trigger
error.catch routing.

Fixed CI/CD build-failure scenario to use { _error: true } so it routes
to handle_build_failure. Fixed insurance counter-offer scenario that
infinite-looped (static fixture always returned 'Counter-offer') by
renaming to senior-review with 'Accepted' outcome.

Added e2e test validating all 24 template×scenario pairs reach terminal
nodes without crashes, no-match fallthrough, or infinite loops.
---
 .../src/data/template-scenarios-e2e.test.ts   | 75 +++++++++++++++++++
 packages/app/src/data/template-scenarios.ts   | 14 ++--
 .../engine/src/__tests__/simulator.test.ts    | 65 ++++++++++++++++
 packages/engine/src/simulator/simulator.ts    | 15 +++-
 4 files changed, 161 insertions(+), 8 deletions(-)
 create mode 100644 packages/app/src/data/template-scenarios-e2e.test.ts

diff --git a/packages/app/src/data/template-scenarios-e2e.test.ts b/packages/app/src/data/template-scenarios-e2e.test.ts
new file mode 100644
index 0000000..d67d487
--- /dev/null
+++ b/packages/app/src/data/template-scenarios-e2e.test.ts
@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest'
+import { simulateGraph } from '@ruminaider/flowprint-engine/browser'
+import type { RulesDocument } from '@ruminaider/flowprint-engine/browser'
+import type { RulesDataMap } from '@ruminaider/flowprint-editor'
+import { getTemplates, loadTemplate } from './templates'
+import { getScenarios } from './template-scenarios'
+
+function convertRulesData(map: RulesDataMap): Record<string, RulesDocument> {
+  const result: Record<string, RulesDocument> = {}
+  for (const [key, entry] of Object.entries(map)) {
+    if (entry.data) {
+      result[key] = entry.data as unknown as RulesDocument
+    }
+  }
+  return result
+}
+
+describe('template scenarios e2e', () => {
+  const templates = getTemplates()
+
+  for (const tmpl of templates) {
+    const doc = loadTemplate(tmpl.id)
+    const docName = doc.name
+    const scenarios = getScenarios(docName)
+
+    if (scenarios.length === 0) continue
+
+    describe(docName, () => {
+      for (const scenario of scenarios) {
+        it(`${scenario.id}: ${scenario.name}`, async () => {
+          const trace = await simulateGraph(doc, {
+            input: scenario.input,
+            fixtures: scenario.fixtures,
+            rulesData: scenario.rulesData ? convertRulesData(scenario.rulesData) : {},
+          })
+
+          // 1. No engine crash
+          expect(
+            trace.status,
+            `Engine error: ${trace.error ?? 'unknown'}`,
+          ).not.toBe('error')
+
+          // 2. Produced steps
+          expect(trace.steps.length).toBeGreaterThan(0)
+
+          // 3. Last step is terminal
+          const lastStep = trace.steps[trace.steps.length - 1]
+          expect(lastStep?.type, 'Last step should be terminal').toBe('terminal')
+
+          // 4. No switch fell through (no-match means missing fixture/case)
+          const noMatchSteps = trace.steps.filter((s) => s.status === 'no-match')
+          expect(
+            noMatchSteps,
+            `Switch nodes fell through: ${noMatchSteps.map((s) => s.node_id).join(', ')}`,
+          ).toHaveLength(0)
+
+          // 5. No unexpected errors (error-caught is OK)
+          const errorSteps = trace.steps.filter(
+            (s) => s.status === 'error' && s.type !== 'error',
+          )
+          expect(
+            errorSteps,
+            `Unexpected errors: ${errorSteps.map((s) => `${s.node_id}: ${s.error}`).join(', ')}`,
+          ).toHaveLength(0)
+
+          // 6. No infinite loops
+          expect(
+            trace.steps.length,
+            `Possible infinite loop: ${trace.steps.length} steps`,
+          ).toBeLessThan(50)
+        })
+      }
+    })
+  }
+})
diff --git a/packages/app/src/data/template-scenarios.ts b/packages/app/src/data/template-scenarios.ts
index 93911f2..3a4aab8 100644
--- a/packages/app/src/data/template-scenarios.ts
+++ b/packages/app/src/data/template-scenarios.ts
@@ -235,7 +235,7 @@ const TEMPLATE_SCENARIOS: Record<string, TemplateScenario[]> = {
       fixtures: {
         push_code: { sha: 'def5678', branch: 'feature/broken' },
         install_dependencies: { cached: false, packages: 142 },
-        build_project: { success: false, error: 'TypeScript compilation failed' },
+        build_project: { _error: true, error: 'TypeScript compilation failed' },
       },
     },
     {
@@ -765,9 +765,10 @@ const TEMPLATE_SCENARIOS: Record<string, TemplateScenario[]> = {
       },
     },
     {
-      id: 'counter-offer',
-      name: 'Counter-Offer Negotiation',
-      description: 'A property claim where the claimant counter-offers, leading to re-evaluation',
+      id: 'senior-review',
+      name: 'Senior Review with Acceptance',
+      description:
+        'A high-value property claim escalated to senior adjuster, settled and accepted',
       input: {
         claim: { type: 'property', amount: 75000, incident: 'Storm damage', date: '2025-03-01' },
         claimant: { id: 'CLT-003', name: 'Carol', policyNumber: 'POL-P300' },
@@ -783,8 +784,9 @@ const TEMPLATE_SCENARIOS: Record<string, TemplateScenario[]> = {
         senior_adjuster_review: { reviewed: true, recommendation: 65000 },
         calculate_settlement: { amount: 62000 },
         present_offer: { amount: 62000 },
-        await_claimant_response: { response: 'counter', requestedAmount: 70000 },
-        check_claimant_decision: 'Counter-offer',
+        await_claimant_response: { response: 'accept' },
+        check_claimant_decision: 'Accepted',
+        process_payment: { paid: true, amount: 62000, method: 'direct deposit' },
       },
       rulesData: {
         'rules/escalation.rules.yaml': {
diff --git a/packages/engine/src/__tests__/simulator.test.ts b/packages/engine/src/__tests__/simulator.test.ts
index 75e5cba..86cd9de 100644
--- a/packages/engine/src/__tests__/simulator.test.ts
+++ b/packages/engine/src/__tests__/simulator.test.ts
@@ -610,6 +610,71 @@ describe('simulateGraph', () => {
     })
   })
 
+  describe('error.catch routing', () => {
+    const makeErrorDoc = (withCatch: boolean) =>
+      makeDoc({
+        risky: {
+          type: 'action',
+          lane: 'default',
+          label: 'Risky',
+          entry_points: [{ file: 'a.ts', symbol: 'fn' }],
+          next: 'done',
+          ...(withCatch ? { error: { catch: 'handler' } } : {}),
+        },
+        handler: {
+          type: 'error',
+          lane: 'default',
+          label: 'Handle Error',
+          next: 'failed',
+        },
+        failed: { type: 'terminal', lane: 'default', label: 'Failed', outcome: 'failure' },
+        done: { type: 'terminal', lane: 'default', label: 'Done', outcome: 'success' },
+      })
+
+    it('_error string routes to catch target', async () => {
+      const trace = await simulateGraph(
+        makeErrorDoc(true),
+        makeOptions({ fixtures: { risky: '_error' } }),
+      )
+
+      expect(trace.steps.map((s) => s.node_id)).toEqual(['risky', 'handler', 'failed'])
+      expect(trace.steps[0]?.status).toBe('error-caught')
+      expect(trace.status).toBe('failure')
+    })
+
+    it('{ _error: true } object routes to catch target', async () => {
+      const trace = await simulateGraph(
+        makeErrorDoc(true),
+        makeOptions({ fixtures: { risky: { _error: true, msg: 'boom' } } }),
+      )
+
+      expect(trace.steps.map((s) => s.node_id)).toEqual(['risky', 'handler', 'failed'])
+      expect(trace.steps[0]?.status).toBe('error-caught')
+    })
+
+    it('normal fixture routes to next', async () => {
+      const trace = await simulateGraph(
+        makeErrorDoc(true),
+        makeOptions({ fixtures: { risky: { ok: true } } }),
+      )
+
+      expect(trace.steps.map((s) => s.node_id)).toEqual(['risky', 'done'])
+      expect(trace.steps[0]?.status).toBe('completed')
+      expect(trace.status).toBe('success')
+    })
+
+    it('_error without error.catch routes to next', async () => {
+      const trace = await simulateGraph(
+        makeErrorDoc(false),
+        makeOptions({ fixtures: { risky: '_error' } }),
+      )
+
+      expect(trace.steps.map((s) => s.node_id)).toEqual(['risky', 'done'])
+      expect(trace.steps[0]?.status).toBe('completed')
+      expect(trace.status).toBe('success')
+    })
+  })
+
   describe('failure terminal', () => {
     it('reports failure status when terminal has outcome=failure', async () => {
       const doc = makeDoc({
diff --git a/packages/engine/src/simulator/simulator.ts b/packages/engine/src/simulator/simulator.ts
index 67b676d..e70b73a 100644
--- a/packages/engine/src/simulator/simulator.ts
+++ b/packages/engine/src/simulator/simulator.ts
@@ -105,11 +105,22 @@ export async function simulateGraph(
       // Entry-point action — use fixture or undefined
       const fixture = options.fixtures?.[nodeId]
       ctx.results.set(nodeId, fixture)
+
+      // Check if fixture signals an error and node has error.catch
+      const isErrorFixture =
+        fixture === '_error' ||
+        (typeof fixture === 'object' &&
+          fixture !== null &&
+          '_error' in (fixture as Record<string, unknown>) &&
+          (fixture as Record<string, unknown>)._error === true)
+      const catchTarget = node.error?.catch
+      const next = isErrorFixture && catchTarget ? catchTarget : node.next
+
       return {
         node_id: nodeId,
         type: 'action',
-        status: 'completed',
-        next: node.next,
+        status: isErrorFixture && catchTarget ? 'error-caught' : 'completed',
+        next,
         stepOutput: { nodeId, value: fixture },
       }
     },

From bec9967e401fcfc070d14558369817f2fd582f20 Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Mon, 9 Mar 2026 19:47:59 -0400
Subject: [PATCH 05/14] fix(sim): sync auto-play step interval with particle
 animation duration

The auto-play timer (1500/speed ms) didn't account for particle
animation duration (1200/speed ms) or the 300ms CSS glow transition.
At 2x+ speed, the next step fired before the particle finished or
the node glow appeared, making edges look unanimated.

Step interval is now particle duration + 500ms settle time, ensuring
the particle completes and the node glow is visible before advancing:
  1x: 1700ms (was 1500ms)
  2x: 1100ms (was 750ms)
  4x:  900ms (was 375ms)
---
 packages/app/src/hooks/useSimulation.test.ts | 14 +++++++-------
 packages/app/src/hooks/useSimulation.ts      | 15 ++++++++++++---
 2 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/packages/app/src/hooks/useSimulation.test.ts b/packages/app/src/hooks/useSimulation.test.ts
index acd4b86..9caf172 100644
--- a/packages/app/src/hooks/useSimulation.test.ts
+++ b/packages/app/src/hooks/useSimulation.test.ts
@@ -316,15 +316,15 @@ describe('useSimulation', () => {
     expect(result.current.isAutoPlaying).toBe(true)
     expect(result.current.currentStep).toBe(0)
 
-    // Advance one tick
+    // Advance one tick (at 1x: particle 1200ms + 500ms settle = 1700ms)
     await act(async () => {
-      await vi.advanceTimersByTimeAsync(1500)
+      await vi.advanceTimersByTimeAsync(1700)
     })
     expect(result.current.currentStep).toBe(1)
 
     // Advance another tick
     await act(async () => {
-      await vi.advanceTimersByTimeAsync(1500)
+      await vi.advanceTimersByTimeAsync(1700)
     })
     expect(result.current.currentStep).toBe(2)
   })
@@ -344,13 +344,13 @@ describe('useSimulation', () => {
 
     // First tick: step 0 → 1 (last step)
     await act(async () => {
-      await vi.advanceTimersByTimeAsync(1500)
+      await vi.advanceTimersByTimeAsync(1700)
     })
     expect(result.current.currentStep).toBe(1)
 
     // Second tick: should stop
     await act(async () => {
-      await vi.advanceTimersByTimeAsync(1500)
+      await vi.advanceTimersByTimeAsync(1700)
     })
     expect(result.current.currentStep).toBe(1)
     expect(result.current.isAutoPlaying).toBe(false)
@@ -412,9 +412,9 @@ describe('useSimulation', () => {
       result.current.setAutoPlay(true)
     })
 
-    // At 2x speed, interval = 1500/2 = 750ms
+    // At 2x speed, interval = particle(600ms) + settle(500ms) = 1100ms
     await act(async () => {
-      await vi.advanceTimersByTimeAsync(750)
+      await vi.advanceTimersByTimeAsync(1100)
     })
     expect(result.current.currentStep).toBe(1)
   })
diff --git a/packages/app/src/hooks/useSimulation.ts b/packages/app/src/hooks/useSimulation.ts
index 8cb69bc..89ca780 100644
--- a/packages/app/src/hooks/useSimulation.ts
+++ b/packages/app/src/hooks/useSimulation.ts
@@ -270,13 +270,22 @@ export function useSimulation(
     playbackSpeedRef.current = speed
   }, [])
 
-  // Review #22: chained setTimeout instead of setInterval for auto-play
+  // Review #22: chained setTimeout instead of setInterval for auto-play.
+  // Step interval must wait for: particle traversal + glow settle + visible glow time.
+  // Without this, at 2x+ the next step fires before the particle finishes or the
+  // node glow appears, making edges look like they don't animate.
   useEffect(() => {
     if (!isAutoPlaying || !trace) return
 
     let timeoutId: ReturnType<typeof setTimeout>
     const stepsLength = trace.steps.length
 
+    function stepInterval(speed: number): number {
+      const particleDur = Math.max(400, 1200 / speed)
+      const glowSettleMs = 500 // 300ms CSS transition + 200ms visible glow
+      return particleDur + glowSettleMs
+    }
+
     function tick() {
       setIsForwardStep(true)
       setCurrentStep((prev) => {
@@ -287,12 +296,12 @@ export function useSimulation(
           return prev
         }
         // Schedule next tick — reads current speed via ref
-        timeoutId = setTimeout(tick, 1500 / playbackSpeedRef.current)
+        timeoutId = setTimeout(tick, stepInterval(playbackSpeedRef.current))
         return next
       })
     }
 
-    timeoutId = setTimeout(tick, 1500 / playbackSpeedRef.current)
+    timeoutId = setTimeout(tick, stepInterval(playbackSpeedRef.current))
 
     return () => {
       clearTimeout(timeoutId)

From c531edb74974050c45cace53fa937c816c3fad5c Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Mon, 9 Mar 2026 20:33:55 -0400
Subject: [PATCH 06/14] fix(sim): handle parallel hub step ordering for correct
 visual playback

Parallel hubs now emit an "entered" step before branch steps so the hub
node lights up before branches fan out. The edge snapshot builder skips
re-animating edges for the hub's "completed" step to avoid wrong visuals.
---
 packages/app/src/hooks/useSimulation.ts         |  8 ++++++--
 packages/engine/src/__tests__/simulator.test.ts |  9 ++++-----
 packages/engine/src/simulator/simulator.ts      | 10 ++++++++++
 3 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/packages/app/src/hooks/useSimulation.ts b/packages/app/src/hooks/useSimulation.ts
index 89ca780..33b40e9 100644
--- a/packages/app/src/hooks/useSimulation.ts
+++ b/packages/app/src/hooks/useSimulation.ts
@@ -92,14 +92,18 @@ function buildTraceSnapshots(
     // This shows the signal arriving at the active node rather than
     // departing, which naturally means step 0 has no edge animation
     // and parallel branches find their edge from the hub node.
-    if (i > 0) {
+    // Skip edge animation for parallel "completed" steps — the hub was
+    // already visited via the "entered" step, so re-animating an edge
+    // into it would show the wrong visual.
+    const isParallelRevisit = step.type === 'parallel' && step.status === 'completed'
+    if (i > 0 && !isParallelRevisit) {
       const prevStep = steps[i - 1]
       if (prevStep) {
         // Strategy 1: direct edge from previous step
         let edgeId = edgeLookup.get(`${prevStep.node_id}->${step.node_id}`)
 
         // Strategy 2: edge via previous step's routing target
-        // (handles parallel hub skipping: build_project.next=run_tests → run_tests→run_unit_tests)
+        // (handles parallel hub → first branch: build_project.next=run_tests → run_tests→run_unit_tests)
         if (!edgeId && prevStep.next && prevStep.next !== step.node_id) {
           edgeId = edgeLookup.get(`${prevStep.next}->${step.node_id}`)
         }
diff --git a/packages/engine/src/__tests__/simulator.test.ts b/packages/engine/src/__tests__/simulator.test.ts
index 86cd9de..cafda5a 100644
--- a/packages/engine/src/__tests__/simulator.test.ts
+++ b/packages/engine/src/__tests__/simulator.test.ts
@@ -418,12 +418,11 @@ describe('simulateGraph', () => {
       }))
 
       expect(trace.status).toBe('success')
-      // Branch steps are pushed by onParallel, plus the parallel step itself, plus terminal
+      // Parallel hub emits "entered" before branches, then "completed" after
       const nodeIds = trace.steps.map((s) => s.node_id)
-      expect(nodeIds).toContain('b1')
-      expect(nodeIds).toContain('b2')
-      expect(nodeIds).toContain('par')
-      expect(nodeIds).toContain('done')
+      expect(nodeIds).toEqual(['par', 'b1', 'b2', 'par', 'done'])
+      expect(trace.steps[0]?.status).toBe('entered')
+      expect(trace.steps[3]?.status).toBe('completed')
     })
   })
 
diff --git a/packages/engine/src/simulator/simulator.ts b/packages/engine/src/simulator/simulator.ts
index e70b73a..4b288ad 100644
--- a/packages/engine/src/simulator/simulator.ts
+++ b/packages/engine/src/simulator/simulator.ts
@@ -216,6 +216,14 @@ export async function simulateGraph(
     },
 
     onParallel(nodeId, node, ctx) {
+      // Emit "entered" step so the hub node lights up before branches fan out.
+      // Without this, the signal visually skips the hub and jumps to branches.
+      ctx.steps.push({
+        node_id: nodeId,
+        type: 'parallel',
+        status: 'entered',
+      })
+
       // Visit all branches sequentially (traces each path with fixtures)
       for (const branchId of node.branches) {
         const fixture = options.fixtures?.[branchId]
@@ -232,6 +240,8 @@ export async function simulateGraph(
         branchResults[branchId] = ctx.results.get(branchId)
       }
       ctx.results.set(nodeId, branchResults)
+      // The walk skeleton pushes this "completed" step after branches.
+      // Edge animation is skipped for this step since the hub was already visited.
       return {
         node_id: nodeId,
         type: 'parallel',

From 413aee0b57ed9915d3c5925ad69761bc940b9875 Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Mon, 9 Mar 2026 20:51:25 -0400
Subject: [PATCH 07/14] fix(sim): skip edge animation at parallel join nodes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hub→join edge physically crosses over branch nodes in the layout,
causing the particle animation to visually "run over" branches. Now
skip edge animation when the previous step is a parallel "completed"
step (i.e. we're arriving at the join target).
---
 packages/app/src/hooks/useSimulation.ts | 46 +++++++++++++------------
 1 file changed, 24 insertions(+), 22 deletions(-)

diff --git a/packages/app/src/hooks/useSimulation.ts b/packages/app/src/hooks/useSimulation.ts
index 33b40e9..644060f 100644
--- a/packages/app/src/hooks/useSimulation.ts
+++ b/packages/app/src/hooks/useSimulation.ts
@@ -95,33 +95,35 @@ function buildTraceSnapshots(
     // Skip edge animation for parallel "completed" steps — the hub was
     // already visited via the "entered" step, so re-animating an edge
     // into it would show the wrong visual.
+    // Also skip for the join target (step after parallel "completed") — the
+    // hub→join edge crosses over branch nodes, making the particle look wrong.
     const isParallelRevisit = step.type === 'parallel' && step.status === 'completed'
-    if (i > 0 && !isParallelRevisit) {
-      const prevStep = steps[i - 1]
-      if (prevStep) {
-        // Strategy 1: direct edge from previous step
-        let edgeId = edgeLookup.get(`${prevStep.node_id}->${step.node_id}`)
-
-        // Strategy 2: edge via previous step's routing target
-        // (handles parallel hub → first branch: build_project.next=run_tests → run_tests→run_unit_tests)
-        if (!edgeId && prevStep.next && prevStep.next !== step.node_id) {
-          edgeId = edgeLookup.get(`${prevStep.next}->${step.node_id}`)
-        }
+    const prevStep = i > 0 ? steps[i - 1] : undefined
+    const isParallelJoin =
+      prevStep?.type === 'parallel' && prevStep?.status === 'completed'
+    if (i > 0 && !isParallelRevisit && !isParallelJoin && prevStep) {
+      // Strategy 1: direct edge from previous step
+      let edgeId = edgeLookup.get(`${prevStep.node_id}->${step.node_id}`)
+
+      // Strategy 2: edge via previous step's routing target
+      // (handles parallel hub → first branch: build_project.next=run_tests → run_tests→run_unit_tests)
+      if (!edgeId && prevStep.next && prevStep.next !== step.node_id) {
+        edgeId = edgeLookup.get(`${prevStep.next}->${step.node_id}`)
+      }
 
-        // Strategy 3: find any edge targeting this node in the schema
-        // (handles 2nd+ parallel branches where prev step is a sibling branch)
-        if (!edgeId) {
-          for (const [key, eid] of edgeLookup.entries()) {
-            if (key.endsWith(`->${step.node_id}`)) {
-              edgeId = eid
-              break
-            }
+      // Strategy 3: find any edge targeting this node in the schema
+      // (handles 2nd+ parallel branches where prev step is a sibling branch)
+      if (!edgeId) {
+        for (const [key, eid] of edgeLookup.entries()) {
+          if (key.endsWith(`->${step.node_id}`)) {
+            edgeId = eid
+            break
           }
         }
+      }
 
-        if (edgeId) {
-          edgeSnapshot[edgeId] = 'traversing'
-        }
+      if (edgeId) {
+        edgeSnapshot[edgeId] = 'traversing'
       }
     }
 

From d8b780af1f5e63d49916092cc7395e892e3b45bd Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Tue, 10 Mar 2026 08:24:19 -0400
Subject: [PATCH 08/14] fix(sim): handle label-style switch cases and improve
 visual highlights

Collapse parallel branch steps into a single grouped "completed" step
with branchNodeIds so all branches highlight simultaneously instead of
sequentially. Fix edge particle animations in both step-through and
autoplay by making SMIL trigger effect depend on highlight state and
stepKey, and restructure autoplay to use stepForward() via refs for
identical behavior in both modes.

- Add branchNodeIds/branchOutputs to SimulationStep type
- Collapse per-branch steps into grouped completed step in onParallel
- Update buildTraceSnapshots for simultaneous branch highlighting
- Add stepKey to SimulationAnimationConfig for animation remounting
- Fix EdgeSimulationOverlay useEffect deps for reliable SMIL triggers
- Add parallel branch highlight test
---
 .../app/src/components/SimulationPanel.tsx    | 14 +++-
 packages/app/src/hooks/useSimulation.test.ts  | 59 ++++++++++++++++
 packages/app/src/hooks/useSimulation.ts       | 68 ++++++++++++-------
 .../editor/src/components/FlowprintEditor.tsx |  1 +
 .../editor/src/contexts/SimulationContext.tsx |  2 +
 .../src/edges/EdgeSimulationOverlay.tsx       | 27 +++-----
 .../engine/src/__tests__/simulator.test.ts    |  9 +--
 packages/engine/src/simulator/simulator.ts    | 25 +++----
 packages/engine/src/simulator/types.ts        |  2 +
 9 files changed, 141 insertions(+), 66 deletions(-)

diff --git a/packages/app/src/components/SimulationPanel.tsx b/packages/app/src/components/SimulationPanel.tsx
index 60ff095..e358eca 100644
--- a/packages/app/src/components/SimulationPanel.tsx
+++ b/packages/app/src/components/SimulationPanel.tsx
@@ -106,13 +106,21 @@ function StatusBadge({ status }: { status: string }) {
 }
 
 function buildCumulativeContext(
-  steps: { stepOutput?: { nodeId: string; value: unknown } }[],
+  steps: {
+    stepOutput?: { nodeId: string; value: unknown }
+    branchOutputs?: Record<string, unknown>
+  }[],
   upToIndex: number,
 ): Record<string, unknown> {
   const ctx: Record<string, unknown> = {}
   for (let i = 0; i <= upToIndex; i++) {
-    const out = steps[i]?.stepOutput
-    if (out) ctx[out.nodeId] = out.value
+    const step = steps[i]
+    if (step?.stepOutput) ctx[step.stepOutput.nodeId] = step.stepOutput.value
+    if (step?.branchOutputs) {
+      for (const [branchId, value] of Object.entries(step.branchOutputs)) {
+        ctx[branchId] = value
+      }
+    }
   }
   return ctx
 }
diff --git a/packages/app/src/hooks/useSimulation.test.ts b/packages/app/src/hooks/useSimulation.test.ts
index 9caf172..feca2d7 100644
--- a/packages/app/src/hooks/useSimulation.test.ts
+++ b/packages/app/src/hooks/useSimulation.test.ts
@@ -260,6 +260,65 @@ describe('useSimulation', () => {
     })
   })
 
+  it('parallel branches highlighted simultaneously at completed step', async () => {
+    const parallelTrace = {
+      status: 'success' as const,
+      duration_ms: 10,
+      steps: [
+        { node_id: 'start', type: 'action', status: 'completed', next: 'par' },
+        { node_id: 'par', type: 'parallel', status: 'entered' },
+        {
+          node_id: 'par',
+          type: 'parallel',
+          status: 'completed',
+          next: 'join',
+          branchNodeIds: ['b1', 'b2', 'b3'],
+          branchOutputs: { b1: 'r1', b2: 'r2', b3: 'r3' },
+          stepOutput: { nodeId: 'par', value: { b1: 'r1', b2: 'r2', b3: 'r3' } },
+        },
+        { node_id: 'join', type: 'terminal', status: 'reached', outcome: 'success' },
+      ],
+    }
+    mockSimulateGraph.mockResolvedValue(parallelTrace)
+    const { result } = renderHook(() => useSimulation(minimalDoc, emptyRules))
+
+    await act(async () => {
+      result.current.start({})
+      await vi.runAllTimersAsync()
+    })
+
+    // Step 0: start is active
+    expect(result.current.nodeHighlights).toEqual({ start: 'active' })
+
+    // Step 1: par entered — hub active, start visited
+    act(() => { result.current.stepForward() })
+    expect(result.current.nodeHighlights).toEqual({
+      start: 'visited',
+      par: 'active',
+    })
+
+    // Step 2: par completed — hub + all branches active simultaneously
+    act(() => { result.current.stepForward() })
+    expect(result.current.nodeHighlights).toEqual({
+      start: 'visited',
+      par: 'active',
+      b1: 'active',
+      b2: 'active',
+      b3: 'active',
+    })
+
+    // Step 3: join — hub + all branches visited, join active
+    act(() => { result.current.stepForward() })
+    expect(result.current.nodeHighlights).toEqual({
+      start: 'visited',
+      par: 'visited',
+      b1: 'visited',
+      b2: 'visited',
+      b3: 'visited',
+      join: 'active',
+    })
+  })
+
   it('stop() clears all state', async () => {
     mockSimulateGraph.mockResolvedValue(mockTrace)
     const { result } = renderHook(() => useSimulation(minimalDoc, emptyRules))
diff --git a/packages/app/src/hooks/useSimulation.ts b/packages/app/src/hooks/useSimulation.ts
index 644060f..0d11f77 100644
--- a/packages/app/src/hooks/useSimulation.ts
+++ b/packages/app/src/hooks/useSimulation.ts
@@ -86,12 +86,14 @@ function buildTraceSnapshots(
       const prev = steps[j]
       if (!prev) continue
       snapshot[prev.node_id] = prev.status === 'error' ? 'error' : 'visited'
+      if (prev.branchNodeIds) {
+        for (const branchId of prev.branchNodeIds) {
+          snapshot[branchId] = 'visited'
+        }
+      }
     }
 
     // Mark the incoming edge (previous → current) as traversing.
-    // This shows the signal arriving at the active node rather than
-    // departing, which naturally means step 0 has no edge animation
-    // and parallel branches find their edge from the hub node.
     // Skip edge animation for parallel "completed" steps — the hub was
     // already visited via the "entered" step, so re-animating an edge
     // into it would show the wrong visual.
@@ -106,13 +108,11 @@ function buildTraceSnapshots(
       let edgeId = edgeLookup.get(`${prevStep.node_id}->${step.node_id}`)
 
       // Strategy 2: edge via previous step's routing target
-      // (handles parallel hub → first branch: build_project.next=run_tests → run_tests→run_unit_tests)
       if (!edgeId && prevStep.next && prevStep.next !== step.node_id) {
         edgeId = edgeLookup.get(`${prevStep.next}->${step.node_id}`)
       }
 
       // Strategy 3: find any edge targeting this node in the schema
-      // (handles 2nd+ parallel branches where prev step is a sibling branch)
       if (!edgeId) {
         for (const [key, eid] of edgeLookup.entries()) {
           if (key.endsWith(`->${step.node_id}`)) {
@@ -127,8 +127,21 @@ function buildTraceSnapshots(
       }
     }
 
+    // Fan-out edges for parallel branches (all animate simultaneously)
+    if (step.branchNodeIds) {
+      for (const branchId of step.branchNodeIds) {
+        const fanOutEdgeId = edgeLookup.get(`${step.node_id}->${branchId}`)
+        if (fanOutEdgeId) edgeSnapshot[fanOutEdgeId] = 'traversing'
+      }
+    }
+
     // Mark current node
     snapshot[step.node_id] = step.status === 'error' ? 'error' : 'active'
+    if (step.branchNodeIds) {
+      for (const branchId of step.branchNodeIds) {
+        snapshot[branchId] = 'active'
+      }
+    }
 
     highlights.push(snapshot)
     edgeHighlights.push(edgeSnapshot)
@@ -137,6 +150,11 @@ function buildTraceSnapshots(
     if (step.stepOutput) {
       cumulativeCtx[step.stepOutput.nodeId] = step.stepOutput.value
     }
+    if (step.branchOutputs) {
+      for (const [branchId, value] of Object.entries(step.branchOutputs)) {
+        cumulativeCtx[branchId] = value
+      }
+    }
     contexts.push({ ...cumulativeCtx })
   }
 
@@ -197,8 +215,9 @@ export function useSimulation(
     () => ({
       isForwardStep,
       particleDurationMs: Math.max(400, 1200 / playbackSpeed),
+      stepKey: currentStep,
     }),
-    [isForwardStep, playbackSpeed],
+    [isForwardStep, playbackSpeed, currentStep],
   )
 
   const start = useCallback(
@@ -276,43 +295,42 @@ export function useSimulation(
     playbackSpeedRef.current = speed
   }, [])
 
-  // Review #22: chained setTimeout instead of setInterval for auto-play.
-  // Step interval must wait for: particle traversal + glow settle + visible glow time.
-  // Without this, at 2x+ the next step fires before the particle finishes or the
-  // node glow appears, making edges look like they don't animate.
+  // Auto-play: automated step-through using the same stepForward() path as
+  // manual stepping. This guarantees identical animation behavior.
+  const stepForwardRef = useRef(stepForward)
+  stepForwardRef.current = stepForward
+  const currentStepRef = useRef(currentStep)
+  currentStepRef.current = currentStep
+
   useEffect(() => {
     if (!isAutoPlaying || !trace) return
 
     let timeoutId: ReturnType<typeof setTimeout>
     const stepsLength = trace.steps.length
 
-    function stepInterval(speed: number): number {
+    function stepInterval(): number {
+      const speed = playbackSpeedRef.current
       const particleDur = Math.max(400, 1200 / speed)
       const glowSettleMs = 500 // 300ms CSS transition + 200ms visible glow
       return particleDur + glowSettleMs
     }
 
     function tick() {
-      setIsForwardStep(true)
-      setCurrentStep((prev) => {
-        const next = prev + 1
-        if (next >= stepsLength) {
-          setIsAutoPlayingState(false)
-          autoPlayRef.current = false
-          return prev
-        }
-        // Schedule next tick — reads current speed via ref
-        timeoutId = setTimeout(tick, stepInterval(playbackSpeedRef.current))
-        return next
-      })
+      if (currentStepRef.current + 1 >= stepsLength) {
+        setIsAutoPlayingState(false)
+        autoPlayRef.current = false
+        return
+      }
+      stepForwardRef.current()
+      timeoutId = setTimeout(tick, stepInterval())
     }
 
-    timeoutId = setTimeout(tick, stepInterval(playbackSpeedRef.current))
+    timeoutId = setTimeout(tick, stepInterval())
 
     return () => {
       clearTimeout(timeoutId)
     }
-  }, [isAutoPlaying, trace, playbackSpeed])
+  }, [isAutoPlaying, trace])
 
   return {
     isActive,
diff --git a/packages/editor/src/components/FlowprintEditor.tsx b/packages/editor/src/components/FlowprintEditor.tsx
index 8c13984..c1fc21d 100644
--- a/packages/editor/src/components/FlowprintEditor.tsx
+++ b/packages/editor/src/components/FlowprintEditor.tsx
@@ -93,6 +93,7 @@ const emptyEdgeHighlights: EdgeHighlightMap = {}
 const defaultAnimationConfig: SimulationAnimationConfig = {
   isForwardStep: true,
   particleDurationMs: 600,
+  stepKey: 0,
 }
 
 // ---------------------------------------------------------------------------
diff --git a/packages/editor/src/contexts/SimulationContext.tsx b/packages/editor/src/contexts/SimulationContext.tsx
index f322a18..6d4d613 100644
--- a/packages/editor/src/contexts/SimulationContext.tsx
+++ b/packages/editor/src/contexts/SimulationContext.tsx
@@ -33,11 +33,13 @@ export function useEdgeHighlight(edgeId: string): EdgeHighlightState | undefined
 export interface SimulationAnimationConfig {
   isForwardStep: boolean
   particleDurationMs: number
+  stepKey: number
 }
 
 const defaultAnimationConfig: SimulationAnimationConfig = {
   isForwardStep: true,
   particleDurationMs: 600,
+  stepKey: 0,
 }
 
 const SimulationAnimationContext = createContext<SimulationAnimationConfig>(defaultAnimationConfig)
diff --git a/packages/editor/src/edges/EdgeSimulationOverlay.tsx b/packages/editor/src/edges/EdgeSimulationOverlay.tsx
index 7a32412..0d14d70 100644
--- a/packages/editor/src/edges/EdgeSimulationOverlay.tsx
+++ b/packages/editor/src/edges/EdgeSimulationOverlay.tsx
@@ -13,11 +13,6 @@ export function EdgeSimulationOverlay({ edgeId, edgePath }: EdgeSimulationOverla
   const pathId = `fp-sim-path-${uniqueId}`
   const filterId = `fp-sim-glow-${uniqueId}`
   const groupRef = useRef<SVGGElement>(null)
-  // Track which edge animation we've already started so re-renders
-  // don't restart the SMIL animation mid-flight.
-  const startedForRef = useRef<string | null>(null)
-  // Store rAF ID in a ref so re-renders don't cancel it via cleanup.
-  // Only cancelled on unmount.
   const rafRef = useRef<number>(0)
 
   // Cancel pending rAF only on unmount
@@ -27,19 +22,15 @@ export function EdgeSimulationOverlay({ edgeId, edgePath }: EdgeSimulationOverla
     }
   }, [])
 
+  // Trigger SMIL animations whenever this edge becomes 'traversing' on a new step.
+  // Deps include highlight + stepKey so the effect re-fires when:
+  //  - the edge transitions to 'traversing' (highlight changes)
+  //  - a new step arrives while still 'traversing' (stepKey changes)
   useEffect(() => {
+    if (highlight !== 'traversing' || !animation.isForwardStep) return
     const g = groupRef.current
-    if (!g) {
-      // Component returned null — reset so next mount triggers animation
-      startedForRef.current = null
-      return
-    }
-    // Already started for this edge — don't restart
-    if (startedForRef.current === edgeId) return
-    startedForRef.current = edgeId
+    if (!g) return
 
-    // The browser's SVG engine needs one frame to register newly inserted
-    // SMIL elements before beginElement() can activate them.
     rafRef.current = requestAnimationFrame(() => {
       const smilElements = g.querySelectorAll('animate, animateMotion')
       smilElements.forEach((el) => {
@@ -50,7 +41,7 @@ export function EdgeSimulationOverlay({ edgeId, edgePath }: EdgeSimulationOverla
         }
       })
     })
-  })
+  }, [highlight, animation.isForwardStep, animation.stepKey])
 
   if (!highlight) return null
 
@@ -66,8 +57,10 @@ export function EdgeSimulationOverlay({ edgeId, edgePath }: EdgeSimulationOverla
   const durSeconds = (animation.particleDurationMs / 1000).toFixed(2)
   const dur = `${durSeconds}s`
 
+  // key includes stepKey so React remounts this <g> on every step change,
+  // guaranteeing SMIL animations restart cleanly (both manual and autoplay).
   return (
-    <g ref={groupRef}>
+    <g ref={groupRef} key={`${edgeId}-${String(animation.stepKey)}`}>
       {/* SVG filter for energy bead glow */}
       <defs>
         <filter id={filterId} x="-200%" y="-200%" width="500%" height="500%">
diff --git a/packages/engine/src/__tests__/simulator.test.ts b/packages/engine/src/__tests__/simulator.test.ts
index cafda5a..e56b2da 100644
--- a/packages/engine/src/__tests__/simulator.test.ts
+++ b/packages/engine/src/__tests__/simulator.test.ts
@@ -389,7 +389,7 @@ describe('simulateGraph', () => {
   })
 
   describe('parallel node', () => {
-    it('traces branches sequentially with fixtures', async () => {
+    it('collapses branches into grouped step with branchNodeIds', async () => {
       const doc = makeDoc({
         par: {
           type: 'parallel',
@@ -418,11 +418,12 @@ describe('simulateGraph', () => {
       }))
 
       expect(trace.status).toBe('success')
-      // Parallel hub emits "entered" before branches, then "completed" after
       const nodeIds = trace.steps.map((s) => s.node_id)
-      expect(nodeIds).toEqual(['par', 'b1', 'b2', 'par', 'done'])
+      expect(nodeIds).toEqual(['par', 'par', 'done'])
       expect(trace.steps[0]?.status).toBe('entered')
-      expect(trace.steps[3]?.status).toBe('completed')
+      expect(trace.steps[1]?.status).toBe('completed')
+      expect(trace.steps[1]?.branchNodeIds).toEqual(['b1', 'b2'])
+      expect(trace.steps[1]?.branchOutputs).toEqual({ b1: 'result1', b2: 'result2' })
     })
   })
 
diff --git a/packages/engine/src/simulator/simulator.ts b/packages/engine/src/simulator/simulator.ts
index 4b288ad..8e4347c 100644
--- a/packages/engine/src/simulator/simulator.ts
+++ b/packages/engine/src/simulator/simulator.ts
@@ -216,38 +216,29 @@ export async function simulateGraph(
     },
 
     onParallel(nodeId, node, ctx) {
-      // Emit "entered" step so the hub node lights up before branches fan out.
-      // Without this, the signal visually skips the hub and jumps to branches.
       ctx.steps.push({
         node_id: nodeId,
         type: 'parallel',
         status: 'entered',
       })
 
-      // Visit all branches sequentially (traces each path with fixtures)
+      // Process branches for results/fixtures without pushing individual steps
+      const branchOutputs: Record<string, unknown> = {}
       for (const branchId of node.branches) {
         const fixture = options.fixtures?.[branchId]
         ctx.results.set(branchId, fixture)
-        ctx.steps.push({
-          node_id: branchId,
-          type: 'action',
-          status: 'completed',
-          stepOutput: { nodeId: branchId, value: fixture },
-        })
+        branchOutputs[branchId] = fixture
       }
-      const branchResults: Record<string, unknown> = {}
-      for (const branchId of node.branches) {
-        branchResults[branchId] = ctx.results.get(branchId)
-      }
-      ctx.results.set(nodeId, branchResults)
-      // The walk skeleton pushes this "completed" step after branches.
-      // Edge animation is skipped for this step since the hub was already visited.
+      ctx.results.set(nodeId, branchOutputs)
+
       return {
         node_id: nodeId,
         type: 'parallel',
         status: 'completed',
         next: node.join,
-        stepOutput: { nodeId, value: branchResults },
+        branchNodeIds: [...node.branches],
+        branchOutputs,
+        stepOutput: { nodeId, value: branchOutputs },
       }
     },
 
diff --git a/packages/engine/src/simulator/types.ts b/packages/engine/src/simulator/types.ts
index e631af3..c6431f4 100644
--- a/packages/engine/src/simulator/types.ts
+++ b/packages/engine/src/simulator/types.ts
@@ -24,6 +24,8 @@ export interface SimulationStep extends BaseStep {
   rulesEvaluation?: RulesEvaluationDetail
   expressionEvaluation?: ExpressionEvaluationDetail
   stepOutput?: { nodeId: string; value: unknown }
+  branchNodeIds?: string[]
+  branchOutputs?: Record<string, unknown>
 }
 
 export interface SimulationTrace extends BaseTrace<SimulationStep> {}

From 4037c725deb34e7c5fe651a4cb4c39f4d16301dc Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Tue, 10 Mar 2026 08:50:46 -0400
Subject: [PATCH 09/14] fix(sim): polish edge fade-out and source node
 departing transitions

Edge overlay now fades out after the particle arrives instead of persisting
until the next step. Source node holds its active glow during particle
transit via a new 'departing' highlight state, then transitions to visited.
---
 packages/app/src/hooks/useSimulation.test.ts  | 26 +++++++++---------
 packages/app/src/hooks/useSimulation.ts       | 13 +++++++++
 .../src/contexts/SimulationContext.test.tsx   |  3 +++
 .../editor/src/contexts/SimulationContext.tsx |  2 +-
 .../src/edges/EdgeSimulationOverlay.tsx       |  8 +++++-
 packages/editor/src/nodes/NodeShell.tsx       |  6 +++++
 packages/editor/src/styles/nodes.css          | 27 +++++++++++++++++++
 7 files changed, 71 insertions(+), 14 deletions(-)

diff --git a/packages/app/src/hooks/useSimulation.test.ts b/packages/app/src/hooks/useSimulation.test.ts
index feca2d7..debded2 100644
--- a/packages/app/src/hooks/useSimulation.test.ts
+++ b/packages/app/src/hooks/useSimulation.test.ts
@@ -243,19 +243,19 @@ describe('useSimulation', () => {
     // Step 0: a is active
     expect(result.current.nodeHighlights).toEqual({ a: 'active' })
 
-    // Step 1: a is visited, b is active
+    // Step 1: a is departing (immediately previous), b is active
     act(() => {
       result.current.stepForward()
     })
-    expect(result.current.nodeHighlights).toEqual({ a: 'visited', b: 'active' })
+    expect(result.current.nodeHighlights).toEqual({ a: 'departing', b: 'active' })
 
-    // Step 2: a and b visited, c is active
+    // Step 2: a is visited, b is departing (immediately previous), c is active
     act(() => {
       result.current.stepForward()
     })
     expect(result.current.nodeHighlights).toEqual({
       a: 'visited',
-      b: 'visited',
+      b: 'departing',
       c: 'active',
     })
   })
@@ -290,14 +290,16 @@ describe('useSimulation', () => {
     // Step 0: start is active
     expect(result.current.nodeHighlights).toEqual({ start: 'active' })
 
-    // Step 1: par entered — hub active, start visited
+    // Step 1: par entered — hub active, start departing (immediately previous)
     act(() => { result.current.stepForward() })
     expect(result.current.nodeHighlights).toEqual({
-      start: 'visited',
+      start: 'departing',
       par: 'active',
     })
 
-    // Step 2: par completed — hub + all branches active simultaneously
+    // Step 2: par completed — hub + all branches active, start visited
+    // Previous step (par entered) has same node_id as current (par completed),
+    // so 'departing' is overwritten by 'active'
     act(() => { result.current.stepForward() })
     expect(result.current.nodeHighlights).toEqual({
       start: 'visited',
@@ -307,14 +309,14 @@ describe('useSimulation', () => {
       b3: 'active',
     })
 
-    // Step 3: join — hub + all branches visited, join active
+    // Step 3: join — par + branches departing (immediately previous), join active
     act(() => { result.current.stepForward() })
     expect(result.current.nodeHighlights).toEqual({
       start: 'visited',
-      par: 'visited',
-      b1: 'visited',
-      b2: 'visited',
-      b3: 'visited',
+      par: 'departing',
+      b1: 'departing',
+      b2: 'departing',
+      b3: 'departing',
       join: 'active',
     })
   })
diff --git a/packages/app/src/hooks/useSimulation.ts b/packages/app/src/hooks/useSimulation.ts
index 0d11f77..103724d 100644
--- a/packages/app/src/hooks/useSimulation.ts
+++ b/packages/app/src/hooks/useSimulation.ts
@@ -135,6 +135,19 @@ function buildTraceSnapshots(
       }
     }
 
+    // Previous step's node holds active appearance during particle transit
+    if (i > 0) {
+      const prevNode = steps[i - 1]
+      if (prevNode && prevNode.status !== 'error') {
+        snapshot[prevNode.node_id] = 'departing'
+        if (prevNode.branchNodeIds) {
+          for (const branchId of prevNode.branchNodeIds) {
+            snapshot[branchId] = 'departing'
+          }
+        }
+      }
+    }
+
     // Mark current node
     snapshot[step.node_id] = step.status === 'error' ? 'error' : 'active'
     if (step.branchNodeIds) {
diff --git a/packages/editor/src/contexts/SimulationContext.test.tsx b/packages/editor/src/contexts/SimulationContext.test.tsx
index d915a14..a4ba0df 100644
--- a/packages/editor/src/contexts/SimulationContext.test.tsx
+++ b/packages/editor/src/contexts/SimulationContext.test.tsx
@@ -98,6 +98,7 @@ describe('useSimulationAnimation', () => {
     expect(result.current).toEqual({
       isForwardStep: true,
       particleDurationMs: 600,
+      stepKey: 0,
     })
   })
 
@@ -105,6 +106,7 @@ describe('useSimulationAnimation', () => {
     const config: SimulationAnimationConfig = {
       isForwardStep: false,
       particleDurationMs: 300,
+      stepKey: 5,
     }
     const wrapper = ({ children }: { children: ReactNode }) => (
       <SimulationAnimationProvider value={config}>{children}</SimulationAnimationProvider>
@@ -113,6 +115,7 @@ describe('useSimulationAnimation', () => {
     expect(result.current).toEqual({
       isForwardStep: false,
       particleDurationMs: 300,
+      stepKey: 5,
     })
   })
 })
diff --git a/packages/editor/src/contexts/SimulationContext.tsx b/packages/editor/src/contexts/SimulationContext.tsx
index 6d4d613..39cef45 100644
--- a/packages/editor/src/contexts/SimulationContext.tsx
+++ b/packages/editor/src/contexts/SimulationContext.tsx
@@ -2,7 +2,7 @@ import { createContext, useContext } from 'react'
 
 // ── Node highlights (existing) ──────────────────
 
-export type NodeHighlightState = 'active' | 'visited' | 'error'
+export type NodeHighlightState = 'active' | 'visited' | 'departing' | 'error'
 export type NodeHighlightMap = Record<string, NodeHighlightState>
 
 const SimulationContext = createContext<NodeHighlightMap>({})
diff --git a/packages/editor/src/edges/EdgeSimulationOverlay.tsx b/packages/editor/src/edges/EdgeSimulationOverlay.tsx
index 0d14d70..4a41293 100644
--- a/packages/editor/src/edges/EdgeSimulationOverlay.tsx
+++ b/packages/editor/src/edges/EdgeSimulationOverlay.tsx
@@ -60,7 +60,13 @@ export function EdgeSimulationOverlay({ edgeId, edgePath }: EdgeSimulationOverla
   // key includes stepKey so React remounts this <g> on every step change,
   // guaranteeing SMIL animations restart cleanly (both manual and autoplay).
   return (
-    <g ref={groupRef} key={`${edgeId}-${String(animation.stepKey)}`}>
+    <g
+      ref={groupRef}
+      key={`${edgeId}-${String(animation.stepKey)}`}
+      style={{
+        animation: `fp-sim-edge-fadeout 0.4s ease-out ${durSeconds}s forwards`,
+      }}
+    >
       {/* SVG filter for energy bead glow */}
       <defs>
         <filter id={filterId} x="-200%" y="-200%" width="500%" height="500%">
diff --git a/packages/editor/src/nodes/NodeShell.tsx b/packages/editor/src/nodes/NodeShell.tsx
index cf13bce..236f55b 100644
--- a/packages/editor/src/nodes/NodeShell.tsx
+++ b/packages/editor/src/nodes/NodeShell.tsx
@@ -35,6 +35,7 @@ export function NodeShell({
 
   // When stepping forward, delay the "active" glow until the particle arrives
   const isDelayedActive = simState === 'active' && simAnimation.isForwardStep
+  const isDeparting = simState === 'departing' && simAnimation.isForwardStep
 
   const classNames = [
     'fp-node',
@@ -44,6 +45,8 @@ export function NodeShell({
     simState === 'active' && 'fp-node--sim-active',
     isDelayedActive && 'fp-node--sim-active-delayed',
     simState === 'visited' && 'fp-node--sim-visited',
+    isDeparting && 'fp-node--sim-departing',
+    simState === 'departing' && !simAnimation.isForwardStep && 'fp-node--sim-visited',
     simState === 'error' && 'fp-node--sim-error',
   ]
     .filter(Boolean)
@@ -57,6 +60,9 @@ export function NodeShell({
       style={{
         '--node-accent': `var(${colorVar})`,
         '--node-accent-subtle': `var(${colorVar}-subtle)`,
+        ...(isDeparting && {
+          '--fp-sim-depart-delay': `${String(simAnimation.particleDurationMs / 2)}ms`,
+        }),
         ...(isDelayedActive && {
           '--fp-sim-particle-dur': `${String(simAnimation.particleDurationMs)}ms`,
         }),
diff --git a/packages/editor/src/styles/nodes.css b/packages/editor/src/styles/nodes.css
index b5ff7b8..96bb843 100644
--- a/packages/editor/src/styles/nodes.css
+++ b/packages/editor/src/styles/nodes.css
@@ -160,6 +160,33 @@
   opacity: 0.8;
 }
 
+@keyframes fp-sim-depart {
+  0% {
+    background: rgba(166, 227, 161, 0.15);
+    border-color: #a6e3a1;
+    box-shadow:
+      0 0 0 3px rgba(166, 227, 161, 0.3),
+      0 0 12px rgba(166, 227, 161, 0.2);
+    opacity: 1;
+  }
+  100% {
+    background: rgba(180, 190, 254, 0.1);
+    border-color: #b4befe;
+    box-shadow: 0 0 0 2px rgba(180, 190, 254, 0.2);
+    opacity: 0.8;
+  }
+}
+
+.fp-node--sim-departing {
+  border-width: 2px;
+  animation: fp-sim-depart 0.3s ease-out var(--fp-sim-depart-delay, 0ms) both;
+}
+
+@keyframes fp-sim-edge-fadeout {
+  from { opacity: 1; }
+  to { opacity: 0; }
+}
+
 .fp-node--sim-error {
   --fp-sim-glow: rgba(243, 139, 168, 0.5);
   background: rgba(243, 139, 168, 0.15);

From bfd2b106156007fb6898e6a34f588bad676a39a9 Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Wed, 11 Mar 2026 14:51:42 -0400
Subject: [PATCH 10/14] fix(editor): default isForwardStep to false in
 animation context

Prevents delayed node highlights when no SimulationAnimationProvider
is present, since the default config should not trigger forward-step
animation behavior.
---
 packages/editor/src/contexts/SimulationContext.test.tsx | 2 +-
 packages/editor/src/contexts/SimulationContext.tsx      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/editor/src/contexts/SimulationContext.test.tsx b/packages/editor/src/contexts/SimulationContext.test.tsx
index a4ba0df..041366a 100644
--- a/packages/editor/src/contexts/SimulationContext.test.tsx
+++ b/packages/editor/src/contexts/SimulationContext.test.tsx
@@ -96,7 +96,7 @@ describe('useSimulationAnimation', () => {
   it('returns default config with no provider', () => {
     const { result } = renderHook(() => useSimulationAnimation())
     expect(result.current).toEqual({
-      isForwardStep: true,
+      isForwardStep: false,
       particleDurationMs: 600,
       stepKey: 0,
     })
diff --git a/packages/editor/src/contexts/SimulationContext.tsx b/packages/editor/src/contexts/SimulationContext.tsx
index 39cef45..053eea2 100644
--- a/packages/editor/src/contexts/SimulationContext.tsx
+++ b/packages/editor/src/contexts/SimulationContext.tsx
@@ -37,7 +37,7 @@ export interface SimulationAnimationConfig {
 }
 
 const defaultAnimationConfig: SimulationAnimationConfig = {
-  isForwardStep: true,
+  isForwardStep: false,
   particleDurationMs: 600,
   stepKey: 0,
 }

From 728ac4186562bb9e18a6583659ed65eda137a7fa Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Mon, 16 Mar 2026 12:46:47 -0400
Subject: [PATCH 11/14] fix(app): scope simulation rules separately from
 project rules

Scenario rules now write to a separate simulationRules state instead of
overwriting the shared rulesDataMap. Editing input JSON no longer silently
drops rules. Simulation rules are cleared on stop/close.
---
 packages/app/src/App.tsx                        | 12 +++++++++---
 packages/app/src/components/SimulationPanel.tsx |  7 +++----
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/packages/app/src/App.tsx b/packages/app/src/App.tsx
index 8fdf58a..42dcd27 100644
--- a/packages/app/src/App.tsx
+++ b/packages/app/src/App.tsx
@@ -27,6 +27,7 @@ export function App() {
   const [showSimPanel, setShowSimPanel] = useState(false)
   const [error, setError] = useState<string | null>(null)
   const [rulesDataMap, setRulesDataMap] = useState<RulesDataMap>({})
+  const [simulationRules, setSimulationRules] = useState<RulesDataMap>({})
 
   const settingsHook = useSettings()
   const { settings } = settingsHook
@@ -37,12 +38,14 @@ export function App() {
     codeSearchUrl: settings.codeSearchUrl || undefined,
   })
 
-  const simulation = useSimulation(doc, rulesDataMap)
+  // Merge project rules with simulation-scoped rules for the simulation hook
+  const effectiveRules: RulesDataMap = { ...rulesDataMap, ...simulationRules }
+  const simulation = useSimulation(doc, effectiveRules)
   const scenarios = doc ? getScenarios(doc.name) : []
 
   const handleSelectScenario = useCallback(
     (scenario: TemplateScenario | null) => {
-      setRulesDataMap(scenario?.rulesData ?? {})
+      setSimulationRules(scenario?.rulesData ?? {})
     },
     [],
   )
@@ -54,6 +57,7 @@ export function App() {
     if (simulation.isActive) {
       simulation.stop()
       setShowSimPanel(false)
+      setSimulationRules({})
     } else {
       setShowSimPanel(true)
     }
@@ -145,6 +149,7 @@ export function App() {
     setDoc(null)
     fileManager.setDirty(false)
     setRulesDataMap({})
+    setSimulationRules({})
     setError(null)
   }, [fileManager, simulation])
 
@@ -239,7 +244,7 @@ export function App() {
               onChange={handleChange}
               theme={settings.theme}
               symbolSearch={symbolSearch ?? undefined}
-              rulesDataMap={rulesDataMap}
+              rulesDataMap={effectiveRules}
               nodeHighlights={simulation.nodeHighlights}
               edgeHighlights={simulation.edgeHighlights}
               simulationAnimation={simulation.simulationAnimation}
@@ -255,6 +260,7 @@ export function App() {
                 stop: () => {
                   simulation.stop()
                   setShowSimPanel(false)
+                  setSimulationRules({})
                 },
               }}
               scenarios={scenarios}
diff --git a/packages/app/src/components/SimulationPanel.tsx b/packages/app/src/components/SimulationPanel.tsx
index e358eca..8b6ce36 100644
--- a/packages/app/src/components/SimulationPanel.tsx
+++ b/packages/app/src/components/SimulationPanel.tsx
@@ -174,12 +174,12 @@ export function SimulationPanel({ simulation, scenarios, onSelectScenario }: Sim
   const handleInputChange = useCallback(
     (value: string) => {
       setInputText(value)
+      // Clear the scenario label but keep rules — user is customizing the input
       if (selectedScenarioId) {
         setSelectedScenarioId(null)
-        onSelectScenario?.(null)
       }
     },
-    [selectedScenarioId, onSelectScenario],
+    [selectedScenarioId],
   )
 
   const handleFixturesChange = useCallback(
@@ -187,10 +187,9 @@ export function SimulationPanel({ simulation, scenarios, onSelectScenario }: Sim
       setFixturesText(value)
       if (selectedScenarioId) {
         setSelectedScenarioId(null)
-        onSelectScenario?.(null)
       }
     },
-    [selectedScenarioId, onSelectScenario],
+    [selectedScenarioId],
   )
 
   const {

From b7fcba2cddbeda6960206f3d229ff7b5099768d8 Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Thu, 26 Mar 2026 21:55:17 -0400
Subject: [PATCH 12/14] fix(app): use case-index lookup for switch edge
 disambiguation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When a switch node has multiple cases targeting the same node (e.g.
triage_assessment → assign_provider for both Urgent and Routine),
the simulation now resolves the correct edge using matched_case from
the trace step rather than always selecting the first edge found.

buildEdgeLookup returns both byPair (source→target) and byCase
(source:caseIndex) maps. Edge resolution checks the case-specific
lookup first when matched_case is present, falling back to byPair.
---
 packages/app/src/hooks/useSimulation.ts | 57 +++++++++++++++++++------
 1 file changed, 44 insertions(+), 13 deletions(-)

diff --git a/packages/app/src/hooks/useSimulation.ts b/packages/app/src/hooks/useSimulation.ts
index 103724d..c2efeaa 100644
--- a/packages/app/src/hooks/useSimulation.ts
+++ b/packages/app/src/hooks/useSimulation.ts
@@ -42,23 +42,43 @@ interface TraceSnapshots {
   contexts: Record<string, unknown>[]
 }
 
+interface EdgeLookups {
+  /** "source->target" → first edge ID (for non-switch edges) */
+  byPair: Map<string, string>
+  /** "source:caseIndex" → edge ID (for switch case disambiguation) */
+  byCase: Map<string, string>
+}
+
 /**
- * Build a lookup from "source->target" to React Flow edge ID.
+ * Build lookups from schema edges to React Flow edge IDs.
  * Mirrors the ID pattern in layout-engine.ts: `e-${source}-${target}-${index}`
  */
-function buildEdgeLookup(doc: FlowprintDocument): Map<string, string> {
+function buildEdgeLookup(doc: FlowprintDocument): EdgeLookups {
   const schemaEdges = getEdges(doc)
-  const lookup = new Map<string, string>()
+  const byPair = new Map<string, string>()
+  const byCase = new Map<string, string>()
+  const caseCounters = new Map<string, number>()
+
   for (let i = 0; i < schemaEdges.length; i++) {
     const edge = schemaEdges[i]
     if (!edge) continue
+    const edgeId = `e-${edge.source}-${edge.target}-${String(i)}`
     const key = `${edge.source}->${edge.target}`
-    // First occurrence wins (matches computeEdges index ordering)
-    if (!lookup.has(key)) {
-      lookup.set(key, `e-${edge.source}-${edge.target}-${String(i)}`)
+
+    // First occurrence wins for the basic pair lookup
+    if (!byPair.has(key)) {
+      byPair.set(key, edgeId)
+    }
+
+    // Track case edges by source + case index for switch disambiguation
+    if (edge.label !== undefined) {
+      const caseIdx = caseCounters.get(edge.source) ?? 0
+      byCase.set(`${edge.source}:${String(caseIdx)}`, edgeId)
+      caseCounters.set(edge.source, caseIdx + 1)
     }
   }
-  return lookup
+
+  return { byPair, byCase }
 }
 
 /**
@@ -68,7 +88,7 @@ function buildEdgeLookup(doc: FlowprintDocument): Map<string, string> {
  */
 function buildTraceSnapshots(
   steps: SimulationStep[],
-  edgeLookup: Map<string, string>,
+  edgeLookup: EdgeLookups,
 ): TraceSnapshots {
   const highlights: NodeHighlightMap[] = []
   const edgeHighlights: EdgeHighlightMap[] = []
@@ -104,17 +124,25 @@ function buildTraceSnapshots(
     const isParallelJoin =
       prevStep?.type === 'parallel' && prevStep?.status === 'completed'
     if (i > 0 && !isParallelRevisit && !isParallelJoin && prevStep) {
+      // Strategy 0: case-specific edge for switch nodes (disambiguates multi-edges)
+      let edgeId =
+        prevStep.matched_case !== undefined
+          ? edgeLookup.byCase.get(`${prevStep.node_id}:${String(prevStep.matched_case)}`)
+          : undefined
+
       // Strategy 1: direct edge from previous step
-      let edgeId = edgeLookup.get(`${prevStep.node_id}->${step.node_id}`)
+      if (!edgeId) {
+        edgeId = edgeLookup.byPair.get(`${prevStep.node_id}->${step.node_id}`)
+      }
 
       // Strategy 2: edge via previous step's routing target
       if (!edgeId && prevStep.next && prevStep.next !== step.node_id) {
-        edgeId = edgeLookup.get(`${prevStep.next}->${step.node_id}`)
+        edgeId = edgeLookup.byPair.get(`${prevStep.next}->${step.node_id}`)
       }
 
       // Strategy 3: find any edge targeting this node in the schema
       if (!edgeId) {
-        for (const [key, eid] of edgeLookup.entries()) {
+        for (const [key, eid] of edgeLookup.byPair.entries()) {
           if (key.endsWith(`->${step.node_id}`)) {
             edgeId = eid
             break
@@ -130,7 +158,7 @@ function buildTraceSnapshots(
     // Fan-out edges for parallel branches (all animate simultaneously)
     if (step.branchNodeIds) {
       for (const branchId of step.branchNodeIds) {
-        const fanOutEdgeId = edgeLookup.get(`${step.node_id}->${branchId}`)
+        const fanOutEdgeId = edgeLookup.byPair.get(`${step.node_id}->${branchId}`)
         if (fanOutEdgeId) edgeSnapshot[fanOutEdgeId] = 'traversing'
       }
     }
@@ -208,7 +236,10 @@ export function useSimulation(
   const currentNodeId = currentStepData?.node_id
 
   // Build edge lookup once when doc changes
-  const edgeLookup = useMemo(() => (doc ? buildEdgeLookup(doc) : new Map<string, string>()), [doc])
+  const edgeLookup = useMemo<EdgeLookups>(
+    () => (doc ? buildEdgeLookup(doc) : { byPair: new Map(), byCase: new Map() }),
+    [doc],
+  )
 
   // Pre-compute snapshots once when trace changes (Review #19/#25/#34)
   const snapshots = useMemo<TraceSnapshots | null>(() => {

From 06f19ff461cc131fb263ee5a9ce2c474ebf0f590 Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Thu, 26 Mar 2026 21:57:06 -0400
Subject: [PATCH 13/14] fix(engine): add isErrorNode guard to simulator
 error.catch routing

The simulator now validates that an error.catch target is both a real
node in the document and an error-type node before routing to it.
This aligns with the runner's behavior in walker.ts, which performs
the same guard. Without this check, a misconfigured error.catch
pointing at a non-error node would silently route there in simulation
but throw in production.
---
 packages/engine/src/simulator/simulator.ts | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/engine/src/simulator/simulator.ts b/packages/engine/src/simulator/simulator.ts
index 8e4347c..3eeceb2 100644
--- a/packages/engine/src/simulator/simulator.ts
+++ b/packages/engine/src/simulator/simulator.ts
@@ -1,6 +1,6 @@
 import { walkGraph } from '../walker/walk.js'
 import type { WalkHandlers, WalkContext } from '../walker/types.js'
-import type { FlowprintDocument } from '@ruminaider/flowprint-schema'
+import { type FlowprintDocument, isErrorNode } from '@ruminaider/flowprint-schema'
 import { evaluateRules } from '../rules/core.js'
 import type { ExpressionEvaluator } from '../rules/core.js'
 import { interpretExpression, buildSafeMath } from '../expressions/interpreter.js'
@@ -114,12 +114,14 @@ export async function simulateGraph(
           '_error' in (fixture as Record<string, unknown>) &&
           (fixture as Record<string, unknown>)._error === true)
       const catchTarget = node.error?.catch
-      const next = isErrorFixture && catchTarget ? catchTarget : node.next
+      const catchNode = catchTarget ? ctx.doc.nodes[catchTarget] : undefined
+      const validCatch = catchNode && isErrorNode(catchNode) ? catchTarget : undefined
+      const next = isErrorFixture && validCatch ? validCatch : node.next
 
       return {
         node_id: nodeId,
         type: 'action',
-        status: isErrorFixture && catchTarget ? 'error-caught' : 'completed',
+        status: isErrorFixture && validCatch ? 'error-caught' : 'completed',
         next,
         stepOutput: { nodeId, value: fixture },
       }

From 3e8477bae2f64b85a1a606529bbabc587e531843 Mon Sep 17 00:00:00 2001
From: albertgwo <albertgwo@gmail.com>
Date: Thu, 26 Mar 2026 22:22:24 -0400
Subject: [PATCH 14/14] refactor: simplify edge lookup keys and error-catch
 guard

Extract edgeKey()/caseKey() helpers to centralize map key formats.
Replace "Strategy N" comments with ones explaining why each fallback
exists. Hoist empty EdgeLookups to a static constant. Collapse the
three-variable error-catch chain into a single boolean guard.
---
 packages/app/src/hooks/useSimulation.ts    | 36 ++++++++++++++--------
 packages/engine/src/simulator/simulator.ts |  8 ++---
 2 files changed, 27 insertions(+), 17 deletions(-)

diff --git a/packages/app/src/hooks/useSimulation.ts b/packages/app/src/hooks/useSimulation.ts
index c2efeaa..9ad5dca 100644
--- a/packages/app/src/hooks/useSimulation.ts
+++ b/packages/app/src/hooks/useSimulation.ts
@@ -49,6 +49,16 @@ interface EdgeLookups {
   byCase: Map<string, string>
 }
 
+const EMPTY_EDGE_LOOKUP: EdgeLookups = { byPair: new Map(), byCase: new Map() }
+
+function edgeKey(source: string, target: string): string {
+  return `${source}->${target}`
+}
+
+function caseKey(nodeId: string, caseIdx: number): string {
+  return `${nodeId}:${String(caseIdx)}`
+}
+
 /**
  * Build lookups from schema edges to React Flow edge IDs.
  * Mirrors the ID pattern in layout-engine.ts: `e-${source}-${target}-${index}`
@@ -63,17 +73,15 @@ function buildEdgeLookup(doc: FlowprintDocument): EdgeLookups {
     const edge = schemaEdges[i]
     if (!edge) continue
     const edgeId = `e-${edge.source}-${edge.target}-${String(i)}`
-    const key = `${edge.source}->${edge.target}`
+    const key = edgeKey(edge.source, edge.target)
 
-    // First occurrence wins for the basic pair lookup
     if (!byPair.has(key)) {
       byPair.set(key, edgeId)
     }
 
-    // Track case edges by source + case index for switch disambiguation
     if (edge.label !== undefined) {
       const caseIdx = caseCounters.get(edge.source) ?? 0
-      byCase.set(`${edge.source}:${String(caseIdx)}`, edgeId)
+      byCase.set(caseKey(edge.source, caseIdx), edgeId)
       caseCounters.set(edge.source, caseIdx + 1)
     }
   }
@@ -124,23 +132,25 @@ function buildTraceSnapshots(
     const isParallelJoin =
       prevStep?.type === 'parallel' && prevStep?.status === 'completed'
     if (i > 0 && !isParallelRevisit && !isParallelJoin && prevStep) {
-      // Strategy 0: case-specific edge for switch nodes (disambiguates multi-edges)
+      // Switch nodes can have multiple cases targeting the same node (e.g.
+      // triage_assessment → assign_provider for both Urgent and Routine).
+      // matched_case disambiguates which case edge to animate.
       let edgeId =
         prevStep.matched_case !== undefined
-          ? edgeLookup.byCase.get(`${prevStep.node_id}:${String(prevStep.matched_case)}`)
+          ? edgeLookup.byCase.get(caseKey(prevStep.node_id, prevStep.matched_case))
           : undefined
 
-      // Strategy 1: direct edge from previous step
+      // Direct source→target lookup (handles single-edge paths)
       if (!edgeId) {
-        edgeId = edgeLookup.byPair.get(`${prevStep.node_id}->${step.node_id}`)
+        edgeId = edgeLookup.byPair.get(edgeKey(prevStep.node_id, step.node_id))
       }
 
-      // Strategy 2: edge via previous step's routing target
+      // Intermediate routing (e.g. switch → hub → branch in parallel flows)
       if (!edgeId && prevStep.next && prevStep.next !== step.node_id) {
-        edgeId = edgeLookup.byPair.get(`${prevStep.next}->${step.node_id}`)
+        edgeId = edgeLookup.byPair.get(edgeKey(prevStep.next, step.node_id))
       }
 
-      // Strategy 3: find any edge targeting this node in the schema
+      // Defensive fallback: linear scan for any edge targeting this node
       if (!edgeId) {
         for (const [key, eid] of edgeLookup.byPair.entries()) {
           if (key.endsWith(`->${step.node_id}`)) {
@@ -158,7 +168,7 @@ function buildTraceSnapshots(
     // Fan-out edges for parallel branches (all animate simultaneously)
     if (step.branchNodeIds) {
       for (const branchId of step.branchNodeIds) {
-        const fanOutEdgeId = edgeLookup.byPair.get(`${step.node_id}->${branchId}`)
+        const fanOutEdgeId = edgeLookup.byPair.get(edgeKey(step.node_id, branchId))
         if (fanOutEdgeId) edgeSnapshot[fanOutEdgeId] = 'traversing'
       }
     }
@@ -237,7 +247,7 @@ export function useSimulation(
 
   // Build edge lookup once when doc changes
   const edgeLookup = useMemo<EdgeLookups>(
-    () => (doc ? buildEdgeLookup(doc) : { byPair: new Map(), byCase: new Map() }),
+    () => (doc ? buildEdgeLookup(doc) : EMPTY_EDGE_LOOKUP),
     [doc],
   )
 
diff --git a/packages/engine/src/simulator/simulator.ts b/packages/engine/src/simulator/simulator.ts
index 3eeceb2..64a99ee 100644
--- a/packages/engine/src/simulator/simulator.ts
+++ b/packages/engine/src/simulator/simulator.ts
@@ -114,14 +114,14 @@ export async function simulateGraph(
           '_error' in (fixture as Record<string, unknown>) &&
           (fixture as Record<string, unknown>)._error === true)
       const catchTarget = node.error?.catch
-      const catchNode = catchTarget ? ctx.doc.nodes[catchTarget] : undefined
-      const validCatch = catchNode && isErrorNode(catchNode) ? catchTarget : undefined
-      const next = isErrorFixture && validCatch ? validCatch : node.next
+      const canCatch =
+        isErrorFixture && catchTarget && isErrorNode(ctx.doc.nodes[catchTarget])
+      const next = canCatch ? catchTarget : node.next
 
       return {
         node_id: nodeId,
         type: 'action',
-        status: isErrorFixture && validCatch ? 'error-caught' : 'completed',
+        status: canCatch ? 'error-caught' : 'completed',
         next,
         stepOutput: { nodeId, value: fixture },
       }