[Demo only DO NOT MERGE] feat(tutorial): silent-by-default copilot, capability-gated guidance, and the Code: Lita series

[Ethanlita]

Rebuilds the tutorial experience around a different premise: a course is a playground the copilot
watches over, not a script it reads out. Based on the prototype in #3330.

Two new documents describe this in full — what this branch adds
(the change surface and the reasoning behind each mechanism) and
the Code: Lita series (what the 28 courses teach).

The core idea

The copilot is silent by default. It perceives everything through real editor events but says
nothing until the user is stuck, has drifted, or asks. How much it may do is not a matter of prompt
etiquette: an intervention level decides which guidance tools are even registered, so a tool
it must not use at this level does not exist for it.

Level	What exists
Silent	api-video only
Nudge	+ guide-modal, spotlight-hint
Guide	+ in-editor code guides

The level moves on the model's own per-round verdict (<user-progress-ahead/> / neutral / back),
counted by the system. A typed question temporarily raises it — someone who asks deserves an answer.

Prompt rules alone proved unreliable with the backend model. The order that works is mechanism
first (unregister the tool), per-round reminder second, protocol prose last.

What's new

• Event-driven perception — run/exit/output/code-change/diagnostics/selection, no polling timer.
  Waking on runtime output (not just errors) is what makes coding courses completable at all: the
  win condition is a log line.
• Course-authored workspace setup — a ```jsonc block in the prompt declares hidden panels and
  whether the copilot starts open. Author intent, applied once, not a runtime copilot decision.
• The ruler — a course-only stage tool. Drag to measure; endpoints snap to sprites; starting on a
  sprite also reads the signed turn angle, which is exactly the number turn expects. Three
  courses are built on it.
• Silence that stays silent — <stay-silent/> hides the whole round; only typed rounds appear in
  chat.
• Opening sequence — story video → new-API video (never repeated per user) → one-line prelude.
• Dev harness (/devtools/course-runner, dev-only) — drives the real WASM runtime
  programmatically, so a course can be verified without clicking through the editor.

Editor extension points

Features drive the editor through owned extension points; the editor never imports tutorial code:
workspace-layout (focused mode, hideable areas, optional tools), leave-confirm, editor-reload,
API-reference filtering, and the code-guides gate.

Testing

193 unit tests pass, 13 test files added — intervention levels and verdict counting, guidance
registration, course config parsing, content visibility, ruler math, workspace layout reset, code
guides, and the course-start flow.

Beyond that, all 28 courses of the Code: Lita series had their reference answers executed against the
real runtime via the harness, checking that every radish in each level is collected: 27 of 27
courses with code pass (course 1 has no code). That exercise surfaced three engine constraints now
documented and designed around — the Main-execution timeout on bare top-level code, inline array
literals failing to compile, and onTouchStart only firing on the transition into contact.

Not included

The ~25MB of demo/story video assets under spx-gui/public/tutorial-*/ are intentionally left out of
git; the step explainer already points at a hosted URL and the rest should follow. Course content
itself lives in the backend, imported from a course-series file.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request implements a comprehensive rebuild of the tutorial copilot system, shifting it to a silent-by-default, event-driven architecture. Key additions include an intervention level state machine (Silent, Nudge, Guide) driven by progress verdicts, gated custom elements and in-editor code guides, a stage ruler tool for measuring distances and angles, and a programmatic course runner dev harness for runtime verification. Feedback on the documentation highlights a few inconsistencies, specifically the mention of the deprecated <tutorial-progress> tag, mismatched intervention level thresholds compared to the code, and a stray code fence in the verification guide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The documentation mentions <tutorial-progress> here and in lines 315-318. However, the "审查修复变更记录" section (line 247) states that <tutorial-progress/> has been deprecated and replaced by the <user-progress-*> verdicts. To avoid confusion and keep the documentation consistent with the implementation, the description of <tutorial-progress> should be removed from this document.

[gemini-code-assist]

The description of intervention levels seems to use simplified thresholds ("after 5 events", "after 8 events"). This might be inconsistent with the actual implementation logic described in docs/develop/tutorial/whats-new.md and the changelog within this file, which mention neutralThreshold = 6, backThreshold = 3, and counters resetting upon escalation. For the LLM to behave correctly and for clarity to human reviewers, the prompt's explanation should accurately reflect the underlying state machine logic. For example, it's unclear how "after 8 events" for Level 3 is reached based on the provided thresholds.

[gemini-code-assist]

This line contains a stray code fence that doesn't seem to be closing any code block and might be a typo. It should probably be removed.

[fennoai]

Review summary

Reviewed the tutorial-refactor / silent-by-default copilot / capability-gated guidance changes across ~92 files (Vue 3 + TS, spx-gui) using code-quality, performance, security, and documentation-accuracy passes. The implementation is generally solid: timers/listeners are cleaned up, guidance levels are enforced as a hard registration boundary (tutorial-guidance.ts), and copilot markdown is sanitized. whats-new.md, course-authoring.md, and verifying-courses.md match the code.

The main issues are documentation drift in llm-payload.md (its main-body "map" and verbatim appendix still describe the pre-refactor model and contradict the shipped code and the sibling whats-new.md), plus one confirmed intervention-state bug on in-course restart. Inline comments cover concrete diff-line findings; broader items are below.

Findings

1. [Bug] Intervention level & counters are not reset on in-course restart — spx-gui/src/components/tutorials/tutorial.ts
restartCurrentCourse() → restartCourse() → startCourse() reassigns this.course.value to the same Course object reference. The TutorialRoot.vue watch(() => tutorial.currentCourse, ...) only fires on a reference change, so on an in-course restart the TutorialIntervention instance is not recreated or reset(). Its levelRef, neutral/back counters, and processedRoundCount all carry over, which (a) contradicts the documented "a course (re)start also resets it", and (b) leaves processedRoundCount larger than the restarted session's rounds.length, so the first verdicts of the restarted course are silently skipped. Note the success-modal "Try again" path is fine — it goes through endCurrentCourse() (sets course.value = null) first, so the null→non-null transition fires the watcher. Only the still-running restartCurrentCourse path is affected. Consider resetting the intervention explicitly on restart. (See inline on tutorial.ts.)

2. [Docs, medium] llm-payload.md intervention thresholds are stale — docs/develop/tutorial/llm-payload.md
The doc states thresholds "nudge=5、guide=8 已按当前代码渲染", but the code uses two verdict counters: neutralThreshold = 6 / backThreshold = 3 (tutorial-intervention.ts:24,26), with no single event count. whats-new.md:34 has the correct values. The verbatim appendix ("三、课程协议全文") likewise reproduces the old event-count ladder and the deprecated <tutorial-progress /> reporting element; it should be regenerated against the current generateTopic in tutorial.ts.

3. [Perf, low] Duplicated per-keystroke full-project serialization — spx-gui/src/components/editor/copilot/user-events.ts:122 and :168
watchCodeChange and watchDiagnostics share the getter () => [stage.code, ...sprites.map(s => s.code)].join('\n'). It re-runs and allocates a full joined copy of all project source on every keystroke — twice (once per watcher) — since the debounce only guards the callbacks, not the getter. The getters are pre-existing, but this PR adds the second watcher over the same shape. Consider one shared computed/version signal both watchers depend on.

4. [Perf, low] Per-keystroke view-zone rebuild for the drag hint — spx-gui/src/components/xgo-code-editor/ui/code-guide/CodeGuideUI.vue:234
dragNewLineZone reads docVersion.value, so the useViewZone effect tears down and rebuilds the (static) drag node on every keystroke while a drag guide is active. Gate on the isNewLineInsertion(...) boolean instead of raw docVersion. Low impact (drag guides are short-lived); the type/change zones are unaffected.

Lower-confidence / worth a look

5. [Robustness] Un-gated onMounted side effects on session restore — spx-gui/src/components/tutorials/tutorial-course-abandon.ts:23,52 (and TutorialCourseSuccess.vue:46)
Unlike the sibling tutorial elements (spotlight-hint.ts, GuideModal.vue, ApiVideo.vue, use-code-guide.ts), the abandon-prediction/dismissal (and success) elements call predictAbandon() / dismissAbandon() / endCurrentCourse() unconditionally in onMounted, without the !(round.isLive && round.isLastRound()) guard. Since copilot sessions are persisted and restored, historical instances re-mount and re-fire on reload, which could spuriously escalate/end a course. These predate the PR but are now relied on within the restore-aware architecture; adopting the same gate would make the element family consistent.

6. [Minor, dev-only hardening] spx-gui/src/apps/xbuilder/pages/devtools/course-runner.vue:190
The ?autorun= handler runs new Function(src)(); it is DEV-gated in router.ts and constrained to startsWith('/'). The prefix check does not reject protocol-relative URLs (//host/...); new URL(autorun, location.origin).origin === location.origin would be a stronger same-origin guard. Not exploitable in production (route absent from prod builds).

Note: the diff patch surfaced a node_modules/.vite/vitest/.../results.json new-file hunk, but it is not in the PR's changed-files list (GET /pulls/3355/files) nor in origin/dev...HEAD, so it is a local diff-generation artifact, not part of this PR — no action needed.

[fennoai]

Intervention state is not reset on in-course restart. restartCurrentCourse → restartCourse → startCourse sets this.course.value = course to the same Course object reference. The TutorialRoot.vue watch(() => tutorial.currentCourse, ...) fires only on a reference change, so the TutorialIntervention is never recreated/reset() here — its level, neutral/back counters, and processedRoundCount carry over from before the restart. This contradicts the documented "a course (re)start also resets it", and because processedRoundCount is now > the restarted session's rounds.length, the restarted course's first verdicts are silently skipped. (The success-modal "Try again" path is fine — it goes through endCurrentCourse() first, so the null→non-null transition fires the watcher.) Consider resetting the intervention explicitly on restart.

[fennoai]

tutorial-progress no longer exists in the code — there are zero matches under spx-gui/src/components/tutorials/; it was replaced by user-progress-ahead / -neutral / -back (user-progress.ts). This registered-elements list is stale (the doc's own changelog at line 247 notes the deprecation). The appendix entry at line 315 and the protocol text at 545/570 reference it too.

[fennoai]

Incorrect: api-video is registered at Silent (level 1), not "≥ nudge". See tutorial-guidance.ts:45 — [InterventionLevel.Silent]: { elements: [apiVideo], ... }; only guide-modal and spotlight-hint are Nudge-level. whats-new.md:28 documents this correctly ("Silent | api-video only"), so the two docs currently contradict each other. (The protocol only restricts the proactive use of api-video to nudge+, but it is registered — and available for answering — at Silent.)

[fennoai]

The global registered-elements list omits thinking. CopilotRoot.vue:201-205 registers thinking globally alongside page-link/highlight-link. Relatedly, the appendix at line 357 claims thinking is "代码里现成但没有任何地方注册" (present but never registered) — that is now false and contradicts the doc's own changelog at line 239.