feat(tutorial): implement the Course-author-facing framework

[Ethanlita]

Refs #3417 (part of #3403). Implements the contract documented in #3439, which should land first.

Summary

Grows the placeholder Tutorial class framework from #3424 into the API a Playground Course is written against: Course presentation and completion (showPrelude / showMessage / showVideo / complete / completeWith), the Editor namespaces (Project, Runtime, CodeEditor, Ruler), Copilot text and structured generation, and Spotlight reveal.

Behavioral decisions worth reviewing:

• Course callbacks run in order on the Course program's own goroutine. The placeholder started a goroutine per event; Course code is written as ordinary sequential code, and runtime logs are a judging channel whose order carries meaning, so events are queued and delivered one at a time.
• Every host event is registered up front, so dispatching an event the Course did not subscribe to is accepted and dropped rather than failing as an unknown event.
• The pending queue is bounded. A Course blocked in a slow capability — an LLM round takes seconds — tells the host it is not keeping up instead of silently losing events.
• complete / completeWith end the program from within: the current callback runs to its end, queued events are abandoned, Start returns and the executor reports the run as completed. Repeated completions are ignored.
• A failed capability panics. The Course asked for something that did not happen, and continuing would judge the learner on a false premise.
• generateJSON derives its schema by reflection and decodes the response back into the Course's struct. A struct with no exported fields is rejected: encoding/json could never fill it, and the Course would silently read zero values. (An XGo author lowercasing field names out of habit is the likely case.)

Validation

• go test ./... in tools/tutorial (event ordering, completion and idempotency, post-completion events, unsubscribed events, queue overflow, capability failure, schema derivation and write-back)
• go test ./... in tools/xgoexec-bundle: builds a Course program that uses the whole API against the real class-framework binding, which also fails if the ixgo exports were not regenerated
• GOOS=js GOARCH=wasm go build ./... in tools/xgoexec-bundle
• go generate ./... in tools/xgoexec-bundle (regenerated exports are included)
• Test on XGo Executor test page passed （/debug/xgoexec）
• Test on Tutorial test page with example course passed （/debug/tutorial-courses）

🤖 Generated with Claude Code

[fennoai]

Review: Tutorial ("Course") class framework

This is a solid, well-documented build-out of the Course framework. The concurrency model is deliberately narrow (one program, mutex-guarded state, single consumer goroutine draining a bounded event channel), the doc comments explain why rather than restate code, and the tests cover the important lifecycle edges: idempotent completion, in-order log delivery, post-completion drop, queue overflow, and capability failure. Removing the //go:build js && wasm constraint from tools/xgoexec-bundle/tutorial.go is correct — the host-only tutorial_test.go needs those symbols and the file pulls in no syscall/js.

A few findings below; the schema-recursion one is the only thing I'd want addressed before merge since it is reachable from Course-author input.

Additional notes (no reliable inline anchor)

• Panic recovery for interpreted Course code. mustCallCapability and GenerateJSON panic on failure. TestCapabilityFailureStopsTheCourse verifies the panic propagates out of Gopt_Course_Main when called directly, but not that it is recovered when the Course runs inside the ixgo interpreter goroutine (tools/xgoexec/runtime.go Run uses a bare go func() with only ctx.SetPanic, no defer/recover). Worth confirming an author-triggered panic degrades to a reported error rather than crashing the host worker.
• Stale design docs vs. shipped API (out of PR scope). docs/develop/tutorial-v2/tutorial-class-framework.go puts getCode() (no args) on CodeEditor and gives Project no methods, while the implementation ships Project.GetCode(sprite) / Project.ListSprites(). docs/develop/tutorial-v2/example-tutorial-course/main_course.gox calls editor.codeEditor.getCode() and will not compile against the shipped API. Consider a follow-up so the example doesn't drift.
• Minor: every namespace receiver is named p (e.g. func (p *Spotlight)), which is non-idiomatic Go; and the drain loop in Start takes the global mutex on every iteration (completed()) — an atomic.Bool for the completed flag would remove that per-event contention. Low priority.

[fennoai]

Review summary

Reviewed the tutorial Course-author framework across four dimensions (quality, performance, security, docs). This is a carefully-reasoned, well-tested PR: the single-consumer event loop, idempotent completion (markCompleted sets the flag before the capability so a panicking capability can't re-open the gate), snapshot-under-lock handler iteration, and the reflection schema derivation (rejecting recursive types and zero-serializable-field structs) are all sound. The two-language wire contract is guarded on both sides (tutorial-framework.test.ts locks the capability names; program_test.go asserts request shapes), and I verified every request shape matches the Go json tags (content, videoName, feedback, apis, sprite, {content,schema}, {target,tip,options}, and SpotlightOptions{mask,duration}).

The removal of //go:build js && wasm from tools/xgoexec-bundle/tutorial.go was confirmed intentional and correct — it lets tutorial_test.go run under host go test, while main.go (the only code touching syscall/js) still carries the wasm tag and off-wasm CallCapability resolves to the erroring stub. Not a defect.

One inline suggestion below. A few non-blocking notes:

• Contract param-name drift (docs, not in this diff): docs/develop/tutorial-v2/module_TutorialFramework.ts:94 and tutorial-class-framework.go:33 declare completeWith(message …), but the code deliberately uses feedback (client.ts, Go json:"feedback"). The wire is consistent; only the contract's parameter name lags. Worth aligning the contract to feedback so it stays the source of truth tutorial.go claims it to be.
• dispatchWithRetry retries on any error (tutorial-courses.vue): the loop retries every thrown error for up to 2s, so a genuine queue-full/decode rejection is masked and then rethrown with the transient cause obscured. Narrowing to the known "not running" registration-race message would surface real failures faster. Debug-only; the same broad-catch assumption exists in the Go test helper dispatch.
• Reminder: both /debug/xgoexec and the new /debug/tutorial-courses routes run arbitrary XGo through the real executor and carry the "remove before merging to dev" TODO — just make sure that removal/gating is enforced before this reaches a non-dev build.

No correctness-breaking bug or security issue found.

[Ethanlita]

对 review summary 里三条 non-blocking notes 的处理：

• completeWith 参数名漂移：成立，但修复方向与建议相反——契约是事实源，改的是代码而不是契约（b85584a0）。wire 回退为与其他展示类能力一致的 {content}，参数名对齐契约的 message；{feedback} 是当时向 Implement Tutorial v2 module #3445 原型对齐引入的偏离，原型侧应向契约对齐。
• dispatchWithRetry 对所有错误重试：接受现状。超时后抛出的就是最后一次的真实错误，失败只是最多晚 2 秒暴露；而按错误串区分"未注册竞态"需要对 xgoexec 内部消息做字符串匹配，对一个调试页来说过于脆弱。Go 测试里的 dispatch helper 同理。
• debug 路由不进非 dev 构建：确认。两个页面共用同一条 "Remove these temporary Tutorial v2 development pages before merging to dev" TODO，集成分支合入 dev 前移除。

[go-wyvern]

我们每一个 OnXXX 对应一个 addLane，产生一个goroutine，也就是一个事件对应一个 goroutine，这样其实不好，建议，每种事件一个 goroutine：同类事件顺序处理的规则容易解释。

比如 两段 OnLog：A 会弹出提示并等待关闭，B 判断是否完成课程。改为每种事件一个 goroutine 后，A 等待期间，B 和后续所有日志都会被堵住。等等，这种存在同一类型，存在先后注册顺序的，按注册顺序执行的需求是合理的

[Ethanlita]

这个地方我们之前有一个讨论：
#3442 (comment)

嗯，所以我稍微放宽了一点。目前是每调用一次 onXXX就建一条 lane，即一个队列加一个专属 goroutine。一条日志到达时投给所有订阅 lane，各自独立处理。

嘛，实际上这样子可能也比较符合spx里面那种感觉，就如同现在的https://x.qiniu.com/editor/curator/Coding-Course-39/sprites/Kiko/code这一课，用户注册了两个onStart回调的时候其实有可能在某种程度上是期待这两个函数在“同时运行”的，如果B 和后续所有日志都会被阻塞的话，可能和spx那边的使用习惯会差的有点远。

[go-wyvern]

其实不会同时运行，wasm 是单线程的，看起来并发，但不并行

[Ethanlita]

嗯好吧，我想一下是不是要简化一下这块的设计……？@nighca 寒星会有什么想法吗？

[nighca]

tutorial 通过假设自己一定运行在浏览器的 wasm 环境中，利用这个环境的行为来简化自己的实现，这个我没问题

回到这里，你们说的好像不是一个事情

其实不会同时运行，wasm 是单线程的，看起来并发，但不并行

这边 Lita 说的“同时运行”就是并发而不是真正的并行，因为事件 handler 中可能存在可被调度的阻塞调用，比如 showMessage，它可能会打开一个 message modal 并等到用户“确认”后才 return，在此期间它不会一直占用 CPU 的。

[go-wyvern]

这种会卡着的命令，调度中是要让出调度权的？runtime.Sched ?

[Ethanlita]

是的，调用会阻塞的Capability的时候是会释放token，这样其他的handler就会执行

[go-wyvern]

execToken 之前没 review 到，按目前设计，改造成是否 按注册顺序 复杂度确实比较高，按课程需求，这个需求可能并不太重要。可以忽略：

目前的调度方式：

M -> 调度到 G1 : callCapability 内部有一个 <- response ，这个异步操作，会让 golang 调度器调度到 G2，但 G2 的 execToken 拿不到（ <- execToken 卡住），继续让出调度权。如果 G1 调用 callCapability 前，判断 式 call 是 kindSlow 或者 kindPresentation 会临时让出 execToken，G2就可以继续走下去。

按目前的设计，我觉得也没问题。我觉得可以先合入。

[Ethanlita]

有关于不可重入的问题，计划采用“可取消”的事件模型替代，并且改用“提供能力”的方式，允许作者根据其需求自行设计。

func longTask(ctx context.Context) {
	doTask1()
	if (ctx.Done()) {
		return
	}
	doTask2()
	if (ctx.Done()) {
		return
	}
	doTask3()
}

var ctrl tutorial.TaskController

// var currentId = 0

// course.onExit => {
// 	var confirmed = ui.confirm("Are you sure you want to exit?")
// 	if !confirmed {
// 		return
// 	}
// 	var confirmed = ui.confirm("Are you sure you want to exit again?")
// 	if !confirmed {
// 		return
// 	}
// 	complete
// }

onLog log => {
	ctrl.trackRoutine() // 1. cancel previous 2. watch and abort current routine on next cancel
	// ctrl.cancelPrevious()

	doCheck
	doCheck2
	complete
}

onExit code => {
	// ctrl.trackFrame()
	doCheck
	complete
}

// ==== 1 ====

onLog log => {
	if log.level == "error" {
		processError(log)
	} else if log.level == "warning" {
		processWarning(log)
	}
}

// ==== 2 ====

onLog log => {
	if log.level == "error" {
		processError(log)
	}
}

onLog log => {
	if log.level == "warning" {
		processWarning(log)
	}
}

[Ethanlita]

该计划已经延后到issue #3509 PR #3510

[nighca]

另外记得 rebase 下 goplus/issue-3403-tutorial-v2，预期 rebase 后

这个会通过

[nighca]

之前 comment 里说合入前最后一个 commit 把注释统一为英文，别忘了