@openmaic/editor

Composable slide-editing package for OpenMAIC.

• @openmaic/editor/core: document operations, transactions, and undo/redo history.
• @openmaic/editor/react: editable slide interaction surface and rich-text editors.
• @openmaic/editor/ui: editor toolbars, insertion controls, and context menus.

Dependencies

@openmaic/editor
├─> @openmaic/renderer   (reuses the read-only slide renderer)
└─> @openmaic/dsl        (document and element data contracts)

@openmaic/renderer does not depend on @openmaic/editor, so the package boundary remains one-way and free of circular dependencies.

The host application owns controlled document state, selection, persistence, and the final onTransaction sink. @openmaic/editor owns built-in element adapters, insertion defaults, toolbars, dialogs, clipboard behavior, shortcuts, and the conversion of UI intents into editor transactions. Hosts may provide stable capabilities such as locale, element ID generation, and a generic asset picker; they do not configure individual element types.

Install and styles

The editor uses the renderer and DSL directly. Install them alongside the renderer's required peers and KaTeX so the host can import their public styles:

pnpm add @openmaic/editor @openmaic/dsl @openmaic/renderer \
  react react-dom motion tailwindcss katex

Import the renderer fonts and KaTeX stylesheet once from the application shell:

import '@openmaic/renderer/fonts.css';
import 'katex/dist/katex.min.css';

The renderer emits Tailwind 4 classes. Configure Tailwind to scan node_modules/@openmaic/renderer/dist/**/*.{js,cjs} as described in the @openmaic/renderer setup. Charts and code elements also need the renderer's optional echarts and shiki peers respectively.

Editor surface

EditableSlideCanvasWithUI is a controlled editor surface. The host provides the current slide and selection, then applies and persists the canonical transactions emitted by the editor. This complete example keeps undo history in React state; a production host can persist history.present whenever it changes:

import { useCallback, useState } from 'react';
import type { SlideContent } from '@openmaic/dsl';
import { applyEditorTransaction, createEditorHistory, type EditorTransaction } from '@openmaic/editor/core';
import { EMPTY_SELECTION, type Selection } from '@openmaic/editor/react';
import { EditableSlideCanvasWithUI, type EditorInsertItem } from '@openmaic/editor/ui';

const insertItems: EditorInsertItem[] = ['text', 'image', 'table', 'audio'];

export function SlideEditor({ initialContent }: { initialContent: SlideContent }) {
  const [history, setHistory] = useState(() => createEditorHistory(initialContent));
  const [selection, setSelection] = useState<Selection>(EMPTY_SELECTION);
  const applyTransaction = useCallback((transaction: EditorTransaction) => {
    setHistory((current) => applyEditorTransaction(current, transaction));
  }, []);

  return (
    <div style={{ width: '100%', height: '100%', minHeight: 480 }}>
      <EditableSlideCanvasWithUI
        slide={history.present.canvas}
        selection={selection}
        onSelectionChange={setSelection}
        onTransaction={applyTransaction}
        insertItems={insertItems}
        snapping
      />
    </div>
  );
}

insertItems is optional. It controls both which insert buttons are visible and their display order. When omitted, the toolbar uses this built-in order:

text, image, table, chart, line, background, latex, video, audio

Pass an empty array to hide the insert toolbar. Repeated values are displayed once, at their first position. This option only changes insert-button visibility and ordering; it does not disable rendering or editing existing elements of those types.

Localization

The editor has built-in Chinese and English labels. A host can provide any other language through a framework-independent translate capability:

const host: EditorHostCapabilities = {
  locale,
  translate: (key, params, defaultMessage) =>
    appTranslate(`edit.${key}`, { ...params, defaultValue: defaultMessage }),
};

<EditableSlideCanvasWithUI host={host} {...props} />;

Changing locale or translate causes visible editor controls and open overlays to use the new language without resetting the controlled document or selection. The editor does not depend on a specific i18n library; appTranslate may come from i18next, react-intl, a local dictionary, or any other translation system. Missing external translations can use defaultMessage, which contains the editor's built-in fallback label.

Inline formula serialization

Inline formulas persist as HTML with their LaTeX source in data-inline-math. Serialization regenerates KaTeX markup with trust: false; imported HTML is not reused as trusted formula markup. Missing or non-string source normalizes to an empty formula atom. An unexpected render failure falls back to escaped source text while retaining the atom and source for reopening. Invalid LaTeX syntax continues to use KaTeX's throwOnError: false behavior.

The text editor schedules persistence only after document changes, with a 300ms trailing debounce. Selection-only transactions do not trigger that persistence path. Explicit serialization (such as clipboard or HTML retrieval) can still render formulas independently.

Performance measurement

A local headless Chrome measurement on 2026-09-17 serialized one paragraph of unique inline formulas of the form \frac{N+i^{(m)}}{1+i} = e^{\delta}. After five warm-up serializations, 30 serializations per document produced:

| Formula count | Median | P95 | | --- | --- | --- | | 5 | 0.4ms | 0.5ms | | 20 | 1.3ms | 1.6ms | | 50 | 3.1ms | 3.6ms | | 100 | 5.9ms | 6.7ms |

These measurements include KaTeX DOM generation and HTML serialization, but not painting, layout, or the full editor transaction. They are synthetic local measurements, not a cross-device performance guarantee. No cache is introduced based on these results. Profile representative documents on slower devices before adding cache lifetime, memory limits, or invalidation behavior.