Embed HTML Content in Quest Nodes

  1. Overview
  2. Hand Off Documentation
  3. Develop (Content Production)
  4. Embed HTML Content in Quest Nodes

Feature Owner: Joshua Uriel Tribiana
Module: Develop (Content Production)
Priority: P1
Week 7 Sprint: Implemented in Current Codebase
Date: 06-30-2026

EXECUTIVE SUMMARY

What is this feature?
Embed HTML Content in Quest Nodes enables creators to add rich, interactive HTML directly into quest nodes. Instead of being limited to simple text or media blocks, creators can author custom layouts, embedded media, forms, SVGs, and lightweight interactive experiences inside a dedicated code/html node.

Why does it matter?
This feature unlocks a much broader range of instructional experiences. Creators can build interactive explainer blocks, embedded videos, forms, tabs, accordions, and other rich content without needing to leave the quest editor or build custom frontend components for each case.

What’s the MVP scope?
The current implementation includes:

  • A custom code/html node in the quest editor

  • HTML input editing with preview support

  • Safe sanitization of embedded HTML for learner rendering

  • Support for forms, iframes, scripts, SVGs, and embedded media

  • Built-in starter templates for common embed patterns

1. USER PAIN POINT & SOLUTION

Current State (Without Feature)

Creators are constrained by the built-in node types and cannot easily embed richer web-based content directly inside a quest. This makes it difficult to create interactive lessons or reuse content from external tools.

Pain Point

  • Emotional: Frustration when a creator wants richer, more expressive content than the default node library allows

  • Functional: No flexible way to embed custom HTML inside a quest node

  • Business Impact: Limited authoring flexibility and slower content production

Future State (With Feature)

Creators can place rich HTML-based content directly into nodes, preview it in the editor, and have it render safely in the learner experience.

Marketing Hook

“Bring your content to life with embedded HTML, interactive widgets, and rich media directly inside your quest nodes.”

2. CODEBASE ASSESSMENT

Current Implementation Status

The HTML embedding capability is already implemented as a custom Code node flow in the quest editor and learner renderer.

Primary Files

Current Behavior Summary

  • Creators can write or paste HTML into a code node

  • The editor offers a live preview of the rendered HTML

  • The content is sanitized before rendering in the learner experience

  • The implementation allows safe iframes, forms, media, and script-based interactions

  • Built-in templates help creators get started quickly

Strengths Already Present

  • Strong support for rich, interactive authoring experiences

  • Security hardening is already built in via HTML sanitization

  • The same node model is usable in both editor preview and learner playback

  • Templates accelerate common use cases

Gaps / Hardening Opportunities

  • The implementation currently trusts a relatively broad set of supported tags and attributes

  • Script execution is enabled, so further hardening may be needed depending on future content policies

  • The experience is still a code-first authoring tool, not a no-code widget builder

3. 4D FRAMEWORK MAPPING

Diagnose

Creators need a way to add rich, reusable content beyond standard node types, especially when they want to embed external media or interactive content inside a quest.

Design

The feature uses a dedicated code/html node that supports direct authoring, preview, and safe rendering. It preserves the editor’s flexibility while controlling risk.

Develop

Creators can author content directly, insert templates, and preview the result before publishing.

Deliver

The embedded HTML renders for learners in a controlled, safe way that preserves the intended experience.

4. USER FLOWS

Entry Point

A creator is editing a quest and adds a Code node to the canvas.

Success Criteria

  • The creator can insert HTML content into the node

  • Preview renders the content as expected

  • The learner sees the content safely and correctly

Main Flow (Happy Path)

  1. Creator adds a Code node to the canvas

  2. Creator pastes or writes HTML content into the editor

  3. Creator uses the preview mode to inspect the rendered output

  4. Creator saves the quest and publishes it

  5. Learners view the rendered HTML-based node in the quest player

Edge Cases

  • Unsafe HTML: The sanitizer strips or removes disallowed tags and attributes

  • Ifsames: Allowed only when the sanitization policy permits them

  • Scripts: Execution is supported in preview/renderer, but only through the controlled execution pipeline

  • Empty content: The UI shows a placeholder message rather than a broken state

Decision Points

  • IF the content is safe → it renders in preview and learner view

  • IF the content contains disallowed markup → it is sanitized or removed

  • IF the creator uses a template → the content is inserted automatically into the editor

5. INFORMATION ARCHITECTURE

Primary Information (Always visible)

  • The HTML/code content itself

  • Preview output

  • Template selector and status indicators

Secondary Information

  • Autosave status

  • Node label and type metadata

  • Fullscreen preview mode

Tertiary Information (Hidden until needed)

  • Sanitization logic and script execution pipeline

  • Internal template definitions and parser behavior

Actions

Primary CTA:

  • Preview HTML content

Secondary Actions:

  • Insert template

  • Copy to clipboard

  • Toggle fullscreen

6. WIREFRAMES

No dedicated new screen is necessary. The feature lives inside the existing node editor surface.

Key Screens:

  1. Code node editor with HTML input

  2. Preview pane rendering the authored HTML

  3. Learner view of the rendered content

Annotations:

  • The editor is code-first with a visual preview

  • The learner experience is read-only and embedded within the quest flow

7. WIREFLOWS

                          CREATOR (Quest Editor)
 
+----------------------------------+
| Creator edits in Monaco Editor   |
+----------------------------------+
                |
                v
+----------------------------------+
| CodeNode.tsx                     |
+----------------------------------+
                |
      (HTML content)
                |
                v
+----------------------------------+
| Debounced Save                   |
+----------------------------------+
                |
                v
+----------------------------------------------+
| PUT /api/creator/update-quest-canvas         |
+----------------------------------------------+
                |
                v
 
                      WYZQUESTS BACKEND
 
+----------------------------------+
| API Route Handler                |
+----------------------------------+
                |
                v
+----------------------------------+
| HTML Sanitization Service        |
+----------------------------------+
                |
                v
+----------------------------------+
| DOMPurify                        |
| - Sanitize HTML                  |
| - Return clean HTML              |
+----------------------------------+
                |
                v
+----------------------------------+
| Update canvas_metadata           |
+----------------------------------+
                |
                v
+----------------------------------+
| Supabase Database                |
+----------------------------------+
 
 
                        LEARNER (Quest Player)
 
+----------------------------------+
| Player loads quest               |
+----------------------------------+
                |
                v
+----------------------------------+
| Fetch canvas_metadata            |
+----------------------------------+
                |
                v
+----------------------------------+
| Render HTML Node                 |
+----------------------------------+
                |
                | Render clean HTML
                v
+----------------------------------------------+
| Sandboxed <iframe srcdoc="...">              |
+----------------------------------------------+

8. PROTOTYPE

Excluded — feature is fully implemented

How to test:

  1. Add a Code node to a quest

  2. Paste a small HTML block or select a template

  3. Preview the content in the editor

  4. Publish the quest and verify the learner view renders it correctly

9. DATA MODEL

Core Payload

The node stores the authored HTML in the codeContent field in the node schema:

codeContent: string;

Supporting Metadata

The schema also includes optional node metadata such as:

  • label

  • isStart / isEnd

  • quest_mode

  • lastSavedAt

  • isArchived

Why it matters

The parser, renderer, preview, and persistence layer all operate around this content field, so it is the primary contract for the feature.

10. COMPONENT RESPONSIBILITIES

CodeNode

Responsibilities:

  • Manage editor state

  • Handle autosave and updates

  • Render the preview pane

  • Support templates and clipboard actions

CodeblockRenderer

Responsibilities:

  • Receive the rendered HTML payload

  • Sanitize and execute it safely for learner playback

  • Render it inside the content card

sanitize-html.ts

Responsibilities:

  • Remove unsafe tags and attributes

  • Allow safe iframe/media/form/SVG usage

  • Provide a security gate for the feature

execute-html-with-scripts.ts

Responsibilities:

  • Execute inline and external scripts inside the preview/renderer container

  • Support interaction-heavy templates such as accordions or tabs

11. SECURITY MODEL

What is allowed

  • Safe semantic markup

  • Embedded media such as images, video, and audio

  • Iframes when allowed by the sanitizer policy

  • Basic interactive form elements

  • SVG markup and simple styles

What is restricted

  • Dangerous URLs such as javascript: or data:

  • Event handlers such as onclick

  • Unsafely injected script tags when script execution is not desired

Why this matters

The HTML content is rendered inside the learner experience and therefore needs a controlled rendering boundary to prevent XSS and unsafe embeds.

12. TEMPLATE SYSTEM

Current Template Coverage

The built-in templates include examples for:

  • Iframe embeds

  • HTML5 video players

  • Contact forms

  • Survey forms

  • Accordions

  • Tabs

How Templates Work

Templates are stored in lib/utils/html-templates.ts and inserted into the editor content when a creator selects one.

Value of Templates

Templates reduce authoring friction and demonstrate the types of experiences this node can support.

13. DATA REQUIREMENTS

Frontend Needs

The editor needs:

  • A place to hold the HTML content

  • A preview path that renders it immediately

  • A save path that persists the content with the node data

Learner Needs

The learner renderer needs:

  • The content payload from the node data

  • A sanitizer and execution pipeline that preserves interactivity while controlling risk

14. PERFORMANCE CONSIDERATIONS

Editor Responsiveness

The preview is updated after content changes and uses a controlled re-render path. The autosave timer also prevents excessive writes during editing.

Learner Rendering

The renderer sanitizes and executes the content once per content change, which is acceptable for the current node model.

Risk Tradeoff

Allowing script execution can make some templates more dynamic, but it also increases the importance of maintaining strict sanitization protections.

15. TESTING CHECKLIST

Happy Path

  • A creator can add a Code node and enter custom HTML

  • Preview renders the HTML as expected

  • Learners can view the HTML content in the quest player

  • A built-in template inserts correctly into the editor

Edge Cases

  • Unsafe HTML is sanitized or stripped

  • Iframe or media content renders in a controlled way

  • Empty content shows a placeholder rather than crashing

  • Script-based templates render without breaking the surrounding UI

16. OPEN QUESTIONS

For Frontend

  • Should the editor eventually offer a more visual, no-code widget builder for common embed patterns?

  • Should creators be able to toggle whether scripts are allowed per node?

For Security

  • Should the sanitization policy be tightened further for production content governance?

  • Should there be explicit content-approval or moderation rules for third-party embeds?

17. OUT OF SCOPE (v1.1+)

Not included in the current implementation:

  • A true WYSIWYG HTML builder experience

  • Per-node allowlist settings for scripts or third-party domains

  • A full content moderation pipeline for foreign embeds

18. SUCCESS METRICS

How will we know this feature is working well?

  • Creators can author richer content without leaving the editor

  • Learners see the intended HTML-based experience without broken layout or unsafe output

  • Templates are used successfully to accelerate content creation

19. DEPENDENCIES

This feature depends on:

  • The node schema and canvas node system

  • The learner content renderer pipeline

  • The shared sanitization and script execution utilities

These features depend on this:

  • Rich content authoring in quests

  • Interactive learning experiences that go beyond basic text and media nodes

20. TIMELINE & OWNERSHIP

Implementation Ownership

  • Owner: Joshua Uriel Tribiana

  • QA: Patrick Babala

Written by Uriel Last updated June 30, 2026
Was this article helpful?