Feature Owner (original Hand-Off): Krizha Onise Cortez
Updated by / current owner: Patrick Babala (babalapatrick@gmail.com)
Reviewers: Joylynne Grace Esportuno (teruterubozuuu), James Derick Billate (zcrnnn) — original review. Update review: Clyde Ador (@clydetims), Christian Denzon (@cdnzn) (PRs #680 / #708 / #776 / #788 / #790 / #870; @ybcole also reviewed #708).
Module: Design (Dual Editor) — Form Editor
Priority: P0
Status: Handoff — Updated and Published (v2.0)
Date: 2026-09-30
Issue: wyzlab/WyzQuests #71 — [2.1] Form Editor (closed). Sub-issues: #248 [2.1.1] Reflection Card, #288 [2.1.4] Scenario Card, #497 [2.1.2] Discussion Card, #549 [2.1.3] Question Card.
PRs covered by this revision: #680 (motivation pop-ups), #708 (activity/code-block fixes), #776 (fullscreen card editors), #788 (responsive UI), #790 (signed-URL uploads + PDF/file mapping), #870 (learner Code sandbox).
Related, separate guide: #667 (Creator Quest Card Background Audio) — the per-card Background Audio tab lives in that guide and is not duplicated here.
Companion doc: Internal Technical Guide — Internal-Technical-Guide-Form-Editor.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.
EXECUTIVE SUMMARY
What is this feature?
The Form Editor is the primary linear content authoring interface used by creators to build quests through modular content cards. It supports creating, editing, deleting, duplicating, reordering, and organizing content while automatically synchronizing with the Visual Canvas.
Why does it matter?
Creators need a simple and structured editing experience without manually managing quest data or canvas metadata. The Form Editor provides a familiar outline-based workflow while maintaining consistency with the Visual Canvas.
What's the MVP scope?
Create content cards
Edit existing cards
Delete and reorder cards
Upload media
Support Scenario child cards
Integrate Question Hub activities
Automatically synchronize with Visual Canvas
Validate content before publishing
Shipped scope added in v2.0:
Motivation pop-ups (PR #680): attach an optional motivational text or media pop-up to any card (text, image, video, GIF, or audio), with an editable pop-up title and three source options (Upload Local, Via Link, From Assets).
Fullscreen card editors (PR #776): every card editor can toggle a focus mode from the header or with Ctrl+Shift+E.
Signed-URL uploads (PR #790): media uploads now use a two-step signed-URL flow, which fixed large/valid files being rejected.
Reliable File/PDF cards (PR #790): File (PDF) cards now render correctly in the learner preview.
Responsive dialogs (PR #788): modals stay inside the viewport and interactive touch targets meet the ≥44 px target.
Safer Code cards (PR #870): learner Code-card HTML renders inside a sandboxed iframe (no same-origin access).
Still deferred (v1.1+): real-time collaboration, version history, bulk card editing, and offline editing.
1. USER PAIN POINT & SOLUTION
Without Form Editor
Creators would need to edit quest content directly through canvas nodes or raw data, making content management slower and more difficult.
Pain Point
Emotional: Editing large quests becomes overwhelming.
Functional: Managing multiple content types without a structured interface is inefficient.
Business Impact: Content production takes longer and increases authoring errors.
Current State (Already Implemented)
Creators can manage all quest content through a centralized card-based editor with automatic synchronization and publishing validation.
2. 4D FRAMEWORK MAPPING
Diagnose
Provides a structured overview of all quest content.
Design
Allows creators to organize, edit, and manage every content card.
Develop
Supports media uploads, Question Hub integration, Scenario child cards, motivation pop-ups, fullscreen editing, and publishing.
Deliver
Provides validated quest content used by the Quest Player and Visual Canvas.
3. USER FLOWS
Entry Point
/quest-editor/[questID]/content/form-editor
Success Criteria
Content cards load successfully, edits persist after saving, media uploads complete successfully, and published quests pass validation.
Main Flow
Open Form Editor.
Load existing quest content.
Create or edit content cards.
Upload media if necessary.
Save changes.
Synchronize with Visual Canvas.
Validate quest.
Save draft or publish.
Edge Cases
Empty quest initializes with no cards.
Upload failure displays an error message (including signed-URL failure).
Validation failure prevents publishing.
Unauthorized users cannot edit content.
Deleted or archived Question Hub activities cannot be selected.
Deleting a card that has learner submissions is blocked ("Cannot delete this card because it has learner submissions").
Signed URL can expire if the upload is not completed promptly; the creator must retry the upload.
Motivation media upload fails when the file type or size is rejected.
Decision Points
IF quest mode is Linear Continue using Form Editor.
ELSE Redirect creators to Visual Canvas.
4. INFORMATION ARCHITECTURE
Primary Information
Content Cards
Scenario Cards
Activity Cards
Media Attachments
Secondary Information
Motivation Content (pop-up)
Card Order
Validation Status
Publishing Status
Tertiary Information
Canvas Synchronization
Upload Progress
Save State
Actions
Primary CTA
Save Draft
Publish
Secondary Actions
Add Card
Edit Card
Delete Card
Duplicate Card
Reorder Card
Upload Media
Add/Edit Motivation (pop-up)
Toggle Fullscreen (card editor)
5. WIREFRAMES
Excluded — Feature fully implemented.
6. WIREFLOWS
Excluded — Feature fully implemented.
7. PROTOTYPE
Excluded — Feature fully implemented.
8. BACKEND SCHEMA
Database Tables
quest_content_cards
Stores all content cards belonging to a quest.
Example:
{ "id": "...", "quest_id": "...", "type": "text", "content": {}, "motivation": {}, "order_index": 1}
Notes for v2.0: id is a text primary key (not UUID); content and motivation are JSON objects. Card type is one of: text, activity, reflection, scenario, image, video, audio, file, link, codeblock, discussion, question. See the ITG §4 for the exact schema and migrations.
quests
Relevant fields:
canvas_metadata
publishing_status
quest_mode
9. API ENDPOINTS
Content cards
GET
/api/creator/quest-content-cards/list— Loads all content cards for a quest.POST
/api/creator/quest-content-cards/create— Creates a new content card.PUT
/api/creator/quest-content-cards/update— Updates an existing content card.DELETE
/api/creator/quest-content-cards/delete— Deletes a content card.PUT
/api/creator/quest-content-cards/reorder— Updates card ordering.
Media
POST
/api/creator/quest-content-nodes/get-upload-url— Returns a signed upload URL; the browser then uploads the file directly to storage.DELETE
/api/creator/quest-content-nodes/delete-media— Removes uploaded media objects.POST
/api/creator/quest-content-cards/upload-motivation-media— Uploads a motivation file (image, video, GIF, or audio).
Legacy — removed
POST/api/creator/quest-content-cards/upload-media— removed in PR #790. Replaced by the signed-URL flow above.
Publishing and canvas
POST
/api/creator/validate-quest-content— Validates quest content before publishing.PATCH
/api/creator/update-quest— Updates publishing status.GET/PUT
/api/creator/update-quest-canvas— Loads and saves canvas metadata.POST
/api/creator/convert-canvas-to-cards— Converts canvas nodes into cards during AI curriculum import.
Supporting
GET
/api/creator/get-activity— Loads a Question Hub activity for Activity (Quiz) cards.POST
/api/forum/create-post— Creates discussion forum posts on publish.
Full request/response shapes, auth checks, and storage paths are in the ITG §4 (API Specification).
10. DATA REQUIREMENTS
Frontend Needs
Quest ID
Quest Mode
Content Cards
Scenario Child Cards
Question Hub Activities
Upload Status
Publishing Status
Validation State
Canvas Synchronization State
API Calls Frontend Will Make
Load content cards
Create card
Update card
Delete card
Reorder cards
Upload media (request signed URL, then upload)
Upload motivation media
Validate quest
Publish quest
11. PERFORMANCE CONSIDERATIONS
Database Optimization
Cards are stored individually while canvas metadata is synchronized only when necessary. This minimizes unnecessary updates while preserving consistency between the Form Editor and Visual Canvas.
12. SECURITY & AUTHORIZATION
Who Can Access This Feature?
Creator Full editing permissions for owned quests.
Agency members Access is scoped to agency resources (via agencyResourceFilter / verifyAgencyResourceOwnership).
Reviewer Read-only access during review workflows.
Learner No access.
Updated in v2.0: authentication is now Supabase Auth (not Clerk). SVG uploads are hard-rejected, and Code-card HTML is rendered to learners inside a sandboxed iframe.
13. ERROR HANDLING
Current Existing Error Handling
Validation failures prevent saving invalid content.
Upload failures display error notifications (including signed-URL failures and type/size rejections).
Unauthorized users are blocked from editing.
Database failures return API error responses.
Deleting a card with learner submissions returns a "has learner submissions" conflict instead of a silent failure.
Publishing validation prevents incomplete quests from being published.
Canvas synchronization failures are logged before returning an error.
Discussion forum post failures during publish are surfaced as a warning; the quest can still publish.
14. TESTING CHECKLIST
Happy Path
Load content cards
Create card
Edit card
Delete card
Duplicate card
Reorder cards
Upload media (image, video, audio, document)
Add and edit a motivation pop-up
Toggle a card editor to fullscreen and back
Save draft
Publish quest
Synchronize with Visual Canvas
Edge Cases
Upload unsupported file type (including SVG).
Upload oversized file (image > 5 MB, audio > 10 MB, video > 25 MB, file > 50 MB).
Validation failure.
Empty quest.
Deleted or archived Question Hub activity.
Unauthorized editing.
Synchronization failure.
Delete a card that has learner submissions (expect a blocked delete).
Complete a signed-URL upload after the URL has expired (expect a retry path).
Motivation pop-up appears only once per card per playthrough, after clicking Continue.
Code-card content is sandboxed in the learner view (no scripts escape).
15. OPEN QUESTIONS
Collaborative editing — Status: still open. Not implemented; confirmed out of scope for v2.0.
Version history — Status: still open. Not implemented; confirmed out of scope for v2.0.
Bulk editing for large quests — Status: still open. Not implemented; confirmed out of scope for v2.0.
16. OUT OF SCOPE
Real-time collaborative editing. (Still out of scope in v2.0.)
Version history. (Still out of scope in v2.0.)
Bulk card editing. (Still out of scope in v2.0.)
Offline editing support. (Still out of scope in v2.0.)
17. SUCCESS METRICS
Successful content save rate.
Media upload success rate.
Publishing success rate.
Canvas synchronization success rate.
Average quest authoring time.
18. DEPENDENCIES
This feature depends on:
Quest Editor
Visual Canvas
Question Hub
Supabase Storage
Supabase Auth (was: Clerk Authentication)
Publishing Workflow
These features depend on this:
Quest Player
Visual Canvas Synchronization
Review Workflow
Publishing Workflow
AI Curriculum Import
19. TIMELINE & OWNERSHIP
Original owner / Hand-Off author: Krizha Onise Cortez (Hand-Off v1.0, February 2026).
Implementation updates & current owner: Patrick Babala.
Reviewers: @clydetims, @cdnzn; @ybcole on #708.
Sprint: Feature already implemented and deployed.
Backend: Multiple contributors. Frontend: Krizha Onise Cortez (original); Patrick Babala (v2.0 updates).
Shipped: core Form Editor February 2026; v2.0 updates merged 2026-08-28 to 2026-09-10 (PRs #680, #708, #776, #788, #790, #870).
Estimate: complete for v2.0 scope; remaining items are the out-of-scope list above.
References
Issue: wyzlab/WyzQuests #71 — [2.1] Form Editor (closed).
Sub-issues: #248 [2.1.1] Reflection Card; #288 [2.1.4] Scenario Card; #497 [2.1.2] Discussion Card; #549 [2.1.3] Question Card.
Milestone: [2] Design (Dual Editor).
v2.0 PRs: #680 — motivation pop-ups; #708 — activity/code-block fixes; #776 — fullscreen card editors; #788 — responsive UI; #790 — signed-URL uploads + PDF/file mapping; #870 — learner Code sandbox.
Related, separate guide: #667 — Creator Quest Card Background Audio.
Companion ITG:
Internal-Technical-Guide-Form-Editor.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 (
upload-media→ signed-URLget-upload-url+ PUT, plusdelete-media,upload-motivation-media, canvas/activity/forum endpoints); motivation pop-ups, fullscreen card editors, responsive dialogs, and learner Code sandbox added; Clerk → Supabase Auth; References fixed with issue sub-issues and PR links; Open Questions and Out of Scope retained with status notes. Summary of PRs: #680, #708, #776, #788, #790, #870.1.0 — February 2026 — Krizha Onise Cortez. Original Hand-Off (linear card authoring, card CRUD/reorder, media uploads, Scenario child cards, Question Hub integration, Visual Canvas synchronization, publishing validation, discussion forum integration).