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: buildssrcDoc, 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 forcodeblockcards.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— definescodeContent(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
codeblockcontent 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>andon*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.wyzQuestsbranching 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)
Creator adds a Code Block node to the canvas.
Creator pastes or writes HTML into the Monaco editor.
Creator uses Preview to inspect the rendered output (scripts run here).
Auto-save persists the node; the server enforces the 50,000-character limit.
Creator saves/publishes the quest.
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
codeContentexceeds 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:
Add a Code Block node to a quest.
Paste a small HTML block or select a template.
Preview it in the editor (interactive/scripted content works here).
Save and publish the quest.
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 thesrcDoc, sanitizes withallowScripts: 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 mountsSandboxedHtmlFrame.CodeblockCardContent— learner content-card view: renderscard.content.htmlthroughSandboxedHtmlFrame.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:, unsafedata:) onhref,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 omitsallow-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,allowScriptsopt-in, forced iframe sandbox, dangerous protocols, wrapper unwrapping, server fallback,LEARNER_CONTENT_SANDBOXhas noallow-same-origin, script-free templates.Unit —
tests/unit/codeblock-card-sandbox.test.tsx: card content renders in a sandboxed iframe; a<script>probe never reachessrcdocor 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; nojavascript: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(noallow-same-origin).Replaced the
stackedit.ioplaceholder file links with real code paths; addedSandboxedHtmlFrame.tsxandCodeblockCardContent.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).