Visual Canvas

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 nodes with ID, type, position, data payload (audio_url, motivation), 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, node_folder_ids, and folder_positions 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 (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-canvas returns badRequest when quest_id is missing.

  • GET /api/creator/update-quest-canvas returns notFound when Supabase returns PGRST116 ("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 (HTTP 400) when the body does not match updateCanvasSchema, and when any Code node exceeds 50,000 characters (message includes the node label and count).

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

  • 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.ts and canvasToForm.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-layout is 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).


Was this article helpful?