<p align="center">
  <img src="apps/dev/public/icon-192.png" width="64" height="56" alt="Enesis Editor" />
</p>

<h1 align="center">Enesis Editor</h1>
<h3 align="center">Block Markdown Editor</h3>

<p align="center">
  A high-performance <strong>block markdown editor</strong> built with Vue 3, TypeScript, ProseMirror, and the Lezer parsing framework.
</p>

Documents are structured as distinct, interactive **Blocks** rather than a single flat string. Each block is a self-contained ProseMirror editor instance that stores raw markdown as plain text — no AST conversion, no mark storage. A Lezer-based parsing pipeline renders syntax as visual decorations in real time, enabling live-preview editing of Obsidian-style references, task states, callouts, headings, and inline formatting.

## Vision

Enesis is being built as a complete block-editing substrate where **plain text stays plain text** — formatting is purely decorative via Lezer-driven decorations, never structural. This makes it ideal for note-taking apps, knowledge bases, and any tool that needs to edit rich markdown with programmatic access to the raw source.

## Design Principles

- **Raw markdown in, raw markdown out.** ProseMirror never converts `**bold**` to `<strong>`. What you type is what's stored.
- **Syntax through decorations, not marks.** Bold, italic, links, references, tags — all rendered via ProseMirror decorations, never via schema marks. This keeps the document model clean and pluggable.
- **Lezer-based parsing.** All syntax features flow through a single `@lezer/markdown` AST walk with custom extensions for Obsidian-style elements.
- **Block-level isolation.** Each block is an independent ProseMirror instance. Blocks coordinate via emitted events (`split`, `merge-previous`, `arrow-up-from-start`, etc.) — no shared state.

### Why Not TipTap?

TipTap's extension ecosystem assumes formatting is structural — Bold becomes a `<strong>` mark, Italic becomes `<em>`, headings become heading nodes. This editor's core premise is the opposite: markdown syntax stays as raw text and formatting is purely decorative via Lezer-driven ProseMirror decorations. Adopting TipTap would mean fighting its content model rather than using it, essentially reimplementing the decoration layer on top of an abstraction that actively resists it. TipTap also manages the ProseMirror schema for you, which would conflict with the deliberately minimal schema here (`doc`, `paragraph`, `code_block`, `math_block`, `text` — no marks at all).

The multi-block architecture is the other major friction point. Each `EditorBlock` is its own independent `EditorView` instance, coordinating via events. TipTap assumes a single editor wrapping the whole document, so the block-per-instance model would require either abandoning TipTap's lifecycle entirely (at which point you're just using raw ProseMirror anyway) or shoehorning the pattern into something TipTap wasn't designed for. The custom Lezer parsing pipeline, pattern plugin, and node view registry all interact directly with ProseMirror's internals in ways that TipTap's abstraction layer would make unnecessarily awkward to access.

## Monorepo Structure

```
├── apps/
│   └── dev/                  Docs-style development site (Vue 3 + Vite)
│       ├── src/
│       │   ├── components/
│       │   │   ├── LiveExample.vue     Editable demo wrapper with source view
│       │   │   └── AppLogo.vue         Enesis brand mark
│       │   ├── pages/
│       │   │   ├── index.vue           Overview / key concepts
│       │   │   ├── editor.vue          Multi-block Editor shell
│       │   │   ├── editor-block.vue    Standalone EditorBlock demo
│       │   │   ├── toolbar.vue         Toolbar integration
│       │   │   ├── suggestion-menu.vue Pattern completion menu
│       │   │   └── themes.vue          Theme presets
│       │   ├── App.vue                 Shell layout with sidebar
│       │   ├── main.ts                 App bootstrap (6 routes)
│       │   └── style.css               Tailwind v4 + Nuxt UI theme
│       ├── public/                     Static assets (icons.svg sprite, favicon)
│       └── vite.config.ts              Vite with Nuxt UI plugin
│
├── packages/
│   └── editor/                Core headless engine
│       ├── src/
│       │   ├── index.ts               Public API (Editor + EditorBlock + EditorToolbar + EditorSuggestionMenu)
│       │   ├── components/
│       │   │   ├── EditorBlock.vue     Self-contained ProseMirror block editor with draggable grip
│       │   │   ├── Editor.vue          Multi-block shell with insertion zones, drag-to-reorder, undo/redo
│       │   │   ├── EditorInsertionZone.vue   32px hit target between blocks, hover-reveal, drag target
│       │   │   └── EditorToolbar.vue   Shared toolbar bound to active block
│       │   ├── composables/
│       │   │   ├── useMarkdownDecorations.ts   ProseMirror decoration plugin
│       │   │   ├── useBlockKeyboardHandlers.ts Keyboard handler (Enter, Backspace, arrows)
│       │   │   ├── useCodeBlockView.ts         CM6 NodeView for fenced code blocks
│       │   │   ├── useMathBlockView.ts         KaTeX NodeView for display math
│       │   │   ├── usePatternPlugin.ts         Pattern detection ([[, ((, /, #)
│       │   │   ├── usePasteHandler.ts          Multi-line paste split handler
│       │   │   └── useFocusRegistry.ts         Cross-block focus management
│       │   └── lib/
│       │       ├── block-parser.ts             splitMarkdownIntoBlocks / serializeBlocks
│       │       ├── content-model.ts            Markdown ↔ ProseMirror conversion
│       │       ├── schema.ts                   Minimal ProseMirror schema
│       │       ├── auto-close-plugin.ts        Auto-close for ```, **, _
│       │       ├── formatting.ts               Formatting handlers (toggleBold, insertLink, etc.)
│       │       ├── operation-history.ts        EditorOperation types + undo/redo stack
│       │       ├── theme.ts                    CSS-variable theme system with presets
│       │       ├── katex.ts                    Dynamic KaTeX import + render helpers
│       │       ├── logger.ts                   Namespace-based debug logger
│       │       ├── markdown-parser.ts          Lezer parser configuration
│       │       ├── markdown-extensions.ts      Custom Lezer extensions
│       │       └── markdown-rules/
│       │           ├── engine.ts               MarkdownRuleEngine (2-stage pipeline)
│       │           ├── types.ts                Shared type interfaces
│       │           ├── inline-rules.ts         Inline syntax rules
│       │           ├── block-rules.ts          Block syntax rules
│       │           └── block-classifier.ts     First-line regex classifier (paste only)
│       ├── vite.config.ts            Library build (ESM, tailwind, vue)
│       └── vitest.config.ts          Test runner configuration
│
├── .forgejo/
│   └── workflows/
│       └── deploy.yml               CI: build + deploy to Codeberg Pages
│
├── package.json                    Workspace root
├── pnpm-workspace.yaml            pnpm workspace definition
├── AGENTS.md                      Context optimization file — strict rules and system boundaries to guide AI coding assistants safely through ProseMirror's state architecture
└── biome.json                     Linting & formatting
```

## Quick Start

```bash
pnpm install
pnpm dev            # Start the dev sandbox at localhost:5173
pnpm test           # Run editor unit tests (Vitest)
pnpm check          # Lint & format check (Biome)
```

## Usage

```bash
pnpm install @enesis/editor
```

```vue
<script setup lang="ts">
import { ref } from "vue"
import { Editor, EditorToolbar } from "@enesis/editor"
import "@enesis/editor/dist/index.css"

const content = ref(`* # Hello World

  * A paragraph with **bold** and *italic* text.
  * A TODO task with ::TODO:: status
`)

function onFocus(payload: { view: EditorView; handlers: FormattingHandlers }) {
  // payload.handlers provides toggleBold, insertLink, setHeading, etc.
}
</script>

<template>
  <EditorToolbar />
  <Editor
    v-model:content="content"
    @focus="onFocus"
    @blur="() => console.log('blurred')"
    @error="(e: any) => console.error(e)"
  />
</template>
```

## Scripts

| Script | Description |
|---|---|
| `pnpm dev` | Start Vite dev server for `@enesis/dev` sandbox |
| `pnpm build` | Build `@enesis/editor` library (ESM + type declarations) |
| `pnpm test` | Run unit tests for `@enesis/editor` |
| `pnpm check` | Run Biome lint & format check across the workspace |

## Deployment

On push to `master`, a Forgejo Actions workflow builds the dev app and deploys it to **Codeberg Pages** at `https://enesismd.codeberg.page/editor/`.

## Technology

| Layer | Technology |
|---|---|
| Framework | Vue 3 (Composition API, `<script setup>`) |
| Editor Engine | ProseMirror (view, state, model, transform, keymap, gapcursor) |
| Parsing | Lezer (`@lezer/markdown` + GFM + custom extensions) |
| Styling | Tailwind CSS v4 + Nuxt UI v4 |
| Type Safety | TypeScript (`strict: true`) |
| Testing | Vitest with jsdom |
| Formatting | Biome |
| Package Manager | pnpm workspaces |
| CI/CD | Forgejo Actions → Codeberg Pages |

## License

MIT
