Form Editor

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

  1. Open Form Editor.

  2. Load existing quest content.

  3. Create or edit content cards.

  4. Upload media if necessary.

  5. Save changes.

  6. Synchronize with Visual Canvas.

  7. Validate quest.

  8. 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-URL get-upload-url + PUT, plus delete-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).


Was this article helpful?