Standalone single-file HTML export (offline, interactive, no server)

[nirvanaslash]

Problem or Motivation

A course built in OpenMAIC can currently leave the app in four ways, and none of them gives a teacher one portable file that keeps a course playable, offline and interactive:

Export | What you get | What is lost -- | -- | -- Export PPTX | slides only | all actions, narration, interactivity Export Resource Pack | *.pptx + one standalone HTML per interactive scene (interactive/NN_<title>.html) | slides are not HTML; scenes are not joined; no narration, no timeline Export Classroom ZIP (.maic.zip) | complete manifest (stage / agents / scenes with actions + whiteboards / mediaIndex) | it must be imported back into an OpenMAIC instance to play; not a distributable artifact Export Video | Hyperframes project → MP4 | interactivity is frozen by design (see Alternatives)

The concrete frustration: I want to hand a lesson to students (or archive it for a school intranet) as a single .html file that opens in any browser and still behaves like the classroom — pages, animations, whiteboard strokes, narration, and the clickable/drag-able interactive simulations — with no OpenMAIC server, no pnpm, no Docker.

Today I have to choose between "an MP4 where the simulations are dead screenshots" and "a PPTX plus a folder of disconnected HTML files".

Proposed Solution

Add an offline standalone player export: compile the whole classroom into one self-contained artifact that plays every scene type in a plain browser.

Suggested name: Export → Offline Player (single-file HTML).

Implementation sketch (reusing what already exists):

1. Drive it from the existing .maic.zip manifest — ClassroomManifest in lib/export/classroom-zip-types.ts already carries everything a player needs: scenes[].content, scenes[].actions (with audioRef), scenes[].whiteboards, scenes[].multiAgent, agents[] and mediaIndex.
2. Bundle a player runtime (the behaviour of lib/playback/ + lib/action/, with every /api/* dependency removed) plus the slide renderer. @openmaic/dsl and @openmaic/renderer are already published and render slides from the DSL rather than rasterising them.
3. Inline everything: JS/CSS, fonts, images, narration audio, and each interactive scene's prepared HTML (the same inlineHtmlAssets machinery the resource pack already uses) — mounted in an <iframe> so it stays interactive instead of being frozen.
4. Offer two shapes, because they trade off differently:

• single .html — everything inlined, easiest to hand out;
• unpacked folder (index.html + assets/ + media/) — small file, incremental updates.

Acceptance Criteria

• A new export action produces one artifact that plays the entire course (slide / quiz / interactive / PBL scenes) in a plain browser with no OpenMAIC server, no Node, and no network access.
• Slide scenes are rendered from the DSL (crisp text), and the action timeline plays: narration audio in sync, whiteboard drawing, spotlight, laser and cue effects.
• Interactive scenes stay interactive (clickable / runnable), not frozen.
• Quiz scenes can be answered locally; if grading is unavailable offline, the learner sees an explicit notice rather than silence or a hang.
• LLM-dependent surfaces (PBL v2 runtime, multi-agent discussion / free Q&A, quiz AI grading, media generation) degrade with a clear, localized "requires a connection" message — they must never hang or spin.
• Resources that could not be inlined are reported at export time, reusing the existing export.inlinePartial warning pattern (count + host names).
• Narration is transcoded (e.g. Opus/MP3) rather than embedded as WAV: my own course had 9 min 42 s of narration = 24.5 MB of WAV, and base64 inlining adds ~33% — that is the difference between a ~33 MB and a ~4 MB artifact.
• Both shapes (single file / folder) are available, and the existing four exports are unchanged.

Alternatives Considered

• Export Video (MP4) — deliberately non-interactive: the emitted composition puts the interactive iframe behind pointer-events:none (lib/video-export/emit-hyperframes/index.ts), bounds readiness with INTERACTIVE_READY_TIMEOUT_MS = 8_000 (lib/video-export/interactive-static.ts) and replaces a scene with a fallback card on timeout; quiz/PBL compile to deterministic covers / read-only question lists (lib/video-export/passes/visuals.ts). Correct for video, wrong for "hand out the interactive lesson".
• Export Resource Pack — already produces self-contained interactive HTML, but one file per scene, no slides, no narration, no timeline or navigation.
• Export Classroom ZIP — complete and portable, but requires an OpenMAIC instance to open it (that is the documented offline/intranet story).
• Serving the app itself — works, but requires the repo, Node and a running server on each machine; not distributable to students.

Additional Context

• The data contract already exists, so this is mostly a player + packaging problem, not a data-model problem.
• Known constraints worth deciding explicitly:
• Anything that calls an LLM at runtime cannot work offline (PBL runtime, discussion/Q&A, AI grading), so a static artifact needs a declared degraded mode.
• Interactive pages that fetch CDN libraries at runtime (e.g. a generated Pyodide + CodeMirror exercise page) cannot be fully inlined; the export needs a policy for them (localize, or mark as "needs network").
• I am running a local native deployment (Windows, no Docker, v1.0.1) and can test builds, measure artifact sizes and prototype the packaging step if that helps.

中文摘要

当前四种导出方式都无法满足"把一堂课交付成一个可在任意浏览器离线打开、且保持可交互的单文件"：

• PPTX：只有幻灯片，动作 / 旁白 / 交互全丢
• 教学资源包：*.pptx + 每个交互场景各一个独立 HTML（幻灯片不是 HTML、场景彼此孤立、无旁白、无时间轴）
• 课堂 ZIP（.maic.zip）：数据完整（scenes[].actions / whiteboards / mediaIndex），但必须导入回 OpenMAIC 实例才能播放
• 导出视频：交互被刻意冻结（交互 iframe 加 pointer-events:none、就绪上限 8 秒、超时降级为回退卡；测验 / PBL 编译成确定性封面与只读题目列表）

建议新增「离线播放器导出（单文件 HTML）」：以现有 manifest 为数据源，打包一套无服务端的播放器运行时（lib/playback + lib/action 的行为，去掉全部 /api/* 依赖），用已发布的 @openmaic/dsl + @openmaic/renderer 渲染幻灯片，把 JS/CSS/字体/图片/旁白音频/交互页全部内联，交互页以 iframe 形式嵌入以保持可交互；同时提供"单文件"与"解压文件夹"两种形态。

需要显式决定的两个边界：① 需要实时调用大模型的功能（PBL 运行时、多智能体讨论 / 问答、AI 判分、媒体生成）在离线静态产物中必须降级为明确提示，不能卡住；② 旁白建议转 Opus/MP3 再内联（本机实测 9 分 42 秒旁白 = 24.5 MB WAV，base64 再涨约 33%）。

[wyuc]

Thanks @nirvanaslash, and sorry for the slow reply. This is a well-argued proposal, and the gap is real: none of the current exports gives a teacher one portable artifact that stays playable, offline and interactive. It also fits where we want OpenMAIC to go: a player that runs from the course manifest with no server is essentially the runtime as a standalone artifact.

We'd like to see it done in phases, because the full version is large:

• The hard part is the runtime, not the packaging. Playback today is tangled with server APIs and app stores, so extracting a player that needs no /api/* is where most of the work and risk is. Getting that seam right is worth more than inlining everything at once.
• Single-file size gets big fast. Narration audio and media inlined as base64 can make one .html very heavy, so the unpacked-folder shape should come first.

A shape we'd welcome:

1. Phase 1: a read-only player from the .maic.zip manifest, as an unpacked folder (index.html + assets/ + media/). It covers slides via the published renderer, scene actions and the timeline, and narration playback.
2. Phase 2: interactive scenes (reusing the resource-pack inlining, mounted in sandboxed iframes) and whiteboard strokes.
3. Phase 3: the single-file .html option, once size and loading behaviour are understood.

Please also state explicitly what won't work offline: anything that needs a model (AI chat, discussion/Q&A, regeneration), so the export UI can say so instead of shipping dead controls.

If you're up for it, could you sketch the Phase 1 design here first, in particular which parts of lib/playback/ and lib/action/ you'd lift out and how you'd cut their server dependencies? Agreeing on that seam before code will save a lot of review churn.