1. Front Matter
Title: Form Editor
Author: Krizha Onise Cortez (armaminter) — original author (February 2026)
Updated by: Patrick Babala (babalapatrick@gmail.com) — author of PRs #680, #708, #776, #788, #790, #870
Reviewers: Joylynne Grace Esportuno (teruterubozuuu), James Derick Billate (zcrnnn) — original review. Update review: Clyde Ador (@clydetims), Christian Denzon (@cdnzn) (reviewed PRs #680 / #708 / #776 / #788 / #790 / #870; @ybcole also reviewed #708).
Created: February 2026
Updated: 2026-09-30
Status: Published (feature live)
References:
Issue: [2.1] Form Editor — #71
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)
Update 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 feature (separate guide): Creator Quest Card Background Audio (#667) — adds the per-card Background Audio tab documented in its own guide; not duplicated here.
2. Introduction & Goals
Problem Summary
The Form Editor is the primary authoring interface used by creators to build quest content through a structured, linear workflow. It enables creators to compose educational content using reusable content cards, upload supporting media, organize scenarios, attach Question Hub activities, configure reflections and discussions, add motivation pop-ups, and publish complete learning experiences without directly modifying quest metadata.
The feature serves as the foundation of the Quest Editor by providing an intuitive card-based editing experience while maintaining synchronization with the Visual Canvas representation. It ensures that creators can freely edit content in either interface while preserving a single source of truth for quest structure and content.
The Form Editor also integrates media management, validation, publishing workflows, AI-generated curriculum imports, and Question Hub activities into one unified editing environment.
Goals & Non-Goals
Goals
Content Authoring
Allow creators to create, edit, duplicate, delete, and reorder content cards.
Support every content card type: Text, Image, Video, Audio, File, Link, Codeblock, Scenario, Question, Reflection, Discussion, and Activity (Quiz).
Allow rich text editing for supported content.
Support drag-and-drop ordering, including folders around cards.
Media Management
Upload images, videos, audio files, and documents through a two-step signed-URL flow to Supabase Storage.
Attach a motivation pop-up (text, image, video, GIF, or audio) to a card.
Automatically replace previous media when updating existing content.
Scenario Management
Support nested child cards inside Scenario cards (one Question card maximum per scenario).
Preserve child ordering.
Support mixed child content types.
Activity Integration
Connect Activity (Quiz) cards to reusable Question Hub activities or to a custom question set.
Display linked activities inside the editor.
Preserve activity references during publishing.
Canvas Synchronization
Automatically synchronize Form Editor changes to the Visual Canvas.
Generate linear canvas nodes for linear quests.
Preserve node positions during synchronization.
Import cards from existing canvas metadata.
Editing Experience
Provide a fullscreen (focus mode) option for every card editor, toggled with a button or Ctrl+Shift+E (PR #776).
Publishing
Validate quest content before publishing.
Create required discussion forum posts.
Update publishing status.
Prevent invalid quests from being published.
Non-goals
The Form Editor does not currently support collaborative real-time editing.
The Form Editor does not perform automatic content versioning.
Creators cannot edit multiple cards simultaneously.
Media editing is limited to upload and replacement.
Visual Canvas remains the primary editor for exploration quests.
Background audio is out of scope for this guide; see the Creator Quest Card Background Audio guide.
Glossary
Content Card — Individual editable unit representing a piece of quest content.
Scenario Card — Parent container capable of holding nested child cards.
Child Card — Content contained within a Scenario Card.
Activity Card (Quiz Card) — Card linked to reusable Question Hub activities or a custom question set.
Motivation Attachment — Optional motivational text or media shown to the learner after they continue past a card.
Question Hub — Central repository of reusable quiz activities.
Canvas Metadata — JSON representation of quest nodes and edges, plus folders and mode.
Linear Quest — Quest authored primarily through the Form Editor.
Exploration Quest — Quest authored primarily through Visual Canvas.
Signed URL Upload — Two-step upload: request a signed URL from the API, then PUT the file directly to Supabase Storage.
Staged Upload — A
linkfile written to storage for preview but persisted to the database only when "Save Changes" is pressed; cleaned up on cancel/replace. (audio_urland motivation media are persisted immediately and are not staged.)CardEditModalWrapper — Shared modal/fullscreen shell that hosts every card editor.
3. High-Level Architecture
System Diagram
Technologies Used
The Form Editor is implemented using the following technologies:
Next.js App Router (Next 16)
React
TypeScript
Supabase (Postgres, Storage, and Auth)
Zod
TailwindCSS
Sonner toast notifications
Supabase Storage (
public-assetsbucket)TipTap Editor (rich-text cards)
Monaco Editor (
@monaco-editor/react, Codeblock cards)@dnd-kit (drag-and-drop reordering)
Corrected in 2.0: the original guide listed Clerk Authentication, which is stale. The platform migrated to Supabase Auth (PRs #821/#822/#824/#828; route handlers use getCreatorAuthContext() in lib/auth/agencyOwnership.ts:674). The original guide also listed React Hook Form; the Form Editor itself does not use it (it is used by the Create Quest/Adventure wizards, e.g. app/creator/(create-content)/create-quest/page.tsx). It has been removed from the editor stack.
The Form Editor also reuses shared application services including authentication helpers, canvas synchronization utilities, media upload services, publishing validation, and shared Quest Editor contexts.
4. Detailed Design & Implementation
Data Model / Schema
quest_content_cards
The Form Editor stores each content block as an independent card inside the quest_content_cards table. Every card belongs to a specific quest and maintains its own content, ordering, and optional motivation attachment.
Relevant fields:
id(text, PK; defaultgen_random_uuid()::text)quest_id(FK →quests.id, ON DELETE CASCADE)type(text; see the card-type allow-list below)content(JSON/JSONB object)motivation(nullable JSON object)order_index(number)created_atupdated_at
This table predates the supabase/migrations folder, so there is no CREATE TABLE in the repo. What the migrations do prove: the primary key was converted from UUID to text (supabase/migrations/20260716_change_content_card_id_to_text.sql:6-7,19-20) and the quest_id FK was recreated ON DELETE CASCADE (supabase/migrations/20260603_fix_quest_fk_cascade_delete.sql:7-14). activity_submissions.content_card_id references this table as a text FK (20260716_change_content_card_id_to_text.sql:1-16), which is why deleting a card with submissions is blocked.
Card type allow-list (app/api/creator/quest-content-cards/create/route.ts:20):
text, activity, reflection, scenario, image, video, audio, file, link, codeblock, discussion, question
Example card:
{ "quest_id": "...", "type": "text", "content": { "title": "Introduction", "text": "<p>Welcome learners...</p>" }, "motivation": { "type": "text", "data": "Great job!", "title": "Stay Motivated!" }, "order_index": 1}
Motivation shape (written by app/api/creator/quest-content-cards/upload-motivation-media/route.ts:192-205): { type: "text" | "image" | "video" | "gif" | "audio", data?: string, file_url?: string, file_path?: string, title?: string }.
Updated in 2.0 (PR #680): motivation is a full pop-up feature — five media types, an editable pop-up title, and three source options (Upload Local / Via Link / From Assets). The original guide treated motivation as a single optional "motivation attachment".
quests
The Form Editor also uses the existing quests table to synchronize content with the Visual Canvas.
Relevant fields:
idcanvas_metadataquest_mode(enum:linear|exploration)publishing_status(enum:published,draft,archived,submitted,in_review,changes_requested,approved)
The canvas_metadata field is JSONB NOT NULL DEFAULT '{"nodes": [], "edges": []}'::jsonb with a structure check that nodes/edges are arrays (supabase/migrations/001_add_canvas_metadata.sql:26-50). At runtime it also carries quest_mode, folders, node_folder_ids, and folder_positions (shared/schemas/questSchema.ts:78-85).
canvas_metadata
Linear quests automatically synchronize Form Editor cards into the canvas_metadata JSON document.
{ "nodes": [], "edges": [], "folders": [], "quest_mode": "linear"}
API Specification
Content Card APIs
GET
/api/creator/quest-content-cards/list— Returns all content cards for a quest. For linear quests it extracts cards fromcanvas_metadatawhen available and merges them with the DB rows (app/api/creator/quest-content-cards/list/route.ts:30-68).POST
/api/creator/quest-content-cards/create— Creates a card and, for linear quests, re-syncs the canvas (create/route.ts:66-77). Returns HTTP 201.PUT
/api/creator/quest-content-cards/update— Updates a card'scontent,motivation, and/ororder_index; cleans up replaced storage objects and re-syncs the matching canvas node (update/route.ts:50-86,:88-124,:149-188).DELETE
/api/creator/quest-content-cards/delete— Deletes a card, removes its storage folderquests/{quest_id}/content-cards/{card_id}, and re-syncs the canvas. Returns HTTP 409HAS_SUBMISSIONSwhen learner submissions reference the card (delete/route.ts:85-106).PUT
/api/creator/quest-content-cards/reorder— Body{ quest_id, card_orders: [{ id, order_index }] }; updates ordering and re-syncs the canvas (reorder/route.ts:43-98).
Media APIs
POST
/api/creator/quest-content-nodes/get-upload-url— Mints a 60-second Supabase signed upload URL. Body{ quest_id, node_id, node_type: image|video|audio|file, file_ext, file_size, file_type?, file_name? }. Size limits: image 5 MB, audio 10 MB, video 25 MB, file 50 MB (get-upload-url/route.ts:57-68). Object pathquests/{node_id}/{safeName}.{file_ext}(:116-117). The browser then PUTs the file directly to storage (form-editor/page.tsx:459-472).DELETE
/api/creator/quest-content-nodes/delete-media— Deletes specificpathvalues (or the wholequests/{node_id}/folder) from storage (delete-media/route.ts:66-127).POST
/api/creator/quest-content-cards/upload-motivation-media—multipart/form-dataupload of a motivation file (image|video|gif|audio); stores atquests/{quest_id}/content-cards/{card_id}/motivation.{ext}and persists themotivationJSON (upload-motivation-media/route.ts:162-205).
Deprecated — do not use
POST
/api/creator/quest-content-cards/upload-media— removed in PR #790. The multipart route no longer exists (app/api/creator/quest-content-cards/upload-media/route.tsis absent). It was replaced by the signed-URL flow above because reverse-proxy body-size limits and storage RLS rejected large/valid multipart uploads. Code that used it now callsget-upload-url(form-editor/page.tsx:427-472). Any older doc or test referencingupload-mediais stale.
Canvas Synchronization APIs
GET
/api/creator/update-quest-canvas— Retrieves canvas metadata (+quest_mode,title) and resets invalid metadata to the default (update-quest-canvas/route.ts:28-88). The Form Editor uses this on load to determine quest mode (form-editor/page.tsx:3340).PUT
/api/creator/update-quest-canvas— Saves canvas metadata; for linear quests it upserts cards and deletes cards absent from the canvas, and reverts a published quest to draft when the change is meaningful (update-quest-canvas/route.ts:103-283).POST
/api/creator/convert-canvas-to-cards— Converts canvas nodes into Form Editor cards during AI curriculum imports. Only runs when the quest has no cards yet (convert-canvas-to-cards/route.ts:56-94).
Publishing APIs
POST
/api/creator/validate-quest-content— Validates quest content before publishing. Note: it validatescanvas_metadataviavalidateQuestContent, not thequest_content_cardsrows (validate-quest-content/route.ts:17-43).PATCH
/api/creator/update-quest— Updates quest fields includingpublishing_status. When publishing, it requires a title, an introduction, and at least one content card or canvas node (app/api/creator/(content)/update-quest/route.ts:57-102).
Supporting APIs
GET
/api/creator/(activity)/get-activity— Retrieves a reusable Question Hub activity and its questions for Activity (Quiz) cards (get-activity/route.ts:23-80).POST
/api/forum/create-post— Creates discussion forum posts; called on publish for Discussion nodes (hooks/quest-editor/useEditorActions.ts:83).
Logic & Workflows
Form Editor Initialization Workflow
Creator opens the Form Editor (
/quest-editor/[questID]/content/form-editor).The system retrieves the quest canvas metadata to determine the quest mode.
Exploration quests redirect to the Visual Canvas.
Linear quests retrieve all content cards (merged from canvas metadata and the DB).
Existing canvas metadata is synchronized with database records.
Cards are rendered in their saved order.
Content Editing Workflow
Creator selects a content card; the edit modal opens inside
CardEditModalWrapper.The creator may toggle fullscreen (button or Ctrl+Shift+E).
The creator modifies the content.
Local state updates immediately.
On "Save Changes", changes are submitted through the Update API.
Database records are updated and replaced storage objects are cleaned up.
Canvas metadata synchronizes automatically.
Success feedback is displayed.
Card Creation Workflow
Creator selects a content type.
Default card values are generated.
A new database record is created.
The card is inserted into the editor.
Canvas synchronization updates the corresponding node.
Card Reordering Workflow
Creator drags a card (or a folder) using @dnd-kit.
The new order is calculated.
Updated ordering is submitted to the Reorder API (folders are persisted first).
Database order indexes are updated.
Canvas nodes are regenerated in the new order.
Media Upload Workflow (signed URL)
Creator selects a file.
Client validates file type and size (
validateFileType).Client requests a signed upload URL.
Client PUTs the file directly to Supabase Storage.
Public URL is generated and shown in the card.
linkuploads are tracked as staged and only persisted on Save (removed on cancel/replace);audio_urlis persisted immediately.Existing media is replaced and the old object removed.
Motivation Workflow (PR #680)
Creator opens the motivation dialog for a card.
Creator picks a type (Text / Image / Video / GIF / Audio) and a source (Upload Local / Via Link / From Assets).
Text is saved through the Update API; media is uploaded through
upload-motivation-media, which persists themotivationJSON and re-syncs the canvas.On the learner side, the pop-up appears after the learner clicks Continue and is shown only once per card per playthrough; text/image/GIF auto-dismiss after 5 seconds.
Canvas Synchronization Workflow
Whenever a card is created, updated, deleted, or reordered:
The latest cards are retrieved.
Cards are converted into canvas nodes (
lib/canvas-sync/formToCanvas.ts→syncFormCardstoCanvas,mapCardDataToNodeData).Linear edges are regenerated.
Existing node positions are preserved.
Updated metadata is saved to the quest.
In the other direction, lib/canvas-sync/canvasToForm.ts (extractCardsFromCanvas, mapNodeDataToCardContent) converts canvas nodes back into cards when the Form Editor loads a linear quest, and update-quest-canvas upserts cards from the canvas.
Publishing Workflow
Creator selects Save Draft or Publish (
hooks/quest-editor/useEditorActions.ts).Canvas state is saved (
saveCanvasNow).validate-quest-contentexecutes for submitted/published statuses.On publish, a forum post is created for each Discussion node that has an internal thread and no
forumPostIdyet.Publishing status is updated through
PATCH /api/creator/update-quest.Success confirmation is displayed.
5. Infrastructure & Operations
Dependencies
Dependency | Notes |
|---|---|
Supabase | Stores quest content cards, canvas metadata, and uploaded assets |
Supabase Storage | Stores images, videos, audio files, and other uploaded media ( |
Supabase Auth | Authenticates creators and validates editing permissions ( |
Zod | Validates card content and API payloads before persistence |
@dnd-kit | Enables drag-and-drop card/folder reordering |
TipTap | Rich text editor for supported content cards |
Monaco Editor | Code editor used by Codeblock cards |
Sonner Toast | Displays success and error notifications |
Corrected in 2.0: Clerk Authentication was replaced by Supabase Auth. React Hook Form was removed (not used by the editor). Reminder that the per-card Background Audio tab is documented in the separate Creator Quest Card Background Audio guide.
The Form Editor also relies on shared Quest Editor contexts, publishing utilities, Visual Canvas synchronization services, and Question Hub integration.
Monitoring & Alerting
The Form Editor validates all creator input using shared Zod schemas and validateFileType before persisting changes.
Validation includes:
Required content validation
Supported media type validation (SVG is hard-rejected)
File size validation (image 5 MB, audio 10 MB, video 25 MB, file 50 MB)
Reflection minimum and maximum word limits
Discussion configuration validation
Question and activity validation
Scenario child card validation (one Question child maximum)
Publishing readiness validation
Current implementation relies on API responses and server logs to monitor:
Failed content saves
Failed media uploads
Canvas synchronization failures
Publishing validation failures
Database update failures
Storage upload failures
Forum post creation failures
Relevant server log strings for triage:
Source | Log |
|---|---|
|
|
|
|
|
|
|
|
Deployment Plan
Execute any required Supabase database migrations.
Verify Row Level Security (RLS) policies.
Ensure the
public-assetsStorage MIME allow-list includes the media types the editor accepts.Deploy updated Form Editor pages.
Deploy Quest Content Card API routes and
quest-content-nodesupload routes.Verify Supabase Storage configuration.
Verify Form Editor and Visual Canvas synchronization.
Verify Question Hub integration.
Verify publishing workflow.
Promote changes to staging after successful validation.
6. Testing & Quality Assurance
Test Strategy
Automated coverage
Area | Test file | Notes |
|---|---|---|
Form Editor create/edit/reorder |
| Creates a text card, edits the title, reloads and asserts persistence; drag-reorders cards and asserts order. |
Form ↔ Canvas sync |
| Edits a title in the Form Editor, saves, then opens the Visual Canvas. |
Motivation upload |
| Rejects SVG (disguised as |
Code-card XSS sandbox |
| Asserts the learner iframe sandbox excludes |
HTML sanitizer |
| Script/event-handler/protocol stripping and iframe sandbox enforcement. |
Canvas schemas |
| Schema-level validation of nodes/edges/metadata. |
Manual coverage
Content Cards: create, update, delete, duplicate, reorder, scenario child cards, activity card linking, motivation pop-ups, fullscreen editing.
Media: upload image/video/audio/document, replace media, motivation media upload, signed-URL failure paths.
Canvas Synchronization: Form → Canvas, Canvas → Form, node ordering preservation, position preservation.
Publishing: draft saving, publishing validation, discussion forum creation, publishing status updates.
Validation: required fields, reflection limits, question validation, activity validation, scenario validation.
Known Limitations
The Form Editor does not currently support collaborative real-time editing. (Still open.)
Content version history is not available. (Still open.)
Bulk editing multiple cards simultaneously is not supported. (Still open.)
Media editing is limited to replacing uploaded files. (Still open.)
Visual Canvas remains the primary editor for exploration quests. (Still open.)
Large quests with hundreds of cards may experience slower synchronization due to full canvas regeneration. (Still open.)
Scenario cards currently support only a single Question Card as a child. (Still open; enforced at
form-editor/page.tsx:2287-2293.)validate-quest-contentvalidates canvas metadata only, so validation quality depends on form↔canvas sync being current. (Documented in 2.0.)The motivation upload route (
upload-motivation-media) does not enforce a server-side file-size limit; only the client and the general upload guard apply. (Documented in 2.0.)No automated tests cover
lib/canvas-sync/*,MotivationPopup, orCardEditModalWrapper. (Documented in 2.0.)
7. Maintenance & Support
Troubleshooting
Cards do not appear
Verify the quest exists.
Verify the creator has permission to edit the quest.
Verify the List Content Cards API returns data.
Verify the quest is using Linear Mode.
Media upload fails
Verify file size limits (image 5 MB, audio 10 MB, video 25 MB, file 50 MB).
Verify the file type is allow-listed (SVG is rejected).
Verify the
public-assetsStorage MIME allow-list is applied.Verify the
get-upload-urlendpoint responds and the direct storage PUT succeeds.Verify no
400 "File is too large"or400 "Invalid file path"is returned.
Canvas is not synchronized
Verify the quest is configured as a Linear Quest.
Verify canvas metadata exists.
Verify synchronization completed successfully (check
[Form Canvas Sync]logs).Verify no API validation errors occurred.
Publishing fails
Verify all required cards are completed.
Verify
validate-quest-contentsucceeds (it validates canvas metadata).Verify the quest has a title, an introduction, and at least one card/node.
Verify discussion cards have valid configurations; forum failures are surfaced as warnings.
Verify Question Hub activities remain valid.
Question Hub activity cannot be selected
Verify the selected activity exists.
Verify the activity has not been archived.
Verify the Question Hub API returns the activity.
Scenario child cards do not save
Verify the Scenario Card exists.
Verify child card validation succeeds.
Verify only one Question child exists per scenario.
Verify synchronization completed successfully.
Motivation pop-up does not show for learners
Verify
quest.motivational_popupis enabled.Verify the card's
motivationJSON is populated.Verify the pop-up is only expected after clicking Continue, once per card per playthrough.
Changelog
v1.0 (February 2026)
Initial implementation of the Form Editor supporting:
Linear quest authoring
Content card management
Scenario child cards
Media uploads
Question Hub integration
Automatic Visual Canvas synchronization
Publishing validation
Discussion forum integration
v2.0 (2026-09-30) — documented by Patrick Babala
Signed-URL upload pipeline (PR #790): removed the multipart
upload-mediaroute; addedquest-content-nodes/get-upload-url+ direct storage PUT +delete-media.Motivation pop-ups (PR #680): five media types, editable title, and three source options (Upload Local / Via Link / From Assets).
Fullscreen card editors (PR #776):
CardEditModalWrapperadds focus mode with Ctrl+Shift+E.Responsive + dialog fixes (PR #788): viewport-safe dialogs and ≥44 px touch targets.
Activity/Codeblock fixes (PR #708): outline preview fields, custom-mode question counts, and quiz tab-state fixes.
Learner Code-card XSS sandbox (PR #870): creator HTML renders in a sandboxed iframe without
allow-same-origin.Corrections: Clerk → Supabase Auth; card-type list refreshed; React Hook Form removed; issue sub-issues and PR links added.
Document Version
2.0 – Updated by Patrick Babala, 2026-09-30. Overhauled for the current codebase: signed-URL uploads, motivation pop-ups, fullscreen card editors, Supabase Auth, refreshed card types, corrected APIs/references, and a redrawn layered architecture diagram.
1.1 – Published, Initial internal technical guide for the Form Editor, July 2026
1.0 – Draft, Feature pushed to development server after initial review, February 2026