Form Editor

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 link file written to storage for preview but persisted to the database only when "Save Changes" is pressed; cleaned up on cancel/replace. (audio_url and 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-assets bucket)

  • 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; default gen_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_at

  • updated_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:

  • id

  • canvas_metadata

  • quest_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 from canvas_metadata when 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's content, motivation, and/or order_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 folder quests/{quest_id}/content-cards/{card_id}, and re-syncs the canvas. Returns HTTP 409 HAS_SUBMISSIONS when 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 path quests/{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 specific path values (or the whole quests/{node_id}/ folder) from storage (delete-media/route.ts:66-127).

  • POST /api/creator/quest-content-cards/upload-motivation-media — multipart/form-data upload of a motivation file (image|video|gif|audio); stores at quests/{quest_id}/content-cards/{card_id}/motivation.{ext} and persists the motivation JSON (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.ts is 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 calls get-upload-url (form-editor/page.tsx:427-472). Any older doc or test referencing upload-media is 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 validates canvas_metadata via validateQuestContent, not the quest_content_cards rows (validate-quest-content/route.ts:17-43).

  • PATCH /api/creator/update-quest — Updates quest fields including publishing_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

  1. Creator opens the Form Editor (/quest-editor/[questID]/content/form-editor).

  2. The system retrieves the quest canvas metadata to determine the quest mode.

  3. Exploration quests redirect to the Visual Canvas.

  4. Linear quests retrieve all content cards (merged from canvas metadata and the DB).

  5. Existing canvas metadata is synchronized with database records.

  6. Cards are rendered in their saved order.

Content Editing Workflow

  1. Creator selects a content card; the edit modal opens inside CardEditModalWrapper.

  2. The creator may toggle fullscreen (button or Ctrl+Shift+E).

  3. The creator modifies the content.

  4. Local state updates immediately.

  5. On "Save Changes", changes are submitted through the Update API.

  6. Database records are updated and replaced storage objects are cleaned up.

  7. Canvas metadata synchronizes automatically.

  8. Success feedback is displayed.

Card Creation Workflow

  1. Creator selects a content type.

  2. Default card values are generated.

  3. A new database record is created.

  4. The card is inserted into the editor.

  5. Canvas synchronization updates the corresponding node.

Card Reordering Workflow

  1. Creator drags a card (or a folder) using @dnd-kit.

  2. The new order is calculated.

  3. Updated ordering is submitted to the Reorder API (folders are persisted first).

  4. Database order indexes are updated.

  5. Canvas nodes are regenerated in the new order.

Media Upload Workflow (signed URL)

  1. Creator selects a file.

  2. Client validates file type and size (validateFileType).

  3. Client requests a signed upload URL.

  4. Client PUTs the file directly to Supabase Storage.

  5. Public URL is generated and shown in the card.

  6. link uploads are tracked as staged and only persisted on Save (removed on cancel/replace); audio_url is persisted immediately.

  7. Existing media is replaced and the old object removed.

Motivation Workflow (PR #680)

  1. Creator opens the motivation dialog for a card.

  2. Creator picks a type (Text / Image / Video / GIF / Audio) and a source (Upload Local / Via Link / From Assets).

  3. Text is saved through the Update API; media is uploaded through upload-motivation-media, which persists the motivation JSON and re-syncs the canvas.

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

  1. Creator selects Save Draft or Publish (hooks/quest-editor/useEditorActions.ts).

  2. Canvas state is saved (saveCanvasNow).

  3. validate-quest-content executes for submitted/published statuses.

  4. On publish, a forum post is created for each Discussion node that has an internal thread and no forumPostId yet.

  5. Publishing status is updated through PATCH /api/creator/update-quest.

  6. 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 (public-assets bucket)

Supabase Auth

Authenticates creators and validates editing permissions (getCreatorAuthContext, verifyAgencyResourceOwnership)

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

app/api/creator/quest-content-nodes/get-upload-url/route.ts

Failed to create upload URL, Failed to generate upload URL

app/api/creator/quest-content-nodes/delete-media/route.ts

Failed to delete media

app/api/creator/quest-content-cards/update/route.ts

[Form Canvas Sync] failures

hooks/quest-editor/useEditorActions.ts

Forum errors:, Canvas save failed:

Deployment Plan

  1. Execute any required Supabase database migrations.

  2. Verify Row Level Security (RLS) policies.

  3. Ensure the public-assets Storage MIME allow-list includes the media types the editor accepts.

  4. Deploy updated Form Editor pages.

  5. Deploy Quest Content Card API routes and quest-content-nodes upload routes.

  6. Verify Supabase Storage configuration.

  7. Verify Form Editor and Visual Canvas synchronization.

  8. Verify Question Hub integration.

  9. Verify publishing workflow.

  10. Promote changes to staging after successful validation.


6. Testing & Quality Assurance

Test Strategy

Automated coverage

Area

Test file

Notes

Form Editor create/edit/reorder

tests/e2e/creator/form-editor.spec.ts

Creates a text card, edits the title, reloads and asserts persistence; drag-reorders cards and asserts order.

Form ↔ Canvas sync

tests/e2e/creator/visual-canvas.spec.ts

Edits a title in the Form Editor, saves, then opens the Visual Canvas.

Motivation upload

tests/api/creator-motivation-upload.test.ts

Rejects SVG (disguised as .png), stores valid PNG/MP4 with pinned MIME types.

Code-card XSS sandbox

tests/unit/codeblock-card-sandbox.test.tsx

Asserts the learner iframe sandbox excludes allow-same-origin and strips scripts.

HTML sanitizer

tests/unit/sanitize-html.test.ts

Script/event-handler/protocol stripping and iframe sandbox enforcement.

Canvas schemas

tests/creator/utils/canvas-schemas.test.ts

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-content validates 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, or CardEditModalWrapper. (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-assets Storage MIME allow-list is applied.

  • Verify the get-upload-url endpoint responds and the direct storage PUT succeeds.

  • Verify no 400 "File is too large" or 400 "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-content succeeds (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_popup is enabled.

  • Verify the card's motivation JSON 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-media route; added quest-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): CardEditModalWrapper adds 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


Was this article helpful?