Visual Canvas

Feature Owner : Joylynne Esportuno
Module : Design
Priority : P0
Sprint #4: Fully Implemented
Date : July 1, 2026

EXECUTIVE SUMMARY

What is this feature ?
Visual Canvas is the creator editor for building quest structure with nodes, edges, scenario containers, and branching paths.

Why does it matter ?
Creators need a visual way to design non-linear learning journeys without manually editing JSON.

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.

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.

Marketing Hook

"Design branching quests as a map, not a spreadsheet."

2. 4D FRAMEWORK MAPPING

Diagnose

Makes structural gaps and disconnected nodes visible.

Design

Defines node sequence, branching, and content relationships.

Develop

Supports editing node content 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 player can render saved metadata.

Main Flow

1. Open visual canvas.

2. Add or edit nodes.

3. Connect nodes.

4. Save canvas.

5. Preview or submit quest.

Edge Cases

• No data : Initialize empty/default canvas.

• API error : Show save/load failure.

• Permission denied : Read-only or blocked editor access.

Decision Points

• IF quest mode is exploration, use canvas as primary editor.

• ELSE keep form editor as primary and preserve canvas sync paths.

4. INFORMATION ARCHITECTURE

Primary Information

• Nodes

• Edges

• Node labels/types

Secondary Information

• Node settings

• Validation state

• Save state

Tertiary Information

• Archived state

• Folder/group assignment

Actions

Primary CTA : Save / Publish
Secondary Actions : Add node, edit node, connect, archive, 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 canvas_metadata JSON.

// Example:
 
{
    edges:[],
    nodes:[],
    folders:[],
    quest_mode: "exploration" | "linear"
}

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, and content folders.

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 when applicable.

10. DATA REQUIREMENTS

Frontend Needs

• Quest ID, title/status context, creator/editor permission state

• Canvas nodes with ID, type, position, data payload, archived state, and optional folderId

• Canvas edges with source, target, handles, labels, and branch logic metadata where used

• quest_mode to determine linear vs exploration behavior

• folders for content-layer organization

• Local drag, selection, modal, fullscreen, and save state

API Calls Frontend Will Make

• Load canvas on editor entry

• Save canvas after edits/autosave

• Optionally call publish/validation endpoints after save

11. PERFORMANCE CONSIDERATIONS

Database Optimization

• The current model stores canvas metadata as a JSON document on quests. This keeps loading simple but means saves can be larger as quests grow.

12. SECURITY & AUTHORIZATION

Who Can Access This Feature?

• Creator: Full edit access to owned quests.

• Reviewer: Read/review access through review flows, not general editing.

• Learner: No access to authoring canvas.

13. ERROR HANDLING

Current Existing Error Handling

• GET /api/creator/update-quest-canvas returns badRequest when quest_id is missing.

• GET /api/creator/update-quest-canvas returns notFound when Supabase returns PGRST116, using the message "Quest not found or you do not have permission to access it".

• GET /api/creator/update-quest-canvas returns internalError for other database fetch failures.

• If stored canvas_metadata fails 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-canvas returns validationError when the body does not match updateCanvasSchema.

• PUT /api/creator/update-quest-canvas returns notFound when 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 internalError if the Supabase update fails.

More Details:

• For further information, the visual canvas validation logic is located at lib/validation/quest-validation.ts

14. TESTING CHECKLIST

Happy Path

• Load existing canvas.

• Add/edit/delete node.

• Connect nodes.

• 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 player.

15. OPEN QUESTIONS

• What is the final parity expectation between form editor and visual canvas?

• Should React Flow remain the long-term interaction layer?

• What happens if the Scenario Node has a lot of child nodes? Won’t it look too cluttered inside?

16. OUT OF SCOPE

• Advanced auto-layout

• Collaborative editing

• Full grouped-node UI (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 branching quest

18. DEPENDENCIES

This feature depends on:

• Project Creation

• Quest Editor

• React Flow integration

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

Sprint #12: Feature already implemented and deployed.
Backend: Joylynne Esportuno
Frontend: Joylynne Esportuno
QA: Patrick Babala
Estimated Completion: Feature completed.