Branching Course Editor

Reference Manual — v6.0

The editor runs entirely in the browser as a single-page application. Courses are exported as portable JSON or YAML files and can be played back in the companion Course Player.

Key Concepts

System Requirements

• Browser: Any modern browser — Chrome 90+, Firefox 90+, Safari 15+, Edge 90+
• JavaScript: Must be enabled
• Screen: Minimum 360px width (mobile-optimized). Desktop experience recommended at 1280px+.
• Network: CDN access required for Tailwind CSS, js-yaml, marked.js, and KaTeX. No backend server is required for core editing (server features are optional).
• Storage: LocalStorage used for auto-save and settings persistence

2. Interface Reference

2.1 Canvas

The canvas is the central work area where nodes are placed and connections are drawn. It is an infinite, pannable, zoomable surface with a dot-grid background.

2.2 Toolbar & Menu Bar

The desktop interface uses a macOS-style menu bar across the top of the editor. Below the menu bar is a pages tab bar and a floating quick-add toolbar on the canvas.

Menu Bar

Quick-Add Toolbar

A floating pill-shaped toolbar centered at the top of the canvas. Contains the most common node types as colored buttons. Each button can be clicked to add at the center of the viewport, or dragged directly to a position on the canvas. The toolbar can be collapsed to a small "Add" stub.

Quick-add buttons: Content Decision Quiz Condition Page Link End

Additionally, the toolbar includes toggle buttons for Link Drag and Downstream Drag physics modes, and a Node Repulsion toggle.

Zoom Controls

Located at the right end of the menu bar: zoom out (−), zoom percentage display, zoom in (+), and fit-all (⊡) buttons.

2.3 Properties Panel

The right sidebar (default 288px wide) shows contextual property editors. It is organized into tabs:

2.4 Mobile Interface

On screens narrower than 768px, the interface adapts:

• Menu bar collapses to a simple title bar with the course name input.
• Properties panel becomes a bottom drawer (60vh height) that slides up from the bottom. A drag handle at the top allows manual dismiss. A backdrop overlay appears behind the drawer.
• Three FABs (Floating Action Buttons) replace the desktop toolbar, stacked at the bottom-right:
  • Properties FAB (blue, bottom) — opens the properties drawer
  • Add Node FAB (green, middle) — opens a bottom sheet with all node types
  • More FAB (gray, top) — opens a bottom sheet with File actions (export, import, clear, etc.)
• Bottom sheets appear with a drag handle and list items. The Add Node sheet lists all node types with icons. The More sheet provides export/import/server actions.
• Touch-friendly connection points are enlarged to 24px diameter for easier tapping.
• Nodes are slightly narrower (185px instead of 220px).

2.5 Keyboard Shortcuts

3. Node Types Reference

The editor supports 11 node types. Each type serves a distinct purpose in branching course design.

Content Content Node

Purpose: Displays information to the learner. The most basic and commonly used node type. Content is displayed as Markdown with support for LaTeX math, tables, and images.

Properties

Connection Rules

• Outgoing: Exactly 0 or 1 (single output type). The connection is always default.
• Incoming: Unlimited

Validation

• Warning if more than 1 outgoing connection
• No outgoing connection is valid (can be a dead end, though not recommended)

Player Behavior

Renders the Markdown content with a "Next" or "Continue" button that follows the single outgoing default connection. Attribute effects are applied on node entry. If a layout is defined, it renders the layout blocks instead of raw Markdown.

Example JSON

JSON
{
  "id": "intro",
  "type": "content",
  "title": "Introduction",
  "content": "Welcome to the course! This is **Markdown** content.\n\nYou can use:\n- Lists\n- `code`\n- Math: $E = mc^2$",
  "position": { "x": 100, "y": 100 },
  "attribute_effects": [
    { "attr_id": "knowledge", "delta": 5, "when": "always" }
  ]
}

Decision Decision Node

Purpose: Presents the learner with explicit choices. Each option maps to an outgoing connection. The learner's selection determines which path is taken.

Properties

Connection Rules

• Outgoing: 1 or more (multi-output). Each outgoing connection should have a label matching an option label. Connections use conditional type.
• Incoming: Unlimited

Player Behavior

Renders content followed by a list of clickable choice buttons (labeled A, B, C...). When the learner selects an option, the player finds the outgoing connection whose label matches the option label and navigates to that node. If no match is found, the first connection is used as a fallback.

Example JSON

JSON
{
  "id": "fork-1",
  "type": "decision",
  "title": "Which path?",
  "content": "Choose your direction:",
  "options": [
    { "id": "opt-a", "label": "Beginner Path", "description": "Start from basics" },
    { "id": "opt-b", "label": "Advanced Path", "description": "Jump to the deep end" }
  ],
  "position": { "x": 300, "y": 100 }
}

Assessment Assessment Node

Purpose: Tests learner knowledge with one or more questions. Routes to different paths based on whether the learner passes or fails (score vs. passing threshold).

Properties

Question Types

Connection Rules

• Outgoing: Typically 2 (pass and fail paths) specified via success_target and failure_target. Can also use standard connections.
• Incoming: Unlimited

Player Behavior

All questions are presented at once. The learner answers each, then clicks "Submit". The player calculates the percentage score, compares to passing_score, shows a pass/fail result with score breakdown, then navigates to success_target or failure_target. Attribute effects with when: "pass" or when: "fail" only apply for the corresponding outcome.

Example JSON

JSON
{
  "id": "quiz-1",
  "type": "assessment",
  "title": "Knowledge Check",
  "passing_score": 80,
  "questions": [
    {
      "id": "q1",
      "type": "multiple-choice",
      "prompt": "What is 2+2?",
      "options": [
        { "id": "a", "label": "3" },
        { "id": "b", "label": "4", "correct": true },
        { "id": "c", "label": "5" }
      ],
      "points": 10
    }
  ],
  "success_target": "module-2",
  "failure_target": "review-1",
  "position": { "x": 600, "y": 100 }
}

Example Example Node

Purpose: Displays a worked example, demonstration, or case study. Functionally similar to a content node but visually distinct to indicate its pedagogical role. Domain themes can automatically flavor example content.

Properties

Same as Content node with type: "example".

Connection Rules

• Outgoing: 0 or 1 (default connection). Same as content.
• Incoming: Unlimited

Player Behavior

Renders identically to content with a green "Example" badge. In the player, a distinct badge style (green background) distinguishes it from standard content. When a domain theme is set, the layout editor can auto-generate domain-specific example content.

Example JSON

JSON
{
  "id": "ex-1",
  "type": "example",
  "title": "Worked Example: Quadratic Formula",
  "content": "Solve $x^2 + 5x + 6 = 0$...",
  "position": { "x": 200, "y": 300 }
}

Practice Practice Node

Purpose: Provides an interactive practice exercise or hands-on activity. Like example, this is functionally a content node with distinct visual identity for instructional design clarity.

Properties

Same as Content node with type: "practice".

Connection Rules

• Outgoing: 0 or 1 (default connection)
• Incoming: Unlimited

Player Behavior

Renders with an orange "Practice" badge. Content is displayed as Markdown with a "Continue" button.

Example JSON

JSON
{
  "id": "practice-1",
  "type": "practice",
  "title": "Try It Yourself",
  "content": "Using the formula above, solve the following problems...",
  "position": { "x": 400, "y": 300 }
}

Random Random Node

Purpose: Introduces controlled randomness. The runtime picks one of the outgoing connections completely at random (uniform probability). Useful for randomized practice sets, unpredictable narrative branches, or A/B testing scenarios.

Properties

Connection Rules

• Outgoing: 2 or more recommended. All connections use random type. Each has equal probability.
• Incoming: Unlimited

Player Behavior

Briefly displays the node content (if any), then automatically picks one outgoing connection uniformly at random and navigates to its target. The learner does not make a choice — the system decides.

Example JSON

JSON
{
  "id": "random-event",
  "type": "random",
  "title": "Random Encounter",
  "content": "Something unexpected happens...",
  "position": { "x": 400, "y": 200 }
}

Weighted Weighted Node

Purpose: Similar to random, but each outgoing connection carries a probability weight (0-100). The runtime samples proportionally. Useful for scenarios where some outcomes are more likely than others.

Properties

Same base properties as Random. Weights are stored on the connections, not the node itself.

Connection Rules

• Outgoing: 2 or more recommended. All connections use weighted type and must include a weight field (0-100). Weights should sum to 100; if they do not, the runtime normalizes automatically.
• Incoming: Unlimited

Validation

• Warning if weights do not sum to 100
• Warning if any connection is missing a weight

Player Behavior

Displays content briefly, then samples one outgoing connection proportionally to its weight. Probability chips are shown on the node in the editor to visualize the distribution.

Example JSON

JSON
{
  "id": "weighted-fork",
  "type": "weighted",
  "title": "Scenario Draw",
  "content": "The outcome depends on probability.",
  "position": { "x": 500, "y": 200 }
}
// Connections from this node:
// { from: "weighted-fork", to: "easy-path", type: "weighted", label: "Easy", weight: 70 }
// { from: "weighted-fork", to: "hard-path", type: "weighted", label: "Hard", weight: 30 }

Condition Condition Node

Purpose: Evaluates a runtime expression and routes the learner to the matching outgoing connection. Works like a programmatic switch/case statement. Used for adaptive routing based on scores, attributes, or custom variables.

Properties

Connection Rules

• Outgoing: 1 or more. All connections use conditional type. Each connection's label carries the condition expression that must evaluate to true for that path to be taken. Connections are evaluated in order; the first match wins.
• Incoming: Unlimited

Player Behavior

Evaluates each outgoing connection's condition expression against the current state (score, attributes, variables). Navigates to the first matching connection. If none match, navigates to default_target. See Expression Language Reference for syntax.

Example JSON

JSON
{
  "id": "score-router",
  "type": "condition",
  "title": "Score Router",
  "condition": "score",
  "default_target": "review-1",
  "position": { "x": 700, "y": 150 }
}

Gate Gate Node

Purpose: Blocks the learner at this point until a condition becomes true. Acts as a prerequisite check or conditional barrier. Once the condition is satisfied, the learner proceeds.

Properties

Connection Rules

• Outgoing: Exactly 0 or 1 (single output type). Uses default connection or default_target.
• Incoming: Unlimited

Player Behavior

When a learner arrives at a gate node, the condition is evaluated. If true, the learner passes through immediately. If false, the gate displays the content/message and a locked state. The runtime periodically re-evaluates the condition. A gate with an empty condition always passes immediately.

Example JSON

JSON
{
  "id": "prereq-gate",
  "type": "gate",
  "title": "Prerequisite Check",
  "content": "Complete Module 1 before continuing.",
  "condition": "completed_modules >= 1",
  "default_target": "module-2-intro",
  "position": { "x": 800, "y": 150 }
}

Page Link Page Link Node

Purpose: Navigates to another page in a multi-page course. Acts as a portal between sub-graphs. The target can be a specific page and optionally a specific node within that page.

Properties

Connection Rules

• Outgoing: 0 or 1 (single output type). The outgoing connection is a fallback; the primary navigation is via target_page.
• Incoming: Unlimited

Player Behavior

When reached, the player switches to the target page and navigates to either the target_node or the start node of that page. Learner state (attributes, variables, score) is preserved across page transitions.

Example JSON

JSON
{
  "id": "go-to-page-2",
  "type": "page_link",
  "title": "Continue to Module 2",
  "target_page": "page-2",
  "target_node": "module-2-intro",
  "position": { "x": 1000, "y": 200 }
}

End End Node

Purpose: Marks the terminal point of a course path. No outgoing connections. Displays a completion screen with final statistics.

Properties

Connection Rules

• Outgoing: Exactly 0 (zero output type). Any outgoing connections produce a validation error.
• Incoming: Unlimited (but at least 1 recommended)

Player Behavior

Displays a completion screen with a trophy icon, the node title, optional content, and a statistics grid showing: final score, nodes visited, questions answered, and final attribute values. A "Restart" button allows the learner to begin the course again.

Example JSON

JSON
{
  "id": "finish",
  "type": "end",
  "title": "Course Complete",
  "content": "Congratulations! You have completed the course.",
  "position": { "x": 1200, "y": 150 }
}

Node Type Summary

* Assessment routing uses success_target / failure_target properties rather than standard connections.

4. Connection Reference

Connection Properties

Connection Types

Creating Connections

1. Hover over a node to reveal connection points — small circles on the left (input) and right (output) sides of the node.
2. Click and drag from an output point (blue circle, right side).
3. A temporary line follows your cursor. Release on another node's input point (left side) to complete the connection.
4. Press Escape to cancel an in-progress connection.

Editing: Click a connection line to select it (turns red). Edit its properties in the Properties panel. Click elsewhere to deselect.

Deleting: Select a connection and press Delete/Backspace, or use the delete button in the properties panel.

Connection Validation Rules

• Self-connections (same source and target) are rejected
• Duplicate connections (same from/to pair) are rejected
• Connections into end nodes are rejected (end nodes are terminal)
• Single-output node types (content, gate, page_link) warn when more than one outgoing connection exists
• Connection type is automatically inferred from the source node type (condition → conditional, weighted → weighted, random → random, others → default)

5. Attribute System Reference

Attributes are named numeric variables that represent learner characteristics (knowledge, confidence, skill level, etc.). They are defined at the course level, modified by node effects, displayed in the player's HUD, and can be used in condition/gate expressions.

Attribute Definitions

Defined in the Attributes tab of the properties panel. Each attribute has:

Attribute Effects

Individual nodes can modify attributes when the learner visits them. Effects are configured in the Properties tab when a node is selected.

Progression Map

The Attributes tab displays a visual Progression Map showing which nodes affect each attribute, with bar charts indicating the magnitude and direction of each effect. Click a node in the map to select it and jump to its properties.

Using Attributes in Expressions

Attributes are available as variables in condition and gate expressions. Reference them by their name (lowercase, underscores for spaces):

Expression
// In a condition node's outgoing connection:
knowledge >= 50

// In a gate node's condition:
confidence > 30 && skill_level >= 2

// Compound conditions:
(knowledge >= 80 || experience >= 5) && attempts < 3

Player HUD Display

When a course has attributes defined, the player shows an Attribute Bar below the header. Each attribute appears as a pill with an icon, name, and current value. When an attribute changes, a delta indicator (+N / -N) flashes with a green (increase) or red (decrease) animation.

Built-in icon mappings:

6. Layout Editor Reference

Each node can have a custom visual layout that controls how it appears to learners at runtime. The layout editor is a full-screen modal with a block-based WYSIWYG canvas.

Opening the Layout Editor

Select a node, then click the "Edit Layout" button in the Properties panel. The editor opens as a full-screen overlay with three areas:

1. Block Palette (left sidebar, 192px) — lists all available block types. Click or drag to add.
2. Page Canvas (center, 900px default) — a positioned canvas with a dot-grid background where blocks are placed.
3. Header Bar (top) — shows node name, canvas width presets, template menu, and close/save buttons.

Block Types

Positioning and Sizing

Each block has absolute positioning on the canvas with properties x, y, w (width), and h (height). Blocks can be:

• Moved by dragging the header bar (cursor: move)
• Resized by dragging the resize handle in the bottom-right corner
• Precisely positioned using the geometry bar at the bottom of each block (X, Y, W, H numeric inputs)
• Aligned using alignment buttons (left/center/right) in the geometry bar

Canvas Width Presets

The header bar provides width presets for the page canvas: common options include 640px (mobile), 900px (default), and wider options for desktop-first designs.

Templates

The layout editor includes pre-built templates accessible from the header menu:

Auto-Generated Layouts

When opening the layout editor for a node that has no layout, the editor auto-generates one based on the node type:

• Content/Example/Practice: Heading + text block with the node's content
• Decision: Heading + nav_button for each option
• Assessment: Heading + quiz_question for each question + submit button
• Condition/Gate: Info/warning callout with condition details
• End: Centered "The End" heading
• Random/Weighted: Callout explaining the branching behavior
• Page Link: Callout explaining the page navigation

7. Course File Format Specification

Courses are stored as JSON or YAML files. The format supports both single-page and multi-page structures.

Top-Level Structure

* Either nodes+connections (single-page) or pages (multi-page) must be present.

Course Metadata Object

Single-Page Format

JSON
{
  "course": {
    "id": "my-course",
    "title": "My Course",
    "version": "1.0.0",
    "attributes": []
  },
  "nodes": [
    { "id": "start", "type": "content", "title": "Start", "content": "...", "position": {"x":100,"y":100} },
    { "id": "end", "type": "end", "title": "Done", "position": {"x":400,"y":100} }
  ],
  "connections": [
    { "from": "start", "to": "end", "type": "default" }
  ]
}

Multi-Page Format

JSON
{
  "course": {
    "id": "multi-page-course",
    "title": "Multi-Page Course",
    "version": "1.0.0"
  },
  "pages": [
    {
      "id": "page-1",
      "title": "Module 1",
      "nodes": [ /* ... */ ],
      "connections": [ /* ... */ ]
    },
    {
      "id": "page-2",
      "title": "Module 2",
      "nodes": [ /* ... */ ],
      "connections": [ /* ... */ ]
    }
  ]
}

Complete Example: Mixed Branching Course

YAML
course:
  id: "adventure-1"
  title: "The Forest Adventure"
  version: "1.0.0"
  attributes:
    - id: courage
      name: Courage
      default: 0
      min: 0
      max: 100

nodes:
  - id: "start"
    type: "content"
    title: "Forest Edge"
    content: "You stand at the forest edge."
    position: {x: 80, y: 200}
  - id: "fork"
    type: "decision"
    title: "Which way?"
    options:
      - {id: left, label: "Go left"}
      - {id: right, label: "Go right"}
    position: {x: 320, y: 200}
  - id: "encounter"
    type: "weighted"
    title: "Random Encounter"
    position: {x: 800, y: 200}
  - id: "quiz"
    type: "assessment"
    title: "Quick Check"
    passing_score: 70
    success_target: "win"
    failure_target: "retry"
    position: {x: 1280, y: 200}
  - id: "retry"
    type: "gate"
    title: "Retry Gate"
    condition: "attempts < 3"
    default_target: "quiz"
    position: {x: 1280, y: 380}
  - id: "win"
    type: "end"
    title: "Victory"
    position: {x: 1520, y: 200}

connections:
  - {from: "start", to: "fork", type: "default"}
  - {from: "fork", to: "encounter", type: "conditional", label: "Go left"}
  - {from: "encounter", to: "quiz", type: "weighted", label: "Friendly", weight: 70}
  - {from: "retry", to: "quiz", type: "default"}

8. Import & Export

Exporting

Export Options (controlled by settings)

• prettyJson — When true, JSON is pretty-printed with 2-space indentation. When false, compact single-line output.
• exportMeta — When false, the metadata field is stripped from the exported course object.

Export Behavior

• Single-page courses export with nodes and connections at the top level (backward-compatible format).
• Multi-page courses export with a pages array, each containing its own nodes and connections.
• Connection types are automatically inferred from the source node type during export.
• Only populated optional fields are included (e.g., attribute_effects is only present if non-empty).

Importing

How: File > Import file, or the mobile More sheet "Import" button. Accepts .json, .yaml, and .yml files.

Format Detection

• Files ending in .json are parsed as JSON
• Files ending in .yaml or .yml are parsed as YAML

Import Handling

• The file must contain either nodes (single-page) or pages (multi-page) at the top level.
• Course metadata is extracted from the course object.
• Connection IDs are regenerated to avoid collisions.
• Missing positions default to {x:100, y:100}.
• Auto-layout: If all nodes share the same position (indicating they lack stored positions), the tree layout algorithm automatically arranges them.
• If autoFit is enabled, the view fits all nodes after import.

Legacy Format Support

Unknown node types encountered during import (e.g., "lesson", "slide", "info") are automatically mapped to the content type.

Print

File > Print diagram opens the browser's print dialog. The canvas is rendered without the grid, toolbar, sidebar, and status bar. Nodes retain their visual styling. Uses landscape orientation by default.

9. Editor Settings Reference

All settings are persisted to localStorage. Access via Settings menu > All settings, or the Settings tab in the properties panel.

Appearance

Canvas

Nodes

Connections

Behavior

Physics

Export

API / Server

Rich Content

Accessibility

10. Player Reference

The Course Player renders branching courses for learners. It supports file upload, URL loading, and a built-in course catalog with server integration.

State Variables

The player maintains these state variables throughout a session:

Built-in Variables Available in Expressions

Runtime Behavior by Node Type

Attribute HUD

When a course defines attributes, the player displays an attribute bar below the header. Each attribute shows as a pill with icon, name, and current value. Changes animate with flash effects (green pulse for increases, red pulse for decreases) and show delta indicators.

History / Breadcrumb Trail

A breadcrumb trail at the top of the content area shows the path taken: each visited node's title is listed, separated by arrows. The current node is highlighted. A floating history FAB opens a slide-out panel listing all visited nodes.

Restart Behavior

Clicking the restart FAB (or the restart button on the end screen) resets all state: score, history, vars, attrs, visited, and quizAnswers return to their initial values. The player navigates back to the start node.

11. Validation Rules

The editor continuously validates the course and shows issue counts in the status bar. Nodes with issues display a warning badge.

Node-Type Specific Rules

Connection Rules

Course-Level Rules

• No start node: At least one node per page should be designated as the start node
• Orphan nodes: Nodes with no incoming or outgoing connections may indicate incomplete wiring (not currently flagged as errors, but visible on the canvas)
• Unreachable nodes: Nodes that cannot be reached from the start node (not currently auto-detected)

Status Bar

The bottom status bar displays: node count, connection count, and issue count. Clicking the issue indicator can reveal details about each validation problem with the option to navigate to the affected node.

12. Common Patterns & Recipes

Linear Progression

Content A → Content B → Content C → End

Binary Choice

Content → Decision (A / B) → Path A → End
                                → Path B → End

Multi-Path Scenario

Decision (A/B/C) → Path A →
                   → Path B → Merge Point → Continue
                   → Path C →

Assessment with Remediation Loop

Content → Assessment -(pass)→ Next Module
                       -(fail)→ Review Content → Gate (attempts < 3) → Assessment

Probabilistic Outcomes

Content → Weighted (70%/30%) → Easy Scenario (70%)
                                → Hard Scenario (30%)

Attribute-Gated Progression

Content (+5 knowledge) → Content (+5 knowledge) → Gate (knowledge ≥ 10) → Advanced Topic

Multi-Page Course

Page 1: Intro → Content → Page Link (to Page 2)
Page 2: Content → Assessment → Page Link (to Page 3)
Page 3: Content → End

Adaptive Difficulty

Assessment → Condition (score) -(score ≥ 90)→ Advanced Track
                                  -(score ≥ 60)→ Standard Track
                                  -(score < 60)→ Remediation Track

13. Expression Language Reference

Expressions are used in condition nodes (outgoing connection labels) and gate nodes (condition field). They are evaluated at runtime using JavaScript semantics.

Operators

Available Variables

Example Expressions

Expressions
// Simple threshold
score >= 80

// Attribute check
knowledge >= 50 && confidence > 20

// Custom variable check
path == "scenic" && visited_scenic

// Compound with grouping
(score >= 90 || (knowledge >= 80 && experience > 3)) && attempts < 5

// Arithmetic in condition
score + bonus >= 100

// Negation
!completed_intro

Evaluation Order

1. All current state variables are collected: vars + attrs + built-in variables.
2. The expression string is evaluated as a JavaScript expression with variables injected as function parameters.
3. The result is coerced to a boolean.
4. If evaluation throws an error (e.g., undefined variable), the result defaults to false.

14. Troubleshooting & FAQ