Scenario Editor interface¶

The Scenario Editor is the tool for creating and modifying scenarios. A scenario is the set of nodes (which the user sees as cards in the Navigator) and connections between nodes (which the user sees as choice buttons within the cards). Scenarios are saved as JSON files. The scenario editor has two modes: the edit mode, in which the elements can be viewed as editable blocks, or as a navigable map.

Mode Edit¶

The interface is divided into two parts.

Left column¶

The left column is dedicated to managing general operations and the open scenario. You can hide it by clicking the arrow button (◀) on its right edge, to have more space for the editing area. To reopen it, click the arrow button (▶).

At the top it shows a row with buttons for:

• New: create a new scenario
• Open: open an existing scenario
• Save: save the current scenario as a JSON file
• Map: activate the map visualization

Button names are in English by default, but can be customized through Settings.

Below the button row appears the list of nodes that are part of the open scenario: only the Start node if starting with a new scenario, a complete list if you're already advanced in creation or if you open an existing scenario.

Each node in the list shows:

• the title (extracted from the content)
• the technical identifier
• informational badges: level and position (e.g., L2-P1), START for the initial node, END for terminal nodes

Editing area¶

The right part is dedicated to editing the selected node.

The top row contains:

• on the left: the scenario file name and total nodes. For a new scenario "New scenario" appears, the name changes automatically after saving
• on the right: the Settings button for metadata and translations

Below the header row appear the blocks that define the node:

• Node: node identifier management
• Content: the text content
• Level: to modify the default level defined by the system
• Choices: the choices available to the user
• Resources: attachments and linked resources

Node¶

The Node block manages the node identifier. It contains:

• Rename: opens a field to modify the identifier. The ID must be unique in the entire scenario and can only contain letters, numbers, and underscores
• DELETE: deletes the entire node from the scenario. Not available for the START node. Before deleting, the system asks for confirmation

Level¶

The Level block controls the node's position in the logical hierarchy. By default, levels are calculated automatically using the shortest path from the start node (BFS algorithm). The start node is level 1, its direct children are level 2, and so on.

However, in complex scenarios with multiple paths to the same node, automatic calculation may not reflect the intended logical structure. In these cases, you can set an explicit level override.

Level section elements:

• Override Level: numeric field to set an explicit level (leave empty for automatic calculation)
• Status indicator: shows whether the level is "Explicit" (manually set) or "Auto-calculated"
• Reset to Auto: button to remove the explicit level and return to automatic calculation

When to use manual level override:

• When a node is reachable via multiple paths of different lengths
• To ensure correct loop coloring (loops connect to ancestor nodes)
• To control vertical positioning in the map view
• To define semantic hierarchy independent of connection paths

Example: If node "assembly" is reachable both directly from "start" (1 step) and after three preparation nodes (4 steps), automatic calculation assigns level 2. Setting explicit level 5 positions it correctly after the preparations and ensures loops are colored correctly.

Content¶

The Content block contains the text that the user will see in the Navigator card.

The text area is vertically resizable: drag the orange handle under the textarea to expand or reduce the editing space.

The content uses a simplified Markdown syntax:

Choices¶

The Choices block defines the choices available to the user, i.e., the buttons that allow proceeding in the path.

In the list of already inserted choices, you can change the sequence using the up/down arrows on the right. Also on the right is the REMOVE button to delete the choice. Clicking the + Add Choice button located below the list adds a new choice with two required fields:

• Button Text: the text that appears on the button
• Target Node: the destination node, selectable from a dropdown menu listing all existing nodes

The Target Node menu also includes the option + Create new node which opens a popup to directly create a new destination node.

The popup includes:

• Node ID: unique identifier for the new node
• Node content: the markdown content
• Level: the node's level in the hierarchy (defaults to parent level + 1, can be modified)

Visual status indicators:

• gray border: newly created choice, not yet filled in
• amber border with "? unsaved": unsaved changes
• green border with "?": complete and saved choice
• red border: validation errors

The Save Choice button saves the choice only if both fields are filled in. The REMOVE button deletes the choice.

A node can have multiple choices leading to different nodes. It's possible to create loops by connecting a node to one of its ancestors.

Resources¶

The Resources block allows attaching external resources to the node.

Clicking + Add Resource adds a resource with three required fields:

• Type: the resource type
  • Link: link to a web page
  • Download: downloadable document (must be accessible via URL)
  • Video: YouTube video (use the share link)
• URL: the resource address, can be either a web link or a relative URL to a local resource. In this case, it's convenient to define a subfolder to collect elements, the URL could be "docs/element1.pdf"
• Label: the description that appears to the user in the Navigator

Visual status indicators work the same as for Choices. The Save Resource button saves only if all fields are filled in.

Settings: metadata and translations¶

The Settings button opens a panel to configure scenario metadata and interface labels.

Metadata:

• Title: the scenario name, visible in the Navigator header
• Description: brief description (optional)
• Author: author name (optional)

UI Labels: allows translating or customizing all user interface labels (step, restart, endOfPath, resources, viewMap, back, download, openLink, watchVideo).

The JSON file¶

A scenario is saved as a structured JSON file in three sections:

• meta: metadata (title, description, author)
• translations: customized labels
• startNode: the identifier of the start node
• nodes: the object containing all nodes with their content, choices, and resources

Saving¶

The Save button generates a JSON file. There is no auto-save: save regularly during work.

Automatic validation: when saving, the editor checks for incomplete choices and resources. If a choice is missing text or target, or a resource is missing type, URL, or label, a popup opens highlighting the incomplete elements and asks for confirmation to save. This prevents empty buttons or non-functional resources from appearing in the Navigator.

Duplicate prevention: when adding a choice, nodes already linked by other choices from the same node no longer appear in the available targets list. This prevents accidentally creating duplicate connections to the same node.

In the status bar at the bottom, the state is always visible:

• "● Unsaved" (orange): there are unsaved changes
• "✓ Saved" (green): everything saved

Mode Map¶

The map view shows the scenario as a visual tree.

Each node shows its identifier and title. Connections between nodes represent available choices, arrows indicate the path direction. The automatic layout arranges nodes in levels based on their logical hierarchy, with the start node at the top and branches expanding downward. Double-clicking on a node in the map opens it directly in the editing area. The red button at the top right, with the X, closes the map view to return to editing.

Once the desired node arrangement is obtained, the scenario must be explicitly saved with the editor's Save function.

Border color codes:

• green: start node (START)
• orange: terminal node (END)
• red: orphan node, unreachable
• purple: selected node
• pink: multi-selected nodes

Connection colors indicate the logical relationship between nodes:

• Gray: forward connection (to a descendant node)
• Orange: loop connection (to an ancestor node)
• Purple: same-level connection (to a sibling node)

Connection colors are based on logical hierarchy (node levels), not visual position. This means colors don't change even when repositioning nodes.

Dynamic canvas: the white map area automatically expands when you drag a node beyond the right or bottom edge. This allows managing scenarios of any size without fixed boundaries.

Node positioning tools¶

The map view includes powerful tools for organizing the scenario layout:

Node movement: holding CTRL (or CMD on macOS) you can drag nodes to customize the layout. Positions automatically snap to a 20px grid for clean and aligned layouts. The "Auto Layout" button restores automatic positioning, aligning nodes at the same level.

Node repositioning mode: Holding SHIFT and selecting a node activates Node repositioning mode, which allows for the ordered placement of nodes. In this mode, a toolbar is activated in the top frame.

Clicking on nodes allows you to add or remove them from a multiple selection; multi-selected nodes display a pink border. The function keys in the toolbar:

• Select Level: after selecting a node, selects all nodes at the same hierarchical level
• Align H: selecting at least 2 nodes, aligns selected nodes horizontally (same Y coordinate)
• Align V: selecting at least 2 nodes, aligns selected nodes vertically (same X coordinate)
• Distrib H: selecting at least 3 nodes, distributes with equal horizontal spacing
• Distrib V: selecting at least 3 nodes, distributes with equal vertical spacing
• ✕: deselects selected nodes and closes node repositioning mode

Typical workflow to uniformize node spacing:

1. Click any node at the level you want to organize
2. Click "Select Level" to select all nodes at that level
3. Click "Distrib H" or "Distrib V" to distribute them evenly
4. Save the scenario to preserve positions