Troubleshooting & FAQ¶

Use this checklist when something feels off. Most responses link back to other chapters for deeper fixes.

Web component isn’t defined¶

Symptom: The console shows customElements.define… already used or sciflow-editor is not defined.

Fixes:

Import the bundle only once per page. When using bundlers, prefer a single entry point that re-exports @sciflow/editor-start.

If you hot-reload modules, guard the definition:

if (!customElements.get('sciflow-editor')) {
  await import('@sciflow/editor-start');
}

Duplicate definitions

Loading the bundle twice on the same page throws NotSupportedError. Ensure that both the demo bundle and your application bundle aren’t included together.

Include the Material Symbols font from Google Fonts (see Web Components Basics). Without it the toolbar still works but the icons are invisible.

Paste turns everything into citations¶

The citation feature only converts clipboard payloads marked with application/x-sciflow-reference. If you see unexpected conversions:

Confirm that your clipboard handler isn’t injecting JSON with { type: 'reference' }.
Update to the latest bundle where paste detection ignores plain text that isn’t tagged as a reference (fix merged via extractDropPayload hardening).

Outline clicks don’t scroll the editor¶

Call commands.focus() before commands.scrollIntoView() (already built into the custom outline recipe). Focus ensures that browsers actually honor the scroll request.

Registry returns 404¶

Double-check your .npmrc:

@sciflow:registry=https://gitlab.com/api/v4/projects/75140004/packages/npm/

If you keep the .npmrc elsewhere (e.g., in your CI runner), make sure the path is exported via NPM_CONFIG_USERCONFIG.

Need help?¶

Review the User Guide sections again.
Check the Developer Guide if you suspect a build issue.
Still stuck? Capture logs/screenshots and share them with the core team.