Chaeditor

A combination markdown editor package that the host app can directly control

chaeditor started from the task of extracting the internal markdown editor of the chaen project as an independent package.

The main focus was on how much control can be retained by the host app while extracting editing features as a package.

Existing markdown editors often leaned to one side. They were either empty enough to require direct assembly or had so many features but with a UI and operation method strongly fixed that it was difficult to integrate naturally into a service. In reality, each host wants different features, and aspects like link previews, file uploads, and image rendering need to connect directly with existing APIs.

chaeditor is designed to bundle writing experiences that felt useful in velog, Naver Blog, Discord, and Notion into a single basic implementation, allowing the host app to continue to manage UI shell, metadata, upload, and rendering responsibilities. Instead of going completely headless, it aims to be an editor that can be used immediately with defaults but can also be modified, replaced, and connected according to the existing service structure if needed.

Rather than merely adding features, we also organized the open surface and operation flow so that other apps can actually use it.

Design Structure

FSD Layer

Internally, it is composed of FSD (Feature-Sliced Design) layers. By separating the writing UI, editing features, pure models, and basic primitives by layer, it became easier to determine where to cut off the open API even after package extraction.

Thanks to having this structure in place, we were able to naturally divide entry points like core, react, . While retaining the writing features, we created a form that makes it easy to manage as a public package by separating logic without React dependencies and basic UI implementations.

Host Adapters

Components such as upload APIs, link previews, and image renderers, which vary by service policy, have been separated as adapters to ensure they are not fixed within the package.

If an adapter is not provided, the respective toolbar action is automatically disabled. The chaeditor/default-host entry point provides a default implementation that calls , , , and includes pre-implemented image optimization before upload (1600×1600px / 84% quality).

MarkdownRenderer is designed for server rendering, the editor surface as a client component, and uploads and link previews are connected to route handler or server action side policies. When reintegrating into chaen, only the editor surface was replaced with the package, while the upload API, rendering based on , link preview, and primitive shell remained as they were on the host side.

Primitive Registry

This structure is in place to consistently apply the host app's design system throughout the editor. Slots like , , , , , and are open for the host app to replace with its own components.

Slots that are not injected fall back to the panda-primitives default implementation. MarkdownPrimitiveProvider injects them at the top of the tree, and they are consumed anywhere inside with . By replacing primitives, the editor's internal link/image/math helpers and overlay UI operate on the same design system.

Theme contract

Style switching points are exposed through CSS custom properties. If only Panda CSS tokens were exposed, it would be difficult for the host app to reuse in environments like Tailwind, Emotion, styled-components, and vanilla-extract, so CSS variables are set as the external contract, with Panda remaining as a basic implementation only.

Deployment and Quality

verify-package-surface

Successful build alone is not sufficient. This is because the @/ alias may not be resolved post-build, type declaration files may be missing, or internal dependencies may be unintentionally removed due to treeshaking. You need to extract the actual npm tarball and verify up to the stage where a temporary consumer imports it to ensure that package exports, type declarations, and CJS/ESM surface are intact.

File: scripts/verify-package-surface.mjs

Vitest Strategy

We operate only two test groups.

Three types of SVG mocks:

Pure markdown helpers and selection utils are sent to node tests, leaving only areas requiring DOM interaction like editor, toolbar, and viewer in dom-ui.

Chromatic and Documentation

By linking Storybook 10 + Chromatic, we ascertain whether CSS changes extend to other surfaces via PR unit visual diffs. During version upgrades, the Storybook build and Chromatic deployment automatically follow in the version script.

Storybook is organized as a reference to compare what changes and which contracts are maintained in the editor / toolbar / renderer / embed workflow, rather than as a "component collection". README, wiki, and host preset documents were divided in the same flow. Storybook is positioned to quickly confirm visual states and interactions, while the wiki organizes integrated guides and references in both English/Korean, and host preset documentation is designed to immediately utilize actual connection examples.

Issues from Actual Application

SVG clipPath Bug

chaeditor was designed to be open for use in both React apps and Next.js apps. Therefore, instead of relying on bundler-specific components for SVG icons, it adopted a method of receiving raw SVG strings, organizing them at runtime, and rendering them as inline SVGs. This was flexible in the source environment, but it caused bugs that appeared only when the dev path and dist path were different.

Immediately after connecting chaeditor to chaen, the Quote icon in the toolbar disappeared. It was normal in Storybook, but only disappeared in the actual deployment environment.

Storybook reads source files directly on the Vite dev server, while the actual host app references dist/ as an npm package. The icon component imports the SVG file as a string with ?raw and renders it into inline SVG with at runtime.

normalizeSvgMarkup included a normalization step to scale the SVG according to the icon size.

This regex was applied globally (g flag) to the entire SVG string. quote.svg included a clipPath definition exported from Figma.

The global regex removed width and from , resulting in , thus the clip area became 0×0 and the entire icon was clipped.

The SVGs with clipPaths were only quote.svg and github.svg. github.svg was also broken for the same reason, but it was used as a link icon, so it went unnoticed for a while.

The fix was to narrow the external matching to a single <svg> opening tag.

This modification also led to the addition of a regression test to handle the clipPath case.

Improving Toolbar Response Delay

When editing existing articles in chaen, there was a noticeable delay in UI changes even when applying just one toolbar function.

Cause 1 — execCommand Replaced Entire Document

Toolbar actions are simple tasks that apply Markdown format only to the selected area. However, the internal implementation always selected from start to finish and replaced the entire document with insertText.

document.execCommand('insertText') is a deprecated API but is the only way to register changes in the browser's native undo stack.

Pressing bold on an article with 50,000 characters causes the browser to record 50,000 characters in the undo stack and handle a DOM mutation that rewrites 50,000 characters synchronously.

We modified it to replace only the changed section by calculating the common prefix and suffix of previous and new values.

In a 50,000-character article, clicking bold now only replaces **text** for around 10 characters. The execCommand cost is reduced from O(n) → O(change amount), and undo only reverts the actual changed parts.

Cause 2 — Preview render executes synchronously with every input

When is called, the preview panel also re-renders synchronously. (scanning the entire document), (custom block parsing), and (code highlighting) were all structured to execute synchronously with every change in .

The value for preview was separated using React.useDeferredValue.

In React 19, useDeferredValue handles urgent updates like user input first and defers the preview render to a lower priority. The textarea responds immediately, and the preview catches up as React has spare time.

The key was realizing that "a disproportionately large cost was being used for a small formatting action." As documents grow longer, such issues become more apparent, so the toolbar transform and preview render paths were simplified first with a patch. Although there is room to reduce further, the critical bottleneck blocking actual editing flow was quickly addressed and deployed at this stage.

In Conclusion

In releasing the package as open source, the main focus was on clearly defining boundaries and documentation. In an extensible structure, if the responsibilities between the package and the host app are unclear, it becomes difficult for the integrator to know what to modify. The host adapter, primitiveRegistry, and CSS variable contract all represent these boundaries in code, while the README and Storybook explain these boundaries in documentation.

Upon reattaching to chaen, we were able to verify if these boundaries were effectively maintained, and we addressed bugs and performance issues that arose during this process at the package level.