Explore and validate an XGo Tutorial class framework

[nighca]

Background

#3341 establishes an experimental browser-side XGo executor with class-framework bindings. Its intended Tutorial use case is more valuable only if course creators can use XGo to describe course logic that is meaningfully more complex than a few static prompts or frontend callbacks.

Before integrating the executor with the production Tutorial feature, validate whether an XGo Course class framework can provide an appropriate authoring model for real tutorial behavior.

Goal

Explore and validate a Tutorial class framework implemented with XGo.

The exploration should make the expected behavior of a course explicit, define the foundational capabilities exposed to course authors, and use realistic examples to determine whether the framework can express that behavior naturally and at acceptable cost.

Questions to answer

1. What behavior should a course describe?

Identify representative course flows that require more than linear text:

• lifecycle and progression: enter/start, step transitions, completion, reset, exit
• observing editor or project state and branching on it
• guiding a learner through actions in the editor
• reacting to learner actions such as submit, selection, run, or retry
• validating code or project state and giving targeted feedback
• asynchronous flow: waiting for user actions, timers, cancellation, and concurrent UI state changes
• maintaining per-course progress or transient state

The selected examples should include conditional logic, event-driven behavior, and asynchronous interaction, so that the evaluation is based on genuinely programmatic course logic rather than a static sequence of prompts.

2. Which capabilities should course authors receive?

Define a controlled, framework-level capability contract. Candidate groups include:

• UI output and guidance: messages, step/progress presentation, highlights, panels, and navigation requests
• application and project queries: current project/files, editor content, selection, diagnostics, run state, and learner progress
• learner interaction events: submit, next/back, retry, editor actions, project changes, and runner events
• validation and actions: request checks, run or stop a project where appropriate, and report structured validation results
• course state: read/write scoped course progress or temporary state
• control flow: time, cancellation, and lifecycle/cleanup signals

For each capability, decide its direction (XGo-to-UI call or UI-to-XGo event), payload/result shape, asynchronous behavior, error/cancellation semantics, and permission boundary.

Plan

1. Define two or more representative Tutorial scenarios and their expected learner experience.
2. Draft the Course class API and the minimal capability/event contract required by those scenarios.
3. Implement a prototype framework binding and example courses on top of xgoexec; use a debug or isolated test surface rather than production Tutorial integration.
4. Verify that the example courses cover branching, state observation, asynchronous waits, repeated events, validation feedback, and cancellation.
5. Evaluate authoring clarity, runtime cost, safety boundaries, and gaps in the capability contract; document whether and how to proceed with production integration.

Out of scope

• Replacing the existing Tutorial product flow in this exploration.
• Reusing xgoexec for existing SPX project preview/runtime.
• Treating the initial prototype API as a final public course-authoring specification.

Related

• Add a frontend module for running XGo code in the browser #3341