SunEditor Architecture

Note: This document describes SunEditor internals in detail. For usage guides and API references, please see GUIDE.md.

---

1. Design Philosophy

SunEditor is architected to be a WYSIWYG editor with constraints:

• Zero Dependencies: No frameworks (React/Vue/Angular) or libraries (jQuery/Lodash) in the core.
• Vanilla JavaScript: Written in modern ES2022+, utilizing native browser APIs.
• State-aware editing: Uses internal state management in addition to native contentEditable behavior.

2. High-Level Architecture

The system follows a layered architecture with a central Dependency Injection (DI) container.

graph TD
    User[User Code] --> Factory[suneditor.js]
    Factory --> Facade[editor.js]
    Facade --> Kernel[CoreKernel - L1]

    subgraph Core Kernel
        Kernel --> Store[Store - State]
        Kernel --> Config[L2 Config Providers]
        Kernel --> Logic[L3 Business Logic]
        Kernel --> Event[L4 Event Orchestrator]
    end

    Logic --> DOM[dom - Selection, Format ...]
    Logic --> Shell[shell - Component, History ...]
    Logic --> Panel[panel - Toolbar, Menu, Viewer]

    Event --> Handlers
    Event --> Reducers
    Event --> Rules
    Event --> Executor[Actions - Executor]
    Event --> Effects

Detailed Structure

┌─────────────────────────────────────────────────────────────────┐
│                        suneditor.js                             │
│                    (Factory Entry Point)                        │
│  • create(target, options) → new Editor()                       │
│  • init(options) → { create() }                                 │
└────────────────────────────┬────────────────────────────────────┘
                             │ creates
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                         editor.js                               │
│                  (Main Editor Class - Facade)                   │
│                                                                 │
│  Public: isEmpty, resetOptions, changeFrameContext, destroy     │
│  Internal: Plugin lifecycle, multi-root, frame init             │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    CoreKernel (L1)                        │  │
│  │          Dependency Container & Orchestrator              │  │
│  │                                                           │  │
│  │  ┌──────────┐  ┌────────────────────────────────────┐     │  │
│  │  │  Store   │  │  $ (Deps bag)                      │     │  │
│  │  │ #state   │  │  All dependencies in one object    │     │  │
│  │  │ mode     │  │  Shared with all consumers         │     │  │
│  │  └──────────┘  └────────────────────────────────────┘     │  │
│  │                                                           │  │
│  │  L2: Config ───────────────────────────────────────────┐  │  │
│  │  │ contextProvider  │ optionProvider                   │  │  │
│  │  │ instanceCheck    │ eventManager                     │  │  │
│  │  └─────────────────────────────────────────────────────┘  │  │
│  │                                                           │  │
│  │  L3: Logic ────────────────────────────────────────────┐  │  │
│  │  │ dom/: selection, format, inline, html               │  │  │
│  │  │       listFormat, nodeTransform, char, offset       │  │  │
│  │  │ shell/: component, focusManager, pluginManager      │  │  │
│  │  │         ui, commandDispatcher, history, shortcuts   │  │  │
│  │  │ panel/: toolbar, subToolbar*, menu, viewer          │  │  │
│  │  └─────────────────────────────────────────────────────┘  │  │
│  │                                                           │  │
│  │  L4: Event ────────────────────────────────────────────┐  │  │
│  │  │ EventOrchestrator                                   │  │  │
│  │  │ (handlers → reducers → rules → executor → effects)  │  │  │
│  │  └─────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

The Entry Point (Factory Pattern)

• suneditor.js: The public entry point. It validates initialization options and target elements before creating the editor instance.
• editor.js: The Facade. It orchestrates initialization, plugin lifecycle, and multi-root management. Exposes minimal public methods (isEmpty, resetOptions, changeFrameContext, destroy) and the $ (Deps) object for full API access.

---

3. CoreKernel & Dependency Injection

The central runtime container is CoreKernel (src/core/kernel/coreKernel.js).

Terminology: The Kernel (CoreKernel) is the runtime container that orchestrates initialization and lifecycle. The $ (Deps bag) is the shared dependency object that the Kernel builds and provides — it is not the Kernel itself. The Store manages runtime state.

The $ (Deps) Object

Instead of passing dozens of arguments between modules, the Kernel builds a single dependency bag called $ (Deps). This object is shared by reference across the entire system. $ is the dependency context provided by the Kernel, not the Kernel itself.

Full $ Object Structure:

$ = {
    // L1: Core
    facade,              // Editor instance (public API)
    store,               // Store instance

    // L2: Config (Phase 1 - available to L3 constructors)
    contextProvider,     // Context/FrameContext management
    optionProvider,      // Options/FrameOptions management
    instanceCheck,       // Iframe-safe type checks
    eventManager,        // Public event API

    // L2: Convenience accessors
    frameRoots,          // Map<rootKey, FrameContext>
    context,             // Global context (toolbar, statusbar, etc.)
    options,             // Base options Map
    icons,               // Icon set
    lang,                // Language strings
    frameContext,         // Current frame context (pointer)
    frameOptions,         // Current frame options (pointer)

    // L3: Logic (Phase 2 - added after all L3 instances created)
    // dom/
    offset, selection, format, inline,
    listFormat, html, nodeTransform, char,
    // shell/
    component, focusManager, pluginManager, plugins,
    ui, commandDispatcher, history, shortcuts,
    // panel/
    toolbar, subToolbar, menu, viewer  // subToolbar: second Toolbar instance, only if _subMode is set
}

The 2-Phase Injection Strategy

1. Phase 1 (Config): The Kernel initializes L2 providers (contextProvider, optionProvider). These are added to the Deps bag ($) immediately.
   • Why? L3 Logic classes need these configs during their own construction.
2. Phase 2 (Logic): The Kernel initializes L3 Logic modules (selection, history, toolbar), then assigns them to the Deps bag ($).
   • Why? Events and circular dependencies are resolved by assigning these instances to $ after they are all created.
3. Init Pass: After Phase 2, the Kernel runs _init() on each L3 instance that implements it.
   • Why? Some Logic modules require references to other L3 modules (which only become available after Phase 2).
4. L4 (Event): Finally, EventOrchestrator is created, completing the initialization chain.

Dependency Access Patterns

Consumer	Constructor	Access Pattern
Plugin	constructor(kernel, pluginOptions?)	this.$ (Deps bag) via KernelInjector
Core Logic (L3)	constructor(kernel)	#kernel (Kernel), #$ (Deps bag), #store (Store)
Module	constructor(inst, $, ...)	#$ (Deps bag passed directly)
EventOrchestrator (L4)	constructor(kernel)	this.$ (Deps bag) via KernelInjector

Example - Plugin:

import { PluginCommand } from '../../interfaces';

class Blockquote extends PluginCommand {
	static key = 'blockquote';

	constructor(kernel) {
		super(kernel); // KernelInjector → this.$ = kernel.$ (Deps bag)
		this.title = this.$.lang.tag_blockquote;
	}

	action() {
		const node = this.$.selection.getNode();
		this.$.format.applyBlock(this.quoteTag.cloneNode(false));
	}
}

Example - Core Logic Class:

class Component {
	#kernel;
	#$;
	#store;

	constructor(kernel) {
		this.#kernel = kernel; // Kernel (runtime container)
		this.#$ = kernel.$; // Deps bag (shared dependency object)
		this.#store = kernel.store; // Store (runtime state)
		// Cache frequently used services from Deps
		this.#options = this.#$.options;
		this.#frameContext = this.#$.frameContext;
		this.#eventManager = this.#$.eventManager;
	}
}

Example - Module:

class Modal {
    #$;

    constructor(inst, $, element) {
        this.#$ = $;  // Deps bag passed directly, no inheritance
        this.inst = inst;
        this.#$.eventManager.addEvent(element, 'submit', ...);
    }
}

Kernel Layers

Layer	Responsibility	Components
L1: Kernel	Dependency Injection & State	CoreKernel, Store, KernelInjector
L2: Config	Environment & Options	ContextProvider, OptionProvider, InstanceCheck, EventManager
L3: Logic	Core editing logic	Selection, Format, History, PluginManager, Toolbar, Component
L4: Event	Input Orchestration	EventOrchestrator (Redux-style event pipeline)

Layer Dependency Rules

Dependency boundaries are enforced at build time via dependency-cruiser (.dependency-cruiser.js).

Allowed dependency direction:

  L1 (Kernel) ─── orchestrates all layers
       ↓
  L2 (Config) ─── available to L3/L4 via Deps ($)
       ↓
  L3 (Logic)  ─── cross-references via Deps ($) only (no direct imports between L3 modules)
       ↓
  L4 (Event)  ─── accesses L2/L3 via Deps ($)
       ↓
  Helper      ─── pure utilities, all layers can import

Enforced constraints:

Rule	Description
Helper isolation	helper/* cannot import from any other layer
Module isolation	modules/* cannot import core/* or plugins/* — receives Deps ($) via constructor
Plugin isolation	Plugins cannot import other plugins (same plugin submodules OK)
No circular deps	No module can import from a module that imports it

Circular dependency resolution: L3 modules that need each other (e.g., format ↔ selection) don't import directly. Both receive the full Deps bag ($) after Phase 2, resolving circular references at runtime.

---

4. State Management (The Store)

State is managed by Store (src/core/kernel/store.js). It distinguishes clearly between Configuration (read-only options) and Runtime State (mutable).

State Keys

Key	Type	Default	Description
rootKey	*	product.rootId	Current root frame key
hasFocus	boolean	false	Whether the editor has focus
tabSize	number	4	Tab character space count
indentSize	number	25	Block indent margin (px)
codeIndentSize	number	2	Code view indent space count
currentNodes	string[]	[]	Selection path tag names
currentNodesMap	string[]	[]	Active command/style names
initViewportHeight	number	0	Viewport height at init
currentViewportHeight	number	0	Current visual viewport height
controlActive	boolean	false	Controller/component active
isScrollable	function	(fc) => ...	Frame content scrollability
_lastSelectionNode	?Node	null	Last selection node (cache)
_range	?Range	null	Cached selection range
_mousedown	boolean	false	Mouse button pressed
_preventBlur	boolean	false	Suppress blur handling
_preventFocus	boolean	false	Suppress focus handling

Direct Properties (not in #state)

• store.mode - Immutable toolbar mode flags (isClassic, isInline, isBalloon, isBalloonAlways, isSubBalloon, isSubBalloonAlways)
• store._editorInitFinished - Editor initialization complete flag

Subscription System

Components subscribe to state changes to update UI reactively without tight coupling.

// Read
const rootKey = store.get('rootKey');
const hasFocus = store.get('hasFocus');

// Write (notifies subscribers)
store.set('hasFocus', true);
store.set('_preventBlur', false);

// Subscribe
const unsubscribe = store.subscribe('hasFocus', (newVal, oldVal) => { ... });
unsubscribe(); // cleanup

---

5. Type System

SunEditor uses JSDoc for type annotations and TypeScript for type checking (no TS source files, only generated .d.ts).

Key Type Names

JSDoc Type	Meaning	Used For
SunEditor.Kernel	Kernel (CoreKernel) — runtime container	Constructor @param in L3/L4 classes
SunEditor.Deps	Deps bag ($) — shared dependency object, NOT the Kernel	this.$ type, event callback params
SunEditor.Store	Store — runtime state management	kernel.store, this.#store
SunEditor.Instance	Editor class	Public API facade
SunEditor.Context	ContextMap	Global context (toolbar, statusbar)
SunEditor.FrameContext	FrameContextMap	Per-frame context
SunEditor.Options	BaseOptionsMap	Shared options
SunEditor.FrameOptions	FrameOptionsMap	Per-frame options

Rule: SunEditor.Kernel is used ONLY for constructor parameter types (the Kernel instance). For everything else (event params, plugin this.$, module deps), use SunEditor.Deps (the Deps bag).

---

6. Content Model

SunEditor uses explicit content rules to reduce inconsistent contentEditable output.

Fundamental Units

Editor operations classify nodes using these categories: Line, Block, Component, and Inline Component.

1. Line (Format Line)

• Definition: Basic text container elements that hold inline content and text
• Purpose: Contains inline content, text, and inline formatting (bold, italic, etc.)
• Validation: format.isLine(element) - checks against formatLine regex
• Default Tags: P, H[1-6], LI, TH, TD, DETAILS, PRE
• Subtypes:
  • Normal Line (format.isNormalLine()): Standard text containers - P, DIV, H1-H6, LI, DETAILS
    • Line breaks: Use Enter key to create new line elements
    • Example: <p>Line 1</p><p>Line 2</p>
  • BR Line (format.isBrLine()): Line breaks use <BR> tags - PRE
    • Line breaks: Enter creates <BR> within same element
    • Example: <pre>Line 1<br>Line 2</pre>
  • Closure BR Line (format.isClosureBrLine()): BR lines that cannot be exited with Enter/Backspace
    • Used for special constrained editing contexts (e.g., table cells with BR mode)

2. Block (Format Block)

• Definition: Structural container elements that wrap lines
• Purpose: Provides structural hierarchy around editable content
• Validation: format.isBlock(element) - checks against formatBlock regex
• Default Tags: BLOCKQUOTE, OL, UL, FIGCAPTION, TABLE, THEAD, TBODY, TR, CAPTION, DETAILS
• Relationship: Blocks structurally contain lines (e.g., <blockquote><p>quoted text</p></blockquote>)
• Subtypes:
  • Normal Block (format.isBlock() but not closure): Standard structural containers
    • Can be exited: Pressing Enter/Backspace at edges exits the block
  • Closure Block (format.isClosureBlock()): Constrained blocks that trap cursor
    • Tags: TH, TD (table cells)
    • Cannot be exited: Enter/Backspace always stays within the block

Special Case: Lists (OL/UL/LI)

Lists are a special Block-Line combination where:

• List Container (OL, UL): Block-level elements
• List Item (LI): Line-level elements that can ONLY exist inside list containers
• Dedicated Class: listFormat.js handles list-specific operations (nesting, indentation, merging)
• Common Checks: dom.check.isList(), dom.check.isListCell()

3. Component

• Definition: Self-contained interactive elements (images, videos, tables, embedded content)
• Purpose: Rich media and special features - same level as line (not contained in line)
• Validation: component.is(element) - checks for component plugins
• Container: Component plugins typically use se-component or se-flex-component at the top level
  • Images, Videos: <div class="se-component"><figure><img|iframe|video></figure></div>
  • Tables: <figure class="se-flex-component"><table>...</table></figure>
  • Audio, File uploads: <div class="se-component se-flex-component"><figure><audio|a></figure></div>
• Examples: Images, videos, audio, tables, drawings

3.1. Inline Component (Special Case)

• Definition: Components that exist inside lines (exception to the component-line sibling rule)
• Validation: component.isInline(element) - checks for se-inline-component class
• Container: Uses <span class="se-component se-inline-component"> wrapper
• Examples: Math formulas, inline anchors

Key Design Rules

1. Category checks: Core logic uses format.isLine/isBlock/isClosureBlock and component.is/isInline during editing operations
2. Hierarchy: block → contains → line (structural containment)
3. Siblings: Block components and line exist at the same hierarchy level
4. Inline Exception: Inline components can exist inside a line
5. Block Wrapping: Blocks provide structure by wrapping multiple lines

Example Structure

<div class="se-wrapper-wysiwyg">
	<p>
		Line 1: text with <span class="se-component se-inline-component"><katex>E=mc^2</katex></span> formula
	</p>
	<blockquote>
		<p>Line 2: quoted text</p>
	</blockquote>
	<div class="se-component">
		<figure><img src="..." /></figure>
	</div>
	<ul>
		<li>Line 3: list item</li>
		<li>Line 4: list item</li>
	</ul>
</div>

Content Filtering: strictMode

The strictMode option controls how strictly SunEditor validates and cleans HTML content.

Configuration:

SUNEDITOR.create('#editor', {
	// Enable all filters (default)
	strictMode: true,

	// Granular control
	strictMode: {
		tagFilter: true,
		formatFilter: true,
		classFilter: true,
		textStyleTagFilter: true,
		attrFilter: true,
		styleFilter: true,
	},
});

Filter	Purpose	When Disabled
tagFilter	Removes disallowed HTML tags	Allows any tags (security risk)
formatFilter	Enforces line/block/component structure	Components may not wrap properly
classFilter	Validates CSS classes	Allows any CSS classes
textStyleTagFilter	Converts <B>, <I>, <U> to styled <SPAN>	Keeps original tags
attrFilter	Filters attributes	Allows any attributes (XSS risk)
styleFilter	Filters inline styles	Allows any inline styles

---

7. Multi-Root Architecture

SunEditor uses a unified frame architecture for both single and multi-root editing.

Data Storage Structure

editor
├── $.frameRoots (Map<rootKey, FrameContext>)  ← Actual data storage
│   ├── null → FrameContext              [Single-root: rootKey is null]
│   ├── rootKey1 → FrameContext1         [Multi-root]
│   └── rootKey2 → FrameContext2
│
├── $.context (ContextMap)               ← Global shared UI
├── $.frameContext (FrameContextMap)      ← Current frame pointer
├── $.frameOptions (FrameOptionsMap)     ← Current frame options pointer
└── $.options (BaseOptionsMap)           ← Shared config

Key Concepts

1. Unified Structure: Single-root (store.get('rootKey') === null) and multi-root use the same architecture
2. frameRoots Map: Actual storage of all frame contexts
3. Global Context ($.context): Shared UI elements (toolbar, statusbar, modal overlay)
4. Current Frame References: $.frameContext and $.frameOptions are pointers, updated by changeFrameContext(rootKey)
5. Frame switching: editor.changeFrameContext(rootKey) updates store.rootKey and resets pointers

---

8. Plugin Architecture

Plugins follow the same integration pattern as core consumers. They extend KernelInjector, giving them direct access to the core $ object.

class MyPlugin extends PluginCommand {
	constructor(kernel) {
		super(kernel); // KernelInjector → this.$ = kernel.$ (Deps bag)
	}

	action() {
		// Access core logic directly
		const selection = this.$.selection.get();
		this.$.history.push();
	}
}

Because plugins extend KernelInjector, they receive this.$ — the same Deps bag that core modules use. Note that $ is the dependency context provided by the Kernel, not the Kernel itself.

---

9. Event System

EventManager vs EventOrchestrator

The event system is split into two distinct classes:

	EventManager (L2)	EventOrchestrator (L4)
Location	config/eventManager.js	event/eventOrchestrator.js
Role	Public event registration API	Internal DOM event processing
Methods	addEvent, removeEvent, addGlobalEvent, removeGlobalEvent, triggerEvent	_addCommonEvents, _addFrameEvents, applyTagEffect, _callPluginEvent
Used by	Plugins, modules, core logic	CoreKernel only (internal)
Extends	None	KernelInjector

EventManager is available as this.$.eventManager throughout the system. EventOrchestrator is created by CoreKernel and manages the internal event pipeline.

Event Pipeline (Internal)

To handle the complexity of cross-browser contentEditable events, SunEditor uses a Redux-like pipeline:

DOM Event → Handler → Reducer → Rules → Action[] → Executor → Effects → DOM Update

Component	Location	Purpose
Handlers	event/handlers/	Capture raw DOM events (key, mouse, input, clipboard, dragDrop)
Reducers	event/reducers/	Analyze event + state → produce action list
Rules	event/rules/	Granular key behavior rules (enter, backspace, delete, arrow, tab)
Actions	event/actions/	Action type definitions ({ t: string, p?: * })
Executor	event/executor.js	Dispatches action list through effect registries
Effects	event/effects/	Side-effect handlers (common.registry, keydown.registry, ruleHelpers)

3-Stage Event Processing

Wysiwyg DOM events pass through three stages in order. Each stage can cancel further processing by returning false.

DOM Event (keydown, input, click, paste, ...)
       ↓
  ┌─────────────────────────────────────┐
  │ Stage 1: Public Event               │
  │ eventManager.triggerEvent('onXxx')   │
  │ → user-registered callback           │
  │ → return false = cancel              │
  └──────────────┬──────────────────────┘
                 ↓
  ┌─────────────────────────────────────┐
  │ Stage 2: Plugin Event               │
  │ pluginManager.emitEventAsync('onXxx')│
  │ → each plugin's onXxx() hook         │
  │ → sorted by eventIndex               │
  │ → first boolean return stops loop    │
  └──────────────┬──────────────────────┘
                 ↓
  ┌─────────────────────────────────────┐
  │ Stage 3: Core Processing            │
  │ Reducer → Rules → Action[]           │
  │ → Executor → Effects → DOM Update    │
  │ → History Push                       │
  │ → triggerEvent('onChange')            │
  └─────────────────────────────────────┘

Example — onKeyDown in handler_ww_key.js:

// Stage 1: User event
if ((await this.$.eventManager.triggerEvent('onKeyDown', { frameContext, event })) === false) return;

// Stage 2: Plugin event
if ((await this._callPluginEventAsync('onKeyDown', { frameContext, event, range, line })) === false) return;

// Stage 3: Core processing (reducer → actions → effects)

Toolbar Button → Plugin Activation

Toolbar clicks bypass the 3-stage pipeline and dispatch directly to plugins via CommandDispatcher:

OnClick_toolbar(e)
    ↓
commandDispatcher.runFromTarget(button)
    ↓
Extract: data-command, data-type
    ↓
Branch by type:
    ├─ "command"      → plugins[cmd].action(button)
    ├─ "dropdown"     → menu.dropdownOn(button) → plugin.on() → item click → plugin.action()
    ├─ "dropdown-free"→ menu.dropdownOn(button) → plugin.on() → plugin handles own events
    ├─ "modal"        → plugins[cmd].open(button)
    ├─ "browser"      → plugins[cmd].open(null)
    ├─ "popup"        → plugins[cmd].show()
    └─ (built-in)     → CommandExecutor.execute(cmd) (bold, undo, etc.)

Public Event API

EventManager.triggerEvent(name, data) dispatches events to user-registered handlers (from options.events).

// Internal implementation
triggerEvent = async (eventName, eventData) => {
	const handler = this.events[eventName];
	if (typeof handler === 'function') {
		return await handler({ $: this.#$, ...eventData });
	}
	return NO_EVENT; // no handler registered
};

Return values:

• false — Handler explicitly canceled the action
• true / truthy — Handler processed, continue normally
• NO_EVENT — No handler registered (distinct from false)

Data Flow Summary

1. Wysiwyg Input (typing, paste, etc.):

   DOM Event → Handler
                 ├─→ Stage 1: triggerEvent('onXxx')     [user callback]
                 ├─→ Stage 2: emitEventAsync('onXxx')   [plugin hooks]
                 └─→ Stage 3: Reducer → Rules → Action[] → Executor → Effects
                                                                          ↓
                                                                     DOM Update → History Push → onChange

2. Toolbar Click:

   Button Click → CommandDispatcher.run(cmd, type)
                    ├─→ plugin.action() / plugin.open() / plugin.show()
                    └─→ (for built-ins) → CommandExecutor → inline/format logic
                                                                ↓
                                                           DOM Update → History Push → onChange

3. Selection Change:

   selectionchange → EventOrchestrator.applyTagEffect(node)
                       ├─→ selectionState.update()   [track current node path]
                       └─→ plugin.active(element, button) for each active command
                                                                ↓
                                                           Toolbar button state updated

This separation keeps event handling predictable and easier to maintain across browsers.