@matrajs/mcp 1.0.0

package/docs/docs-frameworks.md

@@ -0,0 +1,138 @@
+# Frameworks
+
+React, Vue, Svelte and Solid have bindings. Angular, Qwik and plain JavaScript need three calls, and here they are.
+
+Matra is a document model and a view that attaches to an element. It has no opinion about what renders around it, so **every framework already works** — the only question is how much sugar there is.
+
+## Four have bindings
+
+|  | Package | What you get |
+
+        {
+          bindings.map(([name, pkg, what]) => (
+
+|  | `` |  |
+          ))
+        }
+
+All four are MIT, all four are under a hundred lines, and none re-implements anything. They exist for two reasons: turning the editor's changes into a re-render is the one piece of boilerplate worth removing, and mounting twice into one element is the mistake everybody makes once. Each binding guards it.
+
+## Everything else is three calls
+
+Create it, mount it into an element, destroy it when the element goes away.
+
+```
+{`import { createEditor, starterKit } from '@matrajs/core'
+
+const editor = createEditor({ extensions: starterKit, content: '<p>Hello</p>' })
+editor.mount(document.querySelector('#editor'))
+
+// later
+editor.destroy()`}
+```
+
+That is the whole of it. `destroy()` removes the listeners and the `contenteditable` attribute, so the element is safe to reuse — which is what a hot reload, a route change and a recycled list row all rely on.
+
+> Note: The guard worth copying is `editor.unsafe.view`. It is truthy once mounted, so a component that renders twice does not attach a second view to one element. Every binding uses it and so should yours.
+
+## Svelte
+
+An action, which is exactly the shape Svelte has for this. Stores rather than runes, so the same package works in Svelte 4 and 5.
+
+```
+{`<script>
+  import { starterKit } from '@matrajs/core'
+  import { matra } from '@matrajs/svelte'
+
+  const { action, editor, state } = matra({
+    extensions: starterKit,
+    content: '<p>Hello</p>',
+  })
+</script>
+
+<button onclick={() => editor.commands.toggleBold()}
+        aria-pressed={$state.isActive('bold')}>Bold</button>
+
+<div use:action></div>`}
+```
+
+## Solid
+
+A signal rather than an external store · Solid's reactivity is not a render loop, so everything reading `state()` re-runs and nothing else does.
+
+```
+{`import { starterKit } from '@matrajs/core'
+import { createMatra } from '@matrajs/solid'
+
+export function Editor() {
+  const { editor, mount, state } = createMatra({
+    extensions: starterKit,
+    content: '<p>Hello</p>',
+  })
+
+  return (
+    <>
+      <button onClick={() => editor.commands.toggleBold()}
+              aria-pressed={state().isActive('bold')}>Bold</button>
+      <div ref={mount} />
+    </>
+  )
+}`}
+```
+
+## Angular
+
+A directive, so the element stays in the template where it belongs. There is no `@matrajs/angular` package, and the reason is worth saying rather than leaving you to wonder: an Angular library has to be published through `ng-packagr` in Angular's partial-compilation format, or it fails in every consumer's AOT build. Shipping one that breaks in production builds would be worse than these fifteen lines, which *your* compiler handles correctly because it compiles them.
+
+```
+{`import { Directive, ElementRef, OnDestroy, OnInit, inject } from '@angular/core'
+import { createEditor, starterKit } from '@matrajs/core'
+
+@Directive({ selector: '[matra]', standalone: true, exportAs: 'matra' })
+export class MatraDirective implements OnInit, OnDestroy {
+  private host = inject(ElementRef<HTMLElement>)
+  editor = createEditor({ extensions: starterKit, content: '<p>Hello</p>' })
+
+  ngOnInit() {
+    if (!this.editor.unsafe.view) this.editor.mount(this.host.nativeElement)
+  }
+
+  ngOnDestroy() {
+    this.editor.destroy()
+  }
+}
+
+// <div matra #ed="matra"></div>
+// <button (click)="ed.editor.commands.toggleBold()">Bold</button>`}
+```
+
+## Qwik, Astro, Lit, or no framework
+
+The same three calls, wherever you can get an element and a teardown hook. In Astro or a plain page, a `` tag is enough — every editor on this site is exactly that.
+
+## Keeping a toolbar in step
+
+The one thing worth knowing without a binding: `editor.on('change')` and `editor.on('selectionChange')` both return an unsubscribe function, and `editor.isActive('bold')` reads the state from the document. That is everything a toolbar needs, in any framework:
+
+```
+{`const off = editor.on('selectionChange', () => {
+  boldButton.setAttribute('aria-pressed', String(editor.isActive('bold')))
+})
+
+// on teardown
+off()`}
+```
+
+## Server rendering
+
+`createEditor` needs no DOM. Build a document, read `getHTML()` or `getJSON()`, and send it — the view only exists once something calls `mount`. That is also why [toMarkdown](https://matrajs.com/docs/api) runs on a server with no jsdom in sight.
+
+> Note: One condition: content loaded on a server must be JSON or Markdown, not an HTML string. Reading HTML is a DOM job, so `content: '
+
+…
+
+'` needs a browser · `content: storedJson` and `content: fromMarkdown(text)` do not. Writing HTML out with `getHTML()` works either way.
+
+## The paid packages, anywhere
+
+`@matrajs/ai`, `@matrajs/collab` and `@matrajs/versions` are extensions, not components. They go in the same array and know nothing about what renders around them, in every framework on this page.

package/docs/docs-index.md

@@ -0,0 +1,66 @@
+# Introduction
+
+Matra is a headless rich text editor framework. It gives you a document model, an extension API and a command system, and stays out of your interface.
+
+Matra is a headless rich text editor framework. It gives you a document model, an extension API and a command system · and stays out of the way of your interface.
+
+## Why another editor
+
+Every editor framework leaks its engine into your code. You import the engine's types, write against its internals, and upgrading it becomes your problem. Matra wraps the engine completely: your document is plain JSON and no engine type appears in a public signature.
+
+It also has no runtime dependencies. The document model, transforms, position mapping, editor state and the editable view are written from scratch, which is why an app bundles  kB gzipped instead of 117.
+
+## The three ideas
+
+Everything else follows from these, and there is not a fourth.
+
+- **The document is data.** Plain JSON — log it, store it, diff it, read it on a server that has never loaded an editor. [Document model →](https://matrajs.com/docs/document-model)
+
+- **The extension array is the feature list.** What you pass in decides what the editor can do, what it accepts on paste, and what `editor.commands` is typed as. An editor with no heading extension has no heading command, and TypeScript knows. [Writing an extension →](https://matrajs.com/docs/extensions)
+
+- **Positions are mapped, not remembered.** A position held across an `await` is wrong by the time you come back, so the async path never hands you a raw number. [Position mapping →](https://matrajs.com/docs/position-mapping)
+
+## Install
+
+```
+npm i @matrajs/core
+```
+
+```
+{`import { createEditor, starterKit } from '@matrajs/core'
+
+const editor = createEditor({ extensions: starterKit, content: '<p>Hello.</p>' })
+editor.mount(document.querySelector('#editor'))`}
+```
+
+That is a working editor. It will look like unstyled text until you write some CSS, which is what headless means — [Styling](https://matrajs.com/docs/styling) covers it in a page.
+
+## What is in the box
+
+| Package | Licence | What it is |
+
+| `@matrajs/core` | MIT | The engine and 38 extensions |
+
+| `@matrajs/react`, `/vue`, `/svelte`, /solid MIT | Framework bindings · thin, and optional |
+
+| `@matrajs/ai` | Paid | Streaming edits that survive concurrent typing |
+
+| `@matrajs/collab` | Paid | An authority, step rebasing, remote cursors |
+
+| `@matrajs/versions` | Paid | Snapshots, a real diff, restore |
+
+Table of contents, unique block ids, drag handle and comments are in the core and stay there. They are paid features elsewhere.
+
+## Where to go next
+
+Depending on what you came here to do:
+
+- **Get something working.** [Your first editor](https://matrajs.com/docs/first-editor), then [Styling](https://matrajs.com/docs/styling).
+
+- **Fit it into your app.** [Frameworks](https://matrajs.com/docs/frameworks) — React, Vue, Svelte, Solid, Angular and plain JavaScript.
+
+- **Understand it.** [Document model](https://matrajs.com/docs/document-model) and [Commands](https://matrajs.com/docs/commands).
+
+- **Decide whether to trust it.** [Benchmarks](https://matrajs.com/docs/benchmarks), including the row where the harness was wrong and what it was measuring instead.
+
+> Note: Matra is pre-1.0. The API may still change, and the view has not yet met real IME users on iOS and Android at scale · if your users type Bangla, Chinese or Japanese, test before you commit.

package/docs/docs-installation.md

@@ -0,0 +1,50 @@
+# Installation
+
+Which packages exist, which are MIT, and which need a subscription.
+
+One package. **Installing a binding installs the engine with it**, so a React application needs nothing else · no second package, and no third-party dependency arrives behind it.
+
+```
+npm i @matrajs/react   # or vue, svelte, solid
+```
+
+Without a framework, or with one that needs no binding, install the engine directly.
+
+```
+npm i @matrajs/core
+```
+
+It ships no appearance. [Styling](https://matrajs.com/docs/styling) is a page of its own, and worth reading before the first afternoon rather than after it.
+
+## Framework bindings
+
+Each one depends on `@matrajs/core` and pulls it in for you.
+
+```
+npm i @matrajs/react   # useEditor, useEditorState, EditorContent
+npm i @matrajs/vue     # useEditor, EditorContent
+npm i @matrajs/svelte  # matra — a use: action and a store
+npm i @matrajs/solid   # createMatra — a ref and a signal
+```
+
+All four are MIT and all four are thin · the editor does not care which framework renders around it, and no binding re-implements anything. Angular, Qwik and plain JavaScript need no package at all — three calls and a teardown, which [Frameworks](https://matrajs.com/docs/frameworks) shows for each of them.
+
+## The paid packages
+
+```
+npm i @matrajs/ai        # streaming edits
+npm i @matrajs/collab    # authority, rebasing, remote cursors
+npm i @matrajs/versions  # snapshots, diff, restore
+```
+
+Installed the same way as everything else. All three are source-available under a commercial licence rather than MIT · free for evaluation, development, testing, teaching, personal projects and organisations with fewer than three developers on the software, paid beyond that. Each has its own page — [AI](https://matrajs.com/docs/ai), [Collaboration and Version history](https://matrajs.com/docs/collab) — and the terms are on [the licence page](https://matrajs.com/licence).
+
+> Note: There is no registry to configure, no token to obtain and no licence key. Nothing checks anything at runtime and nothing phones home. You install them, build with them, and pay when what you built goes to production · which means an unpaid invoice is a conversation rather than an outage.
+
+## Requirements
+
+- Any bundler. The packages ship ESM and CJS with types.
+
+- No peer dependencies for the core.
+
+- Node 18+ for the parts that run on a server · Markdown needs no DOM.

package/docs/docs-mcp.md

@@ -0,0 +1,66 @@
+# Docs for AI tools (MCP)
+
+An MCP server that serves this documentation to Claude, Cursor, Codex and anything else that speaks the protocol. Zero dependencies, one command.
+
+`@matrajs/mcp` is this documentation as a [Model Context Protocol](https://modelcontextprotocol.io) server. Connect it and an AI assistant answers questions about Matra from these pages rather than from memory — which matters for a framework whose API is inferred from an array and has no ProseMirror underneath, because memory will confidently describe something else.
+
+```
+npx -y @matrajs/mcp            # stdio · what a desktop client spawns
+npx -y @matrajs/mcp --http     # http://localhost:3333/mcp
+```
+
+## Step 1 · Connect it
+
+**Claude Code**
+
+```
+claude mcp add matra -- npx -y @matrajs/mcp
+```
+
+**Claude Desktop** · in `claude_desktop_config.json`
+
+```
+{
+  "mcpServers": {
+    "matra": { "command": "npx", "args": ["-y", "@matrajs/mcp"] }
+  }
+}
+```
+
+**Cursor** · the same object under `"mcpServers"` in .cursor/mcp.json.
+
+**Codex** · in `~/.codex/config.toml`
+
+```
+[mcp_servers.matra]
+command = "npx"
+args = ["-y", "@matrajs/mcp"]
+```
+
+**Anything that speaks HTTP** · run `npx -y @matrajs/mcp --http 3333 and point the client at http://localhost:3333/mcp`.
+
+## Step 2 · Ask
+
+Ask the assistant how to add search and replace, or what `ctx.mark()` is for. It calls `search_docs`, reads the page it needs with `read_doc`, and quotes it. Nothing is fetched at runtime · every page ships inside the package.
+
+## What it serves
+
+| Tool | Does |
+
+| `list_docs` | Every page, with its slug and a one-line description. `read_doc ` | One page, as Markdown. |
+      search_docs Ranked pages with a snippet each.
+
+Every page is also a resource at `matra://docs/`. The pages are the repository's Markdown — the README, the engine notes, benchmarks, security, the changelog — and every page of this site, converted to Markdown when the package is built.
+
+## From code
+
+```
+import { createServer } from '@matrajs/mcp'
+
+const server = createServer(docs)
+server.handle({ jsonrpc: '2.0', id: 1, method: 'tools/list' })
+```
+
+`createServer` is the protocol without a transport: one message in, one reply out. Put it behind whatever transport you already run.
+
+> Note: The server is read-only and speaks only about Matra. It declares three tools, all marked read-only and idempotent, and no prompts. It never sends a message the client did not ask for, which is why the HTTP mode needs no event stream.

package/docs/docs-position-mapping.md

@@ -0,0 +1,112 @@
+# Position mapping
+
+A position is an integer into the document. The moment anything changes, that integer points somewhere else. Mapping is how a position survives an edit it did not expect.
+
+A position is an integer into the document. The moment anything changes, that integer points somewhere else. Mapping is how a position survives an edit it did not expect — and it is the single thing this editor is built around.
+
+## Why positions move
+
+Insert five characters at the start and everything after them is five further along. The number you were holding is still a valid position; it just points at different text.
+
+```
+{`hello world        XXXXXhello world
+      ↑                       ↑
+      7 · "world"             7 · "ello world"`}
+```
+
+That is fine when you act immediately — nothing happened in between. It stops being fine the moment there is a gap: you asked a model for a rewrite two seconds ago, or a colleague's edit arrived over the wire, and the person kept typing while you waited.
+
+## Markers
+
+`ctx.mark()` takes a marker. It records where the document was at that instant, and `map` replays every change made since — so the position comes back pointing at the same *text* rather than at the same number.
+
+```
+{`const at = ctx.mark()
+const { from, to } = ctx.selection
+
+for await (const chunk of stream) {
+  // Not from and to · they are two seconds old.
+  ctx.replace(at.mapRange({ from, to }), chunk)
+}`}
+```
+
+Between one chunk and the next the person may have typed, pasted, or pressed undo. The marker does not care which: it maps through whatever happened.
+
+## What it does in each case
+
+A marker taken over `"world"` in `"hello world"`, then each of these happens, then the range is mapped:
+
+| What happened | Document | 7–12 becomes | Result |
+
+        {
+          cases.map(([what, doc, moved, result]) => (
+
+|  | `` | `` |  |
+          ))
+        }
+
+> Note: The third row is the one to write code for. When the text a marker pointed at has been deleted, the range **collapses** — `from` and `to` come back equal. Check for it, because inserting into a collapsed range is not "the rewrite landed", it is a model's answer appearing where the user just deleted a sentence.
+
+```
+{`const target = at.mapRange({ from, to })
+
+if (target.from === target.to) {
+  // What we were rewriting is gone. Drop the answer rather than paste it
+  // somewhere nobody asked for.
+  return false
+}`}
+```
+
+## A complete example
+
+An AI rewrite that survives whatever the user does while it streams. This is `@matrajs/ai` in miniature:
+
+```
+{`const rewrite: Command<[instruction: string]> = (ctx, instruction) => {
+  const { from, to } = ctx.selection
+  if (from === to) return false          // nothing selected
+
+  const at = ctx.mark()                  // taken now, used later
+  const original = ctx.doc               // for the request, not for positions
+
+  void (async () => {
+    let received = ''
+    for await (const chunk of ask(instruction, original)) {
+      received += chunk
+      const target = at.mapRange({ from, to })
+      if (target.from === target.to) return   // the text went away
+      editor.commands.replace(target, received)
+    }
+  })()
+
+  return true                            // the request started
+}`}
+```
+
+Note what is *not* here: no locking the editor, no disabling input, no "please wait". The user keeps typing and the answer still lands on the words they chose.
+
+## Where else it matters
+
+- **Collaboration** · a remote step arrives in the sender's coordinates, and your unsent work has to be rebased over it. That is mapping, run in both directions.
+
+- **Comments** · anchored as marks rather than as numbers, so mapping keeps them on the right words for free — and a thread does not slide up the page when somebody deletes a paragraph above it.
+
+- **Decorations** · a search highlight, a remote caret, a spell-check squiggle. All positions, all mapped on every change.
+
+- **Version history** · a diff between two documents is only meaningful because an old document stays exactly what it was.
+
+## Is this new?
+
+No, and it is worth being straight about that. ProseMirror has had step maps for a decade and every serious editor has some version of the idea. The difference is the default: there, mapping is something you must remember to do, and forgetting it produces a bug that appears only when somebody types during a slow request — which is to say, in production and not in your tests.
+
+Here the async path does not offer you a raw number to hold. `ctx.mark()` is how you carry a position across an `await`, and there is no shorter way to do it wrong.
+
+> Note: Never hold a raw position across an `await`. A number that was correct when you asked for it is not correct when you come back, and nothing will tell you — the insert will succeed, in the wrong place.
+
+## Next
+
+- [Document model](https://matrajs.com/docs/document-model) · what the integers count.
+
+- [Commands](https://matrajs.com/docs/commands) · where `ctx.mark()` lives.
+
+- [Recipes](https://matrajs.com/docs/recipes) · autosave, and other things with a gap in them.

package/docs/docs-react.md

@@ -0,0 +1,91 @@
+# React
+
+useEditor, useEditorState and EditorContent: a toolbar whose active states stay honest.
+
+```
+npm i @matrajs/react
+```
+
+The engine comes with it · there is no second package, and nothing third-party behind it.
+
+## An editor
+
+```
+import { starterKit } from '@matrajs/core'
+import { EditorContent, useEditor } from '@matrajs/react'
+
+export function Editor() {
+  const editor = useEditor({
+    extensions: starterKit,
+    content: '<p>Hello.</p>',
+  })
+
+  return <EditorContent editor={editor} />
+}
+```
+
+The editor is created once and destroyed on unmount. **Options are read once** · changing them later does not recreate it, because tearing down a live document on a prop change loses whatever the person was writing. Use commands instead.
+
+## A toolbar that stays honest
+
+Commands mutate the document; React does not hear about that on its own, so a naive toolbar's active states go stale the moment the caret moves. `useEditorState` subscribes to both changes and selection changes.
+
+```
+import { useEditorState } from '@matrajs/react'
+
+function BoldButton({ editor }) {
+  const active = useEditorState(editor, (e) => e.isActive('bold'))
+  return (
+    <button
+      aria-pressed={active}
+      onMouseDown={(event) => {
+        event.preventDefault()        // keep the caret in the editor
+        editor.commands.toggleBold()
+      }}
+    >
+      Bold
+    </button>
+  )
+}
+```
+
+> Note: `onMouseDown` with `preventDefault`, not `onClick`. A click moves focus to the button first, which collapses the selection · so the command runs against a caret rather than the words you highlighted.
+
+## Buttons that know when they cannot
+
+`can` is the same command asking rather than doing. A button reads it to be *disabled* instead of looking enabled and doing nothing when pressed — the caret is in a code block, or the selection cannot hold that mark, and the answer is available before the user finds out by pressing.
+
+```
+const canBold = useEditorState(editor, (e) => e.can.toggleBold())
+
+<button disabled={!canBold} …>Bold</button>
+```
+
+## Several changes, one undo
+
+```
+editor.batch((c) => {
+  c.toggleBold()
+  c.toggleItalic()
+})
+```
+
+One history step, and it rolls back entirely if any command in it returns false.
+
+## Saving
+
+```
+useEffect(() => editor.on('change', () => save(editor.getJSON())), [editor])
+```
+
+`on` returns its own unsubscribe function, so it works as an effect cleanup directly.
+
+## Focus
+
+```
+const focused = useEditorFocus(editor)
+```
+
+True while the editor has DOM focus · useful for showing a toolbar only while the caret is actually in the document.
+
+> Note: StrictMode double-invokes effects in development. The mount is guarded, so that cannot leave two views attached to one element — you do not need to disable StrictMode to use this.