RFC: Self-contained classroom export — one runnable HTML file, and interactive scenes kept in place in PPTX

[wyuc]

Summary

Today a classroom leaves OpenMAIC in pieces. The "Resource Pack" is a ZIP holding a PPTX with only the slide scenes, plus each interactive scene as a separate interactive/NN_<title>.html. The two halves do not reference each other, the interactive scenes lose their position in the lesson, and quiz and PBL scenes are not exported at all. Teachers who present from the export have to leave the deck, find the right HTML file, and come back.

This RFC proposes two changes:

1. Short term: the PPTX keeps interactive and quiz scenes in their original position as placeholder slides that link to the matching page in the pack.
2. Main proposal: a new standalone HTML export: a single .html file that plays the whole classroom offline, in order. Slides, interactive scenes and quizzes are all included, with optional narration. It is built from the existing @openmaic/renderer package and the classroom ZIP manifest.

Background and problems

• buildResourcePackZip (lib/export/use-export-pptx.ts) filters scenes to type === 'slide' for the PPTX and writes interactive scenes as standalone files. Scene order across the two is lost.
• PowerPoint has no portable way to embed live HTML. The Web Viewer add-in needs an install and network access, and it does not work in WPS or Keynote. LiveWeb is gone. OLE-embedded HTML is Windows-only and opens externally with a security prompt. So "embed the interactive page in the PPTX" cannot be solved inside PPTX alone.
• The pieces for a self-contained player already exist:
  • @openmaic/renderer: a read-only SlideCanvas with spotlight, laser, highlight and zoom effects.
  • inlineHtmlAssets: already makes an interactive scene's HTML self-contained.
  • ClassroomManifest (.maic.zip, formatVersion: 1): already serializes scenes, actions, agents and a media index.
  • lib/playback: the action and playback model.

Scope

In scope:

• Placeholder slides for interactive and quiz scenes in the PPTX / Resource Pack.
• A new export format: standalone HTML player (offline, no server, no API keys).

Out of scope: live AI features in the exported file (see Non-goals), and changes to the .maic.zip format beyond what embedding it requires.

Design

1. PPTX: keep every scene in place

For each interactive or quiz scene, emit a slide at its original index containing:

• the scene title, its type, and a short description;
• an "Open interactive page" button linking to interactive/NN_<title>.html (a relative path, valid when the pack is extracted). If the deployment exposes a public link for the classroom, also show that URL and a QR code so the deck still works once the PPTX is copied away from the pack.

PBL scenes are left out of the PPTX: a project is not something to present from a slide, and the HTML export covers it (see below). The existing getLinkOption / pptxgenjs hyperlink support covers this. No new dependencies are needed.

2. Standalone HTML export

Shape of the file

<!doctype html>
<html>
  <head> <style>/* precompiled player + renderer CSS, fonts */</style> </head>
  <body>
    <div id="app"></div>
    <script type="application/json" id="openmaic-classroom">{ ...ClassroomManifest... }</script>
    <script type="application/json" id="openmaic-media">{ "audio/…": "data:audio/mpeg;base64,…", … }</script>
    <script>/* player bundle */</script>
  </body>
</html>

• Player bundle: a small React app built at OpenMAIC build time and shipped as a static asset. The export step fetches it and inlines it, so the export itself needs no bundler. The renderer's Tailwind classes are compiled into the player's CSS once, at build time.
• Data: the same ClassroomManifest the .maic.zip export already produces, embedded as JSON, so one serializer serves both formats. Media referenced by mediaIndex is embedded as data URIs.

Scene support

Scene	In the exported HTML
slide	SlideCanvas from @openmaic/renderer; spotlight and laser actions via its effect overlays
interactive	sandboxed <iframe srcdoc> with inlineHtmlAssets output, same sandbox flags as InteractiveIframeHost
quiz	choice questions graded client-side; open-ended questions show the reference answer instead of AI grading
pbl	static scenario briefing and tasks, plus a link to the online classroom on the OpenMAIC deployment that exported it, where the agent workflow runs (shown only when the deployment provides a public link)

Playback: manual navigation (keyboard, click, fullscreen) in every mode. When narration is included, speech actions play their audio and auto-advance, reusing the action sequence from the manifest.

Size control: narration and video dominate file size. Export options:

• Full: everything inlined.
• Without narration: slides, interactive scenes and quizzes only; usually small.
• Above a size threshold, fall back to classroom.html + media/ in a ZIP, with relative URLs.

Security: the file makes no network requests and carries no keys. Interactive scenes stay in sandboxed iframes, the player sets a restrictive CSP, and user content is never evaluated in the player's own origin.

Phases

• P0: PPTX placeholder slides for interactive and quiz scenes, linked to the pack's HTML pages.
• P1: Standalone HTML MVP: slides, interactive scenes and quizzes, manual navigation, no audio.
• P2: Narration and auto-play (speech, spotlight, laser), size modes and the ZIP fallback.
• P3: Whiteboard actions and video. Optionally, make the exported HTML re-importable, since it already embeds the manifest.

Open questions

1. Should the HTML export eventually replace the Resource Pack, with the PPTX kept only for editing, or should both stay?
2. Default size threshold for falling back to HTML + media/?
3. Fonts: embed subsets of the renderer fonts, or rely on system fallbacks?
4. Should the exported HTML be importable back into OpenMAIC (P3), or is .maic.zip the only round-trip format?
5. Placeholder slides in P0: is a title card enough, or do we want a rendered preview of the interactive scene (hard, because it requires rendering the sandboxed page)?

Non-goals

• Live AI features offline: AI teacher and discussion, PBL agents, AI grading of open-ended answers. PBL in particular stays an online activity; the export only carries its briefing and a link, and the PPTX leaves PBL scenes out.
• Embedding live HTML inside PPTX through add-ins or OLE.
• Editing in the exported file.

[wyuc]

Status: implemented for 1.2.0. Thanks to everyone who reviewed and tested along the way.

What landed (tracked in #1810):

• PPTX keeps every scene in place — interactive, quiz and PBL scenes become placeholder slides at their original position, with an "open online" button and QR code; the export submenu chooses "with placeholders" or "slides only" (feat(export): keep interactive and quiz scenes in the PPTX as placeholder slides #1811, fix(export): drop the publish hint and status lookup from PPTX placeholders #1819, feat(export): PBL placeholder slides and a per-export choice of placeholders #1823).
• Standalone HTML export — one offline file built from @openmaic/renderer and the ClassroomManifest (feat(export): export a classroom as a single offline HTML file #1813), which now plays the classroom: narration with captions, spotlight and laser, auto-advance on slides, slide video, discussion cards linking to the online classroom, widget actions in interactive scenes; quiz, interactive and PBL scenes hold after their narration. "With narration and video" / "Without narration" choose the size (feat(export): play the standalone HTML classroom with narration, effects and video #1842, fix(export): follow-ups from the standalone HTML playback review #1848, fix(export): hide the no-JavaScript fallback as soon as the standalone player starts #1850).
• Large classrooms fall back to a ZIP of classroom.html plus audio/, media/ and images/ folders (feat(export): fall back to a ZIP of classroom.html and its media for large classrooms #1845).
• Related fixes found on the way: fix(renderer): repaint clipped chart series on WebKit #1825 (Safari chart lines), fix(export): drop non-woff2 font fallbacks instead of about:invalid #1826 (exported fonts), fix(math): disable formula-defined macros in KaTeX and Temml rendering #1827 (formula-defined macros disabled in every math render), fix(sanitize): store inline math as LaTeX source and typeset it in the client #1829 (inline math kept through saves).

Answers to the open questions:

1. HTML vs Resource Pack: both stay. The HTML is for presenting and sharing; the PPTX/Resource Pack remains for editing in slide tools.
2. Size threshold: single file up to 400 MB (largest size verified to open reliably; a warning above 100 MB), then the ZIP fallback.
3. Fonts: renderer and math fonts are inlined as woff2; fonts that only exist as other formats are dropped rather than left as blocked fallbacks.
4. Re-import of the exported HTML: not planned. .maic.zip stays the round-trip format; the HTML omits whiteboards, agent configuration and discussion prompts, so a re-import would give an incomplete course.
5. Placeholder previews: title, type and description with the online button/QR; no rendered preview of sandboxed pages.

Not in scope: whiteboard actions — generated scenes never carry wb_* actions (they only come from live AI chat), so static playback has nothing to replay.

Follow-ups: #1846 (media inside interactive scenes vs narration), #1847 (iOS Files preview).

[wyuc]

@CXuPercy could you help test the export features on main with fresh eyes? @LING-6150 has already covered desktop Chrome/Firefox/Safari via file://, Windows Explorer (opening classroom.html from inside the ZIP) and iPhone Safari over LAN HTTP, so the most useful gaps are:

1. Single-file HTML (Export → HTML → With narration and video / Without narration) on a few of your own classrooms, ideally ones with formulas, charts, slide videos, interactive pages, quizzes and PBL:
   • open the file locally on Windows (Edge and Chrome) and Android, plus iPhone/iPad if you can (how it opens from Files/Mail/chat apps; see Standalone HTML export shows a blank page in the iOS Files preview #1847);
   • press Play and let it run, then interrupt it (Space, arrows, the scene list, pausing a video from its own controls). Look for narration/caption mismatches, effects pointing at the wrong element, two sounds at once, or scenes that should hold but advance.
2. PPTX with placeholders opened in PowerPoint, WPS and Keynote: placeholders sit at the original scene positions, and the button and QR code open the right scene online (?scene=).
3. Large classrooms: one with several long videos, to hit the ZIP fallback above 400 MB (or temporarily lower STANDALONE_HTML_MAX_BYTES locally). Extract it and open classroom.html.

Please report anything you find as an issue labelled area:import-export (or reply here), with the browser/OS and, if possible, the exported file. Thanks!

[CXuPercy]

@wyuc Export testing done on main@7ca6077c (v1.2.0-rc.2), local dev. Test classroom: a freshly generated Fourier-series course (10 scenes: slide×6 with formula derivations / a line chart / a table, quiz×2, an interactive simulation, PBL; 69 TTS narration lines + one slide video), so every scene type you listed was exercised in both HTML variants and the placeholder PPTX.

1. Single-file HTML

• Both with narration and video and without narration played through cleanly on macOS Chrome: narration/captions in sync, slide video, charts and formulas fine; quiz/interactive/PBL scenes held after narration. Interruption round (Space, arrows, scene list, pausing the video from its own controls) showed no double audio or mis-aimed effects.
• Windows (Edge + Chrome), Android phone (Quark) and Android tablet (Chrome) matched macOS; no significant differences.
• ⚠️ iPhone/WeChat: no "open in browser" option offered, so the file cannot be opened from WeChat (relates to Standalone HTML export shows a blank page in the iOS Files preview #1847; the Files-app path not verified).
• Minor notes: the silent variant's captions feel noticeably slow (reading timer — working as designed, recorded as UX feedback); quizzes hold without a post-quiz explanation, which matches the online-classroom-only design — confirming as expected.

2. PPTX with placeholders

• WPS and PowerPoint both fine: placeholders sit at the original scene positions, the online button works; the slides only variant is fine too.
• ⚠️ Both WPS and PowerPoint show formula line-wrapping: long formulas get wrapped inside the slide.
• Keynote untested (no local copy). The QR code encodes the exporter's origin (localhost here), so it can't be meaningfully tested locally — not a defect; exporting from a LAN origin would make it testable.

3. ZIP fallback

• Triggered by temporarily lowering STANDALONE_HTML_MAX_BYTES locally: correct ZIP layout (classroom.html + audio/ media/ images/ + readme); after full extraction it plays correctly (audio/video/charts all present). The page-size guard also behaved as designed — with the threshold set too low it refuses with a clear "page is about X MB, too large" message.

Side observation (generation, not import-export): narration text occasionally contains homophones — π is written as "派" in some scenes ("负派到正派", "一除以派") while other scenes of the same course write π correctly. The exported captions display the text verbatim; TTS reads "派" (pài), the standard Chinese pronunciation of π, so only the captions look wrong. FYI.

Not covered: Keynote, iPad, the iPhone Files/Mail paths, a real >400 MB classroom. Happy to share the exported files if useful.

[wyuc]

@CXuPercy thanks — this is exactly the coverage we were missing (Windows, Android, WPS/PowerPoint, the ZIP fallback with a real classroom). Follow-ups:

• iPhone / WeChat can't open the file — added to Standalone HTML export shows a blank page in the iOS Files preview #1847 (iOS opening paths).
• Long formulas wrap in WPS and PowerPoint — opened PPTX export: long formulas wrap onto several lines in PowerPoint and WPS #1905.
• π written as "派" in captions — opened Narration captions show phonetic spellings of math symbols (π written as 派) #1906 (narration text is written for speech; captions should show the standard form).
• Silent variant captions feel slow — noted; the reading-time estimate could be tuned, but it's working as designed for now.
• Quizzes holding without a post-quiz explanation, and the QR code encoding the exporter's origin — agreed, both as designed.

Since your run, #1904 also fixes inline formulas in render-service previews and makes their PPTX export clean LaTeX text.