quoin-editor 0.4.2 → 1.0.1

package/README.md

@@ -1,15 +1,20 @@
 # Quoin
 
-[![npm](https://img.shields.io/npm/v/quoin-editor)](https://www.npmjs.com/package/quoin-editor)
-[![CI](https://github.com/AmineSeboui/quoin-editor/actions/workflows/ci.yml/badge.svg)](https://github.com/AmineSeboui/quoin-editor/actions/workflows/ci.yml)
+**Blocks on screen. Markdown on disk.**
 
-A React block editor: typed blocks, drag to reorder, a markdown surface with a slash palette, and an open block type registry.
+Quoin is a block editor for React that keeps every text block as readable markdown inside a typed array you hold in your own state; images, files, code, dividers, tables and the catalogue blocks are typed data beside them. Writers get live formatting, a slash menu and drag handles; you get a document you can save, diff in git or hand to an LLM without a conversion step.
 
-Quoin edits markdown. It does not render it. A markdown block is edited in a plain textarea with shortcuts, list continuation and a slash palette, and it is drawn at rest as plain text. There is no remark or rehype pipeline in the package. A host that wants rich rendering registers its own `preview` on a block definition (see [Custom blocks](#custom-blocks)), so Quoin never forces a markdown renderer on you.
+[![npm](https://img.shields.io/npm/v/quoin-editor)](https://www.npmjs.com/package/quoin-editor) [![CI](https://github.com/AmineSeboui/quoin-editor/actions/workflows/ci.yml/badge.svg)](https://github.com/AmineSeboui/quoin-editor/actions/workflows/ci.yml) [![licence](https://img.shields.io/npm/l/quoin-editor)](LICENSE)
 
-Documentation: [amineseboui.github.io/quoin-editor](https://amineseboui.github.io/quoin-editor). Package: [`quoin-editor` on npm](https://www.npmjs.com/package/quoin-editor).
+[Live demo](https://amineseboui.github.io/quoin-editor/) | [Docs](https://amineseboui.github.io/quoin-editor/docs/getting-started/) | [Changelog](CHANGELOG.md)
 
-Quoin is published on npm as `quoin-editor`, because npm rejects the bare name `quoin` as too similar to an existing package. Everywhere below, `quoin-editor` is the package you install and import.
+![A heading typed with a hash and a space, a bulleted list, two words made bold from the toolbar, a callout inserted from the slash menu and dragged into place, while the panel beside shows the markdown onChange hands back](demo/public/quoin-demo.gif)
+
+- **Live formatting, markdown on disk.** Type `**bold**` or `# ` and see bold text or a heading; the block stores the markdown. Blocks you never edit are never rewritten (`src/engine/blocks/codec.test.ts`).
+- **Typed blocks you control like an input.** A document is `QuoinBlock[]`, plain JSON, passed as `blocks` and returned through `onChange`, so saving, versioning and validation stay in your code.
+- **Notion-style UI included, MIT.** Slash menu, bubble toolbar, block menu, drag handles, a mobile toolbar and a shortcuts dialog, with no account and no paid tier.
+- **Custom blocks as plain React.** `defineBlock` takes an editor, a preview, or both, as React components; no schema language to learn.
+- **Accessible, with tested keyboard and screen reader support.** In CI, axe runs over the canvas and its menus in light and dark mode (`e2e/tests/canvas/a11y.spec.ts`), a document is written with the keyboard alone (`keyboard-only.spec.ts`), and moves and deletions are announced (`shortcuts.spec.ts`). [What is not checked yet](https://amineseboui.github.io/quoin-editor/docs/accessibility/#what-is-not-checked-yet).
 
 ## Install
 
@@ -17,15 +22,7 @@ Quoin is published on npm as `quoin-editor`, because npm rejects the bare name `
 npm install quoin-editor
 ```
 
-```bash
-yarn add quoin-editor
-```
-
-Quoin needs React 18.2 or later (React 19 is supported) and TypeScript 5.4 or later if you use TypeScript. The block registry relies on the built-in `NoInfer` utility type, which arrived in 5.4.
-
-**Tailwind is not required, and either major version works.** See [Tailwind, or no Tailwind](#tailwind-or-no-tailwind) for the one thing a v4 host has to do.
-
-The package is around 200 kB packed. It depends on `@dnd-kit` for dragging, five Radix primitives, `cmdk` for the slash palette, `lucide-react` for the icons, and `clsx`, `tailwind-merge` and `class-variance-authority` for class composition. That is the price of the canvas: the cards, the drag gutter, the inserters, the palette and the dialogs. If you want the text editing and none of the UI, [`quoin-editor/headless`](#headless) has no component or UI library dependency at all.
+React 18.2 or 19, TypeScript 5.4 or later. Tailwind is optional, v3 and v4 both work. The npm tarball is about 1 MB packed, under 5 MB unpacked: ESM and CommonJS builds, with sourcemaps that leave out the source text. A page loads only the entries it imports.
 
 ## Quickstart
 
@@ -40,712 +37,77 @@ export function Editor() {
 }
 ```
 
-A document is an array of `QuoinBlock`, each `{ id, type, data }`. Five block types ship by default: `MARKDOWN`, `CALLOUT`, `CODE`, `IMAGE` and `FILE`. The main entry point is marked `'use client'`, so render `BlockCanvas` from a client component.
-
-If your application has Tailwind of its own, import the stylesheet from your CSS into a layer you have named instead of from JavaScript, so you decide which of the two wins. See [Cascade layers and import order](#cascade-layers-and-import-order).
-
-## The controlled-component contract
-
-`BlockCanvas` behaves like a controlled `<input value onChange>`. Update `blocks` synchronously from `onChange`.
-
-Applying the edit late is tolerated, as long as what you eventually hand back is one of the arrays the canvas gave you. It recognises its own output even when the echo is several keystrokes behind, so `startTransition` and a debounced `setBlocks` both keep typing intact.
-
-```tsx
-import { startTransition, useState } from 'react';
-import { BlockCanvas, type QuoinBlock } from 'quoin-editor';
-import 'quoin-editor/styles.css';
-
-export function TransitionEditor() {
-  const [blocks, setBlocks] = useState<QuoinBlock[]>([]);
-  return (
-    <BlockCanvas
-      blocks={blocks}
-      onChange={(next) => startTransition(() => setBlocks(next))}
-    />
-  );
-}
-```
-
-Since 0.4.1, stores that clone the document on the way through, such as a Redux or Zustand round trip or a server-synced store, are supported too. The canvas recognises an array it emitted however late it comes back, and a structural copy of one as long as it is within the last 64 edits.
-
-Debounce the side effect, not the state. `useAutosave` does exactly that: it tracks the values you give it, waits for the edits to settle, then calls your `save`, and it retries a failed save with exponential backoff.
-
-```tsx
-import { useState } from 'react';
-import { BlockCanvas, useAutosave, type QuoinBlock } from 'quoin-editor';
-import 'quoin-editor/styles.css';
-
-async function saveDocument(blocks: QuoinBlock[]) {
-  const response = await fetch('/api/document', { method: 'PUT', body: JSON.stringify(blocks) });
-  return response.json() as Promise<{ revision: number }>;
-}
-
-export function AutosavingEditor({ initial }: { initial: QuoinBlock[] }) {
-  const [blocks, setBlocks] = useState<QuoinBlock[]>(initial);
-  const { status } = useAutosave({
-    deps: [blocks],
-    build: () => blocks,
-    save: saveDocument,
-    debounceMs: 1000,
-  });
-  return (
-    <>
-      <BlockCanvas blocks={blocks} onChange={setBlocks} />
-      <p role="status">{status}</p>
-    </>
-  );
-}
-```
-
-`save` may return anything, so a mutation, an axios call or a `fetch` that resolves to a body goes straight in with no wrapper to discard the value. A save fails by rejecting, or by resolving to an explicit `{ ok: false }`; everything else, `undefined` included, is a success. `status` moves `idle` to `saving` to `saved`, or to `retrying` while it backs off, and `retry()` tries again at once. Since 0.4.1 one save runs at a time, with the newest payload queued behind it, and a pending edit is saved at once when the component unmounts or the page is hidden (`flush()` does the same on demand). Retries stop after `maxRetries` (default 8) or when `isRetryable(error)` returns false; `status` is then `failed` and `error` holds the reason.
-
-### Loading, undoing and discarding
-
-You can hand the canvas a new `blocks` array at any time to load, undo or merge a document. A new array replaces what the canvas shows when it differs from the last array you supplied.
+What `onChange` hands you, and what you store:
 
-When you echo `onChange` back into `blocks`, as every sample above does, the last array you supplied is the edited document, so `setBlocks(saved)` differs from it and resets the canvas with nothing more to do.
-
-The case that needs care is a host that does not echo edits back. There, the last array you supplied is still the original, and an array structurally equal to it is ignored: a "discard changes" button that re-supplies the original document does nothing. The same goes for restoring a copy of a state from the last 64 edits, which reads as a late echo of the canvas's own output. To force a reset, remount the canvas with a React `key`. The sample below uses a `key` so it works either way.
-
-```tsx
-import { useState } from 'react';
-import { BlockCanvas, type QuoinBlock } from 'quoin-editor';
-import 'quoin-editor/styles.css';
-
-export function EditorWithDiscard({ saved }: { saved: QuoinBlock[] }) {
-  const [blocks, setBlocks] = useState<QuoinBlock[]>(saved);
-  const [revision, setRevision] = useState(0);
-
-  function discard() {
-    setBlocks(saved);
-    setRevision((current) => current + 1);
-  }
-
-  return (
-    <>
-      <BlockCanvas key={revision} blocks={blocks} onChange={setBlocks} />
-      <button type="button" onClick={discard}>
-        Discard changes
-      </button>
-    </>
-  );
-}
-```
-
-The structural comparison is shallow over each block's `data`. A host whose block `data` contains nested objects rebuilt on every render, and which does not echo `onChange` back into `blocks`, can still lose an edit. All five core block types have flat data, so this only affects custom blocks. Keep `data` flat, or keep it referentially stable.
-
-### Undoing a deletion
-
-`onChange` reports a new array and nothing about what changed, so a host that wants a "Block deleted / Undo" toast would have to diff two arrays to find out. `onDelete` tells it instead: it fires when a block is removed through its actions menu, with the block and the index it held.
-
-It runs just after the `onChange` that reports the document without that block, so by the time your handler runs the new array has already been reported. Restoring is an ordinary document load: splice the block back at its index and supply the result as `blocks`.
-
-Do that on a later tick or a later interaction, such as the click of an Undo toast, which is what the sample below does. A restore applied synchronously inside `onDelete` is batched together with the echo of the deletion, so what reaches the canvas is structurally equal to the document it last had from you, which it reads as an unrelated re-render and ignores. Nothing throws; the deletion simply stands.
-
-```tsx
-import { useState } from 'react';
-import { BlockCanvas, type QuoinBlock } from 'quoin-editor';
-import 'quoin-editor/styles.css';
-
-export function EditorWithUndo({ saved }: { saved: QuoinBlock[] }) {
-  const [blocks, setBlocks] = useState<QuoinBlock[]>(saved);
-  const [removed, setRemoved] = useState<{ block: QuoinBlock; index: number } | null>(null);
-
-  function restore() {
-    if (!removed) return;
-    const next = [...blocks];
-    next.splice(removed.index, 0, removed.block);
-    setBlocks(next);
-    setRemoved(null);
-  }
-
-  return (
-    <>
-      <BlockCanvas blocks={blocks} onChange={setBlocks} onDelete={(block, index) => setRemoved({ block, index })} />
-      {removed && (
-        <button type="button" onClick={restore}>
-          Undo delete
-        </button>
-      )}
-    </>
-  );
-}
-```
-
-A restored block comes back at rest, even one that was inserted moments before it was deleted, so the undo does not pull the caret out of whatever is being written.
-
-## Hoist `blockTypes` and your handlers
-
-`BlockCanvas` builds its configuration from `blockTypes`, `upload`, `resolveAssetUrl` and `onError`, and memoises it on their identity. Pass a new array or a new function on every render and the memo is busted, which re-renders every block editor on the page.
-
-```tsx
-import { BlockCanvas, coreBlocks, type QuoinBlock } from 'quoin-editor';
-import 'quoin-editor/styles.css';
-
-export function SlowEditor({ blocks, onChange }: { blocks: QuoinBlock[]; onChange: (next: QuoinBlock[]) => void }) {
-  return (
-    <BlockCanvas
-      blocks={blocks}
-      onChange={onChange}
-      blockTypes={[...coreBlocks]}
-      onError={(error) => console.error(error)}
-    />
-  );
-}
-```
-
-Hoist them to module scope instead, or wrap them in `useMemo` and `useCallback` when they depend on props.
-
-```tsx
-import { BlockCanvas, coreBlocks, type AnyBlockDefinition, type QuoinBlock } from 'quoin-editor';
-import 'quoin-editor/styles.css';
-
-const blockTypes: AnyBlockDefinition[] = [...coreBlocks];
-const reportError = (error: Error) => console.error(error);
-
-export function FastEditor({ blocks, onChange }: { blocks: QuoinBlock[]; onChange: (next: QuoinBlock[]) => void }) {
-  return <BlockCanvas blocks={blocks} onChange={onChange} blockTypes={blockTypes} onError={reportError} />;
-}
-```
-
-## Custom blocks
-
-A block type is a definition built with `defineBlock`. `blockTypes` defaults to `coreBlocks`, so extend it by spreading them and adding your own. When two definitions share a `type`, the last one wins, which is also how you override a core block.
-
-```tsx
-import { Bookmark } from 'lucide-react';
-import {
-  BlockCanvas,
-  coreBlocks,
-  defineBlock,
-  type AnyBlockDefinition,
-  type BlockEditorProps,
-  type BlockPreviewProps,
-  type QuoinBlock,
-} from 'quoin-editor';
-import 'quoin-editor/styles.css';
-
-type BookmarkData = { url: string; title: string };
-
-function BookmarkEditor({ data, onChange }: BlockEditorProps<BookmarkData>) {
-  return (
-    <div>
-      <input
-        aria-label="Title"
-        value={data.title}
-        onChange={(event) => onChange({ ...data, title: event.target.value })}
-      />
-      <input
-        aria-label="URL"
-        value={data.url}
-        onChange={(event) => onChange({ ...data, url: event.target.value })}
-      />
-    </div>
-  );
-}
-
-function BookmarkPreview({ data }: BlockPreviewProps<BookmarkData>) {
-  if (data.url === '') return <p>No bookmark yet</p>;
-  return <a href={data.url}>{data.title || data.url}</a>;
-}
-
-const bookmark = defineBlock({
-  type: 'BOOKMARK',
-  label: 'Bookmark',
-  icon: Bookmark,
-  editor: BookmarkEditor,
-  preview: BookmarkPreview,
-  initialData: () => ({ url: '', title: '' }),
-});
-
-const blockTypes: AnyBlockDefinition[] = [...coreBlocks, bookmark];
-
-export function Editor({ blocks, onChange }: { blocks: QuoinBlock[]; onChange: (next: QuoinBlock[]) => void }) {
-  return <BlockCanvas blocks={blocks} onChange={onChange} blockTypes={blockTypes} />;
-}
-```
-
-A definition has these fields:
-
-| Field | Required | Purpose |
-| --- | --- | --- |
-| `type` | yes | The string stored on each block. It is how the registry finds the definition. |
-| `label` | yes | The name shown in menus and the slash palette. |
-| `icon` | yes | A [lucide](https://lucide.dev) icon component. Quoin depends on `lucide-react@^1`; add that same major to your own dependencies to import icons, so you do not end up with a second copy and mismatched icon types. |
-| `editor` | one of the two | The editing surface. It receives `data` and `onChange`. Call `onChange` with the whole next `data`, not a patch. Omit it for a block that is never editable here. |
-| `preview` | one of the two | What the block shows when it is not being edited. Omit it for an edit-only block. |
-| `initialData` | no | Seeds `data` when a block of this type is inserted. It is checked against the editor's data type. |
-| `inSlashPalette` | no | Set to `false` to keep the type out of the slash palette and the inserter. Defaults to `true`. |
-| `alwaysEditing` | no | Renders the editor permanently instead of a preview you click to edit. |
-
-Supply `editor`, `preview` or both. Omitting both is a type error, because such a block could only ever draw its own label.
-
-**Omit `editor` for a block that is not yours to edit** here: content that belongs to a server-side record, a generated summary, an audit trail. The card then offers no way in, with no edit button and no click target, and `preview` becomes required because it is the only thing left that can draw the block.
-
-```tsx
-import { ShieldCheck } from 'lucide-react';
-import { defineBlock } from 'quoin-editor';
-
-const audit = defineBlock<{ approver: string }>({
-  type: 'AUDIT',
-  label: 'Audit trail',
-  icon: ShieldCheck,
-  preview: ({ data }) => <p>Signed off by {data.approver}</p>,
-});
-```
-
-**Omit `preview` only for a block you never show read-only.** A `readOnly` canvas draws previews and never editors, so such a block shows nothing there but its own label. Quoin warns once per type in the console when that happens, naming the type. The same applies to `alwaysEditing`, which is also an editor and is also not drawn on a read-only canvas.
-
-### What the core blocks store
-
-Each core block keeps its content under its own keys. A host that persists blocks reads and writes these, so they are exported as types: import them rather than retyping the shapes.
-
-| Type | `data` | Exported as |
-| --- | --- | --- |
-| `MARKDOWN` | `markdown: string` | `MarkdownBlockData` |
-| `CALLOUT` | `tone: string`, `body: string` | `CalloutBlockData` |
-| `CODE` | `language: string`, `code: string` | `CodeBlockData` |
-| `IMAGE` | `storageKey: string`, `alt: string`, `caption?: string`, `width?: number`, `height?: number` | `ImageBlockData` |
-| `FILE` | `storageKey: string`, `filename: string`, `size?: number` | `FileBlockData` |
-
-`CoreBlockData` maps each `type` string to its shape, for a host writing one function over all five.
-
-Two of these are worth saying out loud, because both have been guessed wrong:
-
-- **The callout's prose is `body`, not `text`.** The label over the field reads "Callout text", which is what the author sees; `body` is what the block stores. `tone` is one of `info`, `tip`, `warning`, `success` or `danger`, each drawn in its own colour; anything else falls back to the neutral border and fill.
-- **Markdown blocks store markdown source, not rendered HTML.** Quoin edits and stores the source and renders it as plain text; supply a `preview` if you want it rendered.
-
-The optional fields are written after a block's first save: an image's `caption` when the author types one, its `width` and `height` once the uploaded bytes have been measured, a file's `size` when the upload reports it. `src/blocks/data.test.ts` reads the keys back out of each editor's source and fails if one drifts from the table above.
-
-### Reaching uploads from a custom block
-
-A block editor receives only `data` and `onChange`, but the canvas configuration reaches it through context, so an upload control inside a custom block needs no wiring from you.
-
-`UploadField` is the control the image and file blocks use, and it is exported for yours. It reads `upload` from the canvas it is rendered in, disables itself while a file is in flight, announces the progress to assistive technology, renders a rejection's message beside the button, and says that uploads are not configured when the host wired none.
-
-```tsx
-import { UploadField, type BlockEditorProps } from 'quoin-editor';
-
-type SlidesData = { storageKey: string; filename: string };
-
-export function SlidesEditor({ data, onChange }: BlockEditorProps<SlidesData>) {
-  return (
-    <div>
-      <p>{data.storageKey === '' ? 'No deck yet' : data.filename}</p>
-      <UploadField
-        category="slides"
-        label="Upload slides"
-        accept=".pdf"
-        onUploaded={(result) => onChange({ storageKey: result.storageKey, filename: result.filename })}
-      />
-    </div>
-  );
-}
-```
-
-Register that editor with `defineBlock` as above, and the canvas's `upload` function receives `'slides'` as its category. `UploadField` takes `category`, `label`, an optional `accept` and `onUploaded`.
-
-`FilePickerButton` is the picker underneath it: a labelled button laid over a transparent file input, which hands you the chosen `File` and uploads nothing itself. Take that one when you want your own busy and error presentation.
-
-For anything neither control covers, `useQuoin()` returns `blockTypes`, `upload`, `resolveAssetUrl` and `onError`. It throws outside a `QuoinProvider`, so call it from a block the canvas is rendering.
-
-```tsx
-import { useQuoin, type BlockEditorProps } from 'quoin-editor';
-
-type AttachmentData = { storageKey: string; filename: string };
-
-export function AttachmentEditor({ data, onChange }: BlockEditorProps<AttachmentData>) {
-  const { upload, resolveAssetUrl, onError } = useQuoin();
-
-  async function store(file: File) {
-    if (!upload) return;
-    try {
-      const stored = await upload(file, 'attachment');
-      onChange({ storageKey: stored.storageKey, filename: stored.filename });
-    } catch (error) {
-      onError(error instanceof Error ? error : new Error('The upload failed.'));
-    }
-  }
-
-  return (
-    <div>
-      {data.storageKey !== '' && <a href={resolveAssetUrl(data.storageKey)}>{data.filename}</a>}
-      <input
-        type="file"
-        disabled={!upload}
-        onChange={(event) => {
-          const file = event.target.files?.[0];
-          if (file) void store(file);
-        }}
-      />
-    </div>
-  );
-}
+```json
+[
+  { "id": "a1", "type": "MARKDOWN", "data": { "markdown": "# Release notes" } },
+  { "id": "b2", "type": "MARKDOWN", "data": { "markdown": "- Faster **paste**" } },
+  { "id": "c3", "type": "CALLOUT", "data": { "tone": "tip", "body": "Back up first." } }
+]
 ```
 
-`upload` is absent when the host wired none, which is why the control above disables itself rather than failing on the pick. `resolveAssetUrl` defaults to returning the key unchanged, and `onError` to `console.error`.
+## What ships
 
-The preview is also how you bring your own markdown renderer. Register a `MARKDOWN` definition last, reuse the core editor, and swap the preview:
-
-```tsx
-import { blockByType, coreBlocks, defineBlock, type AnyBlockDefinition, type BlockPreviewProps } from 'quoin-editor';
-
-function RichMarkdownPreview({ data }: BlockPreviewProps) {
-  return <article>{String(data.markdown ?? '')}</article>;
-}
-
-const core = blockByType(coreBlocks, 'MARKDOWN');
-
-export const blockTypes: AnyBlockDefinition[] = core
-  ? [...coreBlocks, defineBlock({ ...core, preview: RichMarkdownPreview })]
-  : coreBlocks;
-```
-
-Replace the `<article>` with whatever renderer you use.
-
-## Uploads
-
-Quoin never performs a request. You hand it an `upload` function, and the image and file blocks call it with the chosen `File` and a `category` that names what the file is for (the core blocks use `'image'` and `'file'`). It resolves with an `UploadResult`.
-
-```tsx
-import { BlockCanvas, type QuoinBlock, type UploadFn } from 'quoin-editor';
-import 'quoin-editor/styles.css';
-
-const upload: UploadFn = async (file, category) => {
-  let response: Response;
-  try {
-    response = await fetch(`/api/uploads?category=${encodeURIComponent(category)}`, {
-      method: 'POST',
-      body: file,
-    });
-  } catch {
-    throw new Error('Could not reach the server. Check your connection and try again.');
-  }
-  if (!response.ok) {
-    throw new Error(response.status === 413 ? 'That file is too large.' : 'The upload was refused.');
-  }
-  const stored = (await response.json()) as { key: string };
-  return { storageKey: stored.key, filename: file.name, size: file.size };
-};
-
-const resolveAssetUrl = (storageKey: string) => `/api/files/${encodeURIComponent(storageKey)}`;
-const reportError = (error: Error) => console.error(error);
-
-export function Editor({ blocks, onChange }: { blocks: QuoinBlock[]; onChange: (next: QuoinBlock[]) => void }) {
-  return (
-    <BlockCanvas
-      blocks={blocks}
-      onChange={onChange}
-      upload={upload}
-      resolveAssetUrl={resolveAssetUrl}
-      onError={reportError}
-    />
-  );
-}
-```
-
-- `UploadResult` is `{ storageKey, filename, size, assetId? }`. `storageKey` is an opaque key your storage can find the file by. It is what Quoin stores in the document.
-- `resolveAssetUrl` turns a `storageKey` back into a URL for display. It defaults to returning the key unchanged.
-- **Reject with an `Error` whose `message` is safe to show.** It is rendered verbatim beside the upload button. A rejection that is not an `Error`, or an `Error` with an empty message, shows a generic "Upload failed." instead.
-- **Catch network failures and rethrow with your own wording.** A raw `fetch` rejection such as "Failed to fetch" would otherwise be shown to the user verbatim.
-- The upload control is disabled while an upload is in flight.
-- With no `upload` function, upload fields render disabled, with a note that uploads are not configured.
-- `onError` receives errors Quoin cannot show inline, such as an empty markdown file picked for import. It defaults to `console.error`.
-
-## Read-only
-
-```tsx
-import { BlockCanvas, type QuoinBlock } from 'quoin-editor';
-import 'quoin-editor/styles.css';
-
-const noop = () => {};
-
-export function Reader({ blocks }: { blocks: QuoinBlock[] }) {
-  return <BlockCanvas blocks={blocks} onChange={noop} readOnly aria-label="Article" />;
-}
-```
-
-`readOnly` renders each block's `preview` with no inserters, menus, drag handles or editors. `onChange` is still required by the type, and is never called. `aria-label` names the document for assistive technology, and `className` and `id` go on the root element.
-
-Because it draws previews and never editors, a block type registered without a `preview` has nothing to show here but its own label. Quoin warns once per type in the console when that happens, so give every type you render read-only a `preview`. It is not an error channel: `onError` is for the document, this is for the registration, so it goes to the developer and not to the reader.
-
-## Theming
-
-`quoin-editor/styles.css` is compiled Tailwind CSS v4. Every colour and every radius it draws with comes from a custom property under a `--quoin-` prefix. It ships a default for all of them, on `:root` for light and on `.dark` for dark:
-
-```css
-:root {
-  --quoin-background: oklch(1 0 0);
-  --quoin-foreground: oklch(0.145 0 0);
-  --quoin-muted: oklch(0.97 0 0);
-  --quoin-muted-foreground: oklch(0.54 0 0);
-  --quoin-secondary: oklch(0.97 0 0);
-  --quoin-secondary-foreground: oklch(0.205 0 0);
-  --quoin-popover: oklch(1 0 0);
-  --quoin-popover-foreground: oklch(0.145 0 0);
-  --quoin-border: oklch(0.922 0 0);
-  --quoin-input: oklch(0.922 0 0);
-  --quoin-ring: oklch(0.45 0 0);
-  --quoin-primary: oklch(0.205 0 0);
-  --quoin-primary-foreground: oklch(0.985 0 0);
-  --quoin-accent: oklch(0.97 0 0);
-  --quoin-accent-foreground: oklch(0.205 0 0);
-  --quoin-destructive: oklch(0.55 0.245 27.325);
-  --quoin-info: oklch(0.55 0.17 250);
-  --quoin-success: oklch(0.55 0.14 155);
-  --quoin-warning: oklch(0.65 0.16 65);
-  --quoin-radius: 0.625rem;
-}
-
-.dark {
-  --quoin-background: oklch(0.145 0 0);
-  --quoin-foreground: oklch(0.985 0 0);
-  --quoin-muted: oklch(0.269 0 0);
-  --quoin-muted-foreground: oklch(0.708 0 0);
-  --quoin-secondary: oklch(0.269 0 0);
-  --quoin-secondary-foreground: oklch(0.985 0 0);
-  --quoin-popover: oklch(0.205 0 0);
-  --quoin-popover-foreground: oklch(0.985 0 0);
-  --quoin-border: oklch(1 0 0 / 10%);
-  --quoin-input: oklch(1 0 0 / 15%);
-  --quoin-ring: oklch(0.708 0 0);
-  --quoin-primary: oklch(0.922 0 0);
-  --quoin-primary-foreground: oklch(0.205 0 0);
-  --quoin-accent: oklch(0.269 0 0);
-  --quoin-accent-foreground: oklch(0.985 0 0);
-  --quoin-destructive: oklch(0.704 0.191 22.216);
-  --quoin-info: oklch(0.72 0.14 250);
-  --quoin-success: oklch(0.74 0.15 155);
-  --quoin-warning: oklch(0.79 0.15 65);
-  --quoin-radius: 0.625rem;
-}
-```
-
-Out of the box that is a neutral grey editor that works in both modes with nothing configured.
-
-Those are the only custom properties the stylesheet declares. Apart from them it reads `--tw-*`, which belong to the Tailwind runtime it is compiled with, and the `--radix-*` values Radix writes on its own portalled elements while they are open. Tailwind's theme tokens are imported by reference, so the package resolves `--spacing`, `--text-base`, `--container-md` and the rest at build time and declares none of them on your page.
-
-### The prefix arrived in 0.2.0
-
-Until 0.2.0 these names were unprefixed: `--background`, `--accent`, `--border` and the rest. That was sold as free theme inheritance, and for a shadcn-style host it was. It also meant Quoin read whatever a host happened to keep under those names.
-
-The stock Vite React + TypeScript template is the case that forced the change. It declares `--accent` as a bright purple and `--border` on `:root` with meanings of its own, so a fresh `npm create vite` project that installed Quoin drew the selected slash-palette row on that purple while keeping Quoin's own near-black `--accent-foreground`. The pair measures around 3.2:1, under the 4.5:1 that WCAG AA asks for, with nothing done wrong by the consumer.
-
-A fallback form such as `var(--quoin-accent, var(--accent))` does not fix that, because the colliding value is exactly what gets read when only the unprefixed name is set. So the prefix is unconditional, and the inheritance is no longer free. If your theme stopped reaching Quoin when you upgraded, this is why, and the next section is how to hand it over again.
-
-### Mapping your own tokens
-
-Point the prefixed names at your own in one block on `.quoin`. The canvas root carries that class, and so do the menus, palette, select and dialog Quoin renders into `document.body`, so one rule covers all of them.
-
-```css
-.quoin {
-  --quoin-background: var(--background);
-  --quoin-foreground: var(--foreground);
-  --quoin-muted: var(--muted);
-  --quoin-muted-foreground: var(--muted-foreground);
-  --quoin-secondary: var(--secondary);
-  --quoin-secondary-foreground: var(--secondary-foreground);
-  --quoin-popover: var(--popover);
-  --quoin-popover-foreground: var(--popover-foreground);
-  --quoin-border: var(--border);
-  --quoin-input: var(--input);
-  --quoin-ring: var(--ring);
-  --quoin-primary: var(--primary);
-  --quoin-primary-foreground: var(--primary-foreground);
-  --quoin-accent: var(--accent);
-  --quoin-accent-foreground: var(--accent-foreground);
-  --quoin-destructive: var(--destructive);
-  --quoin-info: var(--info);
-  --quoin-success: var(--success);
-  --quoin-warning: var(--warning);
-  --quoin-radius: var(--radius);
-}
-```
-
-`--quoin-info`, `--quoin-success` and `--quoin-warning` arrived in 0.4.0 and are read only by the callout block, for its rule and the wash behind it, never for type. If your own theme has no equivalent, leave those three out of the block and the defaults above stand; the rest of the editor does not touch them.
-
-`--quoin-ring` colours the keyboard focus outline, which is solid and drawn at full strength, so it should reach 3:1 against both `--quoin-background` and `--quoin-popover`. A pale value, such as the grey many shadcn themes keep for `--ring`, fails that, so give `--quoin-ring` a value of its own that does.
-
-That one block covers both modes: the tokens on the right already flip with your own dark class, and each mapping beats Quoin's `:root` and `.dark` defaults alike. Write it unlayered, or in a layer that sorts after `quoin`, so it outranks those defaults.
-
-To change one token rather than adopt a whole theme, declare it on `:root`, and pair it with a `.dark` rule if you theme dark at all. Pinning a token on `:root` alone also beats Quoin's `.dark` value for it, which would freeze that one token in its light form.
-
-```css
-:root {
-  --quoin-primary: oklch(0.55 0.2 260);
-  --quoin-radius: 0.5rem;
-}
-
-.dark {
-  --quoin-primary: oklch(0.72 0.17 260);
-}
-```
-
-### Dark mode
-
-Dark mode keys on a `.dark` class on an ancestor (for example `<html class="dark">`), not on `prefers-color-scheme`. Quoin redefines its own tokens under `.dark`, and its `dark:` variants follow the same class, so the two cannot disagree when a visitor's OS theme differs from your app's theme.
-
-### Resets
-
-Quoin does not reset your page. The stylesheet contains no `html`, `body`, heading, list or other element rules, and no universal `*` reset. Its own reset (box sizing, zero margins, unstyled lists and form controls) applies only inside a `.quoin` element: the canvas root, and the menus, palette, select and dialog that Quoin renders into `document.body`, which carry the class themselves. Your headings, paragraphs, lists and buttons keep whatever styles you gave them, or the browser's.
-
-All of Quoin's own rules are in cascade layers, so an **unlayered** global reset of yours beats them. A host that ships one (Bootstrap's reboot, or a hand-rolled `* { margin: 0; padding: 0; border: 0 }`) will see Quoin's padding and borders vanish. Tailwind 4's preflight is itself layered and is fine. Either declare your reset in a layer that comes before Quoin's, or scope it away from `.quoin`:
-
-```css
-@layer reset, theme, base, components, quoin, utilities;
-
-@layer reset {
-  * { margin: 0; padding: 0; border: 0; }
-}
-```
-
-```css
-*:where(:not(.quoin, .quoin *)) { margin: 0; padding: 0; border: 0; }
-```
-
-The layer statement has to come before Quoin's stylesheet is parsed, so put it first in your own CSS or in an inline `<style>` in the document head.
-
-### Tailwind, or no Tailwind
-
-`quoin-editor/styles.css` is compiled output. Every value in it is already resolved, so it is a plain stylesheet, not a Tailwind plugin, and a project with no Tailwind at all can import it and be done.
-
-If you do use Tailwind, both major versions work, and what you have to do differs:
-
-| Your setup | What to do |
+| Entry | What it adds |
 | --- | --- |
-| **Tailwind v4** | Name the layer order and import Quoin into it, as [below](#cascade-layers-and-import-order). Without it Quoin's layer sorts last and its utilities beat yours. |
-| **Tailwind v3** | Nothing. v3 emits its own utilities unlayered, and an unlayered rule beats a layered one whatever the order, so yours win over Quoin's by construction. |
-| **No Tailwind** | Nothing. Import the stylesheet and the editor is styled. |
-
-**On Tailwind v3, 0.2.0 is the first version that builds at all.** 0.1.1 and earlier emitted bare `@layer base` and `@layer utilities`, which the v3 PostCSS plugin refuses two different ways: importing the stylesheet from a component raises `'@layer base' is used but no matching '@tailwind base' directive is present`, and `@import`ing it from a stylesheet that does carry the `@tailwind` directives raises `TypeError: layerRule.nodes is not iterable`. Nesting everything under `quoin` in 0.2.0 removed both. If you worked around this by copying the stylesheet into `public/`, you can stop.
-
-### Cascade layers and import order
-
-Everything the stylesheet paints is inside one top-level cascade layer called `quoin`, with nested layers for its own theme, base and utilities inside it. Nothing it ships lands in a bare `theme`, `base`, `components` or `utilities` layer. It carries only the utilities Quoin's own components use, so the set of class names it can collide with at all is small and fixed.
-
-That changed in 0.2.0, and it had to. Until then the package imported Tailwind's utilities into the bare `utilities` layer, so in a Tailwind host they appended into the host's own `utilities` layer, after the host's rules, and beat them on source order. One bare `.hidden { display: none }` from the package was enough to keep every element carrying `hidden md:block` hidden at every width, across the whole application.
-
-The package cannot settle this on its own, because a browser orders layers by first appearance. A host whose own Tailwind is parsed first registers `theme`, `base`, `components` and `utilities` before `quoin` appears, so `quoin` sorts last and still wins. Name the order yourself, as the first thing in your stylesheet, and import Quoin into it:
-
-```css
-@layer theme, base, components, quoin, utilities;
-@import "quoin-editor/styles.css" layer(quoin);
-```
-
-With `quoin` named before `utilities`, your own utilities outrank Quoin's, including the responsive ones, while Quoin still outranks your `components`.
-
-Naming it first instead puts every layer of yours above the package:
-
-```css
-@layer quoin, theme, base, components, utilities;
-@import "quoin-editor/styles.css" layer(quoin);
-```
-
-Layer position settles more than which utility wins. It also settles who owns a custom property both of you declare on `:root`, which is why it is worth deciding rather than inheriting. Quoin no longer declares any name Tailwind owns, because it imports Tailwind's theme by reference, but a package that does, including Quoin before 0.2.0, resizes every `p-4` on the page from whichever layer sorts last.
-
-**Upgrading alone does not fix this.** Import 0.2.0 the way 0.1.1 was imported, with no layer statement of your own, and a host's `hidden md:block` still computes to `display: none`, exactly as before. The layer the package ships is what makes the fix available to you; the two lines above are what apply it.
-
-Importing the stylesheet from a root layout, or with a plain `import 'quoin-editor/styles.css'` in JavaScript, gives you no say in where the layer lands. The bundler decides, and in a Tailwind host that usually means Quoin's layer sorts last. That is fine for an application with no Tailwind of its own, and it is what the samples in this README do for brevity. A Tailwind host should use the two lines above and drop the JavaScript import.
-
-## Headless
-
-`quoin-editor/headless` is the text-editing core with no UI in it: pure transforms over a string and a selection, plus two hooks. It has no component or UI library dependency, and its bundle carries no `'use client'` banner, so the pure functions can be imported from a React Server Component.
-
-| Export | What it does |
-| --- | --- |
-| `wrapSelection`, `linkPaste` | Bold, italic, inline code and link wrapping, and pasting a URL over a selection. |
-| `toggleLinePrefix` | Heading, bullet and ordered list prefixes on the selected lines. |
-| `continueList`, `indentList` | List continuation on Enter, climbing out on an empty item, and Tab indentation. |
-| `insertCommand` | Inserts a slash-palette command at the caret. |
-| `shouldOpenPalette`, `lineAt` | Slash trigger detection and line lookup. |
-| `applyEdit` | Writes an `Edit` into a textarea through the native undo stack so Ctrl+Z keeps working. |
-| `formatShortcut`, `caretRect` | A platform-aware shortcut label, and the caret's pixel position in a textarea. |
-| `useMarkdownKeymap` | The keyboard and paste handlers that wire the above onto a textarea. |
-| `useAutoGrow` | A ref that makes a textarea's height follow its content. |
-
-The text transforms return an `Edit`, `{ value, selectionStart, selectionEnd }`, or `null` when they do not apply.
-
-```ts
-import { wrapSelection } from 'quoin-editor/headless';
-
-export function bold(text: string, start: number, end: number): string {
-  return wrapSelection('bold', text, start, end).value;
-}
-```
-
-`useMarkdownKeymap` and `useAutoGrow` are importable from a React Server Component, because the module that exports them carries no `'use client'` banner. Being hooks, they are callable only from a client component.
-
-```tsx
-'use client';
-
-import { useState } from 'react';
-import { useAutoGrow, useMarkdownKeymap } from 'quoin-editor/headless';
-
-export function Notes() {
-  const [text, setText] = useState('');
-  const [paletteOpen, setPaletteOpen] = useState(false);
-  const ref = useAutoGrow<HTMLTextAreaElement>(text);
-  const keymap = useMarkdownKeymap({
-    commit: setText,
-    onOpenPalette: () => setPaletteOpen(true),
-  });
-
-  return (
-    <>
-      <textarea
-        ref={ref}
-        value={text}
-        onChange={(event) => setText(event.target.value)}
-        {...keymap}
-      />
-      {paletteOpen && <p role="status">Open your own command palette here.</p>}
-    </>
-  );
-}
-```
-
-The keymap swallows a `/` typed at the start of a word (at the start of the text, or after a newline, space or tab, outside a code fence) and calls `onOpenPalette` instead, so open a palette of your own there, or insert the slash yourself.
-
-Everything in the table is re-exported from the main `quoin-editor` entry too, alongside `TEXT_COMMANDS`, the built-in slash-palette entries. Import from `quoin-editor/headless` when you want the transforms without the components behind them, and from `quoin-editor` when you are already importing `BlockCanvas`.
-
-```ts
-import { toggleLinePrefix } from 'quoin-editor';
-
-export function heading(text: string, start: number, end: number): string {
-  return toggleLinePrefix('h2', text, start, end).value;
-}
-```
-
-The main entry carries a `'use client'` banner, so a React Server Component has to import from `quoin-editor/headless` rather than from `quoin-editor`.
-
-## Exports
-
-From `quoin-editor`: `BlockCanvas`, `QuoinProvider`, `useQuoin`, `defineBlock`, `blockByType`, `paletteBlocks`, `coreBlocks`, `UploadField`, `FilePickerButton`, `TEXT_COMMANDS`, `useBlockList`, `useAutosave`, `useAutoGrow`, and the headless transforms and hooks, with their types (`QuoinBlock`, `UploadFn`, `UploadResult`, `BlockDefinition`, `AnyBlockDefinition`, `BlockEditorProps`, `BlockPreviewProps`, `BlockCanvasProps`, `UploadFieldProps`, `FilePickerButtonProps` and others), and the [core block data shapes](#what-the-core-blocks-store): `MarkdownBlockData`, `CalloutBlockData`, `CodeBlockData`, `ImageBlockData`, `FileBlockData` and `CoreBlockData`.
-
-From `quoin-editor/headless`: the transforms and the two hooks listed above, with no UI.
-
-From `quoin-editor/styles.css`: the stylesheet.
-
-## Accessibility
-
-What the test suite checks:
-
-- axe runs over the canvas, the block cards, the inserter, the slash palette and the shortcuts reference.
-- Controls carry accessible names, and the icons in the canvas, the block options menu, the inserter and the slash palette are hidden from assistive technology.
-- Blocks reorder by keyboard, with announcements that name each block by label and position.
-- Escape leaves an open block and returns focus to its Edit button.
-- The default light and dark tokens keep the keyboard focus outline at 3:1 or more and highlighted-row text at 4.5:1 or more, and focusable controls draw the focus as an outline, which Windows forced colours mode keeps.
-
-The checks are automated. A manual pass with NVDA and VoiceOver is not recorded yet.
-
-Known gaps in 0.4:
-
-- A markdown block is read as source. At rest it is plain text, so a screen reader reads the markdown characters as written.
-- Keyboard drag with Space and the arrow keys can drop a block in place, and its announcement can name the wrong position. Use Move up and Move down in the block's options menu to reorder by keyboard.
-
-## Stability
-
-Quoin is 0.x. A minor version may contain breaking changes, and each one is listed in the [changelog](CHANGELOG.md). If you need stability, pin a minor with `~0.4.0`, which takes patch releases only.
+| `quoin-editor` | The canvas: text, lists, tasks, quotes, callouts, toggles, dividers, code, images and files, with every menu and toolbar |
+| `quoin-editor/table`, `/embed`, `/math`, `/toc`, `/mention`, `/emoji`, `/find`, `/stats` | Opt-in features, each its own entry; `quoin-editor/catalogue` adds them all |
+| `quoin-editor/yjs`, `/presence` | Real-time co-editing through your own Yjs provider, and collaborators' carets |
+| `quoin-editor/comments` | Comment threads anchored to text, kept in your store |
+| `quoin-editor/ai` | Your model's answers streamed into the document; Quoin never calls a model |
+| `quoin-editor/view`, `/diff`, `/docx` | Server rendering with no hooks, a diff of two versions, a Word export |
+| `quoin-editor/headless`, `/engine` | The editor without the canvas UI, and the engine alone with no React |
+
+## Why Quoin
+
+Each competitor cell links to the page that shows it, and Quoin's cite the files listed below the table; the Tiptap UI cell also draws on the review in [#73](https://github.com/AmineSeboui/quoin-editor/issues/73) (2026-10-12).
+
+| Feature | Quoin 1.0 | Tiptap 3 | BlockNote | Editor.js |
+| --- | --- | --- | --- | --- |
+| Stored document | Block array, markdown per text block | [JSON, or HTML][tt-store] | [Block JSON][bn-formats] | [JSON][ej-repo] |
+| Markdown | The storage format | [`@tiptap/markdown`, an early release][tt-md] | [Export and import, documented as lossy][bn-formats] | [Community plugin][ej-awesome] |
+| Notion-style UI | Included, MIT | [MIT menus and drag handle][tt-review]; [Notion-like template on a paid plan][tt-notion] | [Included][bn-home] | [Toolbox and inline toolbar][ej-home] |
+| Licence | MIT | [MIT core, paid Pro extensions][tt-repo] | [MPL-2.0, `xl-*` packages GPL-3.0 or commercial][bn-repo] | [Apache-2.0][ej-repo] |
+| Real-time collaboration | Yjs, opt-in entry | [Yjs][tt-collab] | [Yjs][bn-collab] | [On its roadmap][ej-repo] |
+| Comments | Opt-in, your store | [Paid plan][tt-comments] | [Built in, on Yjs or a thread store][bn-comments] | [Community plugin][ej-awesome] |
+| Framework | React | [React, Vue, Svelte, plain JavaScript and more][tt-install] | [React][bn-start] | [Plain JavaScript][ej-start] |
+
+Sources, checked on 2026-10-23: Tiptap [persistence][tt-store], [markdown][tt-md], [Notion-like template][tt-notion], [repository][tt-repo], [collaboration][tt-collab], [comments][tt-comments], [install][tt-install]; BlockNote [home][bn-home], [formats][bn-formats], [repository][bn-repo], [collaboration][bn-collab], [comments][bn-comments], [getting started][bn-start]; Editor.js [home][ej-home], [repository][ej-repo], [getting started][ej-start], [awesome-editorjs][ej-awesome]. Quoin: storage in `src/engine/blocks/markdown-spec.ts`, untouched blocks in `src/engine/blocks/codec.test.ts`, collaboration in `e2e/tests/canvas/presence.spec.ts`, comments in `e2e/tests/canvas/comments.spec.ts`.
+
+[tt-store]: https://tiptap.dev/docs/editor/core-concepts/persistence
+[tt-md]: https://tiptap.dev/docs/editor/markdown
+[tt-review]: https://github.com/AmineSeboui/quoin-editor/issues/73
+[tt-notion]: https://tiptap.dev/docs/ui-components/templates/notion-like-editor
+[tt-repo]: https://github.com/ueberdosis/tiptap
+[tt-collab]: https://tiptap.dev/docs/editor/extensions/functionality/collaboration
+[tt-comments]: https://tiptap.dev/docs/comments/getting-started/overview
+[tt-install]: https://tiptap.dev/docs/editor/getting-started/install
+[bn-home]: https://www.blocknotejs.org/
+[bn-formats]: https://www.blocknotejs.org/docs/foundations/supported-formats
+[bn-repo]: https://github.com/TypeCellOS/BlockNote
+[bn-collab]: https://www.blocknotejs.org/docs/features/collaboration
+[bn-comments]: https://www.blocknotejs.org/docs/features/collaboration/comments
+[bn-start]: https://www.blocknotejs.org/docs/getting-started
+[ej-home]: https://editorjs.io/
+[ej-repo]: https://github.com/codex-team/editor.js
+[ej-start]: https://editorjs.io/getting-started
+[ej-awesome]: https://github.com/editor-js/awesome-editorjs
+
+## Learn more
+
+- [The controlled contract](https://amineseboui.github.io/quoin-editor/docs/contract/): loading, autosave, discarding, undoing a deletion
+- [Theming](https://amineseboui.github.io/quoin-editor/docs/theming/): `--quoin-` tokens, dark mode, cascade layers, Tailwind
+- [Custom blocks](https://amineseboui.github.io/quoin-editor/docs/custom-blocks/) and [uploads](https://amineseboui.github.io/quoin-editor/docs/uploads/)
+- [Extensions](https://amineseboui.github.io/quoin-editor/docs/extensions/): every opt-in feature, and writing your own
+- [Collaboration](https://amineseboui.github.io/quoin-editor/docs/collaboration/), [comments](https://amineseboui.github.io/quoin-editor/docs/comments/) and [AI](https://amineseboui.github.io/quoin-editor/docs/ai/)
+- [Server rendering](https://amineseboui.github.io/quoin-editor/docs/server-rendering/): read-only, `QuoinView`, `QuoinDiff`, `toDocx`
+- [Accessibility](https://amineseboui.github.io/quoin-editor/docs/accessibility/): what each test suite checks, and what it does not yet
+- [FAQ](https://amineseboui.github.io/quoin-editor/docs/faq/): the package name, stability, React versions, and [upgrading from 0.4](MIGRATION.md)
+
+## The name
+
+A quoin is the wedge a letterpress printer tightens to lock blocks of type into the frame, so nothing moves while the page is printed. Quoin does the same for blocks of markdown.
 
 ## Licence