Playable Scenarios: Walk Through a Workflow Like You're Publishing an Article

A simulator that only knew states was only half a simulator

The original SymFlowBuilder simulator could fire transitions, track active places, evaluate guards, and replay Symfony events. What it could not do was answer the most common question someone asks of a workflow diagram:

> "But what does the data look like at each step?"

A workflow is rarely just a graph. It is a graph plus a thing moving through it — an article on its way to publication, an order on its way to fulfillment, a moderation case waiting on a reviewer. Without that thing, the simulator was an abstract token-pusher. You could see that approved was reachable from submitted. You could not see what an approved article actually looked like.

This release fixes that. The simulator now carries a subject — the JSON object your workflow operates on — and lets each transition mutate it as it fires. You can also attach a fake HTTP request to any transition and see exactly what would have hit your backend. The result feels less like watching a state machine and more like clicking through an n8n run.

The article-publishing example, end to end

Open the editor, build a state machine with five places — draft, pending_review, approved, rejected, published — and four transitions: submit_for_review, approve, reject, publish. Click Simulate.

The simulator panel now has three tabs: Steps, Scenario, and Inspector. Open Scenario and click the Publishing an article template card.

The starting subject lands on the page:

{
    "id": "art_1042",
    "title": "My first post",
    "body": "Hello, world.",
    "author": "alice",
    "reviewer": null,
    "reviewNotes": null,
    "publishedAt": null
}

Below it, four transition cards. Each one has patches that mutate the subject and a mock HTTP request that would have fired:

submit_for_review
  patches:  set reviewer = "bob"
  request:  POST /api/articles/{{id}}/submit
            { "reviewer": "bob" }
            → 202 { "id": "{{id}}", "status": "pending_review" }

Switch to Steps. Click submit_for_review. The article is now in pending_review and the reviewer is bob. Click approve. Then publish. The history list shows each step with a colored POST badge — visual proof that a request would have fired.

Click any history row. The panel jumps to Inspector and shows you, side by side, what the article looked like before and after that transition, with the changed fields highlighted. Below that: the resolved mock request — POST /api/articles/art_1042/publish (the {{id}} was substituted with the real subject value at the moment of the transition) and a 200 response with a real-looking publish URL.

That is the moment the feature clicks. You are not reading a YAML file or staring at boxes connected by arrows. You are watching an article get reviewed and published, with the API calls a real backend would make plotted out next to it.

What you can declare per transition

Each transition can carry an optional effect with three pieces, all of them optional:

1. A description

A one-line note about what the transition represents. Shown in the Inspector at the top of the step.

2. Patches that mutate the subject

A list of { op, path, value } operations applied to a deep-cloned subject when the transition fires. Three ops are supported:

• set — write a value at the path. Path syntax is field.nested.deeper or items[0].name.
• push — append a value to an array at the path.
• remove — delete a key or splice an array element.

Patches are interpreted client-side, in pure JavaScript, on a cloned subject. Nothing escapes the simulator. The original subject in the scenario is your "starting state" — re-running the simulator always rewinds to it.

3. A mock HTTP request

A pretend request the transition would have fired, with method, URL, optional body, and an optional canned response with status + body. URLs and JSON values support {{ subject.path }} interpolation, so:

POST /api/articles/{{id}}/publish

…becomes POST /api/articles/art_1042/publish when fired. The substitution happens once, at the moment of the transition, using the subject as it was before the patches ran. That snapshot is frozen into the step's history — even if you patch id later, the historical request keeps the value it had at the time.

No actual network call is made. The mock request is a UI artifact. That is intentional: scenarios are for teaching, reviewing, and demoing a workflow, not for testing your backend.

Three tabs, one mental model

• Steps is the playback surface. Active places, available transitions, history. Click history to jump to Inspector.
• Scenario is the design surface. Subject editor, per-transition patches and mock requests, template gallery. Edits persist with the workflow when you save.
• Inspector is the what just happened surface. Before/after subject diff for the selected step, with changed paths highlighted, plus the resolved mock request and response.

The footer carries the playback controls — Step Back, Restart, Auto-play with a configurable interval, and a stop. The header has tooltipped icons for restart and close.

Persistence and sharing

A scenario is stored alongside the workflow in a new simulationConfig JSONB column. It travels with the workflow:

• Auto-save picks up scenario edits and writes them to the cloud (signed-in users) or localStorage (guests), debounced 2 seconds.
• The public share view at /w/[shareId] loads the scenario when the share owner has saved one. Anyone visiting the link can hit Simulate and walk the article through the workflow without an account.
• The iframe embed at /embed/[shareId] is now interactive. Drop a <iframe> into a docs page, add ?play=1, and the scenario auto-starts. Readers click through it the same way they click through an n8n demo on the n8n website.

<iframe
  src="https://symflowbuilder.com/embed/abc123?play=1&minimap=0&branding=0"
  width="100%"
  height="560"
  style="border:0;border-radius:14px"
  loading="lazy"
  title="Article publishing flow"
></iframe>

That iframe is a runnable demo of your workflow. Embed it in your README, your docs site, your design review document — wherever explaining the flow has so far required either a screenshot or an awkward "let me share my screen" moment.

What this is *not*

A few deliberate non-goals, since people will ask:

• Not a backend mock. No request leaves the browser. Mock responses are static — no scripting, no JavaScript evaluation. If you need a real mock backend, MSW is what you want; this is a teaching surface.
• Not in the Symfony YAML export. Scenarios are simulator-only and live in their own column. Your exported YAML stays a clean Symfony workflow definition that drops into config/packages/workflow.yaml without surprises.
• Not a replacement for tests. It is excellent for showing a flow. It is not a substitute for the integration tests that pin your guards in production.

How it works under the hood

The data model is small enough to describe in one paragraph. SimulationConfig is { subject, effects, templateId }. Each effect is { description?, patches?, mockRequest? }. The simulator store carries the subject as live state, deep-clones it on initialization, and on each apply() runs the matching effect's patches against a clone — preserving the before snapshot on the step. The mock request is resolved with a tiny {{ path }} interpolator that walks the subject via JSON-pointer-style segments and substitutes string and JSON values. Pure functions, fully sandboxed, no eval.

The whole thing is built on the same `symflow` engine that powers Symfony-compatible runtime. The marking is still a Symfony marking. The events still fire in Symfony's order. The subject is a layer the simulator adds on top — the engine itself is unchanged.

Try it

1. Open the editor and either build a workflow or load an existing one.
2. Click Simulate.
3. Switch to the Scenario tab and click Publishing an article.
4. Switch back to Steps and walk submit_for_review → approve → publish.
5. Click any history row.

If you have already shared a workflow publicly, open its /w/[shareId] page — your viewers can now play through whatever scenario you saved.

What is next

The natural follow-ups are user-supplied scenarios via share links (?scenario=template-id to override the saved one), per-place initial-state branches (so you can simulate "what if this article started in pending_review?"), and a record-and-replay button that captures a real run from your app and lets you scrub through it. Open issues if any of those would help.

Until then: design the workflow, save the scenario, share the link, watch your reviewer click through it without ever opening a YAML file.