npm package: @sciflow/editor-core
Description: Documentation: [docs.sciflow.org](https://docs.sciflow.org)
Latest version: 0.0.3

# @sciflow/editor-core

Documentation: [docs.sciflow.org](https://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`):

```ts
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](https://vitest.dev/).