Valstorm Guide & Tour Builder Manual

Welcome to the comprehensive guide for authoring, running, and debugging interactive user walkthroughs and automated tests in the Valstorm Desktop platform.

---

📑 Table of Contents

1. Overview & Architecture
2. How to Access & Launch the Guide Builder
3. Step Types: Tooltip vs Modal vs Banner
4. Targeting Elements (The UX Prefix System)
5. Advance Conditions (How Steps Progress)
6. Auto-Execution & Tour Mode
7. Step-by-Step Authoring Workflow
8. Common Gotchas & Best Practices
9. Complete JSON Schema Reference

---

1. Overview & Architecture

The Valstorm Guide System is built on the Observer Triad:

1. DOM Ground Truth (UX Prefix System): Target any button, input, or section by its stable #id (e.g. desktop-nav-left-panel-btn-new-chat, ai-chat-composer-textarea).
2. Action Ground Truth (Command Bus): Steps advance automatically when matching commands fire on the bus (e.g. navigation:app_select, workspace:new_chat, commander:open).
3. Reactive Guide Runner (GuideRunner): Uses an SVG Cutout Spotlight so users can click and type directly through the spotlight hole into targeted components without backdrop capture issues.

---

2. How to Access & Launch the Guide Builder

You can open the Guide Builder in Valstorm Desktop via three ways:

1. Keyboard Shortcut: Press Cmd + Shift + B (macOS) or Ctrl + Shift + B (Windows/Linux).
2. DX Bottom Drawer: Open the Dev Console (Cmd + \``), click the **GUIDES & TOURS** tab, and click **Open Guide Builder`**.
3. Top Navbar Menu: Click your user avatar / profile menu in the top right and select Guide & Tour Builder.

Pro Tip: The Guide Builder panel is draggable. Grab the top title bar and park it anywhere on your screen so it never blocks the elements you are trying to target.

---

3. Step Types: Tooltip vs Modal vs Banner

Every step in a guide has a type property. Choosing the right type is critical for how the card is positioned:

⚠️ Crucial Nuance:

• If you set "type": "modal", the engine treats it as a general popup dialog and centers the card in the middle of the screen, ignoring element positioning.
• If you want the card to point at a button, input, or box, always choose "type": "tooltip"!

---

4. Targeting Elements (The UX Prefix System)

To ensure guides never break when UI designs change, Valstorm uses deterministic UX Prefix Conventions:

Using the Smart "Pick Element" Tool:

1. In GuideBuilder, click the Pick Element crosshair button.
2. Hover over any element on the screen:
   • Green Badge (#id): Element has a valid UX ID. Clicking it binds the target ID instantly.
   • Orange Badge (⚠️ Missing ID): Element does not have an ID.
3. If you click an element without an ID:
   • GuideBuilder displays a warning banner with a 💡 Suggested ID (e.g. #desktop-nav-left-panel-btn-new-chat).
   • Click Use Suggested ID to populate the step, then add id="..." to your React component.

---

5. Advance Conditions (How Steps Progress)

The advanceCondition determines what triggers the guide to jump to the next step:

1. manual (Click Next)

• The user reads the card and clicks the "Next" button in the tooltip.
• Best for: Informational steps, explanations, and overview steps.

2. click (DOM Click / Focus)

• The step advances immediately when the user clicks or focuses into the targeted element.
• Best for: "Click the New Chat button", "Click into the search bar", "Click on CRM".
• Note: For inputs and textareas, both click and focus trigger the advance.

3. command (Command Bus Event)

• The step advances as soon as a specific Command Bus action is dispatched anywhere in the app (even if triggered via keyboard shortcuts or subagents).
• Format: domain:action (e.g. navigation:app_select, workspace:new_chat, commander:open, phone:dial).
• Wildcard Matching: You can use commander:* to match any commander action, or * to match any action.
• Best for: Keyboard shortcuts (Cmd+K), asynchronous processes, and multi-app switching.

4. delay (Timed Auto-Advance)

• Automatically advances after delayMs milliseconds (e.g. 3000ms).
• Best for: Automated demo reels and quick splash cards.

---

6. Auto-Execution & Tour Mode

Guides can be configured to execute actions programmatically for Automated E2E Testing or AI-Driven Auto-Tours:

• In the Guide tooltip, an "Auto Perform" button appears.
• Clicking it dispatches the command directly through commandBus.dispatch(...).
• In headless automated test runners (like Playwright), the test runner can loop through each step and dispatch autoExecuteCommand to drive the entire application autonomously!

---

7. Step-by-Step Authoring Workflow

Here is the ideal workflow to create a seamless interactive tour:

Step 1: Initialize

1. Press Cmd + Shift + B to open the Guide Builder.
2. Click + New to start a blank guide.
3. Type the Guide Name (e.g. Getting Started with AI Chat) and a short description.

Step 2: Author Steps

• Step 1 (Click New Chat):
  • Title: 1. Start New Chat
  • Type: tooltip | Placement: right
  • Target: desktop-nav-left-panel-btn-new-chat
  • Advance: click
• Step 2 (Interact with Input):
  • Title: 2. Ask AI Anything
  • Type: tooltip | Placement: top
  • Target: ai-chat-composer-textarea
  • Advance: click (advances as soon as user clicks into the box)
• Step 3 (Type & Send):
  • Title: 3. Send Message
  • Type: tooltip | Placement: top
  • Target: ai-chat-composer-box
  • Advance: manual (user types and clicks "Finish")

Step 3: Save & Test

1. Click 💾 Save: Saves the guide to persistent browser storage.
2. Click ▶ Test: The builder closes and the interactive tour starts immediately so you can test the exact user experience live.

---

8. Common Gotchas & Best Practices

1. modal vs tooltip: If you provide a targetElementId, make sure the type is tooltip (or banner), not modal.
2. Asynchronous Page Transitions: When Step 1 navigates to a new tab (e.g. /phone or ai_chat://new), child elements take ~100–200ms to mount. The GuideRunner automatically polls and waits for the element with a MutationObserver, but always ensure the target ID matches the mounted component.
3. Backdrop Click-Through: The GuideRunner uses an SVG fillRule="evenodd" cutout mask. You can click, highlight, scroll, and type directly inside the spotlighted area without clicking the dark backdrop.
4. Copying / Version Controlling Guides: Click the JSON button in the Guide Builder toolbar to copy the clean JSON schema directly to your clipboard or commit it to code.

---

9. Complete JSON Schema Reference