@sciflow/editor-core

Documentation: docs.sciflow.org

SciFlow’s core editor runtime. The package bundles the ProseMirror schema for every node and mark that ships with core features (citation, figure, headings, mark-formatting, math, etc.). The schema elements are always present in the base bundle so documents remain valid even when a feature is toggled off at runtime—turning a feature back on simply re-registers its commands, plugins, or node views. This also guarantees that core transformations to XML and other formats remain operational.

Note: External or custom features do not have that guarantee. If an extension introduces new node/mark types or otherwise alters the schema, documents containing those nodes will only load correctly when the corresponding feature is enabled and has registered its schema additions.

Feature system

Editor.create accepts an array of feature modules defined in packages/editor/core/src/lib/features. Each feature can register commands, provide ProseMirror plugins, and expose node views that are scoped to the editor instance that imports them. Built-in features (citations, figures, headings, mark formatting, etc.) live in this directory so they can be toggled per editor without affecting the global runtime. Custom feature packages should follow the same interface and keep their registration side effects inside initialize() to avoid leaking behavior across editors.

Building

Run nx build @sciflow/editor-core to build the library.

Math feature (equations)

The math feature renders TeX as SVG in the editor using MathJax 4. The host application must load MathJax before the editor uses math nodes:

• Loading: Add a script tag for the MathJax 4 tex-svg component, e.g.
  <script defer src="https://cdn.jsdelivr.net/npm/mathjax@4/tex-svg.js"></script>
• Fallback: If MathJax is not loaded, math nodes show a placeholder message and raw TeX; the document is not corrupted.
• Errors and warnings: Invalid TeX produces an error message in the node view and in the selection sidebar when a math node is selected. MathJax errors and warnings are surfaced so users can fix equations.

Shortcuts and input rules:

• Mod-m (Ctrl/Cmd+M): Wraps the current selection in a math node. Uses selected text as TeX; display style if the selection contains a newline, otherwise inline. With no selection, inserts an empty math node.
• $$ + space: At the start of a block, creates an empty display math node.
• $$...$$: Typing e.g. $$\frac{1}{2}$$ converts the content into a display math node.

Behavior: After insertion, the new math node is selected. Selected math nodes are highlighted. Empty math nodes use dashed-border styling.

Enable the feature by including mathFeature (or createMathFeature()) in the features array when creating the editor. See @sciflow/editor-core/features/math for the public API.

Citation query helpers

The citation feature exports read-only helpers for inspecting which references a document uses and validating that all external resources are present. Import them from @sciflow/editor-core (or @sciflow/editor-core/features/citation):

import { getCitedReferenceIds, validateDocumentResources } from '@sciflow/editor-core';

• getCitedReferenceIds(doc, from?, to?) — returns unique reference IDs cited in the document. Pass optional from/to positions to restrict to a selection range (useful for highlighting references matching the current cursor).
• validateDocumentResources(doc, files, references) — checks that every figure src and citation source in the document JSON resolves against the provided file and reference arrays. Returns an array of MissingResource objects ({ type: 'file' | 'reference', id: string }), empty when everything is valid.

Running unit tests

Run nx test @sciflow/editor-core to execute the unit tests via Vitest.