Feature Owner (original Hand-Off): Joylynne Grace C. Esportuno
Updated by / current owner: Patrick Babala
Reviewers: James Billate and Uriel Tribiana — original review. Update review: Clyde Ador (@clydetims), Christian Denzon (@cdnzn) (PRs #667 / #680 / #700 / #708 / #712 / #760 / #788 / #800; @ybcole also reviewed #708).
Module: Design (Dual Editor) — Visual Canvas
Priority: P0
Status: Handoff — Updated and Published (v2.0)
Date: 2026-09-30
Issue: wyzlab/WyzQuests #31 — [2.2] Visual Canvas (closed). Sub-issues: #160 [2.2.1] Toggleable Button for Outline and Visual View, #161 [2.2.2] Node bar, #162 [2.2.3] Nodes Implementation, #249 [2.2.4] Linear Mode - Visual Canvas, #270 [2.2.5] Node deletion via eraser and "All" implementation, #280 [2.2.6] Quest Mode Conversion Linear to Exploration and vice-versa Logic, #451 [2.2.7] Full Screen Node.
PRs covered by this revision: #667 (quest/card background audio), #680 (motivation pop-ups + canvas bug fixes), #700 (node fullscreen in linear mode), #708 (activity/code-block fixes + linear layout engine), #712 (preview reset, question handles, code language + 50k limit), #760 (archived-node publish validation + persistence), #788 (responsive UI), #800 (canvas CodeBlock input fix).
Related, separate guide: Form Editor ([2.1]); Creator Quest Card Background Audio (#667) — the deeper background-audio/motivation workflow lives in that guide, not duplicated here.
Companion doc: Internal Technical Guide — Internal-Technical-Guide-Visual-Canvas.md (architecture, DB schema, API specs, helpers, ops, testing). This Hand-Off stays product-facing; where engineering depth is needed it cross-references the ITG instead of duplicating it.
Corrected in 2.0: the original Hand-Off referenced the feature in prose only and did not carry a References section. The primary issue link has been corrected to #31 (the ITG originally cited issues/81, which is "[6.3] Suspend User").
EXECUTIVE SUMMARY
What is this feature ?
Visual Canvas is the creator editor for building quest structure with nodes, edges, scenario containers, and branching paths. It is the primary authoring surface for Exploration Mode quests and a synchronized view for Linear Mode quests.
Why does it matter ?
Creators need a visual way to design non-linear learning journeys without manually editing JSON, and to see the whole branch tree at a glance.
What's the MVP scope ?
Create, edit, connect, save, and publish canvas nodes. Full form-editor parity and advanced group visuals are follow-up work.
Shipped scope added in v2.0:
Node fullscreen editing in Linear Mode (PR #700): every openable node exposes a maximize button that opens a focus-mode modal. (Exploration already had it via sub-issue #451.)
Background audio on nodes (PR #667): attach per-node audio with Local / URL / Assets sources and a 10 MB limit, gated by a published-edit confirmation.
Motivation pop-ups on nodes (PR #680): attach a text/image/video/GIF/audio motivational pop-up to a node, with an editable title; shown to learners once per card after Continue.
Reliable archived nodes (PR #760): archived nodes are excluded from publish validation, persist across refresh, and can be restored or permanently deleted.
Comfortable linear editing (PR #708): a rewritten, measured layout engine and a pure-visual drag reorder (the order commits only on drop).
Predictable Code nodes (PRs #708, #712, #800): spacebar/backspace work while typing, a 45k warning and a hard 50,000-character limit, and more stable Monaco mounting.
Correct branch handles (PR #712): question-node choice handles appear only in Exploration Mode.
Safer previews and mobile learner UI (PRs #712, #788): "Try Again" in preview no longer wipes server progress; dialogs stay in-viewport and touch targets meet ≥44 px.
Accurate publish state (PR #760): any real canvas change on a published quest moves it back to Draft so learners never see an inconsistent version.
Still deferred: real-time collaboration, advanced auto-layout, and full grouped-node UI.
1. USER PAIN POINT & SOLUTION
Without Visual Canvas
Creators cannot easily reason about branching quest structure in a linear-only editor.
Pain Point
Emotional: Branching content feels overwhelming.
Functional: Manual sequencing is error-prone.
Business Impact: Complex quests take longer to build and review.
Current State (Already Implemented)
Creators build and review quest paths visually, with node-level audio/motivation, fullscreen editing, and reliable archived-node handling.
Marketing Hook
"Design branching quests as a map, not a spreadsheet."
2. 4D FRAMEWORK MAPPING
Diagnose
Makes structural gaps and disconnected nodes visible (and now flags only active nodes — archived nodes are ignored).
Design
Defines node sequence, branching, and content relationships.
Develop
Supports editing node content, attaching audio/motivation, fullscreen editing, and saving canvas metadata.
Deliver
Feeds the Quest Player/View Content and export flows.
3. USER FLOWS
Entry Point
/quest-editor/[questID]/content/visual-canvas
Success Criteria
Canvas loads, edits persist, and the player can render saved metadata. A published quest reverts to Draft when the canvas changes meaningfully.
Main Flow
1. Open Visual Canvas.
2. Add or edit nodes.
3. Connect nodes (Exploration) or reorder the linear chain (Linear).
4. Optionally open a node fullscreen, or attach background audio / a motivation pop-up.
5. Save canvas (autosave debounced 2s; archive/delete persist immediately).
6. Preview or submit quest.
Edge Cases
No data: initialize an empty/default canvas.
API error: show save/load failure.
Permission denied: read-only reviewer access.
Archived node: stays hidden from the canvas but persists; deleting it from the Archived Nodes modal is permanent and still counts as a canvas change.
Code node over 50,000 characters: save is rejected (HTTP 400) with the node label and count; the editor pauses auto-save and shows a red banner.
Published quest edited: reverts to Draft on the next meaningful change.
Linear-mode question node: no per-choice handles are shown.
Decision Points
IF quest mode is Exploration, use the canvas as the primary editor.
ELSE keep the Form Editor as primary and preserve canvas sync paths.
4. INFORMATION ARCHITECTURE
Primary Information
Nodes
Edges
Node labels/types
Scenario containers and child cards
Secondary Information
Node settings (including background audio and motivation)
Validation state
Save state
Tertiary Information
Archived state
Folder/group assignment
Fullscreen state
Actions
Primary CTA: Save / Publish
Secondary Actions: Add node, edit node, connect, fullscreen edit, add/edit audio, add/edit motivation, archive, restore/delete archived, preview
5. WIREFRAMES
Excluded — Feature fully implemented.
6. WIREFLOWS
Excluded — Feature fully implemented.
7. PROTOTYPE
Excluded — Feature fully implemented.
8. BACKEND SCHEMA
Database Tables
quests.canvas_metadata
Schema includes nodes, edges, quest_mode, and folders in the canvas_metadata JSON, plus node_folder_ids and folder_positions at runtime. Archived nodes are stored inline in nodes[] with data.isArchived = true (there is no separate archive table).
{ "edges": [], "nodes": [], "folders": [], "node_folder_ids": {}, "folder_positions": {}, "quest_mode": "exploration" | "linear"}
Node data is validated by lib/schemas/nodes.schema.ts (one Zod schema per node type). Code nodes carry a 50,000-character codeContent cap. See ITG §4 (Data Model/Schema) for the full field list.
9. API ENDPOINTS
Endpoint 1: GET /api/creator/update-quest-canvas?quest_id=
Purpose: Loads saved canvas metadata for the quest editor.
Auth: Creator/editor access required.
Query Params: quest_id is required.
Response Data: Nodes, edges, quest mode, content folders, and the quest title. Invalid stored metadata is returned as an empty default.
Endpoint 2: PUT /api/creator/update-quest-canvas
Purpose: Persists the full canvas metadata document.
Auth: Creator/editor access required.
Request Body: quest_id and canvas_metadata.
Response Data: Save result and updated metadata. Rejects any Code node over 50,000 characters (HTTP 400) and reverts a published quest to Draft when the change is meaningful.
Other canvas endpoints
GET
/api/reviewer/get-canvas— loads canvas metadata for read-only reviewer mode.POST
/api/ai/compute-canvas-layout— computes better node positions during Exploration AI imports and smart merges.POST
/api/creator/convert-canvas-to-cards— converts imported canvas nodes into Form Editor cards.POST
/api/creator/quest-content-nodes/get-upload-url/ DELETE/api/creator/quest-content-nodes/delete-media— signed-URL upload and cleanup for node media.
Full request/response shapes, auth checks, and the 50k guard are in the ITG §4 (API Specification).
10. DATA REQUIREMENTS
Frontend Needs
Quest ID, title/status context, creator/editor permission state
Canvas
nodeswith ID, type, position, data payload (audio_url,motivation), archived state, and optionalfolderIdCanvas
edgeswith source, target, handles, labels, and branch logic metadata where usedquest_modeto determine linear vs exploration behaviorfolders,node_folder_ids, andfolder_positionsfor content-layer organizationLocal drag, selection, modal, fullscreen, and save state
API Calls Frontend Will Make
Load canvas on editor entry
Save canvas after edits/autosave (and immediately for archive/delete)
Optionally call publish/validation endpoints after save
11. PERFORMANCE CONSIDERATIONS
Database Optimization
The current model stores canvas metadata as a single JSON document on quests. This keeps loading simple but means saves grow with the quest. Autosave is debounced at 2 seconds; archive/unarchive/delete of archived nodes persist immediately. Linear layout now measures real node widths (TARGET_GAP accumulator) instead of assuming a fixed gap, which keeps large linear canvases from overlapping.
12. SECURITY & AUTHORIZATION
Who Can Access This Feature?
Creator: Full edit access to owned quests.
Agency members: Access scoped to agency resources (
verifyAgencyResourceOwnership).Reviewer: Read/review access through review flows (read-only), not general editing.
Learner: No access to the authoring canvas.
Updated in v2.0: authoring is authenticated with Supabase Auth (not Clerk).
13. ERROR HANDLING
Current Existing Error Handling
GET /api/creator/update-quest-canvasreturnsbadRequestwhenquest_idis missing.GET /api/creator/update-quest-canvasreturnsnotFoundwhen Supabase returnsPGRST116("Quest not found or you do not have permission to access it").GET /api/creator/update-quest-canvasreturnsinternalErrorfor other database fetch failures.If stored
canvas_metadatafails schema validation, the API logs the invalid data and returns a successful response with default empty metadata instead of failing the request.PUT /api/creator/update-quest-canvasreturnsvalidationError(HTTP 400) when the body does not matchupdateCanvasSchema, and when any Code node exceeds 50,000 characters (message includes the node label and count).PUT /api/creator/update-quest-canvasreturnsnotFoundwhen the quest is missing or the user does not have update permission.Linear-mode canvas-to-form sync errors are logged but do not fail the canvas save request.
The final canvas update returns
internalErrorif the Supabase update fails.Archive/unarchive (and deleting an archived node) force a save and roll back on failure, showing an error toast rather than leaving the UI out of sync.
A meaningful canvas change on a published quest moves it back to Draft (intentional safeguard).
Publish validation ignores archived nodes; if no active nodes remain, publishing fails with "Quest has no content nodes".
More Details:
The Visual Canvas validation logic is located at
lib/validation/quest-validation.ts. See ITG §5 (Monitoring & Alerting).
14. TESTING CHECKLIST
Happy Path
Load existing canvas.
Add/edit/delete node.
Connect nodes.
Drag-reorder nodes in Linear Mode and confirm the order commits on drop.
Open a node in fullscreen and close it (Linear and Exploration).
Attach background audio (Local / URL / Assets) and a motivation pop-up.
Save persists metadata after refresh.
Preview/player uses saved structure.
Edge Cases
Publish validation detects broken structure.
Unauthorized edit is blocked.
Save failure does not falsely show saved state.
Archived nodes are not delivered to the player.
Archive a node, hard-refresh, and confirm it stays archived; delete it permanently from the Archived Nodes modal.
Publish a quest, then make a canvas change and confirm it reverts to Draft.
Paste/type a Code node over 50,000 characters and confirm the save is rejected (HTTP 400) and auto-save pauses.
Confirm spacebar/backspace work while typing in a Code node (canvas does not pan/zoom).
Confirm per-choice handles appear on question nodes only in Exploration Mode.
Trigger "Try Again" in preview and confirm learner progress is not wiped.
Confirm dialogs stay within the viewport on small screens and touch targets are ≥44 px.
15. OPEN QUESTIONS
What is the final parity expectation between the Form Editor and Visual Canvas? — Resolved (v2.0). Bidirectional sync is implemented (issues #272 / #484;
lib/canvas-sync/formToCanvas.tsandcanvasToForm.ts); Linear quests mirror cards and canvas nodes. Remaining gap: exploration quests remain canvas-first.Should React Flow remain the long-term interaction layer? — Still open. No replacement is planned; the canvas is built entirely on React Flow (
@xyflow/react) with no abstraction layer, so a swap would be a large migration.What happens if the Scenario Node has many child nodes? Won't it look too cluttered? — Partially resolved. Folders, node collapse, and the Archived Nodes modal reduce clutter; full grouped-node visuals are still out of scope (see §16).
16. OUT OF SCOPE
Advanced auto-layout — still out of scope. (
compute-canvas-layoutis used only for AI imports/smart merges; there is no user-triggered "tidy"/auto-arrange.)Collaborative editing — still out of scope.
Full grouped-node UI — still out of scope (to be developed via Content Folder Structure, a sub-feature of Quest Folder Structure).
17. SUCCESS METRICS
Canvas save success rate.
Publish success rate.
Time to build a branching quest.
Archive/restore success rate (new in v2.0).
18. DEPENDENCIES
This feature depends on:
Project Creation
Quest Editor
React Flow integration
Supabase Auth (was implicitly Clerk-era auth)
Supabase Storage (node media, signed-URL uploads)
These features depend on this:
AI Scenario Seed
Linear Mode
Validation Error
View Content/Quest Player
Social Debrief
Scenario Logic
Form Editor and Visual Canvas Bidirectional Sync
19. TIMELINE & OWNERSHIP
Original owner / Hand-Off author: Joylynne Grace C. Esportuno (Hand-Off v1.0; original front matter lists Sprint #4 Fully Implemented, section 19 lists Sprint #12).
Implementation updates & current owner: Patrick Babala.
Reviewers: @clydetims, @cdnzn; @ybcole on #708.
Sprint: Feature already implemented and deployed.
Backend: Joylynne Esportuno (original); Patrick Babala (v2.0 updates). Frontend: Joylynne Esportuno (original); Patrick Babala (v2.0 updates).
QA: Patrick Babala (original).
Shipped: core Visual Canvas (Feb–Mar 2026); v2.0 updates merged 2026-07-14 to 2026-09-03 (PRs #667, #680, #700, #708, #712, #760, #788, #800).
Estimate: complete for v2.0 scope; remaining items are the Out of Scope list above.
References
Issue: wyzlab/WyzQuests #31 — [2.2] Visual Canvas (closed).
Sub-issues: #160 [2.2.1]; #161 [2.2.2]; #162 [2.2.3]; #249 [2.2.4]; #270 [2.2.5]; #280 [2.2.6]; #451 [2.2.7].
Milestone: [2] Design (Dual Editor).
v2.0 PRs: #667 — background audio; #680 — motivation pop-ups + canvas fixes; #700 — linear fullscreen; #708 — activity/code-block fixes + layout engine; #712 — preview reset, question handles, code language + 50k limit; #760 — archived-node validation + persistence; #788 — responsive UI; #800 — canvas CodeBlock input fix.
Related, separate guide: Creator Quest Card Background Audio (#667).
Companion ITG:
Internal-Technical-Guide-Visual-Canvas.md.
Version History
2.0 — 2026-09-30 — Patrick Babala. Hand-Off overhaul. Updated the original v1.0 outline in place: Executive Summary and shipped scope; API section corrected (Code-node 400 limit, unpublish-on-change, reviewer/layout/convert/upload endpoints); background audio, motivation pop-ups, linear fullscreen, layout-engine reorder, archived-node reliability, Code-node fixes, responsive dialogs, and preview reset added; Supabase Auth noted; References fixed with issue sub-issues and PR links; Open Questions and Out of Scope retained with status notes. Summary of PRs: #667, #680, #700, #708, #712, #760, #788, #800.
1.0 — July 1, 2026 — Joylynne Grace C. Esportuno. Original Hand-Off (visual node/edge authoring, scenario containers, branch paths, canvas metadata save/load, read-only reviewer mode, validation, player delivery).