@matrajs/mcp 1.0.0

package/docs/docs-styling.md

@@ -0,0 +1,61 @@
+# Styling
+
+Matra ships no appearance. What you have to style, what comes with a stylesheet you can paste, and what is state rather than UI.
+
+Matra ships **no appearance at all**. Mount an editor and you get a `contenteditable` element holding plain, unstyled HTML — a heading looks like a heading only because your stylesheet says so. That is what headless means, and it is the reason the same package makes a comment box and a document editor.
+
+There are three separate things to know, and they are easy to conflate.
+
+## 1 · The document is yours to style
+
+The editor renders ordinary tags — ``, ``, ``, ``, ``. Style them the way you style any prose on your site. Scope it to the editor and you are done:
+
+```
+{`.matra-editor { outline: none; white-space: pre-wrap; }
+.matra-editor h2 { font-size: 1.5rem; margin: 1.5rem 0 .5rem; }
+.matra-editor p { margin: 0 0 .75rem; line-height: 1.6; }
+.matra-editor blockquote { border-left: 2px solid #ccc; padding-left: 1rem; }
+.matra-editor pre { background: #f4f4f4; padding: 1rem; white-space: pre-wrap; }`}
+```
+
+> Note: `white-space: pre-wrap` is not optional. HTML collapses runs of whitespace and drops a trailing one, so without it pressing space at the end of a line does nothing visible until the next character arrives — which reads as a dropped keystroke.   It is set twice on purpose. A `pre` carries the browser's own `white-space: pre`, which beats the value inherited from the editor around it, so a code block that does not restate it grows a horizontal scrollbar inside a document that is already scrolling. `overflow-x: auto` is the other way to answer that, and it is the worse one.
+
+## 2 · Some extensions bring a stylesheet
+
+An extension that renders something the document does not contain — a checkbox, a drag handle, a remote caret — cannot leave its appearance entirely to you, because there is no tag for you to target. Each of those exports the CSS it needs as a string. Paste it, inject it, or copy the rules out and rewrite them; nothing is minified and nothing is obfuscated.
+
+| Export | From | What it draws |
+
+        {
+          sheets.map(([name, pkg, what]) => (
+
+| `` | `` |  |
+          ))
+        }
+
+```
+{`import { placeholderCSS, taskListCSS, suggestionCSS } from '@matrajs/core'
+
+const sheet = new CSSStyleSheet()
+sheet.replaceSync(placeholderCSS + taskListCSS + suggestionCSS)
+document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet]`}
+```
+
+Or, if you would rather own them, open the file and copy the rules into your own stylesheet. They are a starting point, not a dependency — every one of them is a handful of lines and none of them is imported by the extension itself.
+
+## 3 · A slash menu is state, not a menu
+
+This is the one that catches people. `suggestion()` does not draw a menu. It watches for the trigger character, tracks the query as you type, exposes the range it covers, and gives you `acceptSuggestion` and `cancelSuggestion`. What it hands you is a piece of state:
+
+```
+{`const state = editor.extensionState('slash')
+// { active: true, query: 'head', range: { from: 12, to: 17 } }`}
+```
+
+The list, its position, its keyboard behaviour and its appearance are yours. That is deliberate: a menu is the most opinionated thing in an editor and the thing every product wants to look like its own. The menu on this site is about three hundred lines of ordinary DOM code with no framework, and it is in the repository — copy it and change it rather than starting from nothing.
+
+The same is true of a toolbar, a bubble menu and a comment sidebar. The editor gives you the state and the commands; the interface is the part you were going to design anyway.
+
+## What this costs you
+
+An afternoon at the start, and no fighting later. The alternative — an editor that arrives with a theme — is a week saved on day one and then a month spent overriding selectors when the design changes. If you want a running start, every editor on [the home page](https://matrajs.com/) and [the extensions page](https://matrajs.com/extensions) is a real one, and the CSS behind them is in the same repository.

package/docs/docs-svelte.md

@@ -0,0 +1,86 @@
+# Svelte
+
+A use: action, the editor, and a store that keeps a toolbar honest. Svelte 4 and 5 from one package.
+
+```
+npm i @matrajs/core @matrajs/svelte
+```
+
+## An editor
+
+```
+{`<script>
+  import { starterKit } from '@matrajs/core'
+  import { matra } from '@matrajs/svelte'
+
+  const { action, editor, state } = matra({
+    extensions: starterKit,
+    content: '<p>Hello.</p>',
+  })
+</script>
+
+<div use:action></div>`}
+```
+
+`matra()` gives you three things: the `action` to put on the element, the `editor` itself, and a `state` store that republishes whenever the document or the selection changes.
+
+> Note: The editor is created immediately, not on mount. `editor.getJSON()`, `editor.getText()` and every command work before anything is on screen — which is what a server render, a test, and a form that submits before the user scrolls to the editor all need.
+
+## A toolbar that tells the truth
+
+Subscribe to `state` and ask the editor. The pressed state comes from the document rather than from what was last clicked, so it is right after an undo, after a paste, and after somebody moves the caret with the arrow keys.
+
+```
+{`<script>
+  import { starterKit } from '@matrajs/core'
+  import { matra } from '@matrajs/svelte'
+
+  const { action, editor, state } = matra({ extensions: starterKit })
+</script>
+
+<div class="toolbar">
+  <button
+    onclick={() => editor.commands.toggleBold()}
+    aria-pressed={$state.isActive('bold')}
+  >Bold</button>
+
+  <button
+    onclick={() => editor.commands.toggleHeading(2)}
+    aria-pressed={$state.isActive('heading', { level: 2 })}
+  >H2</button>
+
+  <span>{$state.getText().length} characters</span>
+</div>
+
+<div use:action></div>`}
+```
+
+## Svelte 4 and Svelte 5
+
+One package for both. The store is a plain `svelte/store` readable, which `$state` reads identically under runes — a rune-only build would be a version boundary in exchange for nothing.
+
+## What the action does
+
+Two things you would otherwise write yourself, and one of them is easy to miss:
+
+- Mounts on attach and destroys on detach, so a route change or a `` block leaves nothing behind.
+
+- **Refuses to mount twice into one element.** An action re-run by a hot reload, or a component rendered twice, would otherwise attach a second view to one element — which is two carets fighting over it, and it looks like a browser bug rather than yours.
+
+## Reaching the editor from elsewhere
+
+`editor` is an ordinary object. Put it in a context, a store, or a prop — there is nothing framework-shaped about it, and the paid extensions do not know Svelte exists.
+
+```
+{`import { setContext, getContext } from 'svelte'
+
+// in the parent
+setContext('editor', editor)
+
+// in any child
+const editor = getContext('editor')`}
+```
+
+## Styling
+
+Matra ships no appearance. [Styling](https://matrajs.com/docs/styling) covers what you style yourself, which extensions bring a stylesheet, and why a slash menu is state rather than a menu.

package/docs/docs-versions.md

@@ -0,0 +1,103 @@
+# Version history
+
+Snapshots, a real word-level diff between them, and restore as one undo step.
+
+```
+npm i @matrajs/versions
+```
+
+Snapshots of the document, a **real diff** between any two of them — block pairing and then word runs inside a changed block, not a line-by-line text compare — and a restore that lands as a single undo step.
+
+> Note: This package is [commercial](https://matrajs.com/pricing). Free to evaluate, develop against, test with, teach with and use in personal projects · a subscription buys running it in production. Nothing phones home and there is no runtime licence check.
+
+## Setting it up
+
+```
+import { createEditor, starterKit } from '@matrajs/core'
+import { localVersionStore, versions } from '@matrajs/versions'
+
+const editor = createEditor({
+  extensions: [
+    ...starterKit,
+    versions({
+      idleMs: 30_000,
+      keep: 50,
+      store: localVersionStore('doc-42'),
+      onChange: (state) => render(state.versions, state.diff),
+    }),
+  ] as const,
+})
+```
+
+| Option | Type |  |
+
+| `idleMs` | `number | null` | Snapshot once the document has been still this long. `null` turns automatic snapshots off and leaves them to `snapshotVersion`. A version per keystroke is not history, it is a keylogger with a nicer name. |
+
+| `keep` | `number` | How many to hold. The oldest go first · the very first one never does. |
+
+| `store` | `VersionStore` | Where the list lives between visits. Without one it lives until reload. |
+
+| `onChange` | `(state) => void` | Called whenever the list or the preview changes. |
+
+| `now` | `() => number` | Where "now" comes from. Injected rather than reached for, because a test that has to sleep to make two versions differ is a test that fails on a slow machine. |
+
+A first version — `Opened` — exists from the moment the editor does, mounted or not, so a headless editor in a test, a server render or an import job always has a "before" to compare against.
+
+## Commands
+
+| Command |  |
+
+| `snapshotVersion(label?)` | Takes one now. Returns `false` when nothing has moved since the last version — a list of identical entries is a list nobody will scroll. |
+
+| `restoreVersion(id)` | Puts that document back. Takes a `Before restore` snapshot first, so the way back is the version list rather than undo · and undo is not where anybody thinks to look for their work. |
+
+| `previewVersion(id | null)` |
+
+| `forgetVersion(id)` | Drop one from the list. |
+
+```
+import { versionList } from '@matrajs/versions'
+
+editor.commands.snapshotVersion('before the rewrite')
+
+const [first] = versionList(editor)
+editor.commands.previewVersion(first.id)   // show what changed
+editor.commands.restoreVersion(first.id)   // go back · one undo step
+```
+
+> Note: A restore is **isolated as its own undo step**, whatever was typed a second before it. Undo grouping is a kindness to typing and a hazard to anything deliberate.
+
+## A version
+
+| Field | Type |  |
+
+| `id` | `number` | Continues from what the store loaded, rather than restarting at one and colliding. `label` | `string` | Defaults to `Snapshot`. `at` | `number` | Epoch milliseconds, from the clock you supplied. `doc` | `DocNode` | The document as it was. `size` | `number` | Characters at the time.   ## Persisting  `localVersionStore(key)` is a `localStorage` implementation, and the interface is two methods if you would rather keep them on a server.
+
+```
+interface VersionStore {
+  /** Sync, so the first render already has them. */
+  load(): Version[] | null
+  /** Called whenever the list changes · debouncing it is yours to decide. */
+  save(versions: Version[]): void
+}
+```
+
+ ## The diff on its own  The diff is exported separately, so a review screen can compare two documents without an editor anywhere near it — on a server, in a worker, in a test.
+
+```
+import { diffDocs } from '@matrajs/versions'
+
+const diff = diffDocs(before, after)
+// { blocks, added, removed, changed, same }
+```
+
+  Export |  |
+
+| `diffDocs(a, b)` | `DocDiff` — blocks paired, with word runs inside each changed one. `diffWords(a, b)` | `WordRun[]` · `` where kind is added, removed or same. `textOf(node)` | The text of a node, the way a reader sees it. `sizeOf(node)` | Its size in document coordinates. |
+
+| `blockStarts(doc)` | Where each top-level block begins. |
+      versionClasses — the class names the preview decorations
+          use.
+      versionDiffCSSThe stylesheet for them. See Styling.
+
+A `BlockChange` carries `before` and `after` indices — one of them `-1` when the block is new or gone — so a side-by-side view can line the two documents up without matching text a second time.

package/docs/docs-vue.md

@@ -0,0 +1,126 @@
+# Vue
+
+useEditor, useEditorState, useEditorFocus and EditorContent for Vue 3 — first-class rather than community-maintained.
+
+```
+npm i @matrajs/vue
+```
+
+Vue is first-class here rather than a community package that lags the React one. Both bindings are written together, tested together and released together, against the same version number. The engine comes with it · there is no second package.
+
+## An editor
+
+```
+<script setup lang="ts">
+import { starterKit } from '@matrajs/core'
+import { EditorContent, useEditor } from '@matrajs/vue'
+
+const editor = useEditor({
+  extensions: starterKit,
+  content: '<p>Hello.</p>',
+})
+</script>
+
+<template>
+  <EditorContent :editor="editor" />
+</template>
+```
+
+The editor is destroyed when the component unmounts, or when the surrounding effect scope is stopped — so it also works outside a component, in a composable or a store. It is `markRaw`ped, so Vue never walks the document making it reactive: the editor publishes its own changes and a proxy over a live document would cost a great deal to achieve nothing.
+
+## A toolbar that stays honest
+
+Commands mutate the document; Vue does not hear about that on its own, so a naive toolbar goes stale the moment the caret moves. `useEditorState` returns a readonly ref that follows both changes and selection changes.
+
+```
+<script setup lang="ts">
+import type { Editor } from '@matrajs/core'
+import { useEditorState } from '@matrajs/vue'
+
+const props = defineProps<{ editor: Editor }>()
+
+const bold = useEditorState(props.editor, (e) => e.isActive('bold'))
+const canBold = useEditorState(props.editor, (e) => e.can.toggleBold())
+const characters = useEditorState(props.editor, (e) => e.getText().length)
+</script>
+
+<template>
+  <button
+    :aria-pressed="bold"
+    :disabled="!canBold"
+    @mousedown.prevent="editor.commands.toggleBold()"
+  >
+    Bold
+  </button>
+  <span>{{ characters }}</span>
+</template>
+```
+
+> Note: `@mousedown.prevent` rather than `@click`. A click moves focus to the button first and collapses the selection, so the command runs against a caret instead of the words that were highlighted.
+
+`can` is the same command asking rather than doing, which is how the button knows to be disabled instead of looking enabled and doing nothing — the caret is in a code block, or the selection cannot hold that mark.
+
+## Focus
+
+```
+const focused = useEditorFocus(editor)
+```
+
+A readonly ref · useful for showing a toolbar only while the editor has the caret.
+
+## Saving
+
+```
+<script setup lang="ts">
+import { onScopeDispose } from 'vue'
+
+const editor = useEditor({ extensions: starterKit })
+
+onScopeDispose(editor.on('change', () => save(editor.getJSON())))
+</script>
+```
+
+`on` returns its own unsubscribe function, so it hands straight to `onScopeDispose` with nothing in between.
+
+## v-model, if you want it
+
+There is no `v-model` on `EditorContent` on purpose: a two-way binding over a live document means re-parsing it on every keystroke, and the parse is what loses a selection. Write it yourself where you actually need it, and only in one direction.
+
+```
+const model = defineModel<string>()
+
+const editor = useEditor({
+  extensions: starterKit,
+  content: model.value,
+})
+
+onScopeDispose(editor.on('change', () => {
+  model.value = editor.getHTML()
+}))
+```
+
+> Note: Setting `model.value` from outside will not push back into the editor, which is the behaviour you want · call `editor.commands` or `editor.setContent()` for a deliberate change instead.
+
+## Nuxt
+
+The editor touches the DOM only when it mounts, so it renders on the server without a shim. Keep `EditorContent` out of the server pass and the rest works untouched:
+
+```
+<template>
+  <ClientOnly>
+    <EditorContent :editor="editor" />
+  </ClientOnly>
+</template>
+```
+
+`useEditor` itself runs on the server — the editor exists before anything is on screen, so `getJSON()`, `getHTML()` and `getText()` all answer during a server render, with no DOM polyfill.
+
+> Note: With one condition: server-side content must be JSON or Markdown, not an HTML string. Reading HTML is a DOM job, so `content: '
+
+…
+
+'` needs a browser · `content: fromMarkdown(text)` and `content: storedJson` do not. Writing HTML out with `getHTML()` works either way.
+
+## KeepAlive
+
+The mount is guarded, so a component brought back by `` or a hot reload does not attach a second view to one element and leave two carets fighting over it.