Embed HTML Content in Quest Nodes

Feature Owner (original Hand-Off): Joshua Uriel Tribiana
Updated by: Patrick Babala — author of PR #870 (learner Code-block sandbox / XSS fix)
QA: Patrick Babala (original QA); update review by Christian Denzon (@cdnzn) (reviewed PR #870)
Module: Develop (Content Production)
Priority: P1
Sprint: Implemented in current codebase
Date: 2026-09-30 (original 06-30-2026)
Status: Implemented and live (Hand-Off updated to v2.0)

Issue: [3.9] Embed HTML Custom Node — no numbered parent issue was recorded in the original Hand-Off.

PRs covered by this revision: #398 original Code/HTML node; #666 sanitisation + sandbox; #870 learner code-block XSS fix; #884 sanitizer/sandbox hardening.

Related, separate guides: Visual Canvas ([2.2]) owns canvas node placement, fullscreen, language detection, and the 50,000-character limit (PRs #708/#712); Form Editor ([2.1]) owns the codeblock content card. Link-node provider embeds (PR #798) are a separate feature.

Companion doc: Internal Technical Guide — Internal-Technical-Guide-Embed-HTML-Content-in-Quest-Nodes.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?
Embed HTML Content in Quest Nodes lets creators add rich, custom HTML/CSS directly into a quest node. Instead of being limited to text or media blocks, creators author custom layouts, embedded media, forms, SVGs, and lightweight interactive content inside a dedicated Code Block node (type: Code), preview it in the editor, and have it rendered safely to learners.

Why does it matter?
It unlocks a much broader range of instructional experiences — interactive explainers, embedded media, tabs, accordions, and forms — without needing a custom frontend component for each case.

What's the MVP scope?

  • A Code Block node in the Visual Canvas editor.

  • Monaco-based HTML editing with a live preview.

  • 9 built-in starter templates.

  • A 50,000-character content limit.

  • Sanitized, sandboxed learner rendering (no same-origin access).

Corrected in 2.0: the original scope claimed "safe sanitization … for learner rendering" performed server-side and "support for … scripts". Shipped behaviour is: sanitization is client-side at render; the learner never executes creator scripts; the server only enforces the length limit.


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, making interactive lessons or reuse of external tools difficult.

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 place rich HTML-based content directly into nodes, preview it in the editor, and have it render safely (sanitized and sandboxed) 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 capability is shipped as the custom Code Block node in the Visual Canvas and hardened across PRs #666, #870, and #884.

Primary Files

  • components/quest-editor/visual-canvas/nodes/CodeNode.tsx — creator editor UI (Monaco, preview, templates, autosave, 50k guard, fullscreen).

  • components/learner/renderers/SandboxedHtmlFrame.tsx — the learner frame: builds srcDoc, sanitizes, and renders in a sandboxed iframe.

  • components/learner/renderers/CodeblockRenderer.tsx — learner canvas-node view of the code with a Preview toggle.

  • components/learner/quest-detail/content-cards/CodeblockCardContent.tsx — learner content-card renderer for codeblock cards.

  • lib/utils/sanitize-html.ts — the allow-list sanitizer and sandbox constants.

  • lib/utils/execute-html-with-scripts.ts — executes scripts for the creator preview only.

  • lib/utils/html-templates.ts — starter templates.

  • lib/schemas/nodes.schema.ts — defines codeContent (max 50,000).

Corrected in 2.0: the original list linked these files to https://stackedit.io/<path> (placeholder links) and omitted SandboxedHtmlFrame.tsx and CodeblockCardContent.tsx. Links removed; real paths listed above. Deep detail is in the ITG section 4 (Key Files).

Current Behavior Summary

  • Creators write or paste HTML into a Code Block node and see a live preview.

  • The editor offers templates, copy-to-clipboard, autosave, and fullscreen.

  • Content is saved as authored; the save API rejects content over 50,000 characters (HTTP 400).

  • Learners see the content sanitized (scripts and event handlers removed) inside a sandboxed iframe with no same-origin access.

  • The content is also mirrored into the linear-mode codeblock content card via canvas/form sync.

Strengths Already Present

  • Rich, interactive authoring inside the existing editor.

  • Security hardening built in: allow-list sanitizer + sandboxed, same-origin-less frame.

  • One node model serves both editor preview and learner playback.

  • Templates accelerate common embeds.

Gaps / Hardening Opportunities

  • Creator scripts do not run for learners. Inline <script> and on* handlers are stripped; only the editor preview executes them.

  • No CSP / security headers are set anywhere (the original plan's CSP was never implemented).

  • No server-side sanitization or telemetry; raw HTML is stored as authored and sanitized only at render.

  • The window.wyzQuests branching API is unwired — the Code node advertises it but nothing installs it.

  • Theme tokens are a subset of app CSS variables.

  • Still code-first, 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 external media or interactive content inside a quest.

Design
A dedicated Code Block node supports direct authoring, live preview, and safe rendering. It preserves editing flexibility while controlling risk through sanitization and a sandbox boundary.

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

Deliver
The content renders for learners in a controlled, sanitized, sandboxed frame that preserves the intended experience.


4. USER FLOWS

Entry Point
A creator editing a quest adds a Code Block node to the Visual Canvas.

Success Criteria

  • The creator can insert HTML content into the node.

  • The editor preview renders the content as expected.

  • The learner sees the content safely and correctly (sanitized, sandboxed).

Main Flow (Happy Path)

  1. Creator adds a Code Block node to the canvas.

  2. Creator pastes or writes HTML into the Monaco editor.

  3. Creator uses Preview to inspect the rendered output (scripts run here).

  4. Auto-save persists the node; the server enforces the 50,000-character limit.

  5. Creator saves/publishes the quest.

  6. Learners view the sanitized content (scripts stripped) inside a sandboxed frame.

Edge Cases

  • Unsafe HTML: the sanitizer strips disallowed tags and attributes.

  • Iframes: allowed, but every iframe is forced to a safe sandbox.

  • Scripts: executed in the creator preview only; stripped for learners — this is intended.

  • Empty content: the UI shows a placeholder rather than a broken state.

  • Over 50,000 characters: the client pauses auto-save and the server rejects the save with HTTP 400.

Corrected in 2.0: the original edge cases said scripts "execute in preview/renderer through the controlled execution pipeline". The learner renderer does not execute them.

Decision Points

  • IF the content is safe → it renders in preview and for learners.

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

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

  • IF codeContent exceeds 50,000 characters → the save is rejected (HTTP 400).


5. INFORMATION ARCHITECTURE

Primary Information (Always visible)

  • The Code Block content itself (Monaco editor).

  • The Preview output.

  • Template selector and status indicators.

Secondary Information

  • Autosave status.

  • Node label and type metadata.

  • Fullscreen mode.

Tertiary Information (Hidden until needed)

  • Sanitization rules and the sandbox boundary (see ITG section 4).

  • Internal template definitions.

Actions

  • Primary CTA: Preview HTML content.

  • Secondary actions: Insert template, Copy to clipboard, Toggle fullscreen.


6. WIREFRAMES

No dedicated new screen is required; the feature lives inside the existing node editor surface.

Key screens:

  • Code Block node editor with HTML input and Preview.

  • Learner view of the rendered content.

Annotations:

  • The editor is code-first with a visual preview.

  • The learner experience is read-only, sanitized, and sandboxed within the quest flow.


7. WIREFLOWS

CREATOR (Quest Editor)
+----------------------------------+
| Creator edits in Monaco Editor |
+----------------------------------+
|
v
+----------------------------------+
| CodeNode.tsx (HTML content) |
| Preview: sanitize(allowScripts= |
| true) + executeHtmlWithScripts |
+----------------------------------+
|
v (client autosave)
+----------------------------------------------+
| PUT /api/creator/update-quest-canvas |
| - zod validate |
| - 50k length guard -> HTTP 400 |
| - NO sanitization (stored as authored) |
+----------------------------------------------+
|
v
+----------------------------------+
| Supabase: quests.canvas_metadata |
+----------------------------------+
 
== Quest Published ==
 
LEARNER (Quest Player)
+----------------------------------+
| Player loads quest |
+----------------------------------+
|
v
+----------------------------------+
| CodeblockRenderer / |
| CodeblockCardContent |
+----------------------------------+
|
v
+----------------------------------------------+
| SandboxedHtmlFrame |
| - sanitizeHtml(html, allowScripts:false) |
| - iframe srcdoc, sandbox w/o allow-same- |
| origin (creator scripts stripped) |
+----------------------------------------------+

Corrected in 2.0: the original wireflow inserted an "HTML Sanitization Service → DOMPurify" step in the backend before saving. That step does not exist; sanitization happens in the learner frame at render. See the layered diagram in the ITG section 3.


8. PROTOTYPE

Excluded — the feature is fully implemented.

How to test:

  1. Add a Code Block node to a quest.

  2. Paste a small HTML block or select a template.

  3. Preview it in the editor (interactive/scripted content works here).

  4. Save and publish the quest.

  5. Verify the learner view: content renders, styles are isolated, and any <script>/on* is inert.


9. DATA MODEL

Core Payload

The node stores the authored HTML in codeContent:

codeContent: string; // max 50,000 characters

Supporting Metadata

Optional node metadata such as label, isStart/isEnd, quest_mode, lastSavedAt, and isArchived travels with the node.

Why it matters

codeContent is the primary contract for the feature: the editor, persistence, canvas/form sync, and learner renderer all operate around it. No new database tables were added.

Corrected in 2.0: the original described codeContent as sanitized. It is stored exactly as authored. Full schema detail is in the ITG section 4 (Data Model/Schema).


10. COMPONENT RESPONSIBILITIES

  • CodeNode — creator UI: manages editor state, autosave, preview (executes scripts), templates, clipboard, fullscreen, and the 50k guard.

  • SandboxedHtmlFrame — learner frame: builds the srcDoc, sanitizes with allowScripts: false, and renders a sandboxed iframe with no same-origin access; copies a safe subset of theme tokens.

  • CodeblockRenderer — learner canvas-node view: shows the code with detected language and a Preview toggle that mounts SandboxedHtmlFrame.

  • CodeblockCardContent — learner content-card view: renders card.content.html through SandboxedHtmlFrame.

  • sanitize-html.ts — security gate: allow-list of tags/attributes, dangerous-protocol stripping, forced iframe sandbox.

  • execute-html-with-scripts.ts — preview-only script execution helper.

Corrected in 2.0: the original said CodeblockRenderer "sanitizes and executes embedded HTML for the learner view". It does not execute scripts; it delegates to SandboxedHtmlFrame, which strips them.


11. SECURITY MODEL

What is allowed

  • Safe semantic markup.

  • Embedded media (images, video, audio).

  • Iframes (always re-sandboxed by the sanitizer).

  • Basic form elements.

  • SVG markup and simple styles.

What is restricted

  • Dangerous URLs (javascript:, vbscript:, unsafe data:) on href, src, action, poster.

  • Event handlers (onclick, onerror, …).

  • Creator <script> tags and inline scripts for learners (they are removed before the frame).

  • Access to the parent DOM, cookies, localStorage, or the app origin (sandbox omits allow-same-origin).

Why this matters

The HTML is rendered inside the learner experience, so a controlled rendering boundary prevents XSS and unsafe embeds. The boundary is the allow-list sanitizer plus the sandboxed, same-origin-less iframe.

Corrected in 2.0: the original listed "unsafely injected script tags when script execution is not desired" as a restriction while also describing script execution as enabled. The shipped policy is unambiguous: scripts run only in the creator preview; learner content is script-free. There is still no CSP header and no server-side sanitization.


12. TEMPLATE SYSTEM

Current Template Coverage

The 9 built-in templates cover: Iframe Embed, HTML5 Video, Simple Contact Form, Survey Form, Accordion, Tabs, Timeline, Progress Bar, and Info Box.

How Templates Work

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

Value of Templates

They reduce authoring friction and demonstrate the kinds of experiences the node supports. The Accordion and Tabs templates intentionally ship no scripts (CSS-only) so they still work inside the learner frame.

Corrected in 2.0: the original listed 6 templates and did not note the script-free design of the interactive templates.


13. DATA REQUIREMENTS

Frontend Needs

  • A place to hold the HTML content (Monaco + node data).

  • A preview path that renders it immediately (executes scripts).

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

Learner Needs

  • The content payload from the node data.

  • A sanitizer that removes scripts/handlers and a sandboxed frame that isolates the content.

Corrected in 2.0: the original said the learner needs "an execution pipeline that preserves interactivity". The learner path preserves CSS/markup interactivity (e.g., details, checked, third-party iframe scripts), not creator scripts.


14. PERFORMANCE CONSIDERATIONS

Editor Responsiveness
Preview updates after content changes; a 5-second autosave timer and canvas-level debounce prevent excessive writes.

Learner Rendering
The renderer sanitizes the content and builds a srcDoc string; this runs once per content render and is acceptable for the current node model.

Risk Tradeoff
The original tradeoff (script execution vs. sanitization) no longer applies to learners: executing scripts only in the editor preview, while stripping them for learners and omitting allow-same-origin, is the deliberate risk-reduction choice.


15. TESTING CHECKLIST

Automated coverage

  • Unit — tests/unit/sanitize-html.test.ts: <script>/handler stripping, script-content removal, allowScripts opt-in, forced iframe sandbox, dangerous protocols, wrapper unwrapping, server fallback, LEARNER_CONTENT_SANDBOX has no allow-same-origin, script-free templates.

  • Unit — tests/unit/codeblock-card-sandbox.test.tsx: card content renders in a sandboxed iframe; a <script> probe never reaches srcdoc or the app document.

  • E2E — tests/e2e/creator/embed-html.spec.ts: QA-049 (add node, author HTML, Monaco + live preview + counter + autosave) and QA-050 (XSS payload does not fire; no javascript: iframe).

Happy Path

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

  • Preview renders the HTML as expected (scripts included).

  • Learners can view the content in the quest player.

  • A built-in template inserts correctly.

Edge Cases

  • Unsafe HTML is sanitized or stripped.

  • Iframe/media content renders in a controlled way.

  • Empty content shows a placeholder rather than crashing.

  • Creator scripts are inert in the learner view (by design).

  • Content over 50,000 characters is rejected on save (HTTP 400).

Corrected in 2.0: the original checklist assumed scripts render for learners. That expectation is now inverted.


16. OPEN QUESTIONS

For Frontend

  • Resolved in 2.0: "Should creators be able to toggle whether scripts are allowed per node?" — Decision made: no per-node toggle. Scripts run only in the creator preview and are always stripped for learners.

  • Still open: Should the editor eventually offer a no-code widget builder for common embed patterns?

For Security

  • Partially resolved in 2.0: "Should the sanitization policy be tightened further?" — Hardened in PRs #666, #870, and #884 (allow-list, forced iframe sandbox, same-origin-less learner frame). Ongoing tightening is reasonable but no CSP/security-header layer exists yet.

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


17. OUT OF SCOPE (v1.1+)

Still deferred (unchanged from the original):

  • A true WYSIWYG HTML builder experience.

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

  • A full content-moderation pipeline for foreign embeds.

Note (2.0): the CSP/security-header layer described in the ITG's original plan is also not implemented and should be tracked separately if pursued.


18. SUCCESS METRICS

  • Creators author richer content without leaving the editor.

  • Learners see the intended content 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 (SandboxedHtmlFrame).

  • The shared sanitization utility (sanitize-html.ts).

  • The canvas save API (update-quest-canvas).

These features depend on this

  • Rich content authoring in quests.

  • Interactive learning experiences beyond basic text and media nodes.


20. TIMELINE & OWNERSHIP

Implementation Ownership

Owner: Joshua Uriel Tribiana
QA: Patrick Babala
Updated by: Patrick Babala (babalapatrick@gmail.com) — 2026-09-30 (v2.0)


References

  • Issue: [3.9] Embed HTML Custom Node — no numbered parent issue recorded.

  • Related security issues: #844 (XSS in learner code-block renderer); #861 (HTML sanitizer / iframe sandbox).

  • Update PRs: #398 original feature; #666 sanitisation + sandbox; #870 learner code-block XSS fix; #884 sanitizer/sandbox hardening.

  • Companion ITG: Internal-Technical-Guide-Embed-HTML-Content-in-Quest-Nodes.md.

Version History

  • 2.0 — Updated by Patrick Babala, 2026-09-30. Corrections to match shipped behaviour:

    • Removed the never-built server-side DOMPurify step from the wireflows and the security/executive sections; documented client-side sanitization at render.

    • Corrected "learner renderer sanitizes and executes" → learner content is script-free, rendered via SandboxedHtmlFrame (no allow-same-origin).

    • Replaced the stackedit.io placeholder file links with real code paths; added SandboxedHtmlFrame.tsx and CodeblockCardContent.tsx.

    • Corrected template count to 9 and noted the script-free Accordion/Tabs templates.

    • Marked resolved Open Questions and noted the unimplemented CSP layer.

    • Added References and this Version History; linked PRs #398/#666/#870/#884 and issues #844/#861.

  • 1.0 — Hand-Off created, 2026-06-30 (author: Uriel / Joshua Uriel Tribiana; QA: Patrick Babala).


Was this article helpful?