feat(course-editor): Course Editor for Playground Courses

[Ethanlita]

Course Editor for Playground Courses (#3420): the authoring surface that edits a Course's Tutorial project (embedded SPX project, course program, videos, settings, other files) and saves it through Course APIs. Course metadata (title, thumbnail) stays with course management.

Architecture

Per docs/develop/tutorial-v2/index.md, the Course Editor composes the existing SPX Project Editor rather than modifying it: the course's embedded project is loaded as an ownerless in-memory SpxProject, so the existing ownership rule puts the editor in effect-free mode (edits stay in memory), and the Course Editor's own Save exports the TutorialProject file collection and persists it via Course APIs. Preview snapshots the working copy and runs the same Tutorial lifecycle as learning.

Shell (decided with the product owner, implemented as the design itself): a course explorer on the left and one document at a time on the right. The explorer is a projection of the course's records (the FileCollection), following one rule: every record belongs to exactly one node, and a node may stand for several records. The course itself is the tree root; its document edits the settings stored in index.json (title and thumbnail are course metadata, edited in course management). The tree shows the parts of a course, not the directories its records export to, in a fixed order: the course program, one group per resource kind (videos and pictures are always offered, plus any kind a course brought along), the embedded project, and a heading collecting the records the format gives no role to. assets never appears, and every node is named by what it is; only the unused records are named by path, because they have nothing else to go by and where they came from is worth knowing. The embedded project and each resource package are opaque nodes over their directories (like macOS bundles: the manifest inside never shows). Selecting a node opens its document: course settings, a resource group (which offers adding another of its kind), a video player with rename/delete, a text editor, an image viewer, or a plain file view with delete; the project node opens the full Project Editor. Unclaimed records are kept and written back as they are (also inside video packages), so a course carrying files this editor does not understand, or produced by a newer format, is never silently trimmed — the previous typed-model-only export dropped them. The open node is part of the route, under the course's edit namespace (…/edit/:inCourseEditorPath*): inCourseEditorPath is the node's path (empty for the course itself; under the project's root the tail is the Project Editor's own inEditorPath) — naming follows "inPath": every editor has one, and the Course Editor's path embeds the Project Editor's when the project is open. Preview lives in the sibling preview namespace (…/preview/:inEditorPath*, same page component) so the learner-side playground can drive inEditorPath exactly as it does for learners, and browser history enters and leaves preview. The two namespaces are siblings because a node path is course content: a file or folder named preview must never be read back as the preview. The course's own address redirects to the course root in the editor. Explorer nodes carry a dot while their records have unsaved changes (records are compared by identity with the baseline taken at load and after each save; generated records — config, program, video manifests — keep their File identity while their source is unchanged). Styling is deliberately minimal: this is the prototype designers will restyle.

Steps

• Routes /course-editor/:courseSeriesIdInput/:courseIdInput/edit/:inCourseEditorPath* (editing) and …/preview/:inEditorPath* (preview), with the course's bare address redirecting to the editing root, and page: loads course + series via Course APIs, checks canManageCourses, builds the author's working TutorialProject; Guided Courses are rejected with a pointer to course management.
• Course explorer + document area (see Shell above): models/tutorial now models the course as records with typed parts claiming what they understand (TutorialProject.extraFiles keeps the rest; Video.extraFiles keeps unknown records of a package), and course-tree.ts projects them into nodes, resolves route paths to documents and computes changed paths. SpxProjectEditorHost keeps the author's editor state across document switches, maps the route tail under the project's root (from index.json) to the editor state's inEditorPath, starts route sync when the project is first opened and reopens the project where it was left.
• Embedded project editor: SpxProjectEditorHost composes EditorState + EditorContextProvider + CodeEditorProvider + ProjectEditor for the ownerless course project (effect-free, no local cache), selected through a small registry keyed by index.json's project.type (spx only for now). The Course Editor navbar shares undo/redo and the edit-mode switch with the Project Editor (extracted from EditorNavbar as EditorHistoryButtons / EditorModeSwitch), shows an unsaved indicator, and confirms before leaving with unsaved changes (route guard + beforeunload).
  • The initial in-editor path is taken from the route, else from the course config. A path the Project Editor does not recognize yet (the example course's /simple/sprites/Lita is a Simple Mode route from module_SpxProjectEditor.ts, not implemented yet) falls back to the default selection and is reported via capture instead of blocking the editor; EditorState.selectByRoute is made public for that check.
• Documents (layout is a placeholder for design to iterate on): text files in a plain Monaco editor (main_course.gox with XGo highlighting; completion/diagnostics wait for the Tutorial Language Server), videos (player with rename/remove; the program refers to a video by its name, e.g. showVideo "step-to"), course settings (initial editor path, Copilot context with generation via POST /user/courses/playground/copilot-context on the uploaded working copy), images and other files (view/delete). Adds TutorialProject.setConfig.
• Adding files by what they are (upload.ts, CourseUploadModal): the author says what they are adding — a video, a picture, or anything else — and the type decides where the records go, so no path is typed and none is shown. Underneath, the rules still follow the ownership of the tree so the format's invariants hold by construction. assets/ only contains packages: a video or a picture becomes a package (Resource) with its generated manifest whatever the extension, while assets/ itself and package directories refuse uploads, so the editor can never produce a directory without a manifest; the embedded project's directory belongs to the Project Editor; fixed-path records (index.json, main_course.gox) have their own editors; anything else becomes a plain record, kept with the course but unused by it, and the modal refuses a file whose name would take a path the course claims. Uploads are all-or-nothing.
  • .gox is now registered as text/plain in the MIME table (next to .spx), so course programs inline as data URLs like other text files instead of always being uploaded to Kodo.
• Save: snapshot() → saveFiles (unchanged files keep their universal URLs) → updateCourse(id, { content }). Only the content is sent: title and thumbnail belong to course management, and PATCH /courses/:id patches just the fields given, so the two surfaces do not overwrite each other (UpdateCourseParams is partial now). Cmd/Ctrl+S saves too; the editor refreshes its metadata from the response.
• Preview: a snapshot of the author's current (unsaved) work is loaded into a separate TutorialProject and handed to CoursePlayground, so the course runs the real Tutorial lifecycle without touching the working copy. It replaces the editor while shown (both drive the route's inEditorPath) under a banner with a way back; the completion modal is reused; leaving preview restores the author's editor path. Verified locally with a showMessage / completeWith course. Known limits: a blocking course modal has to be dismissed before the banner is reachable; the example course cannot be previewed until the runner supports the remaining capabilities (filterAPIs, showPrelude, showVideo) and Simple Mode routes (Tutorial v2: Tutorial lifecycle and Course playground #3419 / Tutorial v2: SPX Project Editor support #3416); the runner still reads completeWith as {feedback} while the contract says {content}, so feedback text does not show yet.
• The Copilot knows what a course is (utils/tutorial/skills/tutorial-course, components/course-editor/copilot): a built-in skill carrying a short main document plus two references loaded on demand, one for the course program (API surface, execution model, and the XGo rules that decide whether a program compiles) and one for the format (settings, resources, records kept but unused, what saving does); and a context registration that tells it which course this is and what it carries, the program as it stands including unsaved edits, and which document is open. Registered by CourseEditor and disposed with it, next to the Project Editor's own copilot setup, which comes and goes with the embedded project. The skill deliberately lists no capability status: which calls Preview implements moves with Tutorial v2: Tutorial lifecycle and Course playground #3419, so it says a compiled course may still stop at a call the host has not wired yet. Verified live: asked about the seed course's program, the assistant answered from the actual program and caught the missing parentheses that keep it from compiling. A review round then caught the one lifecycle gap this opens: the Course Editor stays mounted through a preview, and the Copilot assembles context from every registered provider whatever session is running, so the learner session was being handed the author's context and skill. Every registration now goes through whileAuthoring, silent while previewing, so Preview shows what a learner's assistant would see; the embedded project's own context needed nothing, since its host unmounts the subtree with the document.
• The author's copilot survives a preview: the playground's runner takes the copilot over with the learner's session, so the editor exports the author's session and panel state right before the playground mounts and restores them when the preview is left (Copilot.exportCurrentSession / restoreSession, feat(copilot): export and restore the current session #3497).
• Radar metadata follows the selector conventions (feat(spx-gui): add Radar selectors #3504): stable kebab-case roles, identity in attributes (explorer-node[path="assets/videos"], folder-item, toggle-folder-button, target-folder-option), and the root name course-editor scoping selectors such as course-editor save-button.
• Resource-layout guard hardened after a fourth review round, all three findings reproduced first: payload edits no longer count as a clash with the resource itself (the layout carries the resource's id); a package's directory must be free of records the course keeps outside the model, so a rename is refused and an upload derives orphan2 instead of overwriting orphan, with exportFiles throwing on a path claimed by both; names and kinds go through the same validatePathSegment as SPX asset names, so . and .. can no longer produce a course that cannot be loaded. Each has a regression test, including an export-then-load round trip.
• Fifth review round, all three reproduced by tests that fail before the fix: getValidName (shared, made reachable by uploads) increments the numeric suffix as digits, so a name at or above 2^53 no longer hangs the tab, and bounds its search with a separate counter; the file document follows the record's File rather than only its path, so uploading over the open text record shows the upload instead of letting the next keystroke write the old text back; loadFiles places this course's unclaimed records before naming packages and adds intact packages first, so a load-time rename can no longer take an orphan's directory (which left the editor unable to open the course), be triggered by a previous load's orphan, or take the name of a valid package listed after it.
• Sixth review round, reproduced by tests that fail before the fix: package ids are made unique when added (a copied package keeps its manifest's builder_id), the name rule tells a package from itself by instance, and the export refuses any path claimed by two parts of the course, packages included; record maps are queried for their own entries only (hasRecord), so a file named constructor no longer breaks export, and __proto__ is refused; setExtraFile keeps a file and a folder from sharing a path, and the upload modal reports it; name derivation leaves room for the de-duplicating suffix, and an upload adds all its files or none.
• Seventh review round, both reproduced by tests that fail before the fix: a package defines its records with Object.fromEntries, so one named __proto__ is no longer dropped on load; the payload rule also refuses a payload path that is a folder of the package's other records, so a rename or an extension change cannot make a file and a folder share a path inside a package. The export keeps checking exact paths only, by design: a file/folder overlap may already exist in a course as loaded, and refusing to export would make that course impossible to open, so it is refused where records are written instead.
• Eighth review round, both reproduced by tests that fail before the fix: records the model does not otherwise claim now live in Map<string, File> (TutorialProject.extraFiles, Resource.extraFiles) instead of objects, because on a reactive model some property names are Vue's (a record named __v_isReactive read back as true and crashed the explorer; one named __v_skip stopped change tracking, so edits no longer showed as unsaved). This was the third round to hit a special property name, so the class is closed rather than another name blocklisted. The model also reserves the folders it always treats as such (assets, assets/videos), so a file named assets can no longer take their place in a course without resources.
• Ninth review round, reproduced by route tests that fail on the old shape: a course file or folder named preview could not be opened by its address. Node paths sat on the same level as the preview segment, and vue-router ranks a static segment above a param, so the editor's own link to such a node read back as the preview on reload, a shared link or browser history. Editing now has its own edit namespace next to preview (see Shell). The round's other finding, runtime state left in debug after a preview, stays with EditorPreview (Tutorial v2: SPX Project Editor support #3416), as in the earlier rounds.
• Series preview (walk the saved courses of the series in order).

Review fixes

An adversarial review (Codex) of this branch raised five points, all confirmed against the code and fixed:

• Atomic snapshots. TutorialProject.snapshot() exports inside the embedded project's mutex; Save, Preview and Copilot-context generation use it, so an in-flight undo/redo or import can no longer leak an intermediate state into what gets uploaded or previewed.
• Save vs. concurrent edits. Save uploads its snapshot and only clears the unsaved flag if no edit happened after the snapshot (revision counter); metadata comes from the same snapshot as the files.
• Editor state outlives Preview. The project editor host stays mounted with an active flag: while previewing it hides its UI and syncs the editor state with a pausable IRouter wrapper (frozen route, dropped pushes), so undo history and selection survive a preview round trip.
• Course switch on the same route. Route params are read before any await so the query re-runs; the current session ends as soon as a new load starts or fails; superseded loads are discarded; onBeforeRouteUpdate asks about unsaved changes when the course identity changes.
• Monaco re-creation. The course program editor re-syncs the current code whenever the editor is re-created (e.g. language change) before installing its listeners.

Second round (two more findings, both confirmed):

• Save is blocking and session-bound. While saving, a loading mask covers the editor, route changes are refused with a hint and Preview is disabled; the save is tied to an AbortController that is aborted on unmount, so a save that outlives its session cannot publish a stale snapshot over a newer one. (A PATCH already on the wire cannot be recalled; a version-conditional update on the Course API is noted for Release 2.)

• Runtime state after Preview (not fixed here, owner Tutorial v2: SPX Project Editor support #3416): EditorPreview does not reset EditorState.runtime on unmount, so previewing while the author's project is running brings the editor back with the panels still in debug mode. Noted in SpxProjectEditorHost next to the active handling; to be fixed in EditorPreview itself.
  Third round (after the records-and-mounts explorer and uploads):

• Copilot-context generation is bound to its document. The snapshot/upload/request chain is aborted when the config document is closed, the inputs are locked while it runs, and a late result is written back only if the context did not change meanwhile.

• Package-layout guard. The rules a resource package must satisfy live in one ordered list (validateResourceLayout: well-formed name, unique within its kind, payload path clear of the manifest and of the package's extra records) and every mutation goes through it (setName, setFile, name derivation on upload, the rename document); export() refuses a layout that would overwrite a record. Uploading a file named index.json yields the resource index2 instead of a course that cannot be reloaded.

• Async flows bound to the session. Preview snapshot loads carry a generation invalidated by leaving/re-entering the preview or unmounting; out-of-date loads dispose their snapshot instead of publishing and navigating, failed loads dispose what they created. The upload and completion modals (app-level provider) drop their results once the session ended.

• Runtime state left in debug after the project UI unmounts stays with EditorPreview (Tutorial v2: SPX Project Editor support #3416): the side effect is created there, so its cleanup belongs there; this branch adds no compensation.

• Walkthrough comments (docs(course-editor): temporary walkthrough comments): a comment-only commit with a docstring per function/component and per-block notes, added to read the branch; it will be dropped before merge.

• A way in (components/course/management, components/course-editor/starter.ts): Playground Courses are managed where courses are managed. "Manage courses" and "Manage course series" each gain a kind filter (guided / Playground), and the server does the filtering, so pages and totals describe what is shown. Creating follows the filter: a guided course opens the form it always had; a Playground Course asks for a title, a thumbnail and the series it is written for, starts from a starter package (a default SPX project plus a program that compiles and uses only calls the host implements today, so the first Preview shows the course rather than an "unsupported capability" error) and goes straight to the Course Editor. The series is asked for at creation because the editor opens a course through its series, so a course in none could be listed but not edited; a Playground series may be created empty so there is one to choose, and opening a course from the list looks its series up. Adding the new course to its series reads the series right before writing it and sends its course list alone, so a series edited elsewhere while the form was open keeps those edits (UpdateCourseSeriesParams now says what the endpoint always accepted: every field is optional). Creating the course and adding it are two requests, so the form remembers a course it has already created: when the addition fails, the author is told the course exists, and clicking "Create" again only repeats the addition instead of creating a second course. What remains is the gap between that read and that write; closing it takes a server-side append the Course APIs do not have. The series editor lists courses of the series' own kind and keeps its picker and ordering; its file import/export stays with guided series until the course package work. An earlier cut of this step was a separate, series-centred modal, built that way because the course list could not be filtered by kind; the filter now exists, and that modal is gone. Depends on the kind filter of the course list endpoints (goplus/builder-backend#353); against a backend without it the parameter is ignored and the lists behave as before. This step also fixes a bug the existing guided list already had: it filtered each page by kind in the browser, so with Playground Courses being the most recently updated, the first page of "Manage courses" came back empty while the pager counted every course.

Verified locally against the builder-backend Tutorial v2 branches (goplus/builder-backend#350 / #353) with a Playground Course seeded from docs/develop/tutorial-v2/example-tutorial-course.

🤖 Generated with Claude Code