@matrajs/mcp 1.0.0

package/docs/docs-commands.md

@@ -0,0 +1,162 @@
+# Commands
+
+Commands are functions that either change the document and return true, or change nothing and return false. How they compose, how they are typed, and why the boolean matters.
+
+A command is a function that takes a context and returns a boolean: **true if it did something, false if it declined.** It never throws · one that does is caught, logged, and its half-built transaction discarded rather than applied.
+
+```
+{`const toggleBold: Command = (ctx) => ctx.toggleMark('bold')`}
+```
+
+## The boolean is the interesting part
+
+A command returning `false` is not an error. It is the answer to "can this happen here?", and it is how the schema, the selection and the document shape all get a say without anybody writing a check.
+
+```
+{`// In a comment box with no heading in its schema:
+editor.commands.toggleHeading(2)   // undefined · not a command at all
+
+// In a full editor, with the caret inside a code block:
+editor.commands.toggleBold()       // false · code blocks accept no marks
+
+// With nothing selected:
+editor.commands.askAi('shorten')   // false · there is nothing to shorten`}
+```
+
+A keyboard shortcut that returns `false` falls through to the browser's own handling rather than swallowing the key.
+
+## Names are checked too
+
+The same inference covers the names you pass to `isActive`. An editor built without `heading` has no `toggleHeading` — and no node called "heading" either, so asking about one is a compile error rather than a permanent `false`.
+
+```
+{`const editor = createEditor({ extensions: [document, paragraph, text, bold] })
+
+editor.isActive('bold')      // fine
+editor.isActive('heading')   // Argument of type '"heading"' is not assignable
+editor.isActive('bould')     // nor is a typo`}
+```
+
+This is the failure that used to be hardest to see. A missing command is a `TypeError` the first time you press the button; a misspelt name in `isActive` is a toolbar button that simply never lights up, on a page where everything else works.
+
+## Asking without doing
+
+The boolean above only arrives after the change has happened, which is no use to a button that wants to be disabled *before* it is pressed. `editor.can` is the same command surface, with the same names and the same arguments, that returns the answer and changes nothing.
+
+```
+{`bold.disabled = !editor.can.toggleBold()
+undo.disabled = !editor.can.undo()`}
+```
+
+The command builds its transaction as usual and the transaction is thrown away, so asking costs about what pressing the button costs and leaves the document, the selection and the undo stack exactly as they were. No `change` event fires.
+
+> Note: Repaint on `selectionChange` as well as `change`. Whether bold is possible depends on where the caret is, so moving it into a code block has to grey the button out even though nothing was edited.
+
+## Types are inferred, not declared
+
+`editor.commands` is built from the extensions array you passed. Add an extension and its commands appear, typed, with their argument types intact. Leave it out and calling them is a compile error rather than a runtime surprise.
+
+```
+{`const editor = createEditor({ extensions: [document, paragraph, text, bold] })
+
+editor.commands.toggleBold()     // fine
+editor.commands.toggleItalic()   // Property 'toggleItalic' does not exist`}
+```
+
+There is no module augmentation and nothing to declare. This is the one thing here that other editors cannot copy without changing their architecture: Tiptap's commands live in a global interface, so every installed extension's commands appear on every editor whether you passed them or not.
+
+## Running several as one
+
+```
+{`editor.batch((commands) => {
+  commands.toggleBold()
+  commands.insert(' and this')
+})`}
+```
+
+One undo step, and all or nothing · if any command returns `false` the whole batch rolls back and `batch` itself returns `false`. Nothing half-applied reaches the document.
+
+## Making a change its own undo step
+
+Undo groups by time, which is right for typing and wrong for anything deliberate. A command that restores a template, applies a rewrite or accepts a suggestion should not disappear into the sentence somebody was writing a second earlier.
+
+```
+{`const applyTemplate: Command = (ctx) => {
+  if (!ctx.replace({ from: 0, to: size }, template)) return false
+  return ctx.isolateUndo()
+}`}
+```
+
+It seals from both sides: nothing merges into it from before, and the next keystroke does not merge into it either.
+
+## The core commands
+
+These exist whatever extensions you pass, because the engine provides them:
+
+| Command | What it does |
+
+| `select(range)` | Move the selection · a position or a range `insert(content, at?)` | JSON, an array of nodes, or an HTML string `replace(range, content)` | Swap a span for something else `remove(range?)` | Delete a span, or the selection |
+
+| `moveBlock(from, to)` | What a drag handle does |
+
+| `focus()` | Put the caret back in the editor |
+
+## What the context gives you
+
+Inside a command, `ctx` is the whole surface. The document as JSON, the selection, and the operations that change them:
+
+```
+{`ctx.doc                              // the document, as plain JSON
+ctx.selection                        // { from, to, anchor, head, empty }
+
+ctx.toggleMark('bold')               // and addMark, removeMark
+ctx.setBlockType('heading', { level: 2 })
+ctx.setNodeAttrs('taskItem', { checked: true })
+ctx.wrapIn('blockquote')              // and lift()
+
+ctx.insert(content, at?)             // replace, delete, select, focus
+ctx.mark()                           // a position marker · see position mapping
+ctx.isolateUndo()`}
+```
+
+> Note: `setBlockType` only applies to textblocks — nodes that hold text. For a node that holds *blocks*, like a checklist item or a table cell, use `setNodeAttrs`. Ticking a checkbox with `setBlockType` silently does nothing, which is a mistake worth making only once.
+
+## Writing a position down
+
+`Pos` is branded, so arithmetic on one does not typecheck: `from + 5` is a plain `number`, and a plain `number` is not accepted back. That is deliberate · a position computed from a stale one is the bug this editor exists to prevent, and it is invisible at runtime.
+
+It does mean a literal position needs saying out loud. `pos` and `range` are that, and nothing else:
+
+```
+{`import { pos, range } from '@matrajs/core'
+
+editor.commands.select(pos(0))
+editor.commands.replace(range(1, 6), 'goodbye')`}
+```
+
+Use them for positions you are writing down, never for one you are carrying across an `await` · that is `ctx.mark()`, which maps rather than guesses. See [position mapping](https://matrajs.com/docs/position-mapping).
+
+## Writing your own
+
+A command is a plain function on an extension. Nothing registers it, nothing wraps it, and the name you give it is the name on `editor.commands`:
+
+```
+{`import type { Command, ExtensionDef } from '@matrajs/core'
+
+const shout: Command<[times?: number]> = (ctx, times = 1) => {
+  const { from, to } = ctx.selection
+  if (from === to) return false          // nothing selected · decline
+  return ctx.insert('!'.repeat(times), to)
+}
+
+export const emphasis: ExtensionDef<{ shout: Command<[times?: number]> }> = {
+  kind: 'extension',
+  name: 'emphasis',
+  commands: { shout },
+  keys: { 'Mod-Alt-!': 'shout' },
+}`}
+```
+
+`editor.commands.shout(3)` now exists and is typed, because the array it came from says so. See [writing an extension](https://matrajs.com/docs/extensions) for the rest of the shape.
+
+> Note: Positions that are not finite integers inside the document return `false` rather than throwing — `NaN` included. It slips past a naive range check, because both `NaN  size` are false.

package/docs/docs-document-model.md

@@ -0,0 +1,103 @@
+# Document model
+
+Your document is plain JSON: a tree of nodes you can log, diff, store and send over the wire. What positions mean, what the schema refuses, and why it is immutable.
+
+Your document is plain JSON. Not a class, not an engine object · a tree of nodes you can log, diff, store and send over the wire.
+
+```
+{`{ type: 'doc', content: [
+  { type: 'heading', attrs: { level: 1 },
+    content: [{ type: 'text', text: 'Title' }] },
+  { type: 'paragraph', content: [
+    { type: 'text', text: 'Some ' },
+    { type: 'text', text: 'bold', marks: [{ type: 'bold' }] },
+    { type: 'text', text: ' text.' },
+  ] },
+] }`}
+```
+
+That is the whole format. `editor.getJSON()` hands it to you and `editor.setContent()` takes it back, and nothing in between is proprietary.
+
+## Nodes and marks
+
+A **node** is a thing in the document: a paragraph, a heading, an image, a table cell. A **mark** is something applied to a range of text: bold, a link, a comment thread. Nodes nest; marks decorate.
+
+The distinction matters when you write an extension, because it decides three things:
+
+- **Where it can go.** A node lives in another node's `content`; a mark lives on a text node's `marks` array.
+
+- **What it costs in positions.** A node has borders and takes space (below); a mark takes none at all.
+
+- **How it splits.** Marks split and merge freely as you type through them. Nodes do not — splitting one is a deliberate operation.
+
+## Positions
+
+Positions are integers into this tree, and the arithmetic is worth learning once because every command, every selection and every comment anchor is one.
+
+- The document starts at `0`.
+
+- Each character of text costs **one**.
+
+- Each node border costs **one** — so a paragraph costs two, plus its inside.
+
+- A leaf — a hard break, an image, a mention — costs exactly **one**, whatever it renders as. A five-letter mention is one position, not five.
+
+- A mark costs **nothing**. Bold text is the same width as plain text.
+
+```
+{`<p>hi</p>
+
+0  1  2  3
+│  h  i  │
+│           └─ 3 · after the closing border
+│        └──── 2 · after "i", still inside
+│  └─────────── 1 · the start of the text
+└────────────── 0 · before the paragraph`}
+```
+
+So a document holding one paragraph of "hi" has a size of 4, and its content spans 0 to 3. Selecting the word means ``.
+
+> Note: Never do arithmetic on a position across an `await`. Take a marker with `ctx.mark()` and map through it — see [position mapping](https://matrajs.com/docs/position-mapping), which is the page that explains why this one is worth reading.
+
+## The schema decides what is possible
+
+The extensions you pass build a schema, and the schema is enforced on every change. This is not decoration: a transaction that would produce an invalid document is *refused*, and the command that asked for it returns `false`.
+
+```
+{`const editor = createEditor({ extensions: [document, paragraph, text, bold] })
+
+editor.setContent('<h1>A heading</h1><p>Some <em>italic</em>.</p>')
+editor.getHTML()
+// '<p>A heading</p><p>Some italic.</p>'`}
+```
+
+The heading became a paragraph and the emphasis was dropped, because there is no node or mark in that schema to hold them. A node can also name the marks it accepts — `marks: ''` is why the text in a code block stays literal, whatever you paste into it. That is what makes a comment box a comment box: somebody pasting three pages of a Word document into it gets three paragraphs of text, not three pages of headings and tables.
+
+## It is immutable
+
+Every change produces a new document rather than editing the old one. Two consequences you will actually notice:
+
+- **An old document stays valid.** Hold on to `getJSON()` from ten seconds ago and it is still exactly what it was — which is how version history and collaborative rebasing work at all.
+
+- **Unchanged parts are the same object.** Editing one paragraph leaves every other paragraph as literally the same reference, which is what lets the renderer skip them by identity rather than by comparison.
+
+## Reading it without an editor
+
+Because it is ordinary data, you can persist it anywhere, compare two revisions with any diff library, and read it on a server without loading an editor at all.
+
+```
+{`import { toMarkdown } from '@matrajs/core'
+
+// On a server, in a worker, in a test · no DOM anywhere.
+const markdown = toMarkdown(JSON.parse(row.body))`}
+```
+
+`toMarkdown` walks the JSON. It never touches a DOM, which is why it runs on a server with no jsdom in sight and why it is in the benchmark rather than in a caveat.
+
+## Next
+
+- [Commands](https://matrajs.com/docs/commands) · how a change is made and why they return booleans.
+
+- [Position mapping](https://matrajs.com/docs/position-mapping) · how a position survives an edit.
+
+- [Writing an extension](https://matrajs.com/docs/extensions) · adding a node or a mark of your own.

package/docs/docs-extensions.md

@@ -0,0 +1,168 @@
+# Writing an extension
+
+An extension is a plain object. Nodes, marks and behaviour, with command types inferred rather than declared.
+
+An extension is a plain object with the same power as the built-ins. There is no base class to extend, nothing to register, and no declaration merging · pass it to `createEditor` and its commands appear on `editor.commands`, typed.
+
+## A mark
+
+```
+import type { Command, MarkDef } from '@matrajs/core'
+
+export const spoiler: MarkDef<{ toggleSpoiler: Command }> = {
+  kind: 'mark',
+  name: 'spoiler',
+  parseDOM: [{ tag: 'span[data-spoiler]' }],
+  toDOM: () => ['span', { 'data-spoiler': '', class: 'spoiler' }, 0],
+  commands: {
+    toggleSpoiler: (ctx) => ctx.toggleMark('spoiler'),
+  },
+  keys: { 'Mod-Shift-S': 'toggleSpoiler' },
+}
+```
+
+The generic is what makes `editor.commands.toggleSpoiler` exist and be typed. It is the only ceremony, and it buys autocomplete on every call site.
+
+## A node
+
+```
+export const callout: NodeDef<{ setCallout: Command<[tone: string]> }> = {
+  kind: 'node',
+  name: 'callout',
+  group: 'block',
+  content: 'block+',
+  attrs: { tone: { default: 'note' } },
+  parseDOM: [{
+    tag: 'div[data-callout]',
+    getAttrs: (dom) => ({ tone: dom.getAttribute('data-callout') }),
+  }],
+  toDOM: (node) => ['div', { 'data-callout': node.attrs?.tone }, 0],
+  commands: {
+    setCallout: (ctx, tone) => ctx.wrapIn('callout', { tone }),
+  },
+}
+```
+
+> Note: Declare every attribute you intend to keep. Undeclared attributes are dropped on the way in — that is a security property, not an oversight, and it is what stops a document supplying `onclick` to a node type that spreads its attrs.
+
+## Input rules
+
+Text that becomes something else as it is typed. Each match is one undo step.
+
+```
+inputRules: [{
+  match: /^>>\s$/,
+  handler: (ctx, _match, range) => ctx.delete(range) && ctx.wrapIn('callout'),
+}]
+```
+
+## State
+
+An extension can keep state, reduced on every transaction. This is how the character counter works without publishing a global.
+
+```
+export const wordGoal = (target: number): ExtensionDef<Record<string, never>, boolean> => ({
+  kind: 'extension',
+  name: 'wordGoal',
+  state: {
+    init: (ctx) => count(ctx.doc) >= target,
+    apply: (ctx) => count(ctx.doc) >= target,
+  },
+})
+
+// anywhere
+editor.extensionState<boolean>('wordGoal')
+```
+
+## Decorations
+
+Drawing over the document without putting anything in it · search highlights, remote cursors, squiggles. Decorations never travel with a copy, an export or an undo.
+
+```
+decorations: (ctx) => findMatches(ctx.doc, query).map((range) => ({
+  type: 'inline',
+  from: range.from,
+  to: range.to,
+  attrs: { class: 'search-hit' },
+}))
+```
+
+## Attributes on somebody else's node
+
+Alignment belongs on a paragraph, but the paragraph should not have to know about alignment. An extension may declare an attribute for nodes and marks defined elsewhere: it lands in the schema of every type named, is rendered onto the element, and is read back on parse. This is how `textAlign`, `indent` and `uniqueId` work.
+
+```
+export const tone: ExtensionDef = {
+  kind: 'extension',
+  name: 'tone',
+  attributes: [{
+    types: ['paragraph', 'heading'],
+    attrs: {
+      tone: {
+        default: null,
+        render: (value) => ({ 'data-tone': String(value) }),   // onto the element
+        parse: (dom) => dom.getAttribute('data-tone'),          // and back off it
+      },
+    },
+  }],
+  commands: {
+    setTone: (ctx, tone) => ctx.setBlockType('paragraph', { tone }),
+  },
+}
+```
+
+Leave `render` and `parse` off and the value goes to `data-`. A `style` or `class` the render returns is composed with the node's own rather than replacing it. A node that declares the attribute itself keeps its own rendering, and the global is not applied twice.
+
+## Paste and drop
+
+An extension can claim what arrives from the clipboard or by drag before the editor parses it. Return `true` and the editor leaves it alone; anything else and the next handler, then the editor, gets its turn. Files come through the same way — a screenshot pasted from the clipboard is a file — and a drop carries the position it landed on.
+
+```
+handlePaste: (ctx, { html, text, files }) => {
+  if (text !== 'magic') return false
+  return ctx.insert('✨')
+},
+handleDrop: (ctx, { files, pos }) => {
+  const marker = ctx.mark()          // survives the upload
+  upload(files[0]).then((src) =>
+    editor.commands.insert({ type: 'image', attrs: { src } }, pos && marker.map(pos)))
+  return true
+}
+```
+
+`fileHandler()` is this, packaged: an `accept` list and a callback with the editor, the files, the position and the marker already in it.
+
+## Whitespace in code
+
+HTML collapses runs of whitespace and so does the parser — except inside a node that says `code: true`, and inside any ``, where every space and line break is content. The stock code block says it; a node of your own that holds code should too.
+
+## Refusing a change
+
+An extension can veto a change before it lands. The context it gets is built on the document as it is, holding the change as it would be, so it can compare the two; return `false` and the document, the selection and the undo history stay exactly as they were. A keystroke, a paste, a drop, a drag and a command are all changes, so one filter covers them all — which is how `locked()` works — and `editor.can` asks the same question, so a button greys out rather than doing nothing.
+
+```
+filterChange: (ctx) => {
+  const { state, tr } = engine(ctx)   // the state before, the transaction as built
+  return !tr.docChanged || tr.doc.textContent.length <= 280
+}
+```
+
+Undo and redo, and `setContent`, carry a meta the filter can look for, so a change that was allowed in can always be allowed back out.
+
+## Rendering somebody else's node
+
+A node view belongs to the node that needs one — except when the need belongs to another extension. Resize handles belong on an image, and the image should not have to know about them. An extension may render nodes defined elsewhere, keyed by name; its view wins over the node's own. This is how `imageResize()` works, alongside a `width` it adds with `attributes`.
+
+```
+nodeViews: {
+  image: ({ node, getPos, editor }) => {
+    const dom = document.createElement('span')
+    // … an <img> and a handle
+    return { dom, update: (next) => next.type === 'image', stopEvent: (event) => event.target === handle }
+  },
+}
+```
+
+## Ordering
+
+Extensions load in array order, adjustable with `priority`. Later ones win a key binding conflict, and a more specific `parseDOM` rule needs a higher priority to beat a general one · which is how a task list beats a plain bulleted list for the same ``.

package/docs/docs-first-editor.md

@@ -0,0 +1,136 @@
+# Your first editor
+
+A working editor in ten lines, a toolbar wired to real commands, and the four mistakes everybody makes on the first afternoon.
+
+Ten lines, and the result is the editor on the front page.
+
+```
+{`import { createEditor, starterKit } from '@matrajs/core'
+
+const editor = createEditor({
+  extensions: starterKit,
+  content: '<p>Hello.</p>',
+  element: document.querySelector('#editor'),
+})`}
+```
+
+`element` mounts it there and then. Leave it out and you get an unmounted editor to `mount` yourself later, which is what the framework bindings do · in React the element does not exist until after the first render.
+
+> Note: It will look like unstyled text, and that is correct. Matra ships no appearance at all — a heading looks like a heading because your stylesheet says so. [Styling](https://matrajs.com/docs/styling) is fifteen lines and worth reading now rather than after you have decided something is broken.
+
+## What is in the starter kit
+
+Seventeen extensions: document, paragraph, text, heading, blockquote, codeBlock, bulletList, orderedList, listItem, horizontalRule, hardBreak, bold, italic, strike, code, link and history. Enough to write with, and nothing that needs configuring.
+
+Not in it, on purpose: `typography` (curling quotes is a decision), `taskList`, tables, and everything that needs options. Add what you want.
+
+```
+{`// Everything:
+createEditor({ extensions: starterKit })
+
+// Or exactly what you want, and nothing else:
+createEditor({ extensions: [document, paragraph, text, bold, underline] })
+
+// Or the kit plus something:
+createEditor({ extensions: [...starterKit, taskList, taskItem, ...tableKit] })`}
+```
+
+The array is the feature list. An editor built from the second line has no way to make a heading — no command, no shortcut, and pasting one flattens it to a paragraph. That is how you build a comment box that stays a comment box.
+
+## A toolbar
+
+Every button is a command call. `editor.commands` is typed from the array you passed, so `toggleBold` exists because `bold` is in the kit — not because of a declaration merge somewhere.
+
+```
+{`const bold = document.querySelector('#bold')
+
+bold.addEventListener('mousedown', (event) => {
+  event.preventDefault()          // keep the caret in the editor
+  editor.commands.toggleBold()
+})`}
+```
+
+> Note: `mousedown` with `preventDefault`, not `click`. A click moves focus to the button first, which collapses the selection — so the command runs on a caret rather than on the words the user chose, and bold appears to do nothing.
+
+## A toolbar that tells the truth
+
+A button that looks the same whether or not the thing it does is already done is a button you have to check your text to use. Ask the document:
+
+```
+{`const paint = () => {
+  // Is it on?
+  bold.setAttribute('aria-pressed', String(editor.isActive('bold')))
+  h2.setAttribute('aria-pressed', String(editor.isActive('heading', { level: 2 })))
+
+  // Is it even possible here? No, inside a code block.
+  bold.disabled = !editor.can.toggleBold()
+  undo.disabled = !editor.can.undo()
+}
+
+editor.on('change', paint)
+editor.on('selectionChange', paint)
+paint()`}
+```
+
+Two different questions, and a toolbar needs both. `isActive` asks whether the thing is done; `editor.can` asks whether it could be. A button that answers only the first looks pressable over a code block, gets pressed, and does nothing.
+
+`selectionChange` matters as much as `change`: moving the caret into bold text does not change the document, and the button still has to light up · or grey out.
+
+## Reading the document
+
+```
+{`editor.getJSON()   // plain JSON, no engine types
+editor.getHTML()   // a string
+editor.getText()   // block-separated text`}
+```
+
+Store the JSON. It is ordinary data: you can diff two revisions with any library, log it, and read it in a language that has never heard of this editor. HTML is for display and for pasting somewhere else — round-tripping through it loses anything your schema expresses that HTML does not.
+
+## Reacting to changes
+
+```
+{`const off = editor.on('change', () => save(editor.getJSON()))
+
+// later
+off()`}
+```
+
+`on` returns its own unsubscribe, so there is nothing to name and nothing to match up. The events are `change`, `selectionChange`, `focus` and `blur`.
+
+Do not save on every keystroke. [Recipes](https://matrajs.com/docs/recipes) has an autosave that waits for a pause and does not lose the last edit when the tab closes.
+
+## Setting content later
+
+```
+{`editor.setContent(await load(id))   // JSON or an HTML string`}
+```
+
+> Note: `setContent` replaces the document and **clears the undo history** — which is right when you are loading a different document, and wrong if you meant to change the one in front of the user. For that, use a command: `editor.commands.replace(range, content)`.
+
+## Cleaning up
+
+```
+{`editor.destroy()`}
+```
+
+Removes the listeners and the `contenteditable` attribute, so the element is safe to reuse. Every framework binding does it for you on unmount; if you are mounting by hand, a route change or a hot reload is where forgetting shows up.
+
+## Where people get stuck
+
+- **"It looks like plain text."** It does. See [styling](https://matrajs.com/docs/styling).
+
+- **"My toolbar button does nothing."** Almost always `click` instead of `mousedown` with `preventDefault`. If it is right and the button still does nothing, ask `editor.can` · the answer is usually that the caret is somewhere the command refuses.
+
+- **"The command does not exist."** Its extension is not in your array. That is the design, and TypeScript is telling you before the browser would.
+
+- **"Two carets appeared."** The element was mounted twice. Guard with `if (!editor.unsafe.view) editor.mount(element)` — see [frameworks](https://matrajs.com/docs/frameworks).
+
+- **"Pasting loses my formatting."** The schema has no node or mark for it. Add the extension, or accept it — a comment box refusing headings is doing its job.
+
+## Next
+
+- [Styling](https://matrajs.com/docs/styling) · because it will look wrong until you read it.
+
+- [Frameworks](https://matrajs.com/docs/frameworks) · React, Vue, Svelte, Solid and everything else.
+
+- [Commands](https://matrajs.com/docs/commands) · what else the editor can be told to do.