wyuc dfebbcf33f
perf(classroom): speed up classroom loading (media hydration, sidebar thumbnails, media range requests) (#1276)
* perf(classroom): defer non-priority media blob hydration off the load path

Entering a classroom awaited the full mediaFiles restore — one object URL
per restored image/video blob — before the loading gate opened. For
video-heavy courses that is hundreds of MB of IndexedDB materialization
blocking first paint.

Split the restore into two phases:

- The awaited phase now builds metadata-complete task entries but only
  creates object URLs for failed rows (none needed) and for media
  referenced by the scene the classroom opens on (persisted cursor, else
  the first scene). buildRestoredMediaTasks gains an optional
  shouldHydrateBlob predicate, defaulting to eager hydration so existing
  callers are unchanged.
- Remaining blob-backed records hydrate in the background, chunked over
  requestIdleCallback (setTimeout fallback). Each deferred task stays
  'done' — so generation resume never re-runs it — but carries no
  objectUrl yet, which the media resolution state machine already renders
  as a pending skeleton until the URL lands.

Background hydration is guarded per record: a task that was replaced
(classroom switch, regeneration, retry) or that belongs to another stage
is skipped and its freshly minted URLs are revoked immediately.

* perf(classroom): lazy-render slide thumbnails in the playback sidebar

The playback scene sidebar mounted a full SlideCanvas for every slide
scene the moment the classroom opened (and every off-screen video element
opened a preload="metadata" fetch), because SlideThumbnail's existing
visible prop was never passed.

Extract the editor nav rail's near-viewport IntersectionObserver hook to
lib/hooks/use-near-viewport.ts and gate the sidebar's slide thumbnails
through it: only scenes within 200px of the viewport render the live
canvas; the rest show SlideThumbnail's existing placeholder until scrolled
near. The placeholder keeps the same box size, so gating never shifts
layout.

The shared hook now starts hidden instead of eager: with the previous
eager-initial state, opening a long deck still mounted every canvas for a
frame before the observer could flip off-screen items off. The observer's
guaranteed initial delivery flips near-viewport items within a frame; the
no-IntersectionObserver fallback (e.g. jsdom) defers to a microtask so
the effect never synchronously re-renders.

* perf(media): lazy image decoding and HTTP Range support for classroom media

Renderer: BaseImageElement's <img> now carries loading="lazy" and
decoding="async", so thumbnail-heavy surfaces (playback sidebar, editor
nav rail, course cards) no longer fetch and decode every slide image up
front. In-viewport images are unaffected — the browser fetches them
immediately. slideToPng forces eager loading inside its permanently
off-screen snapshot tree, where lazy images would otherwise never fetch
and exports would capture blank slides.

Server: GET /api/classroom-media/[classroomId]/[...path] now answers
single byte-range requests with 206 Partial Content (Content-Range,
Accept-Ranges, correct Content-Length), enabling progressive playback and
seeking for hosted video/audio instead of downloading whole files. Suffix
ranges are supported; unsatisfiable ranges get 416 with the full size;
unsupported units or multi-range sets fall back to the plain 200 full-body
response, which is always a legal answer. Existing caching headers are
kept on every response shape.

* chore(renderer): bump version to 0.1.4 for image lazy-loading change

* fix(classroom): guard deferred hydration against restarted tasks and bound idle waits

A deferred record is only ever 'done' without an objectUrl; a task that
regeneration or retry restarted passes through pending/generating, so skip
those instead of attaching stale persisted bytes. Also give the idle
scheduling a timeout so a busy main thread cannot starve hydration.

* fix(classroom): stop superseded deferred hydration before minting URLs

A restore epoch captured at apply time now gates each idle chunk: loading
another classroom or reloading the same one invalidates any older hydration
loop, so it neither keeps scheduling work for an abandoned classroom nor
attaches bytes read by an older load to a newer load's tasks.

* fix(classroom): keep 416s uncached and classify element-keyed media as priority

A 416 with public immutable caching can poison the media URL for later
valid requests, so range errors now send Cache-Control: no-store. Priority
classification also collects the opening scene's media element ids, since
task lookup binds records keyed stage:<elementId> even when the slide slot
carries a different opaque ref.

* fix(classroom): tie deferred hydration liveness to the classroom load token

The restore epoch only advanced when the next load reached apply, so an
abandoned classroom kept hydrating during the next load's storage/network
phase. Compose the epoch with the load's isCurrent (load token plus effect
cleanup) so navigation stops the loop at the next idle boundary.

* fix(classroom): classify legacy-recovered media before deferring it

Legacy singleton video recovery assigns a placeholderRef only at the end of
the task build, so a record keyed by an allocated id without placeholderRef
was deferred even when it backs the opening scene's gen_vid_* element. Run a
metadata-only build first to learn each record's effective ref and classify
against it, keeping the first visible page's legacy video eager.

* fix(action): wait for deferred video bytes before starting play_video

executePlayVideo treated status done as immediately playable, but a deferred
restore is done without an objectUrl: the renderer shows a skeleton, no
<video> exists, and the later hydration never retriggers play, leaving the
action stuck until the safety timeout. Readiness now follows the renderer's
contract (only done-with-bytes is playable) at the initial check, the
subscription exit, and the post-subscription recheck; the failed skip applies
whether or not a wait happened.

* fix(classroom): include the stage whiteboard in priority media refs

The stage-level whiteboard stays open across standalone classroom switches,
so its media can be visible before any scene is. Classifying it as deferred
left visible whiteboard media pending behind idle hydration chunks.
2026-08-30 03:48:04 +08:00
..

@openmaic/renderer

React component for rendering PPTist-style Slide JSON. Extracted from OpenMAIC.

@openmaic/renderer is the read-only canvas package. Editing lives in the separate @openmaic/editor package, which depends on this renderer.

Migrating from 0.0.x

Version 0.1.0 removes the experimental @openmaic/renderer/editing subpath. Install @openmaic/editor and migrate editing imports to its explicit layers:

import { EditableSlideCanvas } from '@openmaic/editor/react';
import { EditableSlideCanvasWithUI } from '@openmaic/editor/ui';

Read-only rendering imports from @openmaic/renderer are unchanged.

Install

pnpm add @openmaic/renderer
# or
npm install @openmaic/renderer

Required peers:

  • react >= 18
  • react-dom >= 18
  • motion >= 11
  • tailwindcss >= 4 — the package emits Tailwind 4 arbitrary-value classes, consumers must use Tailwind 4

Optional peers (install only if your slides use the corresponding element type):

  • echarts >= 5 — for chart elements
  • shiki >= 1 — for code elements

Quickstart

import { SlideCanvas, type Slide } from '@openmaic/renderer';

const slide: Slide = {
  id: 'demo-1',
  viewportSize: 1000,
  viewportRatio: 0.5625,
  theme: {
    backgroundColor: '#ffffff',
    themeColors: ['#5b8def'],
    fontColor: '#222222',
    fontName: 'sans-serif',
  },
  elements: [
    {
      type: 'text',
      id: 't1',
      left: 100,
      top: 80,
      width: 800,
      height: 60,
      rotate: 0,
      content: '<p>Hello, Slide</p>',
      defaultFontName: 'sans-serif',
      defaultColor: '#222',
    },
  ],
  background: { type: 'solid', color: '#ffffff' },
};

export default function Demo() {
  return (
    <div style={{ width: 800, height: 450 }}>
      <SlideCanvas slide={slide} />
    </div>
  );
}

The canvas auto-fits its parent container. The parent must have a defined width × height.

API

<SlideCanvas slide effects? renderImage? renderVideo? onElementClick? scale? background? />

The main read-only entry. Reads everything from props; zero global state.

interface SlideCanvasProps {
  slide?: Slide;                       // required unless via <SlideRendererProvider>
  scale?: number;                      // omit = auto-fit container
  canvasPercentage?: number;           // percent of the parent used by auto-fit
  onScaleChange?: (scale) => void;     // computed auto-fit scale
  background?: SlideBackground;        // overrides slide.background
  effects?: SlideEffects;              // laser / spotlight / highlight / zoom, all default off
  renderImage?: (el, src, defaultContent) => ReactNode;
  renderVideo?: (el) => ReactNode;
  videoInteractive?: boolean;           // defaults true; set false to disable video pointer interaction
  onElementClick?: (el, event) => void;
  elementIdPrefix?: string;
  className?: string;
  style?: CSSProperties;
}

Play-time effects

All effects are off by default. Pass any combination via effects:

<SlideCanvas
  slide={slide}
  effects={{
    laser:     { elementId: 't1', color: '#ff3b30' },
    spotlight: { elementId: 't1' },
    highlight: { elementId: 't1', color: '#ff6b6b', animated: true },
    zoom:      { elementId: 't1', scale: 1.5 },
  }}
/>

Media injection slots

The package's BaseImageElement and BaseVideoElement render plain <img> / <video> and know nothing about your media pipeline. Inject business behaviour via the renderImage / renderVideo slots:

<SlideCanvas
  slide={slide}
  renderImage={(el, src, defaultContent) => (
    src.startsWith('placeholder:')
      ? <MyPlaceholder taskId={src} />
      : defaultContent
  )}
/>

defaultContent is the renderer-prepared image, including clipping, filters, soft edges, and colorMask. The slot return value is authoritative: return null to intentionally hide the image.

<SlideRendererProvider> + useSlideContext()

Optional high-order pattern when sibling overlays need the same slide data:

import { SlideRendererProvider, SlideCanvas, useSlideContext } from '@openmaic/renderer';

function MyAnnotationLayer() {
  const { slide } = useSlideContext();
  return <div>Annotations for {slide.id}</div>;
}

<SlideRendererProvider slide={slide} scale={0.9}>
  <SlideCanvas /> {/* reads slide/scale from context */}
  <MyAnnotationLayer />
</SlideRendererProvider>

Granular components — @openmaic/renderer/elements

If you want to compose your own layout instead of using SlideCanvas, the 9 base elements are exported individually:

import {
  BaseTextElement, BaseShapeElement, BaseImageElement,
  BaseLineElement, BaseChartElement, BaseLatexElement,
  BaseTableElement, BaseVideoElement, BaseCodeElement,
  ElementOutline,
} from '@openmaic/renderer/elements';

Each accepts { elementInfo: PPTXxxElement }. Image/Video also take a render slot.

Types — @openmaic/renderer/types

import type {
  Slide, PPTElement, SlideBackground, SlideTheme,
  PPTTextElement, PPTShapeElement, PPTImageElement,
  PPTLineElement, PPTChartElement, PPTLatexElement,
  PPTTableElement, PPTVideoElement, PPTCodeElement,
  ImageElementClip, ImageElementFilters,
  Gradient, GradientType, PPTElementOutline, PPTElementShadow,
  SlideEffects, LaserEffectOptions, SpotlightEffectOptions,
  HighlightEffectOptions, ZoomEffectOptions,
} from '@openmaic/renderer/types';

Tailwind 4 setup

Ensure your tailwind.config.{ts,js} includes the package source:

export default {
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@openmaic/renderer/dist/**/*.{js,cjs}',
  ],
};

Fonts (optional, CDN-hosted)

Slides imported from PowerPoint often reference Chinese faces that aren't installed on the viewer's machine. The package ships a fonts.css with @font-face rules for a small whitelist of self-hosted CJK faces — import it once at your app shell to make those faces available:

import '@openmaic/renderer/fonts.css';

Runtime dependency — read this. The @font-face src URLs point at an external font host (https://file.maic.chat/fonts/<name>.woff2); the woff2 files are not bundled in the package. So this is a hard runtime dependency: the host must be reachable and CORS-enabled from the consumer's app, or the browser will silently fall back to system fonts (no error, just different glyphs/metrics). If you need a different origin (self-hosting, air-gapped, a private CDN), change FONT_CDN_BASE_URL in fonts.config.mjs and regenerate with pnpm run genfonts.

The import is optional — slides render fine without it, using whatever fonts the system provides. See FONTS.md for the face list and their licenses.

Companion package

@openmaic/importer converts .pptx files to the same Slide[] shape, so you can do .pptx → @openmaic/renderer end-to-end.

See also

  • DESIGN.md — package design decisions and scope
  • v2 will add editing (<SlideEditor editable onChange />); the read-only <SlideCanvas> API will remain stable

License

MIT