Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions docs/html-preview-block.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# HTML and CSS preview block

A lesson can show real HTML and CSS in a window that looks like a small browser, with the code beside it or hidden. Write a fenced block with the language `preview`.

````
```preview
title: Padding and margin
mode: split
height: 260
address: practice-page.html
slider: pad | Padding | 0 | 60 | 2 | 20 | px
select: shape | Corners | 0px,8px,24px | 8px
---html
<p class="card">Hello</p>
---css
.card { padding: {{pad}}; border-radius: {{shape}}; }
```
````

| Setting | Meaning |
|---|---|
| `mode: split` | Code on the left, browser on the right, with a Hide code button. |
| `mode: preview` | The browser alone, no code. |
| `height` | Browser height in pixels, 120 to 700 (default 280). |
| `address` | Text in the fake address bar. |
| `slider: name \| label \| min \| max \| step \| start \| unit` | A slider. `{{name}}` in the HTML or CSS becomes the value plus the unit. |
| `select: name \| label \| a,b,c \| start` | A dropdown. `{{name}}` becomes the chosen option. |
| `---html`, `---css` | The page body and the style sheet. The CSS is shown as `styles.css`. |

## How it works

- `server/src/shared/html-preview/spec.ts` parses and checks the fence. `server/src/shared/mdx/remark-html-preview.ts` turns it into an `HtmlPreview` element. An invalid fence throws, so it is caught when the course is validated or compiled.
- `packages/learning-ui/src/components/learn/content-blocks/html-preview.tsx` draws it, in the web reader and the desktop app.

## Safety

The example is read-only author content, never learner input. It is drawn in an iframe with `sandbox=""` (no scripts, no forms, no popups, no same-origin access), a content policy of `default-src 'none'` (no network), and links switched off. The source is also refused when it contains script tags, `on...=` attributes, iframe, link, meta, base, `@import`, `javascript:` addresses, or web addresses in `src`, `href` or `url()`. Images must be `data:` images. The check runs when the course is parsed and again when the block is drawn.

Not covered: the frame is its own small window, so `vh`, `vw`, `position: fixed` and `position: sticky` behave as in a real browser inside it. It cannot show the page `title` or `head` content.
184 changes: 184 additions & 0 deletions frontend/src/shared/html-preview/spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/.
/**
* Contract for the HTML and CSS preview block (the ```preview fence in a lesson).
*
* The author writes read-only HTML and CSS. The reader draws it in a sandboxed
* frame that looks like a small browser window, next to the code or on its own.
* This file is pure: the remark plugin and the component both use it, so the two
* always agree on what a valid example is.
*
* Fence format:
*
* ```preview
* title: Same words, with CSS
* mode: split (split = code beside the browser, preview = browser only)
* height: 280 (browser height in pixels, 120 to 700)
* address: practice-page (text shown in the address bar)
* slider: pad | Padding | 0 | 60 | 2 | 20 | px
* select: display | display | block,inline,none | block
* ---html
* <h1>Hello</h1>
* ---css
* h1 { padding: {{pad}}; }
* ```
*
* A control name used as {{name}} in the HTML or CSS is replaced by the current
* value, so the learner sees real code change when they move a control.
*/

export type PreviewMode = "split" | "preview";

export type PreviewControl =
| { type: "range"; name: string; label: string; min: number; max: number; step: number; value: number; unit: string }
| { type: "select"; name: string; label: string; options: string[]; value: string };

export type HtmlPreviewSpec = {
title: string;
mode: PreviewMode;
height: number;
address: string;
html: string;
css: string;
controls: PreviewControl[];
};

export const PREVIEW_MIN_HEIGHT = 120;
export const PREVIEW_MAX_HEIGHT = 700;
export const PREVIEW_DEFAULT_HEIGHT = 280;
export const PREVIEW_MAX_SOURCE = 12000;

const NAME = /^[a-z][a-z0-9-]{0,23}$/;

/** What the preview frame will refuse to draw. The sandbox and the page policy block these too. */
const FORBIDDEN: Array<[RegExp, string]> = [
[/<\s*script/i, "script tags"],
[/<\s*(iframe|object|embed|frame|frameset|applet)/i, "embedded content tags"],
[/<\s*(link|meta|base)\b/i, "link, meta and base tags"],
[/\son[a-z]+\s*=/i, "event handler attributes such as onclick"],
[/javascript\s*:/i, "javascript: addresses"],
[/@import/i, "@import"],
[/expression\s*\(/i, "CSS expressions"],
[/(?:src|href|action|poster|srcset)\s*=\s*["']?\s*(?:https?:)?\/\//i, "web addresses in src or href"],
[/url\(\s*["']?\s*(?:https?:)?\/\//i, "web addresses in CSS url()"],
[/url\(\s*["']?\s*(?!data:image\/)(?!#)[a-z]+:/i, "url() addresses other than data images"],
];

export function findForbiddenPreviewContent(source: string): string | null {
for (const [pattern, label] of FORBIDDEN) {
if (pattern.test(source)) return label;
}
return null;
}

function parseNumber(value: string, label: string): number {
const n = Number(value.trim());
if (!Number.isFinite(n)) throw new Error(`preview control "${label}": "${value.trim()}" is not a number`);
return n;
}

function parseControl(kind: "slider" | "select", rest: string): PreviewControl {
const parts = rest.split("|").map((part) => part.trim());
const name = parts[0] ?? "";
if (!NAME.test(name)) throw new Error(`preview control name "${name}" must be lowercase letters, digits or hyphens, starting with a letter`);
if (kind === "slider") {
if (parts.length < 6) throw new Error(`preview slider "${name}" needs: name | label | min | max | step | start | unit`);
const min = parseNumber(parts[2]!, name);
const max = parseNumber(parts[3]!, name);
const step = parseNumber(parts[4]!, name);
const value = parseNumber(parts[5]!, name);
if (!(min < max) || step <= 0 || value < min || value > max) throw new Error(`preview slider "${name}" has an invalid range`);
return { type: "range", name, label: parts[1] || name, min, max, step, value, unit: parts[6] ?? "" };
}
if (parts.length < 4) throw new Error(`preview select "${name}" needs: name | label | option1,option2 | start`);
const options = parts[2]!.split(",").map((option) => option.trim()).filter(Boolean);
if (options.length < 2 || options.length > 8) throw new Error(`preview select "${name}" needs 2 to 8 options`);
const value = parts[3]!;
if (!options.includes(value)) throw new Error(`preview select "${name}" start value "${value}" is not one of its options`);
return { type: "select", name, label: parts[1] || name, options, value };
}

/** Parse the body of a ```preview fence. Throws an Error with a plain message when it is invalid. */
export function parseHtmlPreviewFence(body: string): HtmlPreviewSpec {
const lines = body.replace(/\r\n/g, "\n").split("\n");
const spec: HtmlPreviewSpec = { title: "", mode: "split", height: PREVIEW_DEFAULT_HEIGHT, address: "index.html", html: "", css: "", controls: [] };
let section: "head" | "html" | "css" = "head";
const html: string[] = [];
const css: string[] = [];
for (const line of lines) {
const marker = /^---\s*(html|css)\s*$/i.exec(line);
if (marker) {
section = marker[1]!.toLowerCase() as "html" | "css";
continue;
}
if (section === "html") html.push(line);
else if (section === "css") css.push(line);
else {
if (!line.trim()) continue;
const m = /^([a-z]+)\s*:\s*(.*)$/i.exec(line.trim());
if (!m) throw new Error(`preview: cannot read the line "${line.trim()}" above ---html`);
const key = m[1]!.toLowerCase();
const value = m[2]!.trim();
if (key === "title") spec.title = value;
else if (key === "address") spec.address = value.slice(0, 60);
else if (key === "mode") {
if (value !== "split" && value !== "preview") throw new Error(`preview mode must be "split" or "preview", not "${value}"`);
spec.mode = value;
} else if (key === "height") {
const n = parseNumber(value, "height");
spec.height = Math.min(PREVIEW_MAX_HEIGHT, Math.max(PREVIEW_MIN_HEIGHT, Math.round(n)));
} else if (key === "slider" || key === "select") spec.controls.push(parseControl(key, value));
else throw new Error(`preview: unknown setting "${key}"`);
}
}
spec.html = html.join("\n").replace(/^\n+|\s+$/g, "");
spec.css = css.join("\n").replace(/^\n+|\s+$/g, "");
if (!spec.html) throw new Error("preview needs an ---html section");
if (spec.html.length + spec.css.length > PREVIEW_MAX_SOURCE) throw new Error(`preview source is longer than ${PREVIEW_MAX_SOURCE} characters`);
const names = new Set<string>();
for (const control of spec.controls) {
if (names.has(control.name)) throw new Error(`preview control "${control.name}" is defined twice`);
names.add(control.name);
}
const bad = findForbiddenPreviewContent(`${spec.html}\n${spec.css}`);
if (bad) throw new Error(`preview cannot contain ${bad}`);
return spec;
}

export function previewDefaults(controls: PreviewControl[]): Record<string, string> {
const values: Record<string, string> = {};
for (const control of controls) {
values[control.name] = control.type === "range" ? String(control.value) : control.value;
}
return values;
}

export function controlText(control: PreviewControl, value: string): string {
return control.type === "range" ? `${value}${control.unit}` : value;
}

/** Replace {{name}} with the current control value (with its unit for sliders). */
export function fillPreviewTemplate(source: string, controls: PreviewControl[], values: Record<string, string>): string {
return source.replace(/\{\{\s*([a-z][a-z0-9-]*)\s*\}\}/g, (match, name: string) => {
const control = controls.find((candidate) => candidate.name === name);
if (!control) return match;
const value = values[name] ?? (control.type === "range" ? String(control.value) : control.value);
return controlText(control, value);
});
}

const POLICY =
"default-src 'none'; style-src 'unsafe-inline'; img-src data:; font-src data:; form-action 'none'; base-uri 'none'";

/** The complete document drawn inside the sandboxed frame. */
export function buildPreviewDocument(html: string, css: string): string {
return [
"<!DOCTYPE html>",
'<html lang="en"><head><meta charset="utf-8">',
`<meta http-equiv="Content-Security-Policy" content="${POLICY}">`,
'<meta name="viewport" content="width=device-width, initial-scale=1">',
'<meta name="color-scheme" content="light">',
"<style>a{pointer-events:none}</style>",
`<style>${css.replace(/<\/style/gi, "<\\/style")}</style>`,
`</head><body>${html}</body></html>`,
].join("");
}
1 change: 1 addition & 0 deletions frontend/src/shared/mdx/component-allowlist.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ export const MDX_COMPONENT_NAMES = [
"TraceRequest",
"TraceStep",
"InteractiveCanvas",
"HtmlPreview",
"Lab",
"EcosystemGallery",
"GoDeeper",
Expand Down
3 changes: 2 additions & 1 deletion frontend/src/shared/mdx/reader-plugins.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,6 @@ import { remarkChecklist } from "./remark-checklist";
import { remarkLearningLog } from "./remark-learning-log";
import { remarkDiagram } from "./remark-diagram";
import { remarkMermaid } from "./remark-mermaid";
import { remarkHtmlPreview } from "./remark-html-preview";

export const readerRemarkPlugins = [remarkChecklist, remarkLearningLog, remarkDiagram, remarkMermaid];
export const readerRemarkPlugins = [remarkChecklist, remarkLearningLog, remarkHtmlPreview, remarkDiagram, remarkMermaid];
37 changes: 37 additions & 0 deletions frontend/src/shared/mdx/remark-html-preview.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
// GENERATED from server/src/shared — do not edit here. Run `pnpm sync-shared` in server/.
/**
* Remark plugin that turns ```preview fences into
* <HtmlPreview title mode height address html css controls /> nodes in the MDX
* tree. The fence format is documented in ../html-preview/spec.ts. An invalid
* fence throws, so the mistake is caught when the course is imported or
* compiled and never reaches a learner.
*/
import type { Code, Root } from "mdast";
import { visit } from "unist-util-visit";
import { parseHtmlPreviewFence } from "../html-preview/spec";

export function remarkHtmlPreview(): (tree: Root) => void {
return (tree: Root) => {
visit(tree, "code", (node: Code, index, parent) => {
if (node.lang !== "preview") return;
if (!parent || index == null) return;
const spec = parseHtmlPreviewFence(node.value);
const attribute = (name: string, value: string) => ({ type: "mdxJsxAttribute", name, value });
const mdxNode: Record<string, unknown> = {
type: "mdxJsxFlowElement",
name: "HtmlPreview",
attributes: [
attribute("title", spec.title),
attribute("mode", spec.mode),
attribute("height", String(spec.height)),
attribute("address", spec.address),
attribute("html", spec.html),
attribute("css", spec.css),
attribute("controls", JSON.stringify(spec.controls)),
],
children: [],
};
parent.children.splice(index, 1, mdxNode as unknown as Code);
});
};
}
41 changes: 41 additions & 0 deletions frontend/tests/unit/mdx/html-preview.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
import { createElement } from "react";
import { renderToStaticMarkup } from "react-dom/server";
import { describe, expect, it } from "vitest";
import { HtmlPreview } from "@buildment/learning-ui/components/learn/content-blocks/html-preview";
import { sharedLessonBlocks } from "@buildment/learning-ui/lesson-blocks";

const controls = JSON.stringify([
{ type: "range", name: "pad", label: "Padding", min: 0, max: 60, step: 2, value: 20, unit: "px" },
]);

const draw = (props: Parameters<typeof HtmlPreview>[0]) => renderToStaticMarkup(createElement(HtmlPreview, props));

describe("HtmlPreview", () => {
it("is registered as a lesson block", () => {
expect(sharedLessonBlocks.HtmlPreview).toBe(HtmlPreview);
});

it("draws the code beside a sandboxed browser frame", () => {
const html = draw({ title: "Padding", mode: "split", height: "240", address: "page.html", html: "<p>Hello</p>", css: "p { padding: {{pad}}; }", controls });
expect(html).toContain("<iframe");
expect(html).toContain('sandbox=""');
expect(html).toContain("Content-Security-Policy");
expect(html).toContain("padding: 20px");
expect(html).toContain("styles.css");
expect(html).toContain("Hide code");
expect(html).toContain('type="range"');
});

it("shows only the browser in preview mode", () => {
const html = draw({ title: "Look", mode: "preview", html: "<p>Hello</p>" });
expect(html).toContain("<iframe");
expect(html).not.toContain("Hide code");
expect(html).not.toContain("index.html code");
});

it("refuses to draw content the frame must not run", () => {
const html = draw({ title: "Bad", html: "<script>alert(1)</script>" });
expect(html).not.toContain("<iframe");
expect(html).toContain("cannot be shown");
});
});
3 changes: 2 additions & 1 deletion packages/learning-ui/contracts.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,5 +19,6 @@
"api/catalog.ts",
"api/syllabus.ts",
"domain/enums.ts",
"lib/course-tracks.ts"
"lib/course-tracks.ts",
"html-preview/spec.ts"
]
Loading
Loading