Diagnostics

Things go wrong in a live editor: a cross-reference loses its target, a plugin throws, a node view crashes, the layout check fails. Each of them is reported through one callback, onDiagnostic, on the mount config:


import type { DiagnosticCallback } from "@stesura/core/types";
 
const onDiagnostic: DiagnosticCallback = (diagnostic) => {
  switch (diagnostic.type) {
    case "reference-missing":
      flagBrokenReference(diagnostic.targetId);
      break;
    case "dispatch-error":
    case "node-view-crash":
      sendToTelemetry(diagnostic.error);
      break;
  }
};
 
const editor = useLocalEditor({
  editorId,
  configuration: { config: { onDiagnostic } },
});

Every diagnostic carries type and editorId, the mount it was raised in. Diagnostics raised inside a sub-editor (a footnote, a header) reach the root mount’s callback with the sub-editor’s own id. A callback that throws is caught and logged, so it never breaks an edit.

`type`	Payload	When
`reference-missing`	`targetId`	A cross-reference now points at an id the document doesn’t have (the target was deleted or hidden). Once per target. A reference already broken in the loaded document is reported on the first pass after mount.
`reference-restored`	`targetId`	A target reported missing is back (undo, reveal, or an id coming back), so its references resolve again. Deleting the broken reference itself is not a restore.
`dispatch-error`	`error`	A transaction threw while being applied. It was dropped and the user got a `dispatchFailed` toast.
`node-view-crash`	`nodeType`, `error`	A node view threw while rendering and now shows a placeholder.
`pagination-failure`	`report`	A layout check failed, recovered or gave up. See Layout failures.
`doc-integrity`	`report`	A broken section structure was repaired on load, or an edit that would break it was refused. `report.doc` is the document as found.

The narrower channels still fire alongside it: addPaginationFailureHandler from @stesura/pagination and addDocIntegrityHandler from @stesura/core/helpers are process-wide, so they suit telemetry set up once per page. Messages for the user still go through onToast; onDiagnostic is for the host.

Reporting your own

reportDiagnostic from @stesura/core/helpers routes a diagnostic to the mount registered under its editorId, or through the EditorState you pass:


import { reportDiagnostic } from "@stesura/core/helpers";
 
reportDiagnostic({ type: "node-view-crash", editorId, nodeType: "chart", error }, view.state);