# Verbal (verbal-editor)

> A block editor for the web with zero runtime dependencies: every block is its own contenteditable, typing costs no React renders, and every feature is a module you opt into.


## Guides · Get started

- [Introduction](docs/introduction.md): A block editor for the web that stays out of your framework's way and weighs what you use.
- [Installation](docs/installation.md): Add the package and its stylesheet; nothing else is installed with it.
- [Quickstart](docs/quickstart.md): A working editor in React, Next.js, Vite or plain JavaScript, saved on every change.
- [Choosing modules](docs/choosing-modules.md): Every block, mark and piece of UI is opt-in; here is what each one adds and weighs.

## Guides · Core concepts

- [How it works](docs/how-it-works.md): Four layers, and exactly what each one does on a keystroke, an Enter, a paste and an AI edit.
- [Document model](docs/document-model.md): A flat map of blocks with stable ids; text is runs of marks. Equal documents are equal JSON.
- [Transactions & undo](docs/transactions.md): Every change is a transaction of invertible operations; your code uses the same path as the keyboard.
- [Rendering model](docs/rendering.md): One host per block, each re-rendered only when what it draws changes; typing changes nothing.

## Guides · Configuration

- [Config file](docs/config-file.md): verbal.config.js names the modules your app enables and the size it may weigh; Joi checks it at build time.
- [CLI](docs/cli.md): verbal init writes a config and prints its imports; verbal doctor checks it and reports each module's cost.
- [Server validation](docs/server-validation.md): validateDoc rejects malformed documents at your API boundary with precise paths; it never repairs.

## Guides · Guides

- [Writing a module](docs/writing-a-module.md): Your own blocks, marks and UI are plain objects with the same contract the built-in modules use.
- [AI review](docs/ai-review.md): AI edits arrive as a proposal painted over the real text; nothing changes until you accept.
- [Theming](docs/theming.md): tokens.css is the whole theming API — custom properties with a light and a dark value each.
- [Clipboard](docs/clipboard.md): Copy writes exact blocks and Markdown; paste parses, never injects.
- [Shortcuts](docs/shortcuts.md): Every key and Markdown rule, generated from the modules this site registers.
- [Mobile & touch](docs/mobile-touch.md): Container-first layout, finger-sized targets, and menus that stay clear of the on-screen keyboard.
- [Accessibility](docs/accessibility.md): Keyboard first, native semantics where they exist, and an honest list of the gaps.

## API Reference · Package

- [Imports](docs/imports.md): Every entry the package exports, what it contains, and what it weighs.
- [Editor API](docs/editor-api.md): The Editor class — options, events and every public member, generated from its JSDoc.

## API Reference · Modules

- [Modules](docs/modules.md): Every block, mark, UI and AI module, with what it adds and what it weighs.
- [blocks/paragraph](docs/modules/blocks/paragraph.md): Paragraph — the one block type core ships with; every other type is a module.
- [blocks/heading](docs/modules/blocks/heading.md): Heading 1–3 — `level` prop; the element is recreated only when the level changes.
- [blocks/todo](docs/modules/blocks/todo.md): To-do — `checked` prop. The checkbox sits outside the editable region, so toggling it never moves the caret.
- [blocks/list](docs/modules/blocks/list.md): List item — bullets and numbers are one module: `ordered` switches a CSS counter, so numbering stays right after any reorder.
- [blocks/quote](docs/modules/blocks/quote.md): Quote — `<blockquote>`; `> ` input rule. Nested blocks sit inside its border.
- [blocks/divider](docs/modules/blocks/divider.md): Divider — a void `<hr>`, never editable; `---` input rule.
- [blocks/code](docs/modules/blocks/code.md): Code block — plain text in a `<pre>`; colours are painted with the CSS Custom Highlight API, so the editable region holds nothing but text and the caret behaves exactly as in plain text.
- [blocks/table](docs/modules/blocks/table.md): Table — a grid of per-cell editable blocks: the table's children are paragraphs laid out row by row, `cols` wide, on a CSS grid.
- [blocks/chart](docs/modules/blocks/chart.md): Chart — hand-written SVG line, bar, area and pie charts drawn from a table block: the first row names the series, the first column labels the points, the other cells are numbers.
- [blocks/math](docs/modules/blocks/math.md): Equations — LaTeX compiled to MathML that the browser renders itself: no JS renderer, no fonts.
- [blocks/columns](docs/modules/blocks/columns.md): Columns — a container of columns on a CSS grid; each column holds ordinary blocks, and blocks drag between columns like anywhere else (an empty column still takes a drop).
- [blocks/image](docs/modules/blocks/image.md): Image — an `<img>` block. Paste or drop image files, or choose them from "/image".
- [blocks/embed](docs/modules/blocks/embed.md): Embed — allow-listed providers (YouTube, Vimeo, Loom, CodePen, Spotify) play in a sandboxed `<iframe>` that loads only when clicked, so nothing third-party is fetched until then.
- [marks/bold](docs/modules/marks/bold.md): Bold — `<strong>`, ⌘B, `**text**`. Pasted HTML counts font-weight too (Google Docs wraps everything in `<b style="font-weight:normal">`).
- [marks/italic](docs/modules/marks/italic.md): Italic — `<em>`, ⌘I, `*text*` or `_text_`.
- [marks/strike](docs/modules/marks/strike.md): Strikethrough — `<s>`, ⌘⇧S, `~~text~~`.
- [marks/code](docs/modules/marks/code.md): Inline code — `<code>`, ⌘E, ``text``. Typing at its end continues as plain text.
- [marks/link](docs/modules/marks/link.md): Link — `<a href>` rendered with rel="noopener noreferrer"; every href is validated before it is committed (http, https, mailto, tel or relative).
- [ui/slash](docs/modules/ui/slash.md): Slash menu — "/" opens a menu built from `registry.slash`: every module contributes its own entries, so registering a module is all it takes to appear.
- [ui/toolbar](docs/modules/ui/toolbar.md): Selection toolbar — floats over a text selection with one button per registered mark.
- [ui/dnd](docs/modules/ui/dnd.md): Drag & drop blocks with Pointer Events — no HTML5 drag-and-drop, so it works with touch and the drop target is exact.
- [ui/emoji](docs/modules/ui/emoji.md): Emoji — type ":" and a name. The 1,900-emoji index is a static file fetched the first time a ":" is typed; it is never part of any bundle.
- [ai/diff](docs/modules/ai/diff.md): Word-level Myers diff: text is split into words, whitespace runs and punctuation, and the shortest edit script between the two token lists is found in O(ND).
- [ai/pending](docs/modules/ai/pending.md): AI edits as a reviewable diff. A proposal is a valid but uncommitted transaction: the document is untouched until you accept.

## API Reference · Theming

- [Tokens](docs/tokens.md): Every custom property in tokens.css with its light and dark value, read from the file itself.

## API Reference · Platform

- [Browser support](docs/browser-support.md): The platform features Verbal relies on instead of shipping replacements, and where they exist.
- [Limitations](docs/limitations.md): What Verbal does not do yet, and what was left out to stay small.

## Changelog · Releases

- [Changelog](docs/changelog.md): What each version contains. Only what is in the package is listed.