# Reetesh Kumar — full content export

> Machine-readable export from https://iamreetesh.com. Lextrix version 2.0.5. Canonical monorepo docs: https://github.com/rishureetesh/lextrix/tree/main/docs.

---

# Lextrix documentation

## Getting Started

Source: https://iamreetesh.com/docs/getting-started

**Try it:** [Live playground](https://iamreetesh.com/lextrix) — themes, import/export, and all modules in the browser.

New here? Follow the [Evaluation guide](/docs/evaluation) for a linear install → export walkthrough.

## Install

```bash
npm install lextrix
```

```javascript
import Lextrix from 'lextrix';
import 'lextrix/snow.css';
```

| Import | Purpose |
|--------|---------|
| `lextrix` | Full editor — ESM (`lextrix.esm.js`) for bundlers, UMD (`lextrix.js`) for script tags |
| `lextrix/core` | Core-only bundle (no formats/themes) |
| `lextrix/lextrix.css` | Base editor styles |
| `lextrix/snow.css` | Snow theme |
| `lextrix/bubble.css` | Bubble theme |
| `lextrix/slate.css` | Dark slate theme |
| `lextrix/dawn.css` | Warm dawn theme |

Named imports (`ChangeSet`, `registerSerializer`, `lxrPath`, …) work from `lextrix` in bundlers (2.0.1+). Script-tag UMD exposes `window.Lextrix` only.

Optional peer dependencies: [highlight.js](https://highlightjs.org/) for syntax, [KaTeX](https://katex.org/) for formulas.

**React / Next.js:** [`@lextrix/react`](/docs/react) · [Frameworks](/docs/frameworks) · [Evaluation](/docs/evaluation) · [Cookbook](/docs/cookbook)

Script-tag setup (npm paths or CDN): [Framework integration — Script tag](/docs/frameworks#script-tag-no-bundler).

## Snow theme

```html
<div id="editor"></div>
```

```javascript
const editor = new Lextrix('#editor', {
  theme: 'snow',
  placeholder: 'Start writing…',
  modules: {
    toolbar: [
      [{ header: [1, 2, false] }],
      ['bold', 'italic', 'underline', 'strike'],
      [{ list: 'ordered' }, { list: 'bullet' }],
      ['link', 'image'],
      ['clean'],
    ],
    imageResize: true,
  },
});

editor.setContents([
  { insert: 'Hello Lextrix\n', attributes: { header: 1 } },
  { insert: 'Select an image and drag the corner handle to resize.\n' },
]);
```

## Bubble theme

```javascript
const editor = new Lextrix('#editor', {
  theme: 'bubble',
  modules: {
    toolbar: [
      ['bold', 'italic', 'link'],
      [{ header: 1 }, { header: 2 }],
    ],
  },
});
```

## Read-only

```javascript
const editor = new Lextrix('#editor', {
  theme: 'snow',
  readOnly: true,
});
```

## Getting content

```javascript
const json = editor.getContents();       // ChangeSet
const html = editor.exportContent('html');
const text = editor.getText();
```

## Listening to changes

```javascript
editor.on('text-change', (delta, oldDelta, source) => {
  if (source === 'user') {
    save(editor.getContents());
  }
});
```

See [Configuration](/docs/configuration) for modules, upload handlers, and format whitelists.

---

## Evaluation Guide

Source: https://iamreetesh.com/docs/evaluation

A linear path for trying Lextrix for the first time. No setup beyond a bundler or static HTML page.

**Using React or Next.js?** Prefer [`@lextrix/react`](/docs/react). See [Frameworks](/docs/frameworks) after step 5.

---

## 1. Try the playground

Open the [live playground](https://iamreetesh.com/lextrix) in your browser. No install required — edit content, switch themes, and try import/export panels.

---

## 2. Install Lextrix

```bash
npm install lextrix
```

Install only the **`lextrix`** package. Everything you need for a full editor ships in that bundle.

---

## 3. Import CSS

Lextrix does not inject styles. Import a theme in your app entry:

```javascript
import 'lextrix/snow.css';
```

Other themes: `lextrix/bubble.css`, `lextrix/slate.css`, `lextrix/dawn.css`.

---

## 4. Create an editor

```html
<div id="editor"></div>
```

```javascript
import Lextrix from 'lextrix';
import 'lextrix/snow.css';

const editor = new Lextrix('#editor', {
  theme: 'snow',
  placeholder: 'Start writing…',
  modules: {
    toolbar: [
      ['bold', 'italic', 'underline'],
      [{ header: [1, 2, false] }],
      [{ list: 'ordered' }, { list: 'bullet' }],
      ['link', 'clean'],
    ],
  },
});
```

You should see a toolbar and an editable area immediately.

---

## 5. Load content

**From ChangeSet JSON** (same shape as `getContents()`):

```javascript
editor.setContents([
  { insert: 'Hello Lextrix\n', attributes: { header: 1 } },
  { insert: 'Edit rich text in the browser.\n' },
]);
```

**From Markdown or HTML:**

```javascript
editor.importContent('# Title\n\n**Bold** paragraph.', 'markdown');
editor.importContent('<p>Hello <strong>world</strong></p>', 'html');
```

---

## 6. Export content

```javascript
const markdown = editor.exportContent('markdown');
const html = editor.exportContent('html');
const json = editor.getContents(); // ChangeSet
```

**Before Markdown or MDX export**, check for unsupported or lossy content:

```javascript
const warnings = editor.getExportWarnings('markdown');
for (const w of warnings) {
  console.warn(w.message);
}
const md = editor.exportContent('markdown');
```

Native editor tables **cannot** export to Markdown/MDX — export throws `SerializationError`. Use `exportContent('html')` instead. See [Serialization](/docs/serialization) for the full limitations list.

---

## 7. Image resize

Enable the opt-in **`imageResize`** module and include **`image`** in the toolbar (or insert an image programmatically). Select a single image — a corner handle appears; drag to resize. Aspect ratio is preserved.

```javascript
const editor = new Lextrix('#editor', {
  theme: 'snow',
  modules: {
    toolbar: [
      ['bold', 'italic'],
      ['link', 'image'],
      ['clean'],
    ],
    imageResize: {
      minWidth: 48,
      maxWidth: null, // null = editor width
    },
  },
});

// Insert via toolbar, drag-and-drop, or API:
editor.insertEmbed(0, 'image', 'https://example.com/photo.jpg');
```

**Programmatic resize** (sets the same `width` / `height` attributes as the handle):

```javascript
editor.formatText(imageIndex, 1, { width: '400', height: '300' }, 'user');
```

Does not apply to video or other embeds. Details: [Configuration — Image resize](/docs/configuration#image-resize) · [API reference — imageResize](/docs/commands#image-resize-imageresize)

---

## 8. Optional modules

These features are opt-in or configured via `modules`. Full API: [API reference — Modules](/docs/commands#modules).

### Undo / redo

Always available via `editor.history`. Keyboard: `Ctrl+Z` / `Ctrl+Shift+Z`.

```javascript
editor.history.undo();
editor.history.redo();
```

### Image upload

Override the default base64 handler to upload to your server:

```javascript
modules: {
  toolbar: [['bold', 'italic'], ['link', 'image'], ['clean']],
  uploader: {
    mimetypes: ['image/png', 'image/jpeg', 'image/webp'],
    async handler(range, files) {
      for (const file of files) {
        const body = new FormData();
        body.append('file', file);
        const res = await fetch('/api/upload', { method: 'POST', body });
        const { url } = await res.json();
        this.lextrix.insertEmbed(range.index, 'image', url, 'user');
        range.index += 1;
      }
    },
  },
}
```

Toolbar **image** and drag-and-drop both use this handler.

### Syntax highlighting

Load [highlight.js](https://highlightjs.org/) first, then enable the module:

```javascript
modules: {
  toolbar: [['bold', 'italic'], ['code-block'], ['clean']],
  syntax: {
    hljs: window.hljs,
    languages: [{ key: 'javascript', label: 'JavaScript' }],
  },
}
```

### Tables

```javascript
modules: {
  toolbar: [['bold', 'italic'], ['table'], ['clean']],
  table: true,
}

editor.getModule('table')?.insertTable(3, 4);
```

Remember: native tables cannot export to Markdown/MDX — use HTML export.

---

## 9. React / Next.js next steps

Prefer the official wrapper:

```bash
npm install lextrix @lextrix/react
```

- [React guide](/docs/react) — `LextrixEditor` (recommended)
- [Frameworks](/docs/frameworks) — Next.js, Vue, script tag, manual mount
- [DOM mounting](/docs/dom-mounting) — if you mount Lextrix yourself
- Examples: [vite-vanilla](https://github.com/rishureetesh/lextrix/tree/main/examples/vite-vanilla) · [vite-react](https://github.com/rishureetesh/lextrix/tree/main/examples/vite-react)

---

## 10. Troubleshooting

| Symptom | Fix |
|---------|-----|
| Unstyled editor | Import `lextrix/snow.css` (or another theme) |
| `document is not defined` | Client-only — see [Frameworks](/docs/frameworks) |
| Duplicate toolbars | Call `editor.destroy()` on unmount — [DOM mounting](/docs/dom-mounting) |
| Markdown export throws | Native table in document — use HTML export or check [Serialization](/docs/serialization) |
| No image resize handle | Enable `modules.imageResize` and select a **single** image — [Image resize](/docs/configuration#image-resize) |
| Code blocks not highlighted | Load highlight.js and enable `modules.syntax` — [API reference](/docs/commands#syntax-highlighting-syntax) |
| Upload does nothing | Check `uploader.mimetypes` matches file type — [API reference](/docs/commands#uploader-uploader) |

More recipes: [Cookbook](/docs/cookbook) · Full API: [API reference](/docs/commands)

---

## What to read next

| Goal | Guide |
|------|-------|
| Copy-paste recipes | [Cookbook](/docs/cookbook) |
| Save on change, uploads, tables | [Cookbook](/docs/cookbook) |
| Image resize | [Configuration — Image resize](/docs/configuration#image-resize) · [API reference](/docs/commands#image-resize-imageresize) |
| Upload, syntax, tables | [Optional modules](#8-optional-modules) · [API reference — Modules](/docs/commands#modules) |
| Custom serializers | [API reference — registerSerializer](/docs/commands#registerserializerserializer) |
| All import/export formats | [Serialization](/docs/serialization) |
| Module and toolbar options | [Configuration](/docs/configuration) |

---

## Cookbook

Source: https://iamreetesh.com/docs/cookbook

# Cookbook

Copy-paste recipes for common tasks. Written for application developers integrating the **npm** package.

**Start here if toolbars duplicate or themes break:** [DOM mounting](/docs/dom-mounting).

---

## 1. Minimal editor

```html
<div id="wrapper"></div>
```

```javascript
import Lextrix from 'lextrix';
import 'lextrix/snow.css';

const wrapper = document.getElementById('wrapper');
const mount = document.createElement('div');
wrapper.appendChild(mount);

const editor = new Lextrix(mount, {
  theme: 'snow',
  placeholder: 'Write here…',
});

editor.setContents([{ insert: 'Hello\n' }]);
```

---

## 2. Toolbar

```javascript
new Lextrix(mount, {
  theme: 'snow',
  modules: {
    toolbar: [
      ['bold', 'italic', 'underline', 'strike'],
      [{ header: [1, 2, 3, false] }],
      [{ list: 'ordered' }, { list: 'bullet' }],
      ['link', 'image'],
      ['clean'],
    ],
  },
});
```

Use your own toolbar DOM:

```javascript
modules: { toolbar: '#my-toolbar' }
```

Button names: see [Configuration — Toolbar](/docs/configuration#toolbar-buttons).

---

## 3. Save on change

```javascript
editor.on('text-change', (delta, oldDelta, source) => {
  if (source === 'user') {
    const json = editor.getContents();
    localStorage.setItem('draft', JSON.stringify(json));
  }
});
```

`source` is `'user'`, `'api'`, or `'silent'`. Ignore `'api'` if you do not want programmatic updates to trigger saves.

---

## 4. Load saved content

```javascript
const saved = localStorage.getItem('draft');
if (saved) {
  editor.setContents(JSON.parse(saved));
}
```

Or import from Markdown/HTML — [Serialization](/docs/serialization).

---

## 5. Read-only display

```javascript
new Lextrix(mount, {
  theme: 'snow',
  readOnly: true,
});
editor.setContents(documentJson);
```

---

## 6. Serialization (Markdown, HTML, MDX, JSON)

```javascript
// Export
const md = editor.exportContent('markdown');
const html = editor.exportContent('html');

// Import (replaces document)
editor.importContent('# Title\n\n**bold**', 'markdown');
editor.importContent('<p>Hello</p>', 'html');

// Slice
const slice = editor.exportContent({ format: 'html', index: 0, length: 50 });
```

Tables: native editor tables cannot export to Markdown/MDX — use HTML. Details: [Serialization](/docs/serialization).

---

## 7. Undo / redo

Keyboard: `Ctrl+Z` / `Ctrl+Shift+Z` (focus must be in the editor).

```javascript
editor.history.undo();
editor.history.redo();
editor.history.clear(); // new document / discard stack
```

Programmatic changes use `source: 'api'` by default and are undoable unless `history.userOnly` is true.

---

## 8. Image upload to your server

Default: base64 in document. Override uploader:

```javascript
modules: {
  uploader: {
    mimetypes: ['image/png', 'image/jpeg', 'image/webp'],
    async handler(range, files) {
      for (const file of files) {
        const body = new FormData();
        body.append('file', file);
        const res = await fetch('/api/upload', { method: 'POST', body });
        const { url } = await res.json();
        this.lextrix.insertEmbed(range.index, 'image', url, 'user');
        range.index += 1;
      }
    },
  },
}
```

Toolbar **image** button and drag-and-drop both use this handler.

---

## 9. Image resize

```javascript
modules: { imageResize: { minWidth: 48 } }
```

Select an image in the editor — drag the corner handle.

---

## 10. Syntax highlighting

Load [highlight.js](https://highlightjs.org/) on the page first.

```javascript
modules: {
  syntax: {
    hljs: window.hljs,
    languages: [
      { key: 'javascript', label: 'JavaScript' },
      { key: 'python', label: 'Python' },
    ],
  },
}
```

---

## 11. Tables

```javascript
modules: { table: true }

editor.getModule('table').insertTable(3, 4); // rows, columns
```

---

## 12. Switch theme at runtime

See [Themes](/docs/themes). Summary:

1. `getContents()`
2. Swap CSS
3. `wrapper.replaceChildren()`
4. New mount + `new Lextrix`
5. `setContents()`

---

## 13. React / Next.js

Full guide: [Framework integration](/docs/frameworks).

Rules:

- `'use client'` + `dynamic(..., { ssr: false })` in Next.js
- **Wrapper ref** + inner mount div
- `import Lextrix from 'lextrix'` (default import)
- Never `<Lextrix />` in JSX

---

## 14. Custom formats (npm)

```javascript
import Lextrix, { lxrPath } from 'lextrix';

class CalloutBlot {
  // blot implementation …
}

Lextrix.register({ [lxrPath.format('callout')]: CalloutBlot });
```

`defineInlineTagFormat` and similar helpers need the monorepo. See [Formats](/docs/plugins).

---

## 15. Custom serializers

```javascript
import { registerSerializer } from 'lextrix';
import { ChangeSet } from 'lextrix';

registerSerializer({
  format: 'plain',
  import: (text) => new ChangeSet().insert(text).insert('\n'),
  export: (delta) => delta.getText(),
});
```

Call **before** `new Lextrix()`.

---

## 16. Check export warnings (Markdown / MDX)

```javascript
const warnings = editor.getExportWarnings('markdown');
for (const w of warnings) {
  console.warn(w.message); // tables blocked, color/align lossy, etc.
}
const md = editor.exportContent('markdown'); // throws if native table present
```

---

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Multiple toolbars | Old 2.0.0 sibling toolbar, or no `destroy()` on remount | Upgrade to 2.0.1+; call `editor.destroy()` |
| `Element type is invalid… undefined` | React: wrong import or `<Lextrix />` | [Frameworks](/docs/frameworks) |
| `document is not defined` | SSR / Server Component | Client-only + `ssr: false` |
| Unstyled editor | Theme CSS not imported | `import 'lextrix/snow.css'` |
| Undo does nothing | Editor not focused | `wrapper.click()` or `editor.focus()` |
| `{ ChangeSet }` undefined (2.0.0) | Old UMD-only build | Upgrade to **2.0.1+** |

---

## API index

| Task | Methods |
|------|---------|
| Content | `getContents`, `setContents`, `getText`, `updateContents` |
| Format | `format`, `formatText`, `removeFormat` |
| Selection | `getSelection`, `setSelection`, `focus` |
| Events | `on('text-change')`, `on('selection-change')` |
| Serialize | `importContent`, `exportContent` |

Full list: [API reference](/docs/commands).

---

## React Integration

Source: https://iamreetesh.com/docs/react

# React integration

Use **`@lextrix/react`** for a typed component with correct mount/teardown. Install **both** packages:

```bash
npm install lextrix @lextrix/react react react-dom
```

Import a theme stylesheet (required):

```ts
import 'lextrix/snow.css';
```

## `LextrixEditor`

```tsx
'use client'; // Next.js App Router only

import { useState } from 'react';
import { LextrixEditor } from '@lextrix/react';
import 'lextrix/snow.css';

export function BlogEditor() {
  const [body, setBody] = useState('# Draft\n');

  return (
    <LextrixEditor
      theme="snow"
      format="markdown"
      value={body}
      onChange={setBody}
      options={{
        placeholder: 'Write your post…',
        modules: {
          toolbar: [['bold', 'italic'], ['link', 'image'], ['clean']],
          imageResize: true,
        },
      }}
      style={{ minHeight: 320 }}
    />
  );
}
```

### Props

| Prop | Description |
|------|-------------|
| `theme` | `snow`, `bubble`, `slate`, `dawn` — changing remounts the editor |
| `options` | `LextrixOptions` (minus `theme`); applied on **mount only** |
| `value` / `defaultValue` | Document string in `format` |
| `format` | `html` \| `markdown` \| `mdx` \| `json` (default `html`) |
| `onChange` | `(content, source) => void` after user edits |
| `onSelectionChange` | Lextrix selection event |
| `onReady` | `(editor) => void` once after create |
| `className` / `style` | Wrapper element |

### Ref handle

```tsx
import { useRef } from 'react';
import type { LextrixEditorHandle } from '@lextrix/react';

const ref = useRef<LextrixEditorHandle>(null);

<LextrixEditor ref={ref} onReady={(e) => e.focus()} />;

ref.current?.exportContent('markdown');
ref.current?.getEditor()?.getModule('history')?.undo();
```

## Remounting when options change

`options` are not deep-watched. Remount with `key` when modules or placeholder change:

```tsx
<LextrixEditor key={locale} options={{ placeholder: t('placeholder') }} />
```

## Next.js

- Component ships with `'use client'`
- Do not import `lextrix` or `@lextrix/react` in Server Components
- Dynamic import optional if you need to defer CSS:

```tsx
import dynamic from 'next/dynamic';

const LextrixEditor = dynamic(
  () => import('@lextrix/react').then((m) => m.LextrixEditor),
  { ssr: false },
);
```

## Manual integration (no wrapper)

See [Framework integration](/docs/frameworks#react-vite-cra-etc) for the wrapper-ref pattern behind this component.

## Example app

```bash
npm run build
npm run example:react
```

Source: [`examples/vite-react`](https://github.com/rishureetesh/lextrix/tree/main/examples/vite-react).

---

## Framework Integration

Source: https://iamreetesh.com/docs/frameworks

Lextrix is a **DOM-based editor**. Vanilla apps call `new Lextrix(container, options)`. React apps should use **[`@lextrix/react`](/docs/react)** (`LextrixEditor`).

## npm package layout

| Package / import | When to use |
|------------------|-------------|
| `lextrix` | Core editor (required for everyone) |
| `@lextrix/react` | Official React component — install **with** `lextrix` |
| `import Lextrix from 'lextrix'` | Bundlers resolve the **ESM** build |
| `import { ChangeSet, registerSerializer, lxrPath } from 'lextrix'` | Named APIs |
| `import 'lextrix/snow.css'` | Theme stylesheet (required) |
| Script tag `lextrix.js` | UMD global `window.Lextrix` |

Always import a theme CSS file. The editor does not inject styles.

### npm vs monorepo

| Need | npm | Monorepo (clone repo) |
|------|-----|------------------------|
| Editor + themes + serialization | `lextrix` | Same |
| React component | `lextrix` + `@lextrix/react` | `packages/react` |
| `ChangeSet`, `registerSerializer`, `lxrPath` | `import { … } from 'lextrix'` | Same |
| Custom blots | `Lextrix.register()` | Or import from `lextrix-formats` |
| Headless serialize only | Editor APIs, or clone for `lextrix-serialize` | `lextrix-serialize` |

Lextrix requires a browser (`document`). Do not import it in Server Components without a client-only boundary.

**Toolbar / remount bugs?** Read [DOM mounting](/docs/dom-mounting) — call `editor.destroy()` (or use `@lextrix/react`, which does this for you).

---

## React

**Recommended:** [`@lextrix/react`](/docs/react)

```bash
npm install lextrix @lextrix/react
```

```tsx
import { LextrixEditor } from '@lextrix/react';
import 'lextrix/snow.css';

<LextrixEditor theme="snow" defaultValue="# Hello\n" format="markdown" />;
```

### Manual mount (advanced)

Only if you cannot use `@lextrix/react`. Use a **wrapper ref**, a **fresh inner div**, and `destroy()` on teardown.

```tsx
'use client'; // Next.js App Router only

import { useEffect, useRef } from 'react';
import Lextrix from 'lextrix';
import 'lextrix/snow.css';

export default function ManualEditor() {
  const wrapperRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const wrapper = wrapperRef.current;
    if (!wrapper) return;

    const mount = document.createElement('div');
    wrapper.appendChild(mount);

    const editor = new Lextrix(mount, {
      theme: 'snow',
      placeholder: 'Start writing…',
      modules: {
        toolbar: [
          ['bold', 'italic', 'underline'],
          [{ header: [1, 2, false] }],
          [{ list: 'ordered' }, { list: 'bullet' }],
          ['link', 'clean'],
        ],
      },
    });

    editor.setContents([{ insert: 'Hello Lextrix\n' }]);

    return () => {
      editor.destroy();
      wrapper.replaceChildren();
    };
  }, []);

  return <div ref={wrapperRef} className="lxr-mount" />;
}
```

**Do not** render `<Lextrix />` — `Lextrix` is a class, not a React component.

For theme switching and controlled Markdown, prefer [`LextrixEditor`](/docs/react) with a remount `key` instead of hand-rolling effects.

See [Themes](/docs/themes) · [React guide](/docs/react).

---

## Next.js App Router

Use `@lextrix/react` from a **client** component (it includes `'use client'`):

```tsx
'use client';

import { LextrixEditor } from '@lextrix/react';
import 'lextrix/snow.css';

export default function PageEditor() {
  return <LextrixEditor theme="snow" format="markdown" />;
}
```

Optional lazy load:

```tsx
import dynamic from 'next/dynamic';

const LextrixEditor = dynamic(
  () => import('@lextrix/react').then((m) => m.LextrixEditor),
  { ssr: false },
);
```

Do not import `lextrix` or `@lextrix/react` in Server Components.

---

## Vue 3

```vue
<script setup>
import { onBeforeUnmount, onMounted, ref } from 'vue';
import Lextrix from 'lextrix';
import 'lextrix/snow.css';

const wrapper = ref(null);
let editor;

onMounted(() => {
  const mount = document.createElement('div');
  wrapper.value.appendChild(mount);
  editor = new Lextrix(mount, {
    theme: 'snow',
    modules: { toolbar: [['bold', 'italic'], ['link']] },
  });
});

onBeforeUnmount(() => {
  editor?.destroy();
  wrapper.value?.replaceChildren();
});
</script>

<template>
  <div ref="wrapper" />
</template>
```

---

## Script tag (no bundler)

Use the published package from **npm** or a **CDN**. After `npm install lextrix`, files are at the package root (e.g. `node_modules/lextrix/lextrix.snow.css`).

**From npm (local static server):**

```html
<link rel="stylesheet" href="node_modules/lextrix/lextrix.snow.css" />
<div id="editor"></div>
<script src="node_modules/lextrix/lextrix.js"></script>
<script>
  const editor = new Lextrix('#editor', { theme: 'snow' });
</script>
```

**From jsDelivr CDN** (pin the version you use):

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/lextrix@2.0.5/lextrix.snow.css" />
<div id="editor"></div>
<script src="https://cdn.jsdelivr.net/npm/lextrix@2.0.5/lextrix.js"></script>
<script>
  const editor = new Lextrix('#editor', { theme: 'snow' });
</script>
```

UMD exposes `window.Lextrix` only. Named exports (`ChangeSet`, `registerSerializer`, …) require a bundler and the ESM entry (`import Lextrix from 'lextrix'`).

---

## Migrating from Quill

| Quill | Lextrix |
|-------|---------|
| `new Quill(el, opts)` | `new Lextrix(el, opts)` |
| `quill.getContents()` (Delta) | `editor.getContents()` (ChangeSet) |
| `quill.root.innerHTML` | `editor.exportContent('html')` |
| `import 'quill/dist/quill.snow.css'` | `import 'lextrix/snow.css'` |
| Delta | **ChangeSet** (same JSON shape, different name) |

See [change-set.md](https://github.com/rishureetesh/lextrix/blob/main/docs/guides/change-set.md) and [serialization.md](/docs/serialization).

---

## TypeScript

Source: https://iamreetesh.com/docs/typescript

# TypeScript

The published `lextrix` npm package includes hand-written declarations (`lextrix.d.ts`).

## Setup

```bash
npm install lextrix
```

```typescript
import Lextrix, { ChangeSet, lxrPath } from 'lextrix';
import type {
  LextrixOptions,
  LextrixModulesConfig,
  ImageResizeOptions,
  TableModule,
  ContentSerializer,
  SafetyIssue,
  Range,
} from 'lextrix';
import 'lextrix/snow.css';

const modules: LextrixModulesConfig = {
  toolbar: [['bold', 'italic'], ['link', 'image']],
  table: true,
  imageResize: { minWidth: 48 } satisfies ImageResizeOptions,
  syntax: { hljs: globalThis.hljs, languages: [{ key: 'javascript', label: 'JS' }] },
};

const options: LextrixOptions = { theme: 'snow', modules };

const editor = new Lextrix('#editor', options);
const table = editor.getModule('table') as TableModule | undefined;
table?.insertTable(3, 3);
```

No `@types/lextrix` package is required.

## Covered APIs

- `Lextrix` class and `LextrixOptions`
- Module config types: `LextrixModulesConfig`, `ImageResizeOptions`, `ToolbarModuleOptions`, `SyntaxModuleOptions`, `UploaderModuleOptions`, `HistoryModuleOptions`, `ClipboardModuleOptions`
- `TableModule` and `getModule('table')`
- `ImageResizeModule` and `getModule('imageResize')`
- `setText`, `getLeaf`, `getLine`, `getLines`, `getIndex`, `scrollSelectionIntoView`
- `importContent`, `exportContent`, `listExportFormats`, `getExportWarnings`
- `text-change` and `selection-change` handler signatures
- `ChangeSet`, `Range`, `SafetyIssue`, `ContentSerializer`, serialization types
- Named exports: `ChangeSet`, `lxrPath`, `registerSerializer`, `getMarkdownExportWarnings`, …

## Gaps

Declarations are maintained manually and may lag new APIs. Report missing types on [GitHub Issues](https://github.com/rishureetesh/lextrix/issues).

Advanced blot types (`Block`, `LeafBlot`, …) are not exported from the npm bundle types — use `unknown` or clone the monorepo for full internal typings.

## Example

See [examples/vite-react](https://github.com/rishureetesh/lextrix/tree/main/examples/vite-react) for a typed React + Vite project.

---

## DOM Mounting

Source: https://iamreetesh.com/docs/dom-mounting

# DOM mounting (read this first)

Lextrix is not a single DOM node. Understanding the layout prevents duplicate toolbars and leaked listeners.

## What Lextrix creates

When you call `new Lextrix(mountElement, options)`:

1. **`mountElement`** becomes `editor.container` (class `lxr-container`).
2. If `modules.toolbar` is an **array**, Lextrix adds **`div.lxr-toolbar`** as the **first child** of `mountElement` (since 2.0.1).
3. Inside `mountElement`, **`div.lxr-editor`** holds the editable surface.

```
div (mountElement — passed to new Lextrix)
├── div.lxr-toolbar      ← when toolbar is a config array
└── div.lxr-editor       ← editable area
```

Older 2.0.0 inserted the toolbar as a **sibling before** the mount node. Upgrade to **2.0.1+** if you still see stacked toolbars outside the mount.

## Cleanup

### Preferred: `editor.destroy()`

```javascript
const editor = new Lextrix(mount, { theme: 'snow', modules: { toolbar: [...] } });

// theme switch, route leave, React unmount
editor.destroy();
```

`destroy()` removes the auto-created toolbar, clears theme `document.body` listeners, drops emitter handlers, and runs `mountElement.replaceChildren()`.

### Manual: clear the mount element

```javascript
mount.replaceChildren(); // removes toolbar + editor inside mount (2.0.1+)
```

### React wrapper pattern

Still use an outer **wrapper** you control — especially when swapping themes or remounting:

```tsx
const wrapperRef = useRef<HTMLDivElement>(null);
const editorRef = useRef<Lextrix | null>(null);

useEffect(() => {
  const wrapper = wrapperRef.current;
  if (!wrapper) return;

  const mount = document.createElement('div');
  wrapper.appendChild(mount);

  const editor = new Lextrix(mount, { theme, modules: { toolbar: [...] } });
  editorRef.current = editor;

  return () => {
    editor.destroy();
    editorRef.current = null;
    wrapper.replaceChildren();
  };
}, [theme]);
```

## Custom toolbar element

| `modules.toolbar` | Toolbar location |
|-------------------|------------------|
| Array `[['bold'], …]` | Auto `div.lxr-toolbar` inside mount |
| `'#my-toolbar'` | Your existing element |
| `{ container: HTMLElement }` | Your element |

You manage cleanup for custom toolbar DOM.

## Theme CSS

Load one theme CSS file (`import 'lextrix/snow.css'`). When switching themes at runtime, swap CSS then `destroy()` + recreate. See [Themes](/docs/themes).

## Peer dependencies

| Feature | Requires | If missing (2.0.1+) |
|---------|----------|---------------------|
| Formula button | [KaTeX](https://katex.org/) on `window.katex` | Button hidden; paste/import shows LaTeX source |
| Syntax highlighting | [highlight.js](https://highlightjs.org/) | Module no-ops; code blocks work unhighlighted |

## Markdown export warnings

Before `exportContent('markdown'|'mdx')`:

```javascript
const warnings = editor.getExportWarnings('markdown');
// e.g. native tables (blocked), color/align (lossy)
```

Native editor tables still **throw** on export — use HTML or check warnings first.

---

## Serialization

Source: https://iamreetesh.com/docs/serialization

Import and export editor content as HTML, Markdown, MDX, or JSON. All formats go through **ChangeSet** — the same model as `getContents()`, clipboard, and OT.

There is no direct HTML ↔ Markdown ↔ MDX conversion. To change formats, import into the editor (or `SerializerHost`) and export the target format.

## Quick start

```typescript
import Lextrix from 'lextrix';

const editor = new Lextrix('#editor');

const html = editor.exportContent('html');
const md = editor.exportContent('markdown');

editor.importContent('<p>Hello <strong>world</strong></p>', 'html');
editor.importContent('# Title\n\nParagraph.', 'markdown');
```

Use `importContent` / `exportContent` instead of `import` / `export`. `Lextrix.import()` is the module loader and is unrelated.

## Limitations

| Topic | Behavior |
|-------|----------|
| Native editor tables → Markdown/MDX | Throws `SerializationError` (`TABLE_EXPORT_UNSUPPORTED`). Use `exportContent('html')`. |
| GFM tables (Markdown import) | Simple tables round-trip. No colspan, rowspan, or merged cells. |
| HTML round-trip | Partial. Export uses `getSemanticHTML()`; re-import normalizes DOM structure. |
| Markdown dialect | Subset only — not full CommonMark/GFM. |
| MDX components | Experimental. JSX preserved as text unless you register handlers. |
| Ordered lists | Numbering is sequential (`1.`, `2.`, …); nested lists restart at `1.` per indent level |
| Combined bold+italic | May export as bold only |
| Align, color, font | HTML/JSON only — not exported to Markdown/MDX |
| Video embed | Markdown/MDX export as \`[video](url)\` |
| Horizontal rule | Literal `---` paragraph exports as `\-\-\-` so it does not become a thematic break |
| Inline escaping | Only `\*`, `` \` ``, `\_`, `\[`, `\]` — not `.` or `!` at end of sentences |

### MDX components (experimental)

`registerMdxComponent` is not stable API.

- Unknown JSX is stored as raw text with an `mdx-component` block attribute
- Frontmatter and `import`/`export` lines are stripped on import
- Parsing uses regex, not an AST — nested or complex JSX will miss edge cases
- No component embed blot, in-editor preview, or JSX runtime
- Use MDX export for CMS storage; register `toChangeSet` / `fromChangeSet` only for components you control and test

## API

### Editor

```typescript
editor.exportContent(format: string): string
editor.exportContent({ format, index?, length? }): string

editor.importContent(content: string, format: string, source?: EmitterSource): void

editor.listExportFormats(): string[]
```

`export()` and `import()` are aliases. Prefer `exportContent` / `importContent` in application code.

### Global registration

```typescript
import { registerSerializer, registerMdxComponent } from 'lextrix';
import ChangeSet from 'lextrix-change';

registerSerializer({
  format: 'plain',
  import: (text) => new ChangeSet([{ insert: text }, { insert: '\n' }]),
  export: (delta) => delta.getText(),
});
```

Call `registerSerializer` before creating editors. Serializers registered globally are merged into each editor unless `serializers: false`.

### Headless (`lextrix-serialize`)

Monorepo / contributors only — the npm package bundles serialization into `lextrix`; use `editor.importContent` / `exportContent` in apps.

```typescript
import {
  SerializerHost,
  createSerializerRegistry,
  markdownSerializer,
} from 'lextrix-serialize';

const host = new SerializerHost(createSerializerRegistry([markdownSerializer()]));

const delta = host.parse('# Hello', 'markdown');
const md = host.stringify(delta, 'markdown');
```

`host.export()` needs a bound editor adapter. For headless export, use `host.stringify()`.

### `LextrixOptions.serializers`

| Value | Effect |
|-------|--------|
| omitted or `true` | Built-in formats (json, html, markdown, mdx) plus globals |
| `ContentSerializer[]` | Listed serializers plus globals |
| `false` | No serializers, including globals |

## Examples

### Partial export

```typescript
const slice = editor.exportContent({ format: 'html', index: 0, length: 100 });
```

### React / Next.js

Prefer **[`@lextrix/react`](/docs/react)** so mount/teardown and `format` are handled for you:

```tsx
import { LextrixEditor } from '@lextrix/react';
import 'lextrix/snow.css';

<LextrixEditor
  theme="snow"
  format="mdx"
  value={initialMdx}
  onChange={(mdx) => save(mdx)}
/>
```

Manual mount pattern: [Frameworks](/docs/frameworks) · [DOM mounting](/docs/dom-mounting).
### Migration from older patterns

| Before | After |
|--------|-------|
| `editor.getSemanticHTML()` | `editor.exportContent('html')` |
| `clipboard.convert({ html })` + `setContents` | `editor.importContent(html, 'html')` |
| `JSON.stringify(editor.getContents().ops)` | `editor.exportContent('json')` |

## How it works

```
HTML / Markdown / MDX / JSON
        ↓ import
    ChangeSet
        ↓ export
HTML / Markdown / MDX / JSON
```

| Package | Role |
|---------|------|
| `lextrix-change` | ChangeSet ops |
| `lextrix-modules/html-import` | HTML string → ChangeSet (shared with clipboard paste) |
| `lextrix-core` | Editor API, HTML export via blot tree |
| `lextrix-serialize` | Markdown, MDX, JSON ↔ ChangeSet; registry; host |

`lextrix-serialize` does not depend on `lextrix-core`. HTML export is DOM-backed, not derived purely from ChangeSet.

## Testing

```bash
npm run test -w lextrix-serialize
npm run test -w lextrix-core
npm run test:unit -w lextrix
```

Tests: `packages/serialize/tests/`, `packages/lextrix/test/unit/core/serialization.spec.ts`, `packages/lextrix/test/e2e/serialization.spec.ts`.

---

## API Reference

Source: https://iamreetesh.com/docs/commands

# API reference

Lextrix exposes a familiar rich-text API centered on **ChangeSet** (operational transforms over document content).

## Construction

```javascript
const editor = new Lextrix(container, options);
```

Static properties: `Lextrix.version`, `Lextrix.events`, `Lextrix.sources`, `Lextrix.import()`, `Lextrix.register()`.

### Lifecycle

| Method | Description |
|--------|-------------|
| `destroy()` | Remove toolbar, theme listeners, and editor DOM inside the mount container |
| `getExportWarnings(input)` | Lossy/unsupported issues before Markdown/MDX export (does not throw) |

See [DOM mounting](/docs/dom-mounting).

### Editor options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `theme` | `string` | `'snow'` | `snow` \| `bubble` \| `slate` \| `dawn` |
| `placeholder` | `string` | `''` | Shown when the document is empty |
| `readOnly` | `boolean` | `false` | Disable editing (`editor.enable()` / `disable()`) |
| `bounds` | `HTMLElement` \| `string` \| `null` | `null` | Root for tooltip positioning |
| `formats` | `string[]` \| `null` | `null` | Whitelist of format names; `null` = all registered |
| `modules` | `object` | `{}` | Module configuration — see [Modules](#modules) |
| `debug` | `boolean` \| `string` | `false` | Log level for development |

```javascript
new Lextrix('#editor', {
  theme: 'snow',
  placeholder: 'Write here…',
  readOnly: false,
  modules: { toolbar: [['bold', 'italic']], table: true },
});
```

## Serialization

Import and export whole documents or slices. Prefer **`importContent`** / **`exportContent`** in application code — not `Lextrix.import()`, which loads internal modules.

Full limitations (tables, lossy formats): [Serialization guide](/docs/serialization).

### `importContent(content, format, source?)`

| | |
|---|---|
| **Parameters** | `content` — string to parse · `format` — `'html'` \| `'markdown'` \| `'mdx'` \| `'json'` · `source` — optional `'user'` \| `'api'` \| `'silent'` (default `'api'`) |
| **Returns** | `ChangeSet` applied to the editor (document replaced) |

```javascript
editor.importContent('# Hello\n\n**bold**', 'markdown');
editor.importContent('<p>Hello <strong>world</strong></p>', 'html');
```

### `exportContent(input)`

| | |
|---|---|
| **Parameters** | `input` — format string (`'html'`, `'markdown'`, `'mdx'`, `'json'`) **or** `{ format, index?, length? }` for a slice |
| **Returns** | `string` — serialized content |
| **Throws** | `SerializationError` when export is unsupported (e.g. native editor table → Markdown/MDX) |

```javascript
const md = editor.exportContent('markdown');
const html = editor.exportContent('html');
const slice = editor.exportContent({ format: 'html', index: 0, length: 50 });
```

Aliases: `editor.import()` / `editor.export()` — same behavior.

### `listExportFormats()`

| | |
|---|---|
| **Returns** | `string[]` — formats registered for this editor (default includes `html`, `markdown`, `mdx`, `json`) |

```javascript
editor.listExportFormats(); // ['html', 'markdown', 'mdx', 'json', …]
```

### `getExportWarnings(input)`

| | |
|---|---|
| **Parameters** | Same shape as `exportContent` — format string or `{ format, index?, length? }`. Only **`markdown`** and **`mdx`** produce warnings. |
| **Returns** | `SafetyIssue[]` — `{ feature, safety: 'lossy' \| 'unsupported', message }`. Does **not** throw. |

```javascript
const warnings = editor.getExportWarnings('markdown');
if (warnings.some((w) => w.safety === 'unsupported')) {
  // e.g. native editor table — use exportContent('html') instead
}
const md = editor.exportContent('markdown'); // throws if unsupported content remains
```

## Content

| Method | Description |
|--------|-------------|
| `getContents(index?, length?)` | ChangeSet JSON |
| `setContents(delta, source?)` | Replace document |
| `getText(index?, length?)` | Plain text |
| `getLength()` | Document length |
| `getSemanticHTML(index?, length?)` | HTML string |
| `insertText(index, text, formats?, source?)` | Insert text |
| `insertEmbed(index, name, value, source?)` | Insert image, video, formula |
| `deleteText(index, length, source?)` | Delete range |
| `updateContents(delta, source?)` | Apply ChangeSet |

## Formatting

| Method | Description |
|--------|-------------|
| `format(name, value, source?)` | Format at cursor |
| `formatText(index, length, name, value, source?)` | Format range |
| `formatLine(index, length, name, value, source?)` | Block format |
| `getFormat(index?, length?)` | Active formats |
| `removeFormat(index, length, source?)` | Clear inline formats |

## Selection

| Method | Description |
|--------|-------------|
| `getSelection(focus?)` | `{ index, length }` or null |
| `setSelection(index, length?, source?)` | Set selection |
| `getBounds(index, length?)` | Pixel rect for caret/range |
| `focus()` / `blur()` / `hasFocus()` | Focus management |

## History

Access via `editor.history` (always loaded). Configure with `modules.history`.

| Method | Description |
|--------|-------------|
| `history.undo()` | Undo |
| `history.redo()` | Redo |
| `history.clear()` | Clear stacks |
| `history.cutoff()` | Start a new undo branch |

Keyboard: `Ctrl+Z` / `Ctrl+Shift+Z` when the editor is focused.

**Module options** (`modules.history`):

| Option | Default | Description |
|--------|---------|-------------|
| `delay` | `1000` | Milliseconds before merging consecutive undo steps |
| `maxStack` | `100` | Maximum undo depth |
| `userOnly` | `false` | When `true`, only `'user'`-sourced changes are undoable |

## Modules

Core modules (`clipboard`, `keyboard`, `history`, `uploader`) load automatically. Opt-in modules require `modules.<name>` in constructor options.

```javascript
editor.getModule('toolbar');
editor.getModule('table');
editor.getModule('syntax');
editor.getModule('imageResize');
editor.clipboard;   // shorthand
editor.keyboard;
editor.uploader;
editor.history;
```

### Toolbar (`toolbar`)

| | |
|---|---|
| **Enable** | `modules: { toolbar: […] }` — button groups array, `'#selector'`, or `{ container, handlers }` |
| **Access** | `editor.getModule('toolbar')` |

Pass an array to auto-create `div.lxr-toolbar` as the **first child** of the mount element:

```javascript
modules: {
  toolbar: [
    ['bold', 'italic', 'underline'],
    [{ header: [1, 2, false] }],
    ['link', 'image', 'video', 'formula', 'table'],
    ['clean'],
  ],
}
```

Custom handlers override theme defaults:

```javascript
modules: {
  toolbar: {
    container: [['image'], ['table']],
    handlers: {
      table() {
        this.lextrix.getModule('table')?.insertTable(3, 3);
      },
    },
  },
}
```

More: [Configuration — Toolbar buttons](/docs/configuration#toolbar-buttons)

### Table (`table`)

| | |
|---|---|
| **Enable** | `modules: { table: true }` |
| **Access** | `editor.getModule('table')` |

```javascript
editor.getModule('table')?.insertTable(3, 4); // rows, columns
```

Also: `insertRowAbove()`, `insertRowBelow()`, `insertColumnLeft()`, `insertColumnRight()`, `deleteRow()`, `deleteColumn()`.

Native editor tables **cannot** export to Markdown/MDX — use `exportContent('html')`. See [Serialization](/docs/serialization).

### Syntax highlighting (`syntax`)

| | |
|---|---|
| **Enable** | `modules: { syntax: true }` or options object |
| **Requires** | [highlight.js](https://highlightjs.org/) on the page (`window.hljs`) |

```javascript
modules: {
  syntax: {
    hljs: window.hljs,
    languages: [
      { key: 'javascript', label: 'JavaScript' },
      { key: 'python', label: 'Python' },
    ],
  },
}
```

Without highlight.js the module no-ops (code blocks still work, without token colors).

### Uploader (`uploader`)

Always loaded. Handles drag-and-drop and the toolbar **image** button.

| Option | Default | Description |
|--------|---------|-------------|
| `mimetypes` | `['image/png', 'image/jpeg']` | Allowed file types |
| `handler` | base64 embed | `(range, files) => void` — `this.lextrix` is the editor |

```javascript
modules: {
  uploader: {
    mimetypes: ['image/png', 'image/jpeg', 'image/webp'],
    async handler(range, files) {
      for (const file of files) {
        const body = new FormData();
        body.append('file', file);
        const res = await fetch('/api/upload', { method: 'POST', body });
        const { url } = await res.json();
        this.lextrix.insertEmbed(range.index, 'image', url, 'user');
        range.index += 1;
      }
    },
  },
}
```

### Clipboard (`clipboard`)

Always loaded. Normalizes paste from HTML, Word, Google Docs.

| Option | Description |
|--------|-------------|
| `matchers` | `[selector, matcherFn][]` — custom HTML → ChangeSet rules |

```javascript
modules: {
  clipboard: {
    matchers: [
      ['B', (node, delta) => delta.insert(node.textContent ?? '', { bold: true })],
    ],
  },
}
```

### Image resize (`imageResize`)

Opt-in module. When exactly **one image embed** is selected, shows a corner drag handle and preserves aspect ratio while resizing.

| | |
|---|---|
| **Enable** | `modules: { imageResize: true }` or an options object (see below) |
| **Access** | `editor.getModule('imageResize')` |
| **Applies to** | Image embeds only — not video, formula, or other embeds |

**Options** (pass as `modules.imageResize`):

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `minWidth` | `number` | `48` | Minimum width in pixels |
| `maxWidth` | `number` \| `null` | `null` | Maximum width; `null` = editor root width |

```javascript
modules: {
  toolbar: [['bold', 'italic'], ['link', 'image'], ['clean']],
  imageResize: { minWidth: 48, maxWidth: null },
},
```

Select an image in the editor, then drag the handle. Resize commits `width` and `height` attributes on the image blot.

**Programmatic resize** (same attributes the handle sets):

```javascript
editor.formatText(index, 1, { width: '400', height: '300' }, 'user');
```

Requires theme CSS (included in `lextrix/snow.css`, etc.) for `.lxr-image-resize` overlay styles.

The overlay mounts on `.lxr-container` and repositions after layout settles (selection, scroll, and resize). Always call `editor.destroy()` on unmount.

More: [Configuration — Image resize](/docs/configuration#image-resize) · [Modules](/docs/plugins#image-resize)

## Registration helpers

Call **before** `new Lextrix()` unless noted.

### `registerSerializer(serializer)`

Register a custom import/export format globally.

| | |
|---|---|
| **Parameter** | `{ format, import(content, context?), export(changeSet, context?) }` |
| **See also** | [Serialization — Custom serializers](/docs/serialization) |

```javascript
import { registerSerializer } from 'lextrix';

registerSerializer({
  format: 'plain',
  import: (text) => [{ insert: text }],
  export: (delta) => delta.getText(),
});
```

### `unregisterSerializer(format)`

Remove a registered format. Returns `boolean`.

### `registerMdxComponent(name, handler)`

Register a JSX component handler for MDX import/export. Experimental — see [Serialization](/docs/serialization).

### `getMarkdownExportWarnings(delta)`

Headless helper — same warnings as `editor.getExportWarnings('markdown')` without an editor instance.

```javascript
import { getMarkdownExportWarnings, ChangeSet } from 'lextrix';

getMarkdownExportWarnings(new ChangeSet().insert('Hello\n'));
```

## Events

```javascript
editor.on('text-change', (delta, oldDelta, source) => {});
editor.on('selection-change', (range, oldRange, source) => {});
editor.on('editor-change', (eventName, ...args) => {});
```

Sources: `'user'`, `'api'`, `'silent'`.

## ChangeSet

```javascript
import { ChangeSet } from 'lextrix';

new ChangeSet()
  .retain(5)
  .insert('Hello', { bold: true })
  .delete(2);
```

Legacy name `Delta` is not supported — use `ChangeSet`. See the [ChangeSet guide](https://github.com/rishureetesh/lextrix/blob/main/docs/guides/change-set.md).

## Registry paths

Register custom formats or modules:

```javascript
import Lextrix, { lxrPath } from 'lextrix';

Lextrix.register({ [lxrPath.format('callout')]: CalloutBlot });
Lextrix.register({ [lxrPath.module('mentions')]: MentionsModule });
```

Bare paths like `formats/bold` or `parchment` throw — use `lxr/*` paths only. See the [Formats guide](/docs/plugins#registration). Advanced blot helpers (`defineInlineTagFormat`, …) require the monorepo — see [Framework integration](/docs/frameworks).

---

## Themes

Source: https://iamreetesh.com/docs/themes

Four built-in themes: **snow**, **bubble**, **slate**, **dawn**.

## Install CSS

Themes are separate CSS files. Import exactly one (or swap at runtime):

```javascript
import 'lextrix/snow.css';
// import 'lextrix/bubble.css';
// import 'lextrix/slate.css';
// import 'lextrix/dawn.css';
```

| Theme | Toolbar style | Best for |
|-------|---------------|----------|
| `snow` | Fixed bar above editor | Docs, CMS, classic UI |
| `bubble` | Floating on selection | Comments, inline editing |
| `slate` | Dark snow-like bar | Dark apps |
| `dawn` | Warm palette | Marketing / editorial |

## Basic usage

```javascript
import Lextrix from 'lextrix';
import 'lextrix/snow.css';

const mount = document.createElement('div');
document.getElementById('wrapper').appendChild(mount);

new Lextrix(mount, {
  theme: 'snow',
  modules: {
    toolbar: [
      ['bold', 'italic', 'underline'],
      [{ header: [1, 2, false] }],
      ['link', 'clean'],
    ],
  },
});
```

Bubble uses a smaller default toolbar set — see [Configuration](/docs/configuration#toolbar-buttons).

## Switch theme at runtime

1. Save document: `const contents = editor.getContents()`
2. Load new CSS (replace `<link>` href or dynamic `import()`)
3. **Clear wrapper** (not just the mount div) — see [DOM mounting](/docs/dom-mounting)
4. Create fresh inner mount + `new Lextrix(mount, { theme: newTheme, … })`
5. `editor.setContents(contents)`

```javascript
async function switchTheme(wrapper, editor, newTheme) {
  const contents = editor.getContents();
  await loadThemeCss(newTheme); // your helper — swap link href

  wrapper.replaceChildren();
  const mount = document.createElement('div');
  wrapper.appendChild(mount);

  return new Lextrix(mount, {
    theme: newTheme,
    modules: { toolbar: toolbarFor(newTheme) },
  }).setContents(contents);
}
```

### Race conditions

If the user clicks themes quickly:

- **Debounce** or disable buttons while switching
- **Await** CSS load before creating the editor
- Always **`wrapper.replaceChildren()`** before each `new Lextrix` — never stack instances

Duplicate toolbars = cleanup skipped on parent wrapper. Not a Lextrix race bug; a DOM lifecycle bug.

## React example

Prefer [`@lextrix/react`](/docs/react) — remount with `key` when the theme changes:

```tsx
import { LextrixEditor } from '@lextrix/react';
import 'lextrix/snow.css'; // or dynamically swap theme CSS in your app

export function ThemedEditor({ theme }: { theme: 'snow' | 'bubble' | 'slate' | 'dawn' }) {
  return (
    <LextrixEditor
      key={theme}
      theme={theme}
      options={{ modules: { toolbar: [['bold', 'italic']] } }}
    />
  );
}
```

Load the matching `lextrix/{theme}.css` when switching themes (global `<link>` or bundler import).

Manual mount pattern (without `@lextrix/react`): [Frameworks](/docs/frameworks) · [DOM mounting](/docs/dom-mounting).

---

## Configuration

Source: https://iamreetesh.com/docs/configuration

# Configuration

> **Integrating in React or switching themes?** Call `editor.destroy()` on teardown — see [DOM mounting](/docs/dom-mounting).

## Editor options

```typescript
new Lextrix(container, {
  theme: 'snow',           // snow | bubble | slate | dawn
  placeholder: '',
  readOnly: false,
  bounds: null,            // tooltip positioning root
  debug: false,
  formats: null,           // null = all registered formats; or string[]
  modules: { /* … */ },
});
```

## Modules

### Always enabled

These load automatically — configure via `modules.<name>`:

| Module | Options | Purpose |
|--------|---------|---------|
| `clipboard` | `matchers` | Paste HTML → ChangeSet |
| `keyboard` | bindings | Shortcuts |
| `history` | `delay`, `maxStack`, `userOnly` | Undo / redo |
| `uploader` | `mimetypes`, `handler` | Drag-drop & toolbar image upload |

### Opt-in modules

| Module | Enable | Notes |
|--------|--------|-------|
| `toolbar` | `toolbar: […]` or `'#selector'` | Button names — see below |
| `syntax` | `syntax: true` | Needs highlight.js |
| `table` | `table: true` | Table blots + cell keyboard nav |
| `imageResize` | `imageResize: true` | Drag handle on selected images |

### Toolbar buttons

Pass an array of groups:

```javascript
modules: {
  toolbar: [
    ['bold', 'italic', 'underline'],
    [{ header: [1, 2, 3, 4, 5, false] }],
    [{ list: 'ordered' }, { list: 'bullet' }, { list: 'check' }],
    [{ indent: '-1' }, { indent: '+1' }],
    [{ align: [] }, { direction: 'rtl' }],
    ['blockquote', 'code-block'],
    ['link', 'image', 'video', 'formula'],
    ['clean'],
  ],
}
```

Or point to existing DOM:

```javascript
modules: { toolbar: '#my-toolbar' }
```

When `toolbar` is an **array**, Lextrix creates `div.lxr-toolbar` as the **first child** of your mount element. Call `editor.destroy()` when tearing down — see [DOM mounting](/docs/dom-mounting).

Custom handlers override theme defaults:

```javascript
modules: {
  toolbar: {
    container: ['image'],
    handlers: {
      image() { /* custom */ },
    },
  },
}
```

## Image upload to your API

Default uploader embeds images as base64. Override the handler:

```javascript
modules: {
  uploader: {
    mimetypes: ['image/png', 'image/jpeg', 'image/webp'],
    async handler(range, files) {
      for (const file of files) {
        const body = new FormData();
        body.append('file', file);
        const res = await fetch('/api/upload', { method: 'POST', body });
        const { url } = await res.json();
        this.lextrix.insertEmbed(range.index, 'image', url, 'user');
        range.index += 1;
      }
    },
  },
}
```

The theme **image** button and drag-and-drop both call `uploader.upload()`.

## Image resize

Enable the module and select an image in the editor — a corner handle appears.

```javascript
modules: {
  imageResize: {
    minWidth: 48,
    maxWidth: null,   // null = editor width
  },
}
```

Resize sets `width` and `height` attributes on the `<img>` blot.

Programmatic resize:

```javascript
editor.formatText(index, 1, { width: '400', height: '300' }, 'user');
```

See also: [API reference — imageResize](/docs/commands#image-resize-imageresize) · [Modules — Image resize](/docs/plugins#image-resize)

## Format whitelist

Restrict allowed formats:

```javascript
formats: ['bold', 'italic', 'link', 'header', 'list', 'image'],
```

Registered format names: `bold`, `italic`, `underline`, `strike`, `link`, `script`, `header`, `list`, `blockquote`, `code`, `code-block`, `color`, `background`, `font`, `size`, `align`, `direction`, `indent`, `image`, `video`, `formula`.

## Syntax highlighting

Load highlight.js, then:

```javascript
modules: {
  syntax: {
    hljs: window.hljs,
    languages: [
      { key: 'javascript', label: 'JavaScript' },
      { key: 'python', label: 'Python' },
    ],
    interval: 1000,
  },
}
```

## Tables

```javascript
modules: { table: true }

// Insert programmatically
editor.getModule('table').insertTable(3, 4); // rows, columns
```

## Modular registration (advanced)

Build a custom bundle from workspace packages:

```javascript
import Lextrix, { registerBlots } from 'lextrix-core';
import { registerFormats } from 'lextrix-formats';
import { registerCoreModules, registerOptionalModules } from 'lextrix-modules';
import { registerUI } from 'lextrix-ui';
import { registerThemes } from 'lextrix-themes';

registerBlots(Lextrix);
registerFormats(Lextrix);
registerCoreModules(Lextrix);
registerOptionalModules(Lextrix);
registerUI(Lextrix);
registerThemes(Lextrix);
```

See [Modules](/docs/plugins) for per-module details and authoring.

---

## Plugin System

Source: https://iamreetesh.com/docs/plugins

# Modules

## Core (always loaded)

### Clipboard

Normalizes paste from HTML, Word, Google Docs, etc. Add custom matchers:

```javascript
modules: {
  clipboard: {
    matchers: [
      ['B', (node, delta) => delta.insert(node.textContent, { bold: true })],
    ],
  },
}
```

### Keyboard

Default bindings for Enter in lists/headers, tab indent, link shortcuts (snow theme adds Ctrl/Cmd+K). Extend:

```javascript
editor.keyboard.addBinding({ key: 'b', shortKey: true }, (range, context) => {
  editor.format('bold', !context.format.bold);
});
```

### History

| Option | Default | Description |
|--------|---------|-------------|
| `delay` | `1000` | ms before merging undo steps |
| `maxStack` | `100` | Max undo depth |
| `userOnly` | `false` | Ignore API changes |

### Uploader

Handles drag-and-drop and cooperates with the toolbar image button. See [Configuration](/docs/configuration#image-upload-to-your-api).

---

## Optional

### Toolbar

Renders formatting controls. Theme provides default handlers for `image`, `video`, and `formula`.

Snow theme auto-builds a default toolbar when `modules.toolbar` is set without a `container`.

### Syntax

Requires **highlight.js**. Adds a language `<select>` on code blocks and debounced highlighting.

### Table

Registers table blots. Keyboard shortcuts for navigation inside cells when the table module is active.

```javascript
const table = editor.getModule('table');
table.insertTable(2, 3);
table.deleteRow();
table.deleteColumn();
table.deleteTable();
```

No default toolbar button — add a custom handler if needed.

### Image resize

Shows a resize handle when a single image embed is selected.

| Option | Default |
|--------|---------|
| `minWidth` | `48` |
| `maxWidth` | `null` (editor width) |

Does not affect video or other embeds.

The overlay mounts on `.lxr-container` (sibling of the scroll surface) and tracks the image via DOM coordinates after layout settles. Call `editor.destroy()` when unmounting the editor to avoid orphan overlays in SPA remounts.

API details: [API reference — imageResize](/docs/commands#image-resize-imageresize)

---

## Authoring a module

Modules extend `Module` from `lextrix-core` and register with `lxrPath.module()`:

```javascript
import Module from 'lextrix-core/core/module.js';
import Lextrix, { lxrPath } from 'lextrix';

class WordCountModule extends Module {
  constructor(lextrix, options) {
    super(lextrix, options);
    lextrix.on('text-change', () => this.update());
  }

  update() {
    console.log('Document length:', this.lextrix.getLength());
  }
}

Lextrix.register({ [lxrPath.module('wordCount')]: WordCountModule });

new Lextrix('#editor', {
  theme: 'snow',
  modules: { wordCount: true },
});
```

Lifecycle: theme loads modules from options → `pluginHost.register()` → `pluginHost.bindAll(editor)`.

Access instances with `editor.getModule('wordCount')`.

Study existing modules in `packages/modules/src/modules/`. Source: `packages/core/src/core/plugins/plugin-host.ts`.


---

# Formats

Built-in formats live in `lextrix-formats`. Custom formats register a blot class and optional attributor metadata.

## Registration

Extensions register through `Lextrix.register()` using `lxr/*` paths:

```javascript
import Lextrix, { lxrPath } from 'lextrix';

lxrPath.format('callout');           // lxr/formats/callout
lxrPath.module('mentions');          // lxr/modules/mentions
lxrPath.blot('scroll');              // lxr/blots/scroll
lxrPath.theme('snow');               // lxr/themes/snow
lxrPath.attributor('block', 'align'); // lxr/attributors/block/align
```

Bare paths like `formats/bold` or legacy keys like `parchment` throw at runtime.

```javascript
Lextrix.register({ [lxrPath.format('callout')]: CalloutBlot });
```

`defineInlineTagFormat` and other format helpers are available when developing **inside the monorepo** (`lextrix-formats`). npm consumers implement a blot class and register it as above. See [Framework integration](/docs/frameworks).

## Inline tag format (monorepo)

```javascript
import { defineInlineTagFormat } from 'lextrix-formats/inline-format.js';

export const Highlight = defineInlineTagFormat({
  blotName: 'highlight',
  tagName: 'MARK',
});

Lextrix.register({ [lxrPath.format('highlight')]: Highlight });
```

## Block format

```javascript
import { defineBlockFormat } from 'lextrix-formats/block-format.js';

export const Callout = defineBlockFormat({
  blotName: 'callout',
  tagName: 'DIV',
  className: 'lxr-callout',
});
```

## Attributor formats

For class, style, or attribute-based formatting (align, color, indent):

```javascript
import {
  defineClassAttributorFormat,
  defineAttributorGroup,
} from 'lextrix-formats/attributor-format.js';

const MarginClass = defineClassAttributorFormat('margin', 'lxr-margin', {
  scope: Scope.BLOCK,
  whitelist: ['small', 'large'],
});

defineAttributorGroup('margin', [MarginClass]);
```

## Embeds

Embeds are non-text leaf nodes (image, video, formula):

```json
{ "insert": { "image": "https://example.com/photo.png" } }
```

```javascript
editor.insertEmbed(index, 'image', url, 'user');
```

Define an embed blot extending the embed base. Study built-ins in `packages/formats/src/formats/image.ts`, `video.ts`, `formula.ts`.

| Kind | Behavior |
|------|----------|
| Inline embed | Single leaf in a line (image, formula) |
| Block embed | Own block row (video) |

Custom embeds may need clipboard matchers for non-standard pasted HTML. See `packages/modules/src/modules/clipboard.ts`.

## Format metadata hooks

`defineDocumentFormat` attaches Lextrix-native metadata to a blot class:

| Hook | When it runs |
|------|--------------|
| `optimize` | Early in the optimize pass |
| `postOptimize` | After structure enforcement |

## Scope

Formats declare a **Scope** bitmask (block, inline, attribute, embed).

## Examples

- `packages/formats/src/formats/bold.ts`, `align.ts`, `blockquote.ts`
- Tests: `packages/lextrix/test/unit/formats/`

---

## Markdown Support

Source: https://iamreetesh.com/docs/markdown

Lextrix is a rich-text engine with a ChangeSet document model — not a Markdown-first editor. Markdown enters and leaves through `importContent` and `exportContent`.

## Import and export

```javascript
editor.importContent('# Title\n\n**bold** paragraph.', 'markdown');
const md = editor.exportContent('markdown');
editor.listExportFormats(); // ['json', 'html', 'markdown', 'mdx', …]
```

## Limitations (summary)

See [Serialization](/docs/serialization) for the full list. Highlights:

- **Native editor tables** cannot export to Markdown/MDX — use `exportContent('html')`.
- **Dialect** is a subset, not full CommonMark/GFM.
- **Ordered lists** export as sequential `1.`, `2.`, … (including across empty lines between items).
- **Align, color, font** — HTML/JSON only.
- **Video embeds** export as `[video](url)` in Markdown/MDX.

## Before export

```javascript
const warnings = editor.getExportWarnings('markdown');
for (const w of warnings) {
  console.warn(w.message);
}
const md = editor.exportContent('markdown');
```

## Storage patterns

| Use case | Format |
|----------|--------|
| Full fidelity + undo | ChangeSet JSON via `getContents()` |
| CMS with Markdown | `exportContent('markdown')` on save, `importContent(md, 'markdown')` on load |
| Read-only render | `exportContent('html')` |
| Search / LLM | `getText()` |

## Next steps

- [Serialization](/docs/serialization)
- [MDX Support](/docs/mdx)
- [ChangeSet guide on GitHub](https://github.com/rishureetesh/lextrix/blob/main/docs/guides/change-set.md)

---

## MDX Support

Source: https://iamreetesh.com/docs/mdx

Lextrix imports and exports MDX through the same ChangeSet pipeline as HTML and Markdown.

## Basic usage

```javascript
editor.importContent(`# Hello

<Callout type="warning">Ship carefully.</Callout>
`, 'mdx');

const mdx = editor.exportContent('mdx');
```

## React persistence

Prefer [`@lextrix/react`](/docs/react) (`LextrixEditor` with `format="mdx"`). For a manual mount, see [Framework Integration](/docs/frameworks) and [DOM Mounting](/docs/dom-mounting).

```tsx
import { LextrixEditor } from '@lextrix/react';
import 'lextrix/snow.css';

<LextrixEditor
  theme="snow"
  format="mdx"
  value={mdx}
  onChange={setMdx}
/>
```

## Experimental: MDX components

`registerMdxComponent` is **not stable API**. Unknown JSX is stored as raw text; parsing uses regex, not an AST. See [Serialization](/docs/serialization) for details.

For in-editor structured blocks, register a custom format blot — see [Plugin System](/docs/plugins).

## Limitations

- Native editor tables cannot export to MDX — use HTML export.
- Horizontal rules export as escaped `---` text so they do not become thematic breaks.

## Next steps

- [Serialization](/docs/serialization)
- [Markdown Support](/docs/markdown)
- [Plugin System — formats](/docs/plugins)

---

# Blog

## Building @reetesh/sudoku-engine

Source: https://iamreetesh.com/blog/building-sudoku-engine

I built the Sudoku game on [iamreetesh.com](/games/sudoku) before I extracted the logic into an npm package. That order mattered. The UI felt like the product until I spent a week fixing puzzles that looked fine but had two solutions, or hints that spoiled half the grid.

The engine now lives in its own repo: [`@reetesh/sudoku-engine`](https://www.npmjs.com/package/@reetesh/sudoku-engine) **v2.0.0** on npm, [sudoku-engine on GitHub](https://github.com/rishureetesh/sudoku-engine). Zero runtime dependencies. Works in Node and the browser. This site uses v2 for classic and variant modes.

## What the library has to do

These were non-negotiable:

- Generate puzzles with **exactly one** solution
- Hit **clue-count ranges** per difficulty (easy through expert)
- Validate moves fast enough for every keystroke
- Solve grids quickly enough for hints and import checks
- Stay **UI-free** — React on the site is a consumer, not the owner

If generation and solving disagree about what a valid puzzle is, you get bugs that only show up in production. I learned that the hard way when an early generator passed `hasUniqueSolution` in tests but failed on symmetric layouts under load.

## Public API: a 9×9 grid, not a clever internal shape

Consumers work with a plain `Board`:

```typescript
type Board = (1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | null)[][];
```

`null` is empty. Givens and player entries are digits 1–9. That is it. No bitmasks in the public API, no flat index math in app code.

Internally I convert to a `BitGrid` when solving or carving puzzles. Keeping the external shape boring made the React game and the npm package easier to reason about. I wrote more about that split in [Lessons Learned Building a TypeScript Library](/blog/lessons-learned-building-typescript-library).

Helpers like `boardToString`, `stringToBoard`, and `createEmptyBoard` exist because Sudoku strings (81 chars, `.` or `0` for blank) show up everywhere — puzzle banks, imports, tests.

## BitGrid: where the bitmasks actually live

The old draft of this post talked about a flat 81-cell array and row/column/box sets. The shipped code is slightly different but the idea is the same: **track used digits with bits, not nested loops on every check.**

`BitGrid` keeps:

- `cells` — `Uint8Array(81)` (0 = empty, 1–9 = filled)
- `rows`, `cols`, `boxes` — nine `Uint16Array` entries each, one 9-bit mask per unit

Digit `5` sets bit `(1 << 4)`. Full candidate mask for an empty cell:

```typescript
const FULL_MASK = 0x1ff; // nine bits on

candidateMaskAt(row, column) {
  const used = rows[row] | cols[column] | boxes[boxIndex(row, column)];
  return FULL_MASK & ~used;
}
```

`place` and `clear` update all four structures together so masks never drift from cell values. That invariant saved me from a class of "solver says valid, UI says conflict" bugs.

For hot paths — generation, counting solutions — everything runs on `BitGrid`. For simple checks in app code, `isValidMove` and `getCandidates` can work directly on `Board` using the same bitmask helpers.

## Solver: MRV backtracking

The solver is textbook backtracking with **MRV** (minimum remaining values): pick the empty cell with the fewest candidates, try each digit, recurse.

```typescript
function solveRecursive(grid: BitGrid): boolean {
  const next = grid.findMrv();
  if (!next) return grid.isComplete();

  const { row, column, mask } = next;
  for (const digit of maskToDigits(mask)) {
    grid.place(row, column, digit);
    if (solveRecursive(grid)) return true;
    grid.clear(row, column);
  }
  return false;
}
```

`findMrv` early-exits when it finds a cell with one candidate — no need to scan the rest of the grid.

Before solving, `validateBoard` rejects boards that already violate Sudoku rules (duplicate in row, column, or box). Invalid player states return `{ solved: false }` instead of throwing. Games need that distinction.

## Uniqueness: stop at two solutions

Puzzle generation depends on **unique** solutions. Counting every solution for a partial grid is wasteful. `countSolutionsBitGrid` takes a **limit** and bails once it hits it:

```typescript
export function hasUniqueSolution(board: Board): boolean {
  return countSolutions(board, 2) === 1;
}
```

During cell removal, each candidate carve runs `countSolutionsBitGrid(grid, 2)`. If count exceeds 1, put the digit back. That is the difference between "feels slow when generating expert" and "hangs forever."

## How puzzles are generated

Pipeline:

1. **`generateSolvedBoard`** — fill a complete valid grid (randomised backtracking).
2. **Remove clues** until target clue count, checking uniqueness after each removal.
3. **Verify** clue count falls in the difficulty range and `hasUniqueSolution` still passes.

Target clue ranges (givens on the board):

| Difficulty | Givens |
|------------|--------|
| easy       | 40–45  |
| medium     | 32–39  |
| hard       | 26–31  |
| expert     | 22–25  |

`generatePuzzle("medium")` tries up to 12 attempts with a random solved board and either random or **symmetric** removal (`{ symmetric: true }` mirrors cells across the centre like newspaper puzzles).

If the fast path fails, a fallback loop relaxes targets slightly rather than returning garbage. Worst case it throws — I prefer that over shipping a broken puzzle.

Symmetric removal was trickier than random removal. Removing one cell is easy; removing a mirrored pair without breaking uniqueness required backing up both cells and rolling back together. There is a dedicated test file for this in the repo.

## Two ways to measure difficulty

Clue count alone is not enough. An expert-looking 24-clue puzzle might still collapse with naked singles only.

The library exposes:

- **`rateDifficulty(board)`** — clue-count buckets only
- **`rateDifficultyByTechniques(board)`** — simulates repeated "only one candidate in this cell" passes (naked singles), counts how many singles you need, tracks max candidate set size seen

```typescript
// Simplified idea from rateDifficultyByTechniques
while (progressed) {
  for each empty cell {
    if (getCandidates(working, row, column).length === 1) {
      fill it;
      singlesRequired++;
    }
  }
}
```

If you need many singles and candidate sets stay small, it rates easier. Few clues + large candidate sets → expert. This is not human-grade Sudoku grading (no X-Wing logic), and players still tell me some "hard" puzzles feel easy — but it beats counting givens alone for batch labelling.

## Hints without spoiling the puzzle

Hints on the site use `revealNext(board, solution, puzzle)` — scan for the first cell where the player value differs from the solution (skipping givens), then fill that one cell from the solution.

That is intentionally dumb compared to full logical hints. It nudges without implementing human-style technique detection. `revealRandom` exists when you want variety. All hint helpers respect givens via `isGiven(puzzle, row, column)`.

`getCellDisplayState` returns `"given" | "empty" | "player" | "incorrect"` so the UI can colour cells without duplicating rules.

## Play helpers

`applyMove(board, row, column, value, puzzle)` returns `{ success, board }` — it refuses to overwrite givens when `puzzle` is passed. `isSolvedCorrectly(board, solution)` is the win check.

`isValidMove` only checks Sudoku constraints (no duplicate in row/column/box). It does **not** check whether the move makes the puzzle unsolvable. That is deliberate: players can paint themselves into a corner; the UI shows incorrect cells against the solution when you want strict feedback.

## Batch, daily, import

Useful outside the browser game:

```typescript
generateBatch({ count: 100 });
dailyPuzzle("2026-05-30", "hard");
validateImportedPuzzle(puzzleFromString("530070000..."));
```

`generateBatch` caps at 1000 per call and can split across difficulties. `dailyPuzzle` is deterministic from a date string + difficulty — same puzzle for everyone that day.

Import validation runs uniqueness + solvability so pasted strings do not crash the app.

The site pre-generates a puzzle bank with a script (`scripts/generate-sudoku-puzzles.mjs`) so players get instant loads; live generation is for "new game" and daily modes.

## Mistakes I made

**Coupling UI state into the engine early.** Notes, undo stacks, and timer logic belong in React hooks (`useSudoku`), not npm.

**Trusting clue count as difficulty.** Players complained "hard felt easy." Technique rating was the fix.

**Not using `BitGrid` everywhere at first.** Mixed board-only solver paths were slower and harder to test.

**Flaky tests on technique rating.** CI on Node 22 caught a race in parallel vitest runs — fixed in 1.0.1. Small thing, but it eroded trust in the test suite until fixed.

## Testing

Tests live in the [sudoku-engine repo](https://github.com/rishureetesh/sudoku-engine) — solver, generator, symmetric removal, hints, import, performance, batch. `prepublishOnly` runs build + test before npm publish. This site keeps UI tests under `src/games/sudoku/*.test.ts` (storage, notes, puzzle bank — not core generation logic).

What I would test again if I started over: **uniqueness** and **generation** together, not the solver in isolation.

## Size and dependencies

Roughly **13 KB minified** ESM, tree-shakeable. No runtime deps. Subpath export `@reetesh/sudoku-engine/sudoku` if you want a smaller import surface.

## Version 2.0: variant framework

`@reetesh/sudoku-engine` **2.1.0** adds Windoku and Jigsaw on top of the classic / Mini / Sudoku X / Hyper set. **iamreetesh.com** exposes all six variants in the Sudoku game UI. Classic 9×9 has the most test coverage; newer variants still get edge-case fixes as people play them.

Use `createEngine` for other rules:

```typescript
import { createEngine } from "@reetesh/sudoku-engine";

const classic = createEngine({ variant: "classic" });
const mini = createEngine({ variant: "6x6" });       // 6×6, 2×3 boxes, digits 1–6
const sudokuX = createEngine({ variant: "diagonal" }); // Sudoku X: unique diagonals
const hyper = createEngine({ variant: "hyper" });       // Hyper: four extra 3×3 regions
const windoku = createEngine({ variant: "windoku" });   // Windoku: four inner windows
const jigsaw = createEngine({ variant: "jigsaw" });     // Jigsaw: irregular regions

mini.generatePuzzle("easy");
sudokuX.validateBoard(board);
windoku.generatePuzzle("medium");
jigsaw.generatePuzzle("easy");
```

Batch generation with a variant:

```typescript
import { SudokuEngine } from "@reetesh/sudoku-engine";

new SudokuEngine({ variant: "jigsaw" }).generateBatch({ count: 8 });
```

**Migration notes from 1.x:**

- `Digit` is now `number` (6×6 uses 1–6)
- `generatePuzzle` returns `null` on exhaustion instead of throwing in some paths
- Top-level import helpers remain classic 9×9 only

Upgrade guide: [MIGRATION.md on GitHub](https://github.com/rishureetesh/sudoku-engine/blob/main/docs/MIGRATION.md).

## Try it

- [Play Sudoku on this site](/games/sudoku)
- [npm package](https://www.npmjs.com/package/@reetesh/sudoku-engine)
- [GitHub repo](https://github.com/rishureetesh/sudoku-engine) — includes a small React example under `examples/react`

Sudoku looks like a toy problem. It is, until you care about unique puzzles, fair difficulty, and hints that do not ruin the game. Extracting the engine forced me to get those details right once instead of patching the React layer forever.

That pattern — engine first, UI second — is the same one I use for [2048](/blog/building-2048-game) and, at a much larger scale, [Lextrix](/lextrix). Simple rules, fussy implementation.

---

## Why I Started Building Lextrix

Source: https://iamreetesh.com/blog/why-i-started-building-lextrix

I did not set out to build a rich-text editor.

I set out to use one. Quill worked fine for what I needed at first — toolbar, bold, lists, paste from Word without completely destroying the layout. Then requirements grew. Custom embeds. Stricter undo behaviour. A theme that did not fight our design system. And I kept hitting walls where the fix was either a fragile DOM hack or a deep dive into Quill internals I did not fully understand.

That is when I started reading Quill's source code instead of Stack Overflow answers. I wrote about that separately in [Reading Quill Source Code](/blog/reading-quill-source). The short version: once you see how a document model, change operations, and blot registry fit together, you cannot unsee it. You also start noticing where your own mental model is fuzzy.

Lextrix came from that fuzziness. Not from a pitch deck. Not because I thought the world needed another editor. I wanted to understand editors properly, in TypeScript, with package boundaries I could explain to myself six months later.

## The problem I actually had

Most projects do not need a custom editor on day one. A `contentEditable` div gets you surprisingly far if you are careful. Libraries like Quill, TipTap, and ProseMirror exist because "careful" does not scale.

My pain points were boring but real:

- **Extension without fork.** I wanted to register formats and modules without copying vendor files into our repo.
- **Predictable changes.** Undo/redo broke in edge cases when HTML and internal state drifted apart.
- **TypeScript.** I wanted types at the boundaries — document ops, selection ranges, module config — not just `@types` hope.
- **Ownership.** When something broke at 11pm before a release, I wanted a codebase I could trace, not a minified bundle and prayer.

None of that is unique. Every team that outgrows a basic textarea hits some version of this list. What was different for me: I had time outside work, and I had already burned a weekend reading Quill. Building my own thing felt less insane than it would have a year earlier.

## Why not just switch libraries?

I looked at TipTap and ProseMirror seriously. ProseMirror is excellent — the reference many people point to for document models done properly. TipTap gives you a productive React layer on top.

I did not pick them for Lextrix not because they are bad, but because my goal was not "ship an editor this sprint." My goal was "learn the substrate." ProseMirror would have taught me a lot, but I would have been learning ProseMirror's architecture, not building muscle for designing my own module graph.

That sounds precious. Maybe it is. But side projects die when they are only about the outcome. This one stayed alive because the process was the point — with the hope that something useful would come out the other end.

Also, honestly: I am stubborn. Once I had sketched a package layout on paper, I wanted to see if I could make it work.

## The first wrong version

My first attempt was a monolith. One repo, one bundle, `lextrix.ts` that did everything — DOM sync, keyboard shortcuts, toolbar, themes, clipboard sanitisation. It worked in a demo page. Then I tried to extract "just the change layer" for a test and realised I had coupled everything through a shared mutable editor instance.

Classic mistake. I had read about separation of concerns in Quill's blot/module split and still built a god object because it was faster for the weekend demo.

Throwing that away hurt. But it clarified the boundary I actually wanted:

1. **Document + DOM** — blots, attributors, registry, browser integration
2. **Change processing** — operations, compose, invert, transform (for undo and future collab)
3. **Editor shell** — selection, commands, lifecycle, plugin host
4. **Modules** — clipboard, keyboard, toolbar, syntax, image resize
5. **UI** — optional toolbar widgets for teams that want React components without forking internals

That maps to what became `lextrix-dom`, `lextrix-change`, `lextrix-core`, `lextrix-modules`, `lextrix-formats`, `lextrix-ui`, and `lextrix-themes`, with a published `lextrix` bundle on npm for people who want the batteries-included install. The boundaries made sense on paper. In practice I still catch imports crossing layers that should not talk directly — refactoring those is ongoing.

Naming the packages took longer than I expected. I renamed things twice. If you browse early commits, you will see evidence of my indecision. That is fine. Public OSS means your naming mistakes are archived forever. Welcome to the club.

## What Lextrix is trying to be

[Lextrix](/lextrix) is an open-source modular TypeScript rich-text editor ecosystem. That sentence is careful on purpose.

**Modular** — you can depend on `lextrix-change` alone if you only want the operation layer, or ship the full bundle if you want a Quill-like getting-started path.

**TypeScript-first** — not "types bolted on later." The public APIs are written TS-first even if some internals still carry scars from the JS prototype phase.

**Ecosystem** — I do not think a single npm package is enough for editors. Editors touch DOM, input events, clipboard, IME, mobile keyboards, accessibility. One package always becomes a junk drawer.

What Lextrix is **not**: a finished Quill killer. Version **2.0.5** on npm is real and usable — including HTML, Markdown, and MDX serialization — and **`@lextrix/react`** ships official React bindings. The public playground is live on this site. Stable MDX component handlers and a Vue starter are still on the roadmap. I would rather say that plainly than pretend otherwise.

## Technical bet: ChangeSets

Quill uses Deltas — insert/retain/delete operations on a document. Lextrix uses a ChangeSet layer with compose, diff, invert, and transform utilities. Same family of idea, different naming and implementation details shaped by what I needed while building.

I chose to make change processing explicit because undo/redo kept being the canary in the coal mine. If you cannot invert an operation reliably, your editor will gaslight users. "I pressed undo why did my list disappear?"

Getting invert right for nested formats taught me more about the document tree than any tutorial. I still have edge cases filed as GitHub issues. That is not a fake humble brag — go look at the repo.

## Open source because it has to be

Lextrix is MIT licensed on [GitHub](https://github.com/rishureetesh/lextrix). Practical reasons:

- I used open-source editors for years without paying forward. This is partial repayment.
- If nobody can read the code, nobody can trust it for anything beyond a toy demo.
- Issues and PRs force me to explain decisions in writing — which usually surfaces gaps I had not noticed.

Selfish reason: public repos are my portfolio now. Recruiters can read code instead of another CRUD tutorial.

## Mistakes I am still living with

**Documentation lag.** The code moved faster than docs for stretches. npm READMEs are okay; deep architecture docs are still catching up. That hurts adoption and I know it.

**Scope creep in modules.** Every module "just one more feature" adds maintenance surface. I had to cut a syntax module variant because it was half-working and confusing.

**Testing gaps.** Unit tests exist for change logic and parts of the DOM layer. Full browser integration tests are thinner than I want. Editors are event-heavy; Vitest alone is not enough long term.

**Marketing instinct.** I am an engineer, not a devrel person. I built Lextrix before I wrote this post. That order was backwards for discoverability. Fixing that now.

## If you are thinking about building an editor

Do not start here unless you mean it. Use ProseMirror, TipTap, Quill, Slate — people have spent years on edge cases you have not hit yet.

One item still on my list: IME composition for CJK input. I have not solved that fully in Lextrix yet. Quill and ProseMirror have years of bug reports on composition boundaries. That is not a reason to avoid building — it is a reason to be honest about maturity.

I wish I had shipped one format, one module, and undo that works before designing a theme system. I did it backwards once with the god object weekend demo.

## Where Lextrix goes next

Public playground. React starter template. More cookbook examples for custom blots and clipboard filters. Bundle size benchmarks documented honestly. Maybe collaboration examples built on transform — not because v1 needs it, but because I am not sure the change layer is as general as I think until something concurrent actually uses it.

If any of that sounds useful, try `npm install lextrix`, open an issue, or tell me what broke. I respond faster to bug reports than to "great project" tweets. Both are welcome. Bugs more so.

I started building Lextrix because I did not understand editors well enough. I am still building it for the same reason — just with more code and fewer illusions.

If you read one other post on this site for context, make it [What Reading Quill's Source Code Taught Me About Editors](/blog/reading-quill-source). That is the technical prelude to this one.

---

## Shipping 2048: Small Game, Real Polish

Source: https://iamreetesh.com/blog/building-2048-game

2048 is a small game, but the first version on this site had a UX problem: the logic was correct, yet every arrow press felt random. Numbers changed in place with no clear sense of what slid or merged.

This post is a short note on how I shipped a version that actually feels good to play.

## Keep the engine separate

The rules live in plain TypeScript — slide a row, merge equals, spawn a tile, check win/loss. React only handles rendering and input.

That split means the grid math is easy to reason about and test without mounting components. Other games on the site (Sudoku, Tiger and Goat) follow the same pattern: engine first, UI second.

## Tiles need stable IDs

Rendering a 4×4 grid with fixed cell keys makes every update look like a teleport. The fix was a tile layer: each number gets an `id` that survives as it moves across the board. When two tiles merge, one id stays with the doubled value.

The UI animates position changes with Motion — slide on move, a small pop on merge, scale-in when a new tile spawns. That was the biggest quality jump, though drag-to-swipe on mobile still feels less crisp than keyboard input on desktop.

## Input and offline play

Keyboard arrows work as expected. On desktop and mobile I also added drag/swipe so you can pull the board in a direction and release.

The game is a PWA, so after one online visit it caches and runs offline. Stats (best score, best tile, games played) persist in the browser via a small per-game tracker.

## Worth the effort?

For a weekend-sized puzzle, yes — if you care about feel. The algorithm is well known; the polish is in movement, input, and making progress stick.

[Play 2048 here](/games/2048) if you want to try it.

---

## Lessons Learned Building a TypeScript Library

Source: https://iamreetesh.com/blog/lessons-learned-building-typescript-library

Publishing a TypeScript library on npm looks straightforward until you do it twice and realise the first time was luck.

I have two public packages that taught me different lessons: [`@reetesh/sudoku-engine`](https://www.npmjs.com/package/@reetesh/sudoku-engine) for the Sudoku game on this site, and [`lextrix`](https://www.npmjs.com/package/lextrix) for the editor ecosystem I have been building for longer than I planned. Same toolchain on paper — TypeScript, npm, GitHub Actions — completely different failure modes.

This post is what I wish someone had told me before my first publish. Not generic "semantic versioning good" advice. Actual things that broke.

## Lesson 1: Your first API shape will be wrong

The Sudoku engine started as functions inside a React hook. `generatePuzzle()`, `validateMove()`, `solve()` — all exported from one file because the game was the product, not the library.

When I extracted it to npm, I renamed things for "cleanliness." Consumers (well, me, two weeks later) had to rewrite imports. Nobody else was using it yet, so the damage was zero. That will not be true forever.

After that rename pain, I try to keep the npm package API boring and stable. Internal names can change behind explicit exports. If I need a breaking change, I bump major and write a one-line migration note in the README. No silent renames. I still slip on this — Lextrix 2.x had more internal churn than I would like.

For Lextrix, the package split forced this early. `lextrix-change` cannot casually rename `compose` without breaking anyone building undo on top. Smaller surface area per package helps — but multiplies release coordination pain. Tradeoff, not a win.

## Lesson 2: `exports` in package.json is not optional anymore

Modern Node, bundlers, and tools expect the `exports` field. I learned this when a Next.js app resolved the wrong entry and I got `Cannot use import statement outside a module` in a server component path that should never have touched the editor bundle.

Rough pattern that worked:

```json
{
  "name": "lextrix",
  "type": "module",
  "main": "./dist/lextrix.umd.cjs",
  "module": "./dist/lextrix.js",
  "types": "./dist/lextrix.d.ts",
  "exports": {
    ".": {
      "types": "./dist/lextrix.d.ts",
      "import": "./dist/lextrix.js",
      "require": "./dist/lextrix.umd.cjs"
    },
    "./style.css": "./dist/lextrix.css"
  }
}
```

Your exact paths will differ. The lesson is not copy-paste this JSON. The lesson is: **test resolution paths you do not use daily** — require(), dynamic import(), CSS side effects, subpath exports for `/change` or `/dom` if you split packages.

Scoped packages (`@reetesh/sudoku-engine`) add another footgun: people forget the scope when installing. Document the install command like you are talking to tired-you at midnight.

## Lesson 3: Types are part of the public API

I shipped a minor version where a generic defaulted differently. TypeScript consumers broke without a runtime change. Semver purists argue whether that is a major bump. Pain is pain.

Since then, if TS types change in a way that forces consumer code edits, I treat it as breaking even if JavaScript still runs. I am still not always sure where that line is — optional generics and stricter inference have surprised me more than once.

Also generate `.d.ts` from the same build pipeline as JS. Hand-maintained types drift. I have seen projects where types describe an API that shipped two versions ago. Embarrassing and hard to debug.

## Lesson 4: Build output should be boring

I tried fancy for a week — multiple bundlers, experimental configs, output formats I did not need. Build flakiness ate the time I saved on the hello-world demo.

These days I stick to one primary build tool per repo (esbuild or tsup-style setup for libraries), a deterministic output directory, CI running build + test on every PR, and a published tarball that contains only `dist/` and README — not source, not tests, not my `.vscode` folder (yes, I almost published that once).

For Lextrix monorepo, coordinating builds across packages is its own job. Root scripts that build in dependency order saved me. "Build package X alone" failing because package Y was stale is a full afternoon gone.

## Lesson 5: Tests that only run in your head do not count

Sudoku engine: solver correctness is testable with fixtures — puzzles in, solutions or failure out. Easy wins. Property-based tests would be better; I still have that on the list.

Lextrix: pure change-layer functions test well in Node. DOM-linked behaviour does not. I leaned on unit tests for operations and manual browser clicking for selection quirks. That gap shows up as regressions when I refactor blots.

Splitting pure logic early felt like over-engineering at first. The editor shell will never be fully testable in Vitest alone, but `invert(compose(a, b))` can be.

## Lesson 6: README is the homepage

GitHub README and npm page are most visitors' entire experience. My early READMEs listed features like marketing bullets. Useless.

I rewrite them to include: install command, a minimal copy-paste example, a link to docs, an explicit "not ready yet" list, and the license. For Lextrix I added the install one-liner and links to the docs tree on GitHub. Still need a hosted playground — README cannot compensate for try-it-yourself forever.

## Lesson 7: Version numbers are communications

I bumped patch versions for internal refactors consumers should not have noticed. I delayed major bumps because I did not want to look "unstable." Both choices confused future-me.

What I aim for now:

- **Patch** — bug fix, no API change
- **Minor** — backward-compatible feature
- **Major** — break or intentional API cleanup

Pre-1.0 (`0.x`) is not a license to break weekly without changelog notes. People still depend on 0.x in production. Ask npm download stats if you doubt that.

Keep a CHANGELOG even if it is ugly. "Fixed invert bug with nested list items" helps more than `fix: stuff`.

## Lesson 8: Dependencies are a liability

Sudoku engine: zero runtime dependencies. Beautiful. Small tarball. Fast installs.

Lextrix: intentionally few, but build-time tooling adds up. Every devDependency is a supply-chain node. Not paranoia — maintenance.

Before adding a dependency I ask:

- Can I write 40 lines instead? (Sometimes yes, often no)
- Will this run in consumer browsers or only at build time?
- Who maintains it when ESLint 27 breaks the plugin ecosystem again?

## Lesson 9: Publishing is not the finish line

First npm publish felt huge. Download count stayed at zero for days. Normal.

Real work after publish:

- Issue triage
- Repro steps from strangers who use Windows and a browser you forgot to test
- Documentation PRs you should have written yourself
- Deciding whether feature requests align with scope

Open source is a long feedback loop. Sudoku engine gets occasional installs. Lextrix gets fewer but deeper issues when someone actually embeds it.

## Lesson 10: Dogfood or drift

Both libraries exist because this site uses them. Sudoku game imports the engine. Lextrix dogfooding is slower — migrating this blog to Lextrix MDX authoring is on my list, not done yet. That gap matters. Without dogfooding, API pain stays theoretical.

If you publish a library you do not use, expect API drift toward what you imagine people want instead of what integration requires.

## India-specific practical note (not a sob story)

I build this from India on normal hardware, evenings and weekends, timezone overlap with US/EU OSS communities limited. Release notes go out when I am awake; issues sit overnight. That is fine. Async OSS works if you document response times honestly in README.

Do not pretend to be a funded startup. Solo maintainers set expectations with tone: "I maintain this in spare time" is not weakness; it prevents resentment on both sides.

## What I would tell past-me

- Ship `@reetesh/sudoku-engine` earlier — smaller scope, faster learning loop
- Split Lextrix packages before the god object hardened
- Write the Quill reading notes before writing change-layer abstractions
- Publish changelogs from commit one
- Stop waiting for perfect docs to npm publish — but do not leave docs empty forever either

## CI and release automation (the unglamorous part)

GitHub Actions for test + build on push is baseline setup. What I under-invested in early: **automated npm publish on tag** with provenance and a dry-run check of package contents (`npm pack` + inspect tarball). I published a broken tarball once because `files` in package.json was wrong. Nobody downloaded it. Lucky.

Now I check tarball contents before publish. Boring step. It caught one bad publish; I assume I will miss something else eventually.

For monorepos, version bump coordination across packages is still manual-ish. Tools exist (changesets, etc.). I have not adopted one fully yet — another item on the honest roadmap list.

## Publishing your first library

My first scope felt too big. Sudoku validation without generation would have been enough. One Lextrix package without themes would have been enough. I wish I had gotten install + import working on a fresh Vite app and a fresh Next app before expanding.

These lessons cost me weekends. Maybe they save you one afternoon. If you hit a weird `exports` resolution bug, someone else probably hit it too and wrote nothing about it — that was me for too long.

---

## What Reading Quill's Source Code Taught Me About Editors

Source: https://iamreetesh.com/blog/reading-quill-source

I had used Quill in a couple of projects before I ever opened its repository.

You npm install, follow the docs, customise the toolbar, fight paste behaviour once, ship. Quill is good at letting you do that. What it does not automatically give you is a mental model of what happens between a keypress and the DOM updating.

I wanted that model because bugs were getting harder to debug. Selection jumping after format toggles. Undo doing almost the right thing. Paste from Google Docs leaving phantom newlines. I could patch symptoms, but I did not understand the system.

So I spent a few evenings reading Quill source — not cover to cover, but tracing specific flows until they clicked. That reading directly led to [why I started building Lextrix](/blog/why-i-started-building-lextrix). This post is the technical half of that story.

## What Quill optimises for

Quill is a rich-text editor built around a document model called **Deltas**. Instead of treating the editor as "a div of HTML we hope is sane," changes are described as operations:

- **insert** — add text or embed with optional attributes
- **retain** — skip N characters, optionally apply format
- **delete** — remove N characters

A Delta is a JSON-serialisable list of these ops. User edits become Delta transformations. Undo becomes applying an inverse Delta. Collaborative editing (with appropriate transform rules) becomes merging concurrent Deltas.

That sounds abstract until you see a concrete example. Suppose the document is `Hello` and the user selects `ell` and makes it bold. You might express the change roughly as:

```json
{
  "ops": [
    { "retain": 1 },
    { "retain": 3, "attributes": { "bold": true } },
    { "retain": 1 }
  ]
}
```

Exact ops depend on selection indices and internal representation, but the shape is what matters: **index-based operations with attributes**, not "wrap this substring in `<b>` and hope."

Once I internalised that, a lot of Quill API surface made sense — `getContents()`, `setContents()`, `updateContents()`, format toggles as attribute changes on retain ops.

## Blots: the DOM tree with rules

Quill's DOM layer uses **Blots** — objects representing nodes in the editor tree. Block blots, inline blots, embed blots. Each knows how to create DOM, read value back, and interact with the registry.

This was the second big unlock for me.

Contenteditable browsers give you a soup of nodes. Quill constrains the soup by saying: these node types exist, they nest in allowed ways, unknown stuff gets normalised on ingest. The blot layer is where paste sanitisation, cursor behaviour, and format boundaries actually live — not in the toolbar React component you wrote.

When I traced **bold** formatting, I did not start in the toolbar button handler. I started at the format module, followed into the blot that applies inline attributes, watched how it cooperates with selection. Boring path. Useful path.

I noticed that if you only read the public API files, you miss why the API is shaped that way.

## Modules: clipboard, keyboard, toolbar

Quill splits cross-cutting behaviour into **modules** registered on the editor instance — clipboard, keyboard shortcuts, history (undo), toolbar bindings, etc.

Two observations:

1. **Modules are not React components.** They hook into editor lifecycle and events. Your UI framework sits outside.
2. **Clipboard is where editors go to suffer.** Paste from Word, Slack, browser quirks, image drops — the clipboard module normalises external HTML into something the document model accepts.

I spent one evening only on clipboard code. I do not remember every branch. I remember thinking: "Ah, so this is why my custom format disappeared on paste — it never mapped through the matchers."

That single realisation saved me days of random CSS attempts later.

## Selection is state, not a DOM accident

Before reading source, I treated selection as whatever `window.getSelection()` returned. Quill tracks selection indices relative to the document model and syncs with the DOM.

When those layers desync, you get the classic bugs — caret before a line break visually but after logically, format apply targeting wrong range, undo restoring content but not selection.

Reading how Quill normalises selection after operations changed how I think about editor state generally. The DOM is a render target; the document + selection indices are supposed to be truth. Lextrix still desyncs in edge cases I have not fully traced — HTML-in-contenteditable as source of truth falls apart under undo pressure, and I am not convinced I have eliminated every path where it sneaks back in.

This is the main idea I carried into Lextrix's architecture — explicit change processing and clear ownership of document state, even though Lextrix uses a **ChangeSet** layer with compose/diff/invert/transform rather than Quill's Delta naming. Whether I got the split right is still an open question; nested lists and paste are where it shows.

Same family of problem. Different implementation choices shaped by TypeScript modules and what I needed while building.

## What I deliberately did not do

I did not memorise every file. Quill is not small. The goal was a **map**, not trivia:

- Where do ops enter the system?
- Where is DOM updated?
- Where would I add a custom format?
- Where does undo hook in?

Four questions. I answered each by following one stack trace end to end.

If you are reading ProseMirror instead, swap "steps" for "ops" and "schema" for "blots" — the reading strategy still works.

## Quill vs what I wanted (and why Lextrix exists)

Quill is mature and battle-tested. I am not writing this to convince you to replace it.

What I wanted personally:

| Need | Quill | What I built in Lextrix |
|------|-------|-------------------------|
| TypeScript-first internals | Mostly JS heritage | TS packages from the start |
| Package-level composition | Monolithic npm package ergonomics | `lextrix-dom`, `lextrix-change`, etc. |
| Learning the full stack | Use as dependency | Read + rebuild to learn |
| Long-term extensibility | Good, with community patterns | `lxr/*` registry paths, explicit modules |

None of that means Quill failed me. It means my side-project goals were orthogonal to "pick the best editor for production tomorrow."

For work projects I would still evaluate Quill, TipTap, ProseMirror, Slate on requirements. This post is about learning from source, not picking a winner for production tomorrow.

If you want a learning path: read one of them deeply. Quill's Delta + Blot split was a readable on-ramp for me.

## Notes I kept after reading

I stopped trusting HTML diffing once undo had to be reliable — document ops were the only approach that held up for me so far, though invert for nested formats is still where I find bugs.

Hardcoding `document.execCommand` or manual `<span style>` insertion did not scale; a registry for formats and embeds made more sense once I saw how Quill wired it.

React re-renders should not be the editor's internal heartbeat. Quill keeps the UI framework outside core; that matched how I wanted to build Lextrix.

Paste took one full evening in source and still was not finished. I stopped treating it as a CSS problem after that.

One vertical slice at a time worked better than random file hopping: toolbar → format → blot → DOM → change event, then paste, undo, selection.

## Mistakes I made while reading

- **Reading randomly.** First night I jumped file to file. Second night I picked "bold toggle" and finished the trace. Night two was worth five of night one.
- **Assuming names match mental models.** Quill's `retain` confused me until I stopped thinking in HTML strings.
- **Ignoring tests.** Quill's test files show expected op sequences. Faster than guessing from implementation alone.
- **Not taking notes.** I repeated traces a week later. Short diagrams in a scratch file would have helped.

## How this connects to Lextrix concretely

When I implemented invert for nested list items in Lextrix, I knew *why* invert mattered — Quill's history module is the reference behaviour users expect even if they never read source. Getting it right took longer than I expected; there are still cases filed as issues.

When I split clipboard handling into `lextrix-modules`, I thought I knew *where* matchers belong — not scattered in app code. Paste from Word and Slack still surfaces formats I had not mapped yet.

When I resisted storing raw HTML as canonical state, I knew *what* I was avoiding — bugs I had already paid for in production patches. Serialization to Markdown and MDX introduced a different set of edge cases I am still working through.

[Lextrix](/lextrix) is not a Quill rewrite. It is what happened after Quill taught me the questions. The answers are mine, incomplete, open source, and still evolving.

I started reading Quill because I was annoyed by bugs. I kept reading because good abstractions are interesting. I built Lextrix because reading alone was not enough for what I wanted to learn.

Compare on [GitHub](https://github.com/rishureetesh/lextrix), disagree, open issues — that is how this gets better than anything I could write alone. For the project story after this post, see [Why I Started Building Lextrix](/blog/why-i-started-building-lextrix). Docs and playground are still catching up to code; read source with that expectation.

---