Plugins

The editor’s behaviour is composed from ProseMirror plugins in three tiers:

1. Core plugins: everything in @stesura/core, assembled by stesuraPlugins (each opt-out).
2. Feature-pack plugins: plugins outside core (pagination, references, track-changes, proofread, comments, …).
3. Collab plugins: composed by your mount hook (useCollabEditor via composeCollabPlugins).

The mount hooks (useLocalEditor, useCollabEditor, …) build tier 1 for you and accept extraPlugins for tier 2. You only assemble plugin arrays by hand for custom mounts and tests.

stesuraPlugins

import { stesuraPlugins } from "@stesura/core/plugins";
 
stesuraPlugins(
  schema: Schema,
  editorId: string,
  configuration?: ConfigPluginProps,
  options?: StesuraPluginsOptions, // base + custom toggles in one object
): Plugin[]

It returns basePlugins(…) followed by customPlugins(…). options merges both toggle sets (minus field, which is filled with editorId). Both pieces remain exported.

configuration (ConfigPluginProps) carries the mount config:

basePlugins

import { basePlugins } from "@stesura/core/plugins";
 
basePlugins(
  schema: Schema,
  editorId: string,
  configuration?: ConfigPluginProps,
  props?: BasePluginsProps,
): Plugin[]

Source: packages/core/src/plugins/index.ts.

reactKeys() is not included. The editor-react mount hooks add it (with stesuraKeymapPlugin); in a hand-built array for @handlewithcare/react-prosemirror, add it yourself:

import { reactKeys } from "@handlewithcare/react-prosemirror";
import { stesuraKeymapPlugin, stesuraPlugins } from "@stesura/core/plugins";
 
const plugins = [reactKeys(), stesuraKeymapPlugin(schema), ...stesuraPlugins(schema, editorId)];

onToast is an accessibility contract

Several core actions have no visible outcome when they are refused (dropping a table into a table, an upload the host rejects) and report it only through configuration.config.onToast. Without it the mount warns once, and messages go to console.warn where no user perceives them.

Your onToast must therefore render into an ARIA live region (role="status" for ordinary messages, role="alert" for errors), mounted before the message arrives so the insertion is announced.

The demo routes onToast into Sonner, whose <Toaster /> renders an aria-live region with role="status" per toast. Any toast library with the same contract will do; a bespoke one needs the region added by hand.

Toasts raised inside a sub-editor (a footnote body, a header) go to the root mount’s onToast: the sub-editor’s own configPlugin carries only the ids.

Toast messages are keys, not sentences

Core emits a ToastKey and, where the message interpolates something, its params, never English prose. @stesura/editor-react resolves the key against the mount’s locale and hands your callback a Toast:

import type { ToastCallback } from "@stesura/core/types";
 
const onToast: ToastCallback = (toast) => {
  // Default copy, already in the editor's locale:
  showToast(toast.description, toast.type);
 
  // …or replace a specific message with your own:
  if (toast.key === "nestedTablesNotAllowed") showToast(myOwnWording, "warning");
};

key and params are absent when your own code raises a toast through the same callback. Without editor-react nothing translates the key, so description falls back to it; pass your own resolver as ConfigPluginProps["toastText"].

customPlugins

import { customPlugins } from "@stesura/core/plugins";
 
customPlugins({ field, /* per-plugin toggles */ }): Plugin[]

field (the editor id) is required; the call throws without it. stesuraPlugins fills it with editorId. Every plugin is on by default; pass false to disable one.

viewModeInteractionsPlugin is added unconditionally (a no-op outside view mode) and has no toggle.

Turning uniqueIdPlugin off is unsupported. Ids are healed once on load and never again, so from the first edit on every split, paste and cell split leaves a null or duplicate id behind: pagination under-fills pages, node comments cannot be created, cross-references resolve to the wrong target, and the TOC skips nodes. A root mount without it logs a one-time console.warn.

Things people commonly look for that are not here: commentsPlugin (comments come from commentsPlugins() in @stesura/comments), proofreadPlugin, paginationPlugin, trackChangesPlugin, referencesPlugins, notesPlugin, headerFooterSyncPlugin. They live in feature packs (next section).

Feature-pack plugins

These ship outside core so you only pay for what you mount.

proofreadPlugin requires a checking backend (generateProofreadErrors), parentEditorId and a cache factory (createCache: createCollabProofreadCacheFactory from @stesura/collab-adapter-react, or createIdbProofreadCacheFactory from @stesura/proofread/cache-idb). trackChangesPlugin has to be paired with transactionModifier={trackChangesTransactionModifier} on StesuraEditor (and on the mount hook) so transactions go through the diff layer.

Collab plugins (composed for you)

useCollabEditor composes composeCollabPlugins from @stesura/collab-adapter — collab({ version }) plus the presence plugin — in front of your plugins. See Collaboration.

Plugin keys

@stesura/core/plugins re-exports the keys from packages/core/src/plugins/keys.ts:

configPluginKey, numberingPluginKey, numberingPropsPluginKey, trackChangesKey, paginationPluginKey, codeHighlightPluginKey, formatPainterPluginKey, highlightPluginKey, imagePluginKey, imageUploadPolicyKey, invisibleCharactersPluginKey, languagePluginKey, pendingLinkPluginKey, mathEditorPluginKey, searchPluginKey, headerFooterSyncPluginKey, styleSheetPluginKey, tableDragHandlePluginKey, tocPluginKey, wordPasteHandlerPluginKey, plus tabStopsPluginKey.

trackChangesKey, paginationPluginKey and headerFooterSyncPluginKey live in core so other packages can read those states without depending on the feature packs. Keys that are not in core: pendingCommentPluginKey comes from @stesura/comments (the other comment plugin keys are internal); proofreadPluginKey from @stesura/proofread.

Read state with the key:

import { highlightPluginKey } from "@stesura/core/plugins";
 
const state = highlightPluginKey.getState(view.state);

Send a message via transaction metadata:

const tr = view.state.tr.setMeta(highlightPluginKey, { persistedColor: "#FFFF00" });
view.dispatch(tr);

Order matters

1. configPlugin comes first (from basePlugins), so every plugin after it can resolve the editor’s identity and stores.
2. basePlugins precede customPlugins: tableSizingPlugin must run after tableEditing()’s table fixing.
3. transformPasted hooks chain in registration order: uniqueIdPlugin (id strip on copies) → sectionUnwrapPastePlugin → trackChangesStripPastePlugin. wordPasteHandlerPlugin’s transformPastedHTML runs before the parse.
4. Collab sync plugins run before user plugins so transactions are mapped against the latest shared state.

The pattern that satisfies all of the above:

const plugins = [
  reactKeys(),
  stesuraKeymapPlugin(schema),
  ...stesuraPlugins(schema, editorId, { config: { onToast } }, { history: false }),
  // feature-pack plugins last:
  trackChangesPlugin(),
  ...paginationPlugins(),
  ...referencesPlugins(),
  ...commentsPlugins(),
];

Writing a custom plugin

Standard ProseMirror; the editor doesn’t constrain you:

import { Plugin, PluginKey } from "prosemirror-state";
 
const myPluginKey = new PluginKey<{ wordCount: number }>("my-plugin");
 
const myPlugin = new Plugin({
  key: myPluginKey,
  state: {
    init: () => ({ wordCount: 0 }),
    apply(tr, value, _old, newState) {
      if (!tr.docChanged) return value;
      let count = 0;
      newState.doc.descendants((n) => {
        if (n.isText && n.text) count += n.text.split(/\s+/).filter(Boolean).length;
      });
      return { wordCount: count };
    },
  },
});

Append it after stesuraPlugins(...) in your plugin array (or pass it through the mount hook’s extraPlugins).

Plugins inside sub-editors

Header/footer, footnote, and endnote panels are nested ProseMirror sub-editors: a separate editor whose doc mirrors one region of the main document, kept in sync by a two-way step binding. When a panel mounts, it calls your plugin factory again to build its own plugin instances, then strips a curated exclusion list (SUB_EDITOR_EXCLUDED_PLUGINS in @stesura/core/sub-editor: pagination, notes, cross-references, header/footer sync, comments, numbering, stylesheet, TOC, proofread, history, the root configPlugin, …), adding its own configPlugin (with parentEditorId) and history(). Everything else, including your custom plugins, runs inside the sub-editor. Collab plugins never reach a panel: the mount hook adds them to the root state only, not to the pluginFactory it returns.

A plugin is sub-editor-safe by default. It only becomes a problem if it:

1. Dispatches into other editors (looks up a view by id and calls dispatch). Inside a sub-editor this can echo transactions across the sync boundary.
2. Keys global state by editorId without handling sub-editor ids. Each sub-editor has its own id; its configPlugin carries parentEditorId, which you read when you need the owning document’s stores.
3. Structurally rewrites the doc in appendTransaction based on assumptions about the document shape. The sub-editor doc is doc > wrapper > section_content > blocks; positions below 2 are scaffolding that never syncs to the main document.

Even then, the failure is contained: the binding fences scaffolding steps, verifies convergence after every sync, and resyncs the panel from the main document when they diverge. A misbehaving plugin costs a logged resync, never silent divergence or a crash. To keep your plugin out of panels, give it a PluginKey and add its label via the kind config’s extraExcludedPlugins, or filter it in your own plugin factory.

Next steps

• Customizing the Toolbar: toolbar tabs and UI extensions.
• Extending the Schema: adding custom nodes/marks.
• Comments: adapter-driven comment threads.