@yanzongzhen/openmaic-courseware-react

React integration package for rendering OpenMAIC courseware with the embeddable OpenMAIC StageCore: scene rendering, navigation, media playback, fullscreen presentation, and generated-agent hydration without the OpenMAIC page shell, editor, whiteboard, or AI workspace.

Install

npm install @yanzongzhen/openmaic-courseware-react

import '@yanzongzhen/openmaic-courseware-react/styles.css';
import { OpenMAICCourseware } from '@yanzongzhen/openmaic-courseware-react';

Functional Entrypoints

The package is split by renderer capability:

import { OpenMAICCourseware } from '@yanzongzhen/openmaic-courseware-react';
import { OpenMAICCourseware as OpenMAICCoursewareCore } from '@yanzongzhen/openmaic-courseware-react/core';
import { CoursewareRenderer, StageCore, SceneRendererCore } from '@yanzongzhen/openmaic-courseware-react/stage';
import { SlideRenderer } from '@yanzongzhen/openmaic-courseware-react/slide';
import { QuizView, QuizRenderer } from '@yanzongzhen/openmaic-courseware-react/quiz';
import { InteractiveRenderer } from '@yanzongzhen/openmaic-courseware-react/interactive';
import { PBLFallbackRenderer } from '@yanzongzhen/openmaic-courseware-react/pbl';

• Root / core: recommended external integration surface.
• stage: lower-level stage and scene rendering primitives.
• slide, quiz, interactive: scene-type modules for hosts that compose their own shell. slide exports a read-only viewer runtime, not the OpenMAIC slide editor. Chart, LaTeX, and table rendering are split into lazy chunks so ordinary slide playback does not eagerly load richer element renderers such as ECharts. quiz exports a lightweight viewer with local choice grading; it does not call OpenMAIC AI grading APIs or include speech input. interactive renders iframe-based widgets, including visualization3d Three.js HTML generated by OpenMAIC.
• pbl: lightweight fallback contract only. Full OpenMAIC PBL AI workspace/chat is intentionally not bundled into the npm renderer.

Component mode: direct data

Use this mode when your backend proxies OpenMAIC data and the browser should not call OpenMAIC directly.

<OpenMAICCourseware classroom={classroom} height="100vh" />

Component mode: remote data

Use this mode when the browser can call OpenMAIC APIs.

<OpenMAICCourseware
  baseUrl="https://openmaic.example.com"
  classroomId="courseware001"
  apiKey="optional-service-api-key"
  height="100vh"
  initialSceneId="scene-2"
  showToolbar
  readonly
  theme="system"
  onSceneChange={(scene) => console.log(scene.id)}
  onComplete={() => console.log('complete')}
/>

For public websites, prefer backend proxy + direct data mode so service API keys stay server-side.

iframe fallback

<OpenMAICCourseware
  renderUrl="https://openmaic.example.com/embed/classroom/courseware001"
  height="100vh"
/>

The package defaults to component rendering. renderUrl is only for compatibility when a host application prefers iframe isolation.

Props

type OpenMAICCoursewareProps = {
  baseUrl?: string;
  apiKey?: string;
  classroomId?: string;
  classroom?: OpenMAICClassroomData;
  renderUrl?: string;
  height?: number | string;
  initialSceneId?: string;
  showToolbar?: boolean;
  readonly?: boolean;
  theme?: 'light' | 'dark' | 'system';
  className?: string;
  loadingFallback?: React.ReactNode;
  errorFallback?: (error: Error) => React.ReactNode;
  pblFallback?: React.ReactNode | ((scene: OpenMAICScene) => React.ReactNode);
  onReady?: (classroom: OpenMAICClassroomData) => void;
  onError?: (error: Error) => void;
  onSceneChange?: (scene: OpenMAICScene) => void;
  onComplete?: () => void;
};

The package uses the lightweight courseware runtime by default. PBL scenes do not pull in OpenMAIC's AI workspace/chat renderer; pass pblFallback to show a host-specific placeholder or action for those scenes. The default runtime also excludes OpenMAIC's slide editor, whiteboard, AI quiz grading, speech input, and media generation retry controls. Slide chart, LaTeX, and table elements remain supported through on-demand chunks. 3D scenes are supported through interactive visualization3d iframes; Three.js is not bundled into the default React runtime.

Package Check

pnpm --filter @yanzongzhen/openmaic-courseware-react build
pnpm --filter @yanzongzhen/openmaic-courseware-react check-package

check-package verifies the dist size budget and scans entries/chunks for accidental inclusion of PBL/AI-heavy, editor, AI quiz grading, speech, animation, OSS, or server runtime markers. It also keeps the default slide runtime under budget and prevents ECharts from re-entering SlideViewerCore.