flowstride 1.0.21 → 1.0.22

package/examples/native-workflows/audio-to-text/flows/microphone-demo.flow

@@ -0,0 +1,23 @@
+Feature: Microphone and transcript UI fixture
+Scenario: Capture a known microphone signal
+Given "Configure a PCM WAV before browser startup"
+  flow.injectAudio "workflow-examples/audio-to-text/fixtures/microphone-tone.wav";
+  flow.browser.permissions {
+    "permissions": [
+      "microphone"
+    ]
+  };
+  flow.open "/audio";
+When "Start recording"
+  flow.click button "Start recording";
+  flow.expect visible "Recording active";
+When "Allow the fixture audio to play and stop"
+  flow.waitForPipeline;
+  flow.click button "Stop recording";
+Then "The simulated transcription result is displayed"
+  flow.expect transcript contains "Fixture transcript: audio received.";
+  flow.assert.that {
+    "selector": "#transcript",
+    "condition": "text",
+    "value": "Fixture transcript: audio received."
+  };

package/examples/native-workflows/audio-to-text/negative/wrong-transcript.flow

@@ -0,0 +1,23 @@
+Feature: Microphone and transcript UI fixture
+Scenario: Capture a known microphone signal
+Given "Configure a PCM WAV before browser startup"
+  flow.injectAudio "workflow-examples/audio-to-text/fixtures/microphone-tone.wav";
+  flow.browser.permissions {
+    "permissions": [
+      "microphone"
+    ]
+  };
+  flow.open "/audio";
+When "Start recording"
+  flow.click button "Start recording";
+  flow.expect visible "Recording active";
+When "Allow the fixture audio to play and stop"
+  flow.waitForPipeline;
+  flow.click button "Stop recording";
+Then "The simulated transcription result is displayed"
+  flow.expect transcript contains "This phrase was never produced.";
+  flow.assert.that {
+    "selector": "#transcript",
+    "condition": "text",
+    "value": "Fixture transcript: audio received."
+  };

package/examples/native-workflows/audio-to-text/templates/real-transcription.flow

@@ -0,0 +1,25 @@
+Feature: Verify a real application's speech transcription
+
+  Scenario: Record known spoken audio and check the resulting transcript
+    Given "A spoken PCM WAV and an authorized recording page"
+      flow.injectAudio "fixtures/voice-note.wav";
+      flow.browser.permissions {
+        "permissions": ["microphone"]
+      };
+      flow.open "{{env.TRANSCRIPTION_URL}}";
+
+    When "Start the application's recording"
+      flow.click button "Start recording";
+      flow.expect visible "Recording active";
+
+    When "Allow the audio clip to play and stop recording"
+      flow.waitForPipeline;
+      flow.click button "Stop recording";
+
+    Then "The new transcript contains the expected spoken words"
+      flow.assert.that {
+        "selector": "#transcript",
+        "condition": "containsText",
+        "value": "{{env.EXPECTED_TRANSCRIPT}}",
+        "timeout": 60000
+      };

package/examples/native-workflows/iframes/README.md

@@ -0,0 +1,116 @@
+# Work with iFrames
+
+Flowstride can discover a readable control in a child frame and can scope native assertions to an explicit iframe. For an action requiring an exact child-frame CSS selector, use the focused plugin example in this chapter.
+
+| Requirement | Value |
+| --- | --- |
+| Engine | OS or Cloud |
+| Browser | Chromium, Firefox or WebKit |
+| Application | Shared local demo |
+| Cloud account | Optional |
+
+Complete the [shared setup](../README.md) and leave the demo app running.
+
+## Readable target with an explicit frame assertion
+
+The `/frames` page embeds a profile containing a **Frame action** button. The button is inside the iframe; the parent page has no matching control.
+
+[readable-frame.flow](flows/readable-frame.flow):
+
+```flow
+Feature: Supported iframe interaction
+Scenario: Find a readable target in a child frame
+Given "The embedded profile is open"
+  flow.open "/frames";
+When "Click the readable child-frame target"
+  flow.click "Frame action";
+Then "Assert the explicit child-frame result"
+  flow.assert.that {
+    "frame": "#profile-frame",
+    "selector": "#frame-result",
+    "condition": "text",
+    "value": "Clicked in frame"
+  };
+```
+
+Run:
+
+```sh
+npx flowstride run workflow-examples/iframes/flows/readable-frame.flow --ci
+```
+
+Expected: the child-frame button is clicked, its result changes to `Clicked in frame`, and the frame-scoped assertion passes.
+
+`flow.click "Frame action"` uses readable-target discovery. The assertion's `frame` identifies the iframe in the parent document, and its `selector` identifies the result inside that frame.
+
+## Exact frame action through a project plugin
+
+A raw selector such as `flow.click "#frame-only"` is not a general instruction to search every frame. The raw-selector path and readable-target discovery have different behavior.
+
+[frame-actions.ts](plugins/frame-actions.ts) uses the public plugin browser access:
+
+This optional TypeScript plugin needs a compatible compiler in your project. Install it before running the plugin example:
+
+```sh
+npm i --save-dev typescript@5.9.3
+```
+
+The native readable-target example above does not need this extra setup. Keep the compiler in your lockfile so CI uses the same version; newer compiler majors may be incompatible with the plugin loader.
+
+```ts
+export async function click(sdk: any, args: { frame: string; selector: string }) {
+  await sdk.browser.page()
+    .frameLocator(args.frame)
+    .locator(args.selector)
+    .click();
+}
+```
+
+The supplied file also validates its arguments. [explicit-frame-plugin.flow](flows/explicit-frame-plugin.flow) registers the plugin and calls it:
+
+```flow
+Feature: An explicit iframe action through a focused project plugin
+  let frameActions = "workflow-examples/iframes/plugins/frame-actions.ts";
+
+  Scenario: Click a CSS target in the selected child frame
+    Given "The embedded profile is open"
+      flow.open "/frames";
+
+    When "Click the explicit child-frame selector"
+      frameActions.click {
+        "frame": "#profile-frame",
+        "selector": "#frame-only"
+      };
+
+    Then "The selected frame shows its result"
+      flow.assert.that {
+        "frame": "#profile-frame",
+        "selector": "#frame-result",
+        "condition": "text",
+        "value": "Clicked in frame"
+      };
+```
+
+```sh
+npx flowstride run workflow-examples/iframes/flows/explicit-frame-plugin.flow --ci
+```
+
+Expected: the same child-frame result passes. This is a project extension for the explicit action; it uses the normal Flowstride runner and requires no private runner imports.
+
+## Deliberate failure
+
+```sh
+npx flowstride run workflow-examples/iframes/negative/wrong-frame-result.flow --ci
+```
+
+The button is clicked, but the assertion expects `Never clicked`. The mismatch must fail, retain failure evidence and exit nonzero.
+
+## Scope and troubleshooting
+
+- Use a unique readable target or select the frame explicitly when several frames contain the same control.
+- The `frame` option belongs to the native assertion shown here; it is not an extra argument supported by every legacy action.
+- This fixture has one same-origin iframe. Qualify your own nested, cross-origin, sandboxed or dynamically replaced frame structure. A focused plugin can explicitly chain `frameLocator` calls for nested frames.
+- Confirm that the iframe and its document actually load. An assertion retries its condition; it does not repair a failed application navigation.
+- iFrames and browser tabs are different. `flow.switchTo "next"` switches pages/tabs in the current profile, not an iframe.
+
+See the [plugin guide](https://docs.flowstride.io/flow-language/getting-started/plugins) and [native assertions](../../../NATIVE_BROWSER.md#assertions-that-wait-for-a-condition).

package/examples/native-workflows/iframes/flows/explicit-frame-plugin.flow

@@ -0,0 +1,20 @@
+Feature: An explicit iframe action through a focused project plugin
+  let frameActions = "workflow-examples/iframes/plugins/frame-actions.ts";
+
+  Scenario: Click a CSS target in the selected child frame
+    Given "The embedded profile is open"
+      flow.open "/frames";
+
+    When "Click the explicit child-frame selector"
+      frameActions.click {
+        "frame": "#profile-frame",
+        "selector": "#frame-only"
+      };
+
+    Then "The selected frame shows its result"
+      flow.assert.that {
+        "frame": "#profile-frame",
+        "selector": "#frame-result",
+        "condition": "text",
+        "value": "Clicked in frame"
+      };

package/examples/native-workflows/iframes/flows/readable-frame.flow

@@ -0,0 +1,13 @@
+Feature: Supported iframe interaction
+Scenario: Find a readable target in a child frame
+Given "The embedded profile is open"
+  flow.open "/frames";
+When "Click the readable child-frame target"
+  flow.click "Frame action";
+Then "Assert the explicit child-frame result"
+  flow.assert.that {
+    "frame": "#profile-frame",
+    "selector": "#frame-result",
+    "condition": "text",
+    "value": "Clicked in frame"
+  };

package/examples/native-workflows/iframes/negative/wrong-frame-result.flow

@@ -0,0 +1,13 @@
+Feature: Supported iframe interaction
+Scenario: Find a readable target in a child frame
+Given "The embedded profile is open"
+  flow.open "/frames";
+When "Click the readable child-frame target"
+  flow.click "Frame action";
+Then "Assert the explicit child-frame result"
+  flow.assert.that {
+    "frame": "#profile-frame",
+    "selector": "#frame-result",
+    "condition": "text",
+    "value": "Never clicked"
+  };

package/examples/native-workflows/iframes/plugins/frame-actions.ts

@@ -0,0 +1,7 @@
+/** A project extension for an explicit frame action; not a private runner import. */
+export async function click(sdk: any, args: { frame: string; selector: string }) {
+  if (typeof args.frame !== 'string' || typeof args.selector !== 'string') {
+    throw new Error('frame and selector must be strings');
+  }
+  await sdk.browser.page().frameLocator(args.frame).locator(args.selector).click();
+}

package/examples/native-workflows/manual-testing/README.md

@@ -0,0 +1,85 @@
+# Manual design, execution and saved results
+
+The Manual Workspace lets you describe steps and expected results visually, perform those actions in your application, record outcomes and reopen a saved run. It is available in OS and Cloud. A human decides whether each manual step matches its expected result.
+
+Complete the [shared setup](../README.md) and leave the local demo app running. The default application page for this chapter is `http://127.0.0.1:4107/profile`. If you changed the demo port, use the printed server URL and update the design instructions to match.
+
+## 1. Load the supplied design
+
+The fixture [profile-review.json](fixtures/profile-review.json) defines three connected steps, expected results, a Test Plan identifier and the local environment. Copy it into the normal project template folder:
+
+```sh
+mkdir -p manual_flows/templates
+cp workflow-examples/manual-testing/fixtures/profile-review.json "manual_flows/templates/Profile review.json"
+```
+
+PowerShell:
+
+```powershell
+New-Item -ItemType Directory -Force manual_flows/templates
+Copy-Item workflow-examples/manual-testing/fixtures/profile-review.json "manual_flows/templates/Profile review.json"
+```
+
+Use a new destination filename when you already have a template with that name. Open the local workspace:
+
+```sh
+npx flowstride manual
+```
+
+Choose **Profile review** / its template filename from the flow selector. Refresh the workspace if it was open before the file was copied. Inspect the title, Test Plan, instructions and expected results. This JSON is a manual design, not an automated `.flow` test.
+
+You can also create a design with **Step**, **Arrow**, **Group** and **Text**. The runtime starts with the lowest internal node ID and follows outgoing connections. Moving a node or changing its visible step label does not change its execution identity. Keep an unambiguous path and confirm the highlighted starting step.
+
+## 2. Save and perform a passing run
+
+In Design Mode, click **Save** and wait for confirmation. Switch to **Execution Mode**; the design is saved before the transition.
+
+Open the demo application's `/profile` page in another tab/window and perform these actions:
+
+| Step | Action | Expected result |
+| --- | --- | --- |
+| Open the sample profile | Open `/profile` | Display name is visible |
+| Update the display name | Enter `Lola Idowu`, then click Save profile | The page shows `Saved as Lola Idowu` |
+| Reopen the profile | Reload the application page | Display name still contains `Lola Idowu` |
+
+After checking each result, return focus to the workspace canvas and press **Enter** to mark it Passed. All three steps should be Passed. The server keeps the profile change in memory; restarting it resets demo data.
+
+If nodes extend beyond the viewport, pan with the Hand tool or use the zoom/recenter controls. The workspace's metadata environment label does not navigate or configure the application browser for you.
+
+## 3. Save the execution record
+
+| Engine | Button in Execution Mode |
+| --- | --- |
+| OS | **Save** |
+| Cloud | **Submit Run** |
+
+Wait for confirmation. The design remains under `manual_flows/templates`; the new run is stored separately under `manual_flows/runs`. A browser file download is not proof that a run was persisted: confirm the saved record in **Runs**.
+
+The passing exercise should show three Passed steps and a PASS run summary. Keep your template and referenced media together when backing up the project.
+
+## 4. Reopen history
+
+Open **Runs**, locate the saved record and select it. Check its saved flow name, step results and canvas. Review historical records as evidence of that execution; return to the design for a fresh run. Cloud presents a vaulted historical record with its editing controls locked.
+
+Manual results are local records by default in OS. Cloud can synchronize manual results when valid Cloud credentials are configured. Check delivery status separately and avoid including real personal data in example evidence.
+
+## 5. Practice a failure and skipped work
+
+Copy [profile-review-mismatch.json](fixtures/profile-review-mismatch.json) into the template folder under its own filename and open it as another design. It deliberately expects `Saved as A Different Person` after you enter `Lola Idowu`.
+
+Perform the first action and record Passed. At the mismatching second step, observe the actual application result and record Failed. For this exercise, mark the remaining follow-up step Skipped and save/submit the run. Expected: one Passed, one Failed, one Skipped, and an overall FAIL summary. Skipped work must not be reported as verified success.
+
+In Execution Mode, focus the canvas before using these shortcuts:
+
+| Key | Result |
+| --- | --- |
+| Enter | Passed |
+| Delete / Backspace | Failed |
+| Tab | Blocked |
+| Escape | Skipped |
+
+These keys have different meanings in Design Mode. A focused text editor may consume them instead of the canvas.
+
+Expand **Failure Details** for the failed step. Describe the actual versus expected outcome, add appropriate evidence/assignee, save the defect form, and then save/submit the run. Confirm the recorded defect when reopening history. Design-reference media and defect evidence serve different purposes; keep uploads within the limits shown by their respective chooser.
+
+The [manual documentation](https://docs.flowstride.io/manual-workspace/manual-testing) covers planning, canvas controls, evidence, reporting and collaboration in more detail.

package/examples/native-workflows/manual-testing/fixtures/profile-review-mismatch.json

@@ -0,0 +1,93 @@
+{
+  "metadata": {
+    "flowName": "Profile review \u2014 intentional mismatch",
+    "version": "1.0",
+    "environment": "Local",
+    "testPlan": "TP-PROFILE-01",
+    "lastUpdatedBy": "Workflow fixture"
+  },
+  "nodes": [
+    {
+      "id": 1,
+      "x": 80,
+      "y": 160,
+      "width": 280,
+      "height": 150,
+      "visual_step": "1",
+      "title": "Open the sample profile",
+      "description": "Disposable local example data.",
+      "steps": "<p>Open http://127.0.0.1:4107/profile in your application browser.</p>",
+      "expected_result": "<p>The Display name field is visible.</p>",
+      "references": "",
+      "priority": "High",
+      "defect_report": "",
+      "defect_media": "",
+      "assigned_to": "",
+      "is_active": false
+    },
+    {
+      "id": 2,
+      "x": 430,
+      "y": 160,
+      "width": 280,
+      "height": 150,
+      "visual_step": "2",
+      "title": "Update the display name",
+      "description": "Disposable local example data.",
+      "steps": "<p>Enter Lola Idowu and click Save profile.</p>",
+      "expected_result": "<p>The page shows Saved as A Different Person.</p>",
+      "references": "",
+      "priority": "High",
+      "defect_report": "",
+      "defect_media": "",
+      "assigned_to": "",
+      "is_active": false
+    },
+    {
+      "id": 3,
+      "x": 780,
+      "y": 160,
+      "width": 280,
+      "height": 150,
+      "visual_step": "3",
+      "title": "Reopen the profile",
+      "description": "Disposable local example data.",
+      "steps": "<p>Reload the profile page.</p>",
+      "expected_result": "<p>The Display name field still contains Lola Idowu.</p>",
+      "references": "",
+      "priority": "Low",
+      "defect_report": "",
+      "defect_media": "",
+      "assigned_to": "",
+      "is_active": false
+    }
+  ],
+  "groups": [],
+  "texts": [],
+  "connections": [
+    {
+      "id": 4,
+      "start_x": 360,
+      "start_y": 235,
+      "end_x": 430,
+      "end_y": 235,
+      "start_node_id": 1,
+      "end_node_id": 2,
+      "start_anchor": "Right",
+      "end_anchor": "Left",
+      "is_active": false
+    },
+    {
+      "id": 5,
+      "start_x": 710,
+      "start_y": 235,
+      "end_x": 780,
+      "end_y": 235,
+      "start_node_id": 2,
+      "end_node_id": 3,
+      "start_anchor": "Right",
+      "end_anchor": "Left",
+      "is_active": false
+    }
+  ]
+}

package/examples/native-workflows/manual-testing/fixtures/profile-review.json

@@ -0,0 +1,93 @@
+{
+  "metadata": {
+    "flowName": "Profile review",
+    "version": "1.0",
+    "environment": "Local",
+    "testPlan": "TP-PROFILE-01",
+    "lastUpdatedBy": "Workflow fixture"
+  },
+  "nodes": [
+    {
+      "id": 1,
+      "x": 80,
+      "y": 160,
+      "width": 280,
+      "height": 150,
+      "visual_step": "1",
+      "title": "Open the sample profile",
+      "description": "Disposable local example data.",
+      "steps": "<p>Open http://127.0.0.1:4107/profile in your application browser.</p>",
+      "expected_result": "<p>The Display name field is visible.</p>",
+      "references": "",
+      "priority": "High",
+      "defect_report": "",
+      "defect_media": "",
+      "assigned_to": "",
+      "is_active": false
+    },
+    {
+      "id": 2,
+      "x": 430,
+      "y": 160,
+      "width": 280,
+      "height": 150,
+      "visual_step": "2",
+      "title": "Update the display name",
+      "description": "Disposable local example data.",
+      "steps": "<p>Enter Lola Idowu and click Save profile.</p>",
+      "expected_result": "<p>The page shows Saved as Lola Idowu.</p>",
+      "references": "",
+      "priority": "High",
+      "defect_report": "",
+      "defect_media": "",
+      "assigned_to": "",
+      "is_active": false
+    },
+    {
+      "id": 3,
+      "x": 780,
+      "y": 160,
+      "width": 280,
+      "height": 150,
+      "visual_step": "3",
+      "title": "Reopen the profile",
+      "description": "Disposable local example data.",
+      "steps": "<p>Reload the profile page.</p>",
+      "expected_result": "<p>The Display name field still contains Lola Idowu.</p>",
+      "references": "",
+      "priority": "Low",
+      "defect_report": "",
+      "defect_media": "",
+      "assigned_to": "",
+      "is_active": false
+    }
+  ],
+  "groups": [],
+  "texts": [],
+  "connections": [
+    {
+      "id": 4,
+      "start_x": 360,
+      "start_y": 235,
+      "end_x": 430,
+      "end_y": 235,
+      "start_node_id": 1,
+      "end_node_id": 2,
+      "start_anchor": "Right",
+      "end_anchor": "Left",
+      "is_active": false
+    },
+    {
+      "id": 5,
+      "start_x": 710,
+      "start_y": 235,
+      "end_x": 780,
+      "end_y": 235,
+      "start_node_id": 2,
+      "end_node_id": 3,
+      "start_anchor": "Right",
+      "end_anchor": "Left",
+      "is_active": false
+    }
+  ]
+}

package/examples/native-workflows/shared/server.mjs

@@ -0,0 +1,80 @@
+import http from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+
+const escapeHtml = value => String(value).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+const page = (body, script = '') => `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Flowstride workflow examples</title></head><body>${body}<script>${script}</script></body></html>`;
+
+/** Local demonstration application. It sends no email and performs no speech recognition. */
+export async function startExampleApp({ port = 4107 } = {}) {
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Example port must be between 0 and 65535.');
+  const users = new Map();
+  let lastAudioPeak = 0;
+  let profileName = 'Ada Obi';
+  const server = http.createServer(async (request, response) => {
+    const host = request.headers.host;
+    const boundPort = server.address().port;
+    const allowed = [`127.0.0.1:${boundPort}`, `localhost:${boundPort}`];
+    if (!allowed.includes(host) || (request.headers.origin && request.headers.origin !== `http://${host}`)) {
+      response.writeHead(403); response.end('Forbidden'); return;
+    }
+    const url = new URL(request.url, `http://${host}`);
+    const json = (status, data) => { response.writeHead(status, { 'Content-Type': 'application/json' }); response.end(JSON.stringify(data)); };
+    const html = source => { response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' }); response.end(source); };
+    let raw = '', size = 0;
+    for await (const chunk of request) {
+      size += chunk.length;
+      if (size > 65536) { json(413, { error: 'Demo request exceeds 64 KiB' }); return; }
+      raw += chunk;
+    }
+    let data = {};
+    if (raw) { try { data = JSON.parse(raw); } catch { json(400, { error: 'Invalid JSON' }); return; } }
+    if (url.pathname === '/api/users' && request.method === 'POST') {
+      if (!['email', 'password', 'name'].every(key => typeof data[key] === 'string' && data[key].trim())) return json(400, { error: 'Email, password and name are required' });
+      const user = { id: randomUUID(), email: data.email, password: data.password, name: data.name, loginCount: 0 };
+      users.set(user.id, user);
+      return json(201, { id: user.id, email: user.email, name: user.name, loginCount: user.loginCount });
+    }
+    if (url.pathname.startsWith('/api/users/') && request.method === 'GET') {
+      const user = users.get(url.pathname.split('/').pop());
+      return user ? json(200, { id: user.id, email: user.email, name: user.name, loginCount: user.loginCount }) : json(404, { error: 'Unknown demo user' });
+    }
+    if (url.pathname === '/api/session' && request.method === 'POST') {
+      const user = [...users.values()].find(value => value.email === data.email && value.password === data.password);
+      if (!user) return json(401, { error: 'Invalid demo credentials' });
+      user.loginCount += 1;
+      response.setHeader('Set-Cookie', `example-user=${user.id}; Path=/; HttpOnly; SameSite=Lax`);
+      return json(200, { id: user.id });
+    }
+    if (url.pathname === '/api/echo' && request.method === 'POST') return json(200, data);
+    if (url.pathname === '/api/audio-observed' && request.method === 'POST') { lastAudioPeak = Number(data.peak) || 0; return json(200, { received: lastAudioPeak > 0.001 }); }
+    if (url.pathname === '/api/audio-observed' && request.method === 'GET') return json(200, { peak: lastAudioPeak });
+    if (url.pathname === '/api/profile' && request.method === 'POST') {
+      if (typeof data.name !== 'string' || !data.name.trim()) return json(400, { error: 'A display name is required' });
+      profileName = data.name.trim(); return json(200, { name: profileName });
+    }
+    if (url.pathname === '/login') return html(page('<h1>Demo sign in</h1><input placeholder="Email" type="email"><input placeholder="Password" type="password"><button>Sign in</button><p id="error"></p>', `document.querySelector('button').onclick=async()=>{const r=await fetch('/api/session',{method:'POST',body:JSON.stringify({email:document.querySelector('input[type=email]').value,password:document.querySelector('input[type=password]').value})});if(r.ok){localStorage.setItem('account-mode','signed-in');sessionStorage.setItem('account-session','active');location.href='/dashboard';}else document.querySelector('#error').textContent='Invalid credentials';};`));
+    if (url.pathname === '/dashboard') {
+      const id = request.headers.cookie?.match(/example-user=([^;]+)/)?.[1], user = users.get(id);
+      return html(page(`<h1>${user ? 'Welcome, ' + escapeHtml(user.name) : 'Not authenticated'}</h1><div id="storage"></div>`, `document.querySelector('#storage').dataset.mode=localStorage.getItem('account-mode')||'missing';document.querySelector('#storage').dataset.session=sessionStorage.getItem('account-session')||'missing';`));
+    }
+    if (url.pathname === '/frames') return html(page('<h1>Embedded profile</h1><iframe id="profile-frame" title="Embedded profile" src="/frame"></iframe>'));
+    if (url.pathname === '/frame') return html(page('<button id="frame-only">Frame action</button><p id="frame-result">Waiting</p>', `document.querySelector('button').onclick=()=>document.querySelector('#frame-result').textContent='Clicked in frame';`));
+    if (url.pathname === '/orders') return html(page('<h1>Orders</h1><input placeholder="Search orders"><table id="orders"><thead><tr><th>Order</th><th>Customer</th><th>Status</th><th>Action</th></tr></thead><tbody><tr><td>FS-101</td><td>Ada Obi</td><td>Pending</td><td><button>View</button></td></tr><tr><td>FS-102</td><td>Bayo Ade</td><td>Approved</td><td><button>View</button></td></tr></tbody></table><p id="details">Select an order</p>', `const rows=[...document.querySelectorAll('tbody tr')];document.querySelector('input').oninput=e=>rows.forEach(r=>r.hidden=!r.textContent.toLowerCase().includes(e.target.value.toLowerCase()));rows.forEach(r=>r.onclick=()=>document.querySelector('#details').textContent='Order '+r.cells[0].textContent);`));
+    if (url.pathname === '/reuse') return html(page('<h1>Reuse extracted data</h1><input placeholder="Selected value"><button>Apply value</button><p id="reused"></p>', `document.querySelector('button').onclick=()=>document.querySelector('#reused').textContent='Selected '+document.querySelector('input').value;`));
+    if (url.pathname === '/profile') return html(page(`<h1>Profile review</h1><label>Display name<input id="name" value="${escapeHtml(profileName)}"></label><button>Save profile</button><p id="profile-result"></p>`, `document.querySelector('button').onclick=async()=>{const r=await fetch('/api/profile',{method:'POST',body:JSON.stringify({name:document.querySelector('input').value})});const data=await r.json();document.querySelector('#profile-result').textContent=r.ok?'Saved as '+data.name:data.error;};`));
+    if (url.pathname === '/audio') return html(page('<h1>Microphone demo — simulated transcription</h1><button id="start">Start recording</button><button id="stop" disabled>Stop recording</button><p id="recording"></p><p id="transcript"></p>', `let stream,context,timer,peak=0;document.querySelector('#start').onclick=async()=>{stream=await navigator.mediaDevices.getUserMedia({audio:true});context=new AudioContext();await context.resume();const source=context.createMediaStreamSource(stream),analyser=context.createAnalyser();source.connect(analyser);const samples=new Float32Array(analyser.fftSize);timer=setInterval(()=>{analyser.getFloatTimeDomainData(samples);for(const sample of samples)peak=Math.max(peak,Math.abs(sample));},10);document.querySelector('#recording').textContent='Recording active';document.querySelector('#stop').disabled=false;};document.querySelector('#stop').onclick=async()=>{clearInterval(timer);stream.getTracks().forEach(t=>t.stop());await context.close();await fetch('/api/audio-observed',{method:'POST',body:JSON.stringify({peak})});document.querySelector('#recording').textContent='Recording stopped';setTimeout(()=>document.querySelector('#transcript').textContent=peak>0.001?'Fixture transcript: audio received.':'Microphone input was silent',150);};`));
+    if (url.pathname === '/') return html(page('<h1>Flowstride workflow examples</h1><ul><li><a href="/login">Demo login</a></li><li><a href="/frames">Iframe</a></li><li><a href="/orders">Orders table</a></li><li><a href="/reuse">Variable reuse</a></li><li><a href="/audio">Microphone demo</a></li><li><a href="/profile">Manual profile review</a></li></ul>'));
+    return json(404, { error: 'Unknown example route' });
+  });
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); });
+  return { url: `http://127.0.0.1:${server.address().port}`, close: async () => { server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); } };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const port = process.env.FLOWSTRIDE_EXAMPLE_PORT === undefined ? 4107 : Number(process.env.FLOWSTRIDE_EXAMPLE_PORT);
+  const app = await startExampleApp({ port });
+  console.log(`Flowstride example application: ${app.url}`);
+  console.log('Local demo only. No real email delivery or speech recognition.');
+  for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => app.close().then(() => process.exit(0)));
+}