GUIDE.md

Purpose: Technical reference for developers and AI agents. Navigation and developer reference. Authoritative contracts live in the linked architecture, coding, editing and testing guides.

---

Table of Contents

• Project Overview
• Directory Structure
• Technical Requirements
• Architecture (overview) | ARCHITECTURE.md (deep dive)
  • Plugin System
  • Modules
• Essential Commands
  • Project Agent Skills
• Naming Conventions
• Common Pitfalls
• Plugin Registration Flow
• Example Implementations
• Testing Strategy
• Initialization: onload Event
• iframe Mode
• Markdown View
• Build System
• Changes Log
• Supplementary Guides
  • Performance and Feature Guide - Reuse map, event/resource costs and targeted validation
  • Coding Rules - Enforceable conventions for src/*.js
  • Editing Rules - File-level edit restrictions
  • Custom Plugin Guide - Creating custom plugins
  • External Libraries - CodeMirror, KaTeX, MathJax
  • Type Definitions - SunEditor namespace types

---

Project Overview

SunEditor is a WYSIWYG editor written in pure vanilla JavaScript (ES2022+) with no runtime dependencies.
It uses JSDoc for type definitions and TypeScript for type checking.
The editor supports a modular plugin architecture where features can be enabled/disabled as needed.

Architecture Components:

• Kernel (CoreKernel): Central runtime container — orchestrates initialization, builds the Deps bag, manages Store
• Deps ($): Shared dependency object built by the Kernel — all services in one object. Not the Kernel itself.
• Store: Central runtime state (mode, focus, selection cache, etc.)
• Config: Context providers, option providers, event management
• Logic: DOM operations (selection, format, inline), shell operations (component, history, focus), panel UI (toolbar, menu, viewer)
• Event: Redux-like event orchestration (handlers, reducers, effects)
• Plugins: image, video, link, table, mention, etc.
• Modules: Modal, Controller, Figure, ColorPicker, etc.
• Helpers: DOM utilities, converters, env detection

Terminology:

Directory Structure

suneditor/
├── src/
│   ├── core/
│   │   ├── kernel/          # L1: Dependency container & state
│   │   ├── config/          # L2: Configuration & providers
│   │   ├── logic/
│   │   │   ├── dom/         # DOM manipulation (selection, format, inline, html, ...)
│   │   │   ├── shell/       # Editor operations (component, history, focus, ...)
│   │   │   └── panel/       # Panel UI (toolbar, menu, viewer)
│   │   ├── event/           # L4: Event orchestration (Redux-like)
│   │   │   ├── actions/
│   │   │   ├── handlers/
│   │   │   ├── reducers/
│   │   │   ├── rules/
│   │   │   ├── effects/
│   │   │   └── support/
│   │   ├── schema/          # Data definitions (context, options)
│   │   └── section/         # DOM construction
│   ├── plugins/
│   │   ├── command/         # Direct actions
│   │   ├── dropdown/        # Dropdown menus
│   │   ├── modal/           # Dialog plugins
│   │   ├── browser/         # Gallery plugins
│   │   ├── field/           # Autocomplete
│   │   ├── input/           # Toolbar inputs
│   │   └── popup/           # Inline controllers
│   ├── modules/
│   │   ├── contract/        # Module contracts (Modal, Controller, Figure, ...)
│   │   ├── manager/         # Managers (FileManager, ApiManager)
│   │   └── ui/              # UI utilities (SelectMenu, ModalAnchorEditor)
│   ├── hooks/               # Hook interface definitions
│   ├── interfaces/          # Plugin base classes & contracts
│   ├── helper/              # Pure utility functions
│   │   └── dom/             # DOM utilities
│   ├── assets/              # Static assets (icons, CSS, design)
│   ├── langs/               # i18n language files
│   └── themes/              # CSS theme files
├── test/
│   ├── unit/
│   ├── integration/
│   ├── e2e/                # Native editing regressions
│   └── browser/            # CI geometry contracts and performance budgets
├── types/                   # Generated TypeScript definitions
├── webpack/                 # Build configuration
└── dist/                    # Built bundles (not tracked in git)

Technical Requirements

Runtime Environment:

• JavaScript: ES2022+ (modern browsers only)
• Zero dependencies: No external libraries in production bundle

Development Environment:

• Node.js: v22 for repository tooling and CI (the package engines field is not a toolchain guarantee)
• Build tools: Webpack 5, Babel, ESLint, Prettier

Type System:

• JSDoc for inline type annotations in source files
• TypeScript for type checking (no TS source files, only generated .d.ts)
• Generated types: npm run ts-build

Testing Stack:

• Unit/Integration: Jest with jsdom
• Browser: Playwright (Chromium and Firefox)
• Coverage: Jest coverage reports

---

Architecture

For detailed internal engineering, see ARCHITECTURE.md.

Layer Architecture:

Initialization and dependency availability are defined in the two-phase injection strategy. Wait for onload before using initialized editor UI.

---

Plugin System (src/plugins/)

Plugins are modular features that extend editor functionality.

Architecture Pattern: ES6 classes extending plugin type base classes from src/interfaces/plugins.js, which extend KernelInjector (injects this.$ — the Deps bag).

Inheritance Chain:

KernelInjector → Base → PluginCommand/PluginModal/PluginDropdown/...
                         ↓
                    constructor(kernel) → super(kernel) → this.$ = kernel.$

Plugin Type Base Classes:

Plugins receive this.$ through super(kernel); it is the Deps bag, not the Kernel. Use the plugin shape for source conventions and Custom Plugin Guide for JavaScript/TypeScript examples, module contracts and multi-interface composition. The Deps reference lists available services.

Plugin Hooks & Methods Reference

The Custom Plugin Guide owns hook tables, signatures and examples. Hook order and cancellation belong to the event system. Keep repeated active() hooks synchronous and local to the supplied node; see the performance guide.

---

Modules (src/modules/)

Architecture Pattern: ES6 classes that receive $ (Deps bag) directly — no inheritance from KernelInjector.

• Constructor: constructor(inst, $, ...) → receives plugin instance + Deps bag + custom params
• Private fields: #privateField (ES2022 syntax)
• Manually instantiated by plugins (not auto-registered)

Module Classes:

Helper Utilities (src/helper/)

Architecture Pattern: Standalone utilities with no editor-layer imports; prefer pure functions. DOM helpers mutate nodes, and utilities such as debounce hold per-call closure state.

• Export: export function funcName() + export default { funcName }
• Can be imported as import { dom } from '../helper' → dom.check.isElement()

Helper Modules:

---

Options System

Options are split into two categories:

1. Base Options ($.options): Shared across all frames (plugins, mode, toolbar, shortcuts, events)
2. Frame Options ($.frameOptions): Per-frame configuration (width, height, placeholder, iframe, statusbar)

Options use Map-based storage. Some are marked 'fixed' (immutable) or resettable via editor.resetOptions().

Context System

Global context holds shared UI references; frameContext and frameOptions are moving views of the active root. Per-root ownership and storage are defined in Multi-Root Architecture. Async work must retain its originating frame, rather than trusting the active view after an await.

---

Essential Commands

Development

npm run dev              # Start local dev server (http://localhost:8088)
npm start               # Alias for npm run dev

Building

npm run build:dev       # Build for development (with source maps)
npm run build:prod      # Build for production (minified)

Testing

Commands, browser installation, CI coverage and benchmark budgets are maintained in Testing and Validation. For changed code, follow the post-edit pipeline.

Linting

npm run lint            # All: ESLint (JS + TS) + TypeScript type check + Architecture check
npm run lint:type       # Run TypeScript type checking without emitting files
npm run lint:fix-js     # Auto-fix JavaScript issues with ESLint
npm run lint:fix-ts     # Auto-fix TypeScript issues with ESLint
npm run lint:fix-all    # Fix all lint issues (JS + TS)
npm run check:arch      # Check architecture dependencies with dependency-cruiser

TypeScript & i18n

npm run ts-build        # Build TypeScript definitions from JSDoc
npm run check:langs     # Sync language files (requires Google API credentials)
npm run check:inject    # Inject plugin JSDoc types into options.js

Project Agent Skills (.agents/skills/)

Shared across agents; .claude/skills is a symlink. Read the relevant SKILL.md if the host has no skill invocation tool.

Invoke these project skills using the current host’s supported skill mechanism.

---

Naming Conventions

File Naming:

• JavaScript files: camelCase (e.g., selection.js, eventManager.js)
• Class files: Preserve the directory convention and exact case (modules/contract/Modal.js, but core/logic/dom/selection.js)
• Plugin files: Match plugin key (e.g., blockquote.js for key 'blockquote')

Code Naming:

• Classes: PascalCase (e.g., KernelInjector, Modal, CoreKernel)
• Functions/Methods: camelCase (e.g., getRange, setContent, applyTagEffect)
• Private fields/methods: #privateField, #privateMethod() (ES2022)
• Constants: UPPER_SNAKE_CASE (e.g., ACTION_TYPE, EVENT_TYPES)

Plugin Naming:

• Plugin keys: case-sensitive registration strings (e.g., 'image', 'video', 'blockStyle'); preserve spelling in buttonList and options
• Plugin types: lowercase string (e.g., 'command', 'modal', 'dropdown')
• Plugin class names: PascalCase (e.g., Blockquote, Link, Image)

CSS Naming:

• Prefix: All classes start with se- (e.g., se-wrapper, se-component)
• Component classes: se-component, se-flex-component, se-inline-component

---

Common Pitfalls

Use the coding checklist for events, shared DOM methods, state, history and iframe/RTL behavior. API names are not proof of ownership: trace the actual caller before adding a history push, listener or async cleanup path.

---

Plugin Registration Flow

Pass plugin classes in options.plugins; PluginManager constructs them with the Kernel and owns their lifecycle. Source contracts are in Plugin shape; runtime activation is in Toolbar button → plugin activation.

---

Example Implementations

Trace the closest existing implementation and its callers before extending a feature:

The reuse map lists shared owners by behavior. The event pipeline explains handlers, decisions and effects.

---

Testing Strategy

Testing and Validation is the command and coverage reference. Use behavioral assertions for jsdom, real browsers for native editing/geometry, and explicit work budgets for repeated paths. Passing coverage alone does not establish those contracts.

---

Initialization: onload Event

Editor initialization completes asynchronously. Use onload for operations that depend on fully initialized UI/state:

// Wrong - may fail
const editor = SUNEDITOR.create('#editor');
editor.focusManager.focus();

// Correct
SUNEDITOR.create('#editor', {
	events: {
		onload: ({ $ }) => {
			$.focusManager.focus();
			$.html.set('<p>Initial content</p>');
		},
	},
});

Why: suneditor.create() returns immediately, but toolbar visibility, ResizeObserver registration, and history reset happen in a deferred setTimeout. Calling methods before onload may cause errors.

---

iframe Mode

SunEditor supports DIV mode (default) and iframe mode (iframe: true).

SUNEDITOR.create('#editor', {
	iframe: true,
	iframe_attributes: {
		sandbox: 'allow-downloads', // allow-same-origin is auto-added
	},
});

SSR frameworks (Next.js/Nuxt): Use dynamic import with ssr: false to avoid contentDocument is null errors.

---

Markdown View

SunEditor supports a Markdown View mode alongside the existing Code View and WYSIWYG modes. The markdown view converts editor content to GitHub Flavored Markdown (GFM) for editing and converts back to HTML on exit.

Toggle: Use the markdownView button in the toolbar or call editor.viewer.markdownView() programmatically.

Supported GFM Syntax:

• Headings (# ~ ######), paragraphs, line breaks
• Bold, italic, strikethrough, inline code, ==highlight==
• Ordered/unordered lists, task lists (- [x])
• Blockquotes (>), fenced code blocks (```), horizontal rules (---)
• Links, images, tables (pipe syntax with alignment)

How it works:

1. WYSIWYG → Markdown: converter.htmlToJson() → markdown.jsonToMarkdown() — converts the editor's HTML to a JSON tree, then to GFM string
2. Markdown → WYSIWYG: markdown.markdownToHtml() — parses GFM back to HTML

Key files:

• src/helper/markdown.js — Markdown ↔ HTML converter (GFM)
• src/core/logic/panel/viewer.js — View mode management (code view, markdown view, fullscreen, preview)

Mutual exclusivity: Code View and Markdown View are mutually exclusive — activating one automatically deactivates the other.

---

Build System

• Webpack for bundling (config in webpack/)
• Babel (@babel/preset-env) with Browserslist targets
• ESLint with Prettier for code quality
• Output: dist/suneditor.min.js and dist/suneditor.min.css

The dist/ folder is NOT tracked in git and is built via CI/CD.

---

Changes Log

For user-facing changes, update changes.md using prompts/changes-guide.md, the sole formatting authority. Use ### feat, ### fix, ### change, ### breaking groups and concise bullets with source/plugin references. Do not use dated category headings. Skip documentation/harness, tests and internal-only changes. Clear the log only after release completion or an explicit request, not while drafting release notes.

---

Supplementary Guides

• Performance and Feature Guide - Reuse map, event/resource costs and targeted validation
• Coding Rules - Enforceable conventions for src/*.js (events, DOM, state, history, plugin shape)
• Editing Rules - File-level edit restrictions (generated files, lang files, sync rules)
• Custom Plugin Guide - Creating custom plugins
• External Libraries - CodeMirror, KaTeX, MathJax integration
• Type Definitions - SunEditor namespace types reference