open-wysiwyg-editor 0.1.0 → 1.0.0

package/README.md

@@ -1,57 +1,126 @@
-# open-wysiwyg-editor
+<p align="center"><a href="https://alhassan73.github.io/open-wysiwyg-editor/"><img src="https://raw.githubusercontent.com/alhassan73/open-wysiwyg-editor/main/.github/assets/banner.png" alt="Open WYSIWYG Editor — accessible, RTL-first rich text editor for every framework" width="100%"></a></p>
 
-An accessible rich text editor that is RTL-first and safe under a strict CSP. It works in plain JavaScript and in any framework.
+# Open WYSIWYG Editor
 
-- **Accessible by design.** Built against WCAG 2.2 AA, ATAG 2.0 and the WAI-ARIA Authoring Practices. You can do everything from the keyboard and never get trapped. Screen readers hear announcements, and Windows High Contrast is supported.
-- **Secure by default.** All HTML input passes through DOMPurify, URLs are checked against an allow-list, and Trusted Types are supported. It runs under `script-src 'self'; style-src 'self'` with no `unsafe-inline`.
-- **Arabic and RTL first.** It ships with English and Arabic UIs, mirrors the layout, and lets each block carry its own direction.
-- **Complete out of the box.** You get headings, lists, task lists, tables, images, links, code, text and highlight colors, alignment, find & replace, an HTML source view, word count and more.
-- **Headless if you want it.** The same engine is available with no UI, so you can build your own interface on top.
-- **MIT license.** There is no license key, no telemetry and no cloud dependency.
+[![npm version](https://img.shields.io/npm/v/open-wysiwyg-editor)](https://www.npmjs.com/package/open-wysiwyg-editor)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/open-wysiwyg-editor)](https://bundlephobia.com/package/open-wysiwyg-editor)
+[![license](https://img.shields.io/npm/l/open-wysiwyg-editor)](https://github.com/alhassan73/open-wysiwyg-editor/blob/main/LICENSE)
+
+**[Live demo →](https://alhassan73.github.io/open-wysiwyg-editor/)** · [GitHub](https://github.com/alhassan73/open-wysiwyg-editor) · [npm](https://www.npmjs.com/package/open-wysiwyg-editor)
+
+An accessible rich text editor that works on **any website**: plain HTML/JS, React, Next.js, Preact, Vue, Nuxt, Angular, Svelte, Solid, Astro, WordPress and more. It's RTL-first, it runs under a strict Content Security Policy, and it ships its own TypeScript types. MIT licensed, with no license key, no telemetry and no cloud service.
 
 Built on [ProseMirror](https://prosemirror.net). Content is stored as HTML or JSON, and node and mark names match Tiptap's.
 
----
+## Features
+
+| Area | What you get |
+| --- | --- |
+| **Formatting** | Headings · Bold, italic, underline, strike, inline code · Subscript / superscript · Text and highlight colors · Alignment · Text direction per block |
+| **Blocks** | Bullet, numbered and task lists · Blockquote · Code block · Horizontal rule · Tables with caption and header rows · Images with alt text and caption · Links |
+| **Tools** | Find & replace · HTML source view · Word and character count · Element path · Keyboard shortcut help · Undo / redo · Markdown-style typing shortcuts |
+| **Accessibility** | WCAG 2.2 AA, ATAG 2.0 and WAI-ARIA patterns · Fully keyboard operable, no keyboard trap · Screen reader announcements · Windows High Contrast · Dark theme |
+| **Security** | DOMPurify on every input · URL allow-list · Trusted Types · No `unsafe-inline` needed |
+| **Languages** | English and Arabic built in (add your own) · Mirrored UI in RTL · `dir="auto"` on every block |
+| **Everywhere** | `<owe-editor>` web component for plain HTML and forms · Packages for React, Next.js, Preact, Vue, Nuxt, Angular, Svelte, Solid and Astro |
+| **Your way** | Full UI by default · Headless mode for your own UI · Custom toolbar buttons · Extensions API · Theme with CSS variables |
+
+Every release is tested end to end in Chromium, Firefox and WebKit, under a strict CSP with Trusted Types and with axe-core accessibility checks.
 
 ## Install
 
-```sh
+```bash
 npm install open-wysiwyg-editor
 # or
 pnpm add open-wysiwyg-editor
+# or
+yarn add open-wysiwyg-editor
 ```
 
-Without a bundler, load the browser build from a CDN:
+Or with no build step, from a CDN:
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/open-wysiwyg-editor/dist/style.min.css" />
-<script src="https://unpkg.com/open-wysiwyg-editor/dist/open-wysiwyg-editor.global.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/open-wysiwyg-editor@1/dist/style.min.css" />
+<script src="https://cdn.jsdelivr.net/npm/open-wysiwyg-editor@1/dist/open-wysiwyg-editor.global.js"></script>
 ```
 
-## Quick start
+### Pick your framework
+
+The core package works everywhere. Each framework also has its own small package. It re-exports the whole core API, ships the stylesheets, and handles mounting, cleanup, server-side rendering and two-way binding for you. Install **one** of them (it brings the core with it):
+
+| Framework | Package | Install |
+| --- | --- | --- |
+| Plain JS, HTML forms, CMSs, Lit, Alpine, htmx, Ember, Qwik | [`open-wysiwyg-editor`](https://www.npmjs.com/package/open-wysiwyg-editor) | `npm install open-wysiwyg-editor` |
+| React, Remix, Gatsby, Vite | [`@open-wysiwyg-editor/react`](https://www.npmjs.com/package/@open-wysiwyg-editor/react) | `npm install @open-wysiwyg-editor/react` |
+| Next.js | [`@open-wysiwyg-editor/next`](https://www.npmjs.com/package/@open-wysiwyg-editor/next) | `npm install @open-wysiwyg-editor/next` |
+| Preact | [`@open-wysiwyg-editor/preact`](https://www.npmjs.com/package/@open-wysiwyg-editor/preact) | `npm install @open-wysiwyg-editor/preact` |
+| Vue 3 | [`@open-wysiwyg-editor/vue`](https://www.npmjs.com/package/@open-wysiwyg-editor/vue) | `npm install @open-wysiwyg-editor/vue` |
+| Nuxt | [`@open-wysiwyg-editor/nuxt`](https://www.npmjs.com/package/@open-wysiwyg-editor/nuxt) | `npm install @open-wysiwyg-editor/nuxt` |
+| Angular | [`@open-wysiwyg-editor/angular`](https://www.npmjs.com/package/@open-wysiwyg-editor/angular) | `npm install @open-wysiwyg-editor/angular` |
+| Svelte, SvelteKit | [`@open-wysiwyg-editor/svelte`](https://www.npmjs.com/package/@open-wysiwyg-editor/svelte) | `npm install @open-wysiwyg-editor/svelte` |
+| Solid, SolidStart | [`@open-wysiwyg-editor/solid`](https://www.npmjs.com/package/@open-wysiwyg-editor/solid) | `npm install @open-wysiwyg-editor/solid` |
+| Astro | [`@open-wysiwyg-editor/astro`](https://www.npmjs.com/package/@open-wysiwyg-editor/astro) | `npm install @open-wysiwyg-editor/astro` |
+
+All packages share one version number and are released together.
+
+## Usage
+
+The core is one function, `createEditor(options)`. It mounts the editor inside the element you pass and returns an `editor` instance. The framework packages do the three steps below for you. If you use the core directly, follow them in every framework:
+
+1. Load the stylesheet once: `import "open-wysiwyg-editor/style.css"` (or the `<link>` above).
+2. Call `createEditor()` **in the browser**, after the element exists. It throws during server-side rendering.
+3. Call `editor.destroy()` when the element goes away.
+
+### Plain HTML / JavaScript (no framework, no bundler)
+
+The CDN script defines the `<owe-editor>` tag, so one tag is enough:
 
 ```html
-<div id="editor"><p>Hello <strong>world</strong></p></div>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/open-wysiwyg-editor@1/dist/style.min.css" />
+<script src="https://cdn.jsdelivr.net/npm/open-wysiwyg-editor@1/dist/open-wysiwyg-editor.global.js"></script>
+
+<owe-editor id="editor" placeholder="Write something…">
+  <template><p>Hello <strong>world</strong></p></template>
+</owe-editor>
+
+<script>
+  document.querySelector("#editor").addEventListener("input", (event) => {
+    console.log(event.target.value); // '<p dir="auto">Hello <strong>world</strong></p>'
+  });
+</script>
 ```
 
-```js
-import { createEditor } from "open-wysiwyg-editor";
-import "open-wysiwyg-editor/style.css";
+Or call the function yourself:
 
-const editor = createEditor({ element: document.querySelector("#editor") });
+```html
+<div id="editor"><p>Hello <strong>world</strong></p></div>
 
-editor.getHTML(); // "<p dir=\"auto\">Hello <strong>world</strong></p>"
+<script>
+  const editor = OpenWysiwygEditor.createEditor({
+    element: "#editor", // a selector, or document.querySelector("#editor")
+    placeholder: "Write something…",
+  });
+  // editor.getHTML() → '<p dir="auto">Hello <strong>world</strong></p>'
+</script>
 ```
 
-With the global build:
+This also works in WordPress, Shopify, Webflow, PHP, Django and Rails templates.
 
-```js
-const editor = OpenWysiwygEditor.createEditor({ element: document.querySelector("#editor") });
-```
+### HTML forms
+
+Use `<owe-editor name="…">`. It is a form-associated element, so the form submits the editor's HTML under that name, and `form.reset()` restores the starting content. A `<label for>` pointing at its `id` becomes the accessible name.
 
-### Plain HTML forms
+```html
+<form method="post">
+  <label for="body">Article</label>
+  <owe-editor id="body" name="body">
+    <template><p>Draft…</p></template>
+  </owe-editor>
+  <button>Save</button>
+</form>
+```
 
-If you mount the editor on a `<textarea>`, it hides the textarea and keeps its value in sync, so the form submits the HTML. It also uses the textarea's `<label>` as its accessible name.
+Or mount the editor on a `<textarea>`. The editor hides the textarea and keeps its value in sync, so the form submits the HTML. The textarea's `<label>` becomes the editor's accessible name.
 
 ```html
 <form method="post">
@@ -59,40 +128,270 @@ If you mount the editor on a `<textarea>`, it hides the textarea and keeps its v
   <textarea id="body" name="body"><p>Draft…</p></textarea>
   <button>Save</button>
 </form>
-<script type="module">
-  import { createEditor } from "open-wysiwyg-editor";
-  createEditor({ element: document.querySelector("#body") });
+<script>
+  OpenWysiwygEditor.createEditor({ element: "#body" });
 </script>
 ```
 
-### React / Next.js
+### Any bundler (Vite, Webpack, Parcel…), JS or TS
 
-Dedicated adapters for React, Vue, Svelte and Angular, and an `<owe-editor>` web component, are on the way. Until they ship, the core works in any framework. Mount it in an effect and destroy it on cleanup:
+```js
+import { createEditor } from "open-wysiwyg-editor";
+import "open-wysiwyg-editor/style.css";
+
+const editor = createEditor({
+  element: "#editor", // or an HTMLElement
+  onUpdate: (editor) => console.log(editor.getHTML()),
+});
+```
+
+To use the `<owe-editor>` tag with a bundler, import its entry once: `import "open-wysiwyg-editor/element";`.
+
+### React (Vite, CRA, Remix, Gatsby)
+
+```bash
+npm install @open-wysiwyg-editor/react
+```
 
 ```tsx
-"use client"; // Next.js: the editor needs the DOM
-import { useEffect, useRef } from "react";
-import { createEditor, type Editor } from "open-wysiwyg-editor";
-import "open-wysiwyg-editor/style.css";
+import { useState } from "react";
+import { RichTextEditor } from "@open-wysiwyg-editor/react";
+import "@open-wysiwyg-editor/react/style.css";
+
+export function Article() {
+  const [html, setHtml] = useState("<p>Hello</p>");
+  return <RichTextEditor value={html} onChange={setHtml} placeholder="Write something…" />;
+}
+```
+
+For a custom UI, `useEditor({ ui: false })` returns `{ ref, editor }`. [Full guide →](https://github.com/alhassan73/open-wysiwyg-editor/tree/main/packages/react#readme)
+
+### Next.js
+
+```bash
+npm install @open-wysiwyg-editor/next
+```
+
+App Router: the package is already marked `"use client"`, so you can use it straight from a Server Component. Import the stylesheet once in the layout:
+
+```tsx
+// app/layout.tsx
+import "@open-wysiwyg-editor/next/style.css";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+```tsx
+// app/articles/new/page.tsx  (a Server Component)
+import { RichTextEditor } from "@open-wysiwyg-editor/next";
+import { saveArticle } from "./actions";
+
+export default function Page() {
+  return (
+    <form action={saveArticle}>
+      <RichTextEditor name="body" defaultValue="<p>Hello</p>" />
+      <button>Save</button>
+    </form>
+  );
+}
+```
+
+`name` keeps a hidden `<input>` in sync, so the Server Action receives the HTML in its `FormData`:
+
+```ts
+// app/articles/new/actions.ts
+"use server";
+
+export async function saveArticle(formData: FormData) {
+  const html = String(formData.get("body")); // sanitize again here before you store it
+}
+```
+
+Pages Router: use the same component in any page and import the stylesheet in `pages/_app.tsx`. [Full guide →](https://github.com/alhassan73/open-wysiwyg-editor/tree/main/packages/next#readme)
+
+### Preact
+
+```bash
+npm install @open-wysiwyg-editor/preact
+```
+
+```tsx
+import { useState } from "preact/hooks";
+import { RichTextEditor } from "@open-wysiwyg-editor/preact";
+import "@open-wysiwyg-editor/preact/style.css";
+
+export function Article() {
+  const [html, setHtml] = useState("<p>Hello</p>");
+  return <RichTextEditor value={html} onChange={setHtml} class="article-editor" />;
+}
+```
+
+Same API as the React package, with `class` instead of `className`. [Full guide →](https://github.com/alhassan73/open-wysiwyg-editor/tree/main/packages/preact#readme)
+
+### Vue 3
+
+```bash
+npm install @open-wysiwyg-editor/vue
+```
+
+```vue
+<script setup>
+import { ref } from "vue";
+import { RichTextEditor } from "@open-wysiwyg-editor/vue";
+import "@open-wysiwyg-editor/vue/style.css";
+
+const html = ref("<p>Hello</p>");
+</script>
+
+<template>
+  <RichTextEditor v-model="html" placeholder="Write something…" />
+</template>
+```
+
+Pass more `createEditor` options with `:options="{ … }"`. A template ref exposes `editor`. [Full guide →](https://github.com/alhassan73/open-wysiwyg-editor/tree/main/packages/vue#readme)
+
+### Nuxt
+
+```bash
+npm install @open-wysiwyg-editor/nuxt
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["@open-wysiwyg-editor/nuxt"],
+  // optional: wysiwygEditor: { css: true, componentName: "RichTextEditor" },
+});
+```
+
+The module adds the stylesheet and auto-imports the component, so it works in any page without an import:
+
+```vue
+<script setup>
+const html = ref("<p>Hello</p>");
+</script>
+
+<template>
+  <RichTextEditor v-model="html" />
+</template>
+```
+
+[Full guide →](https://github.com/alhassan73/open-wysiwyg-editor/tree/main/packages/nuxt#readme)
+
+### Angular
+
+```bash
+npm install @open-wysiwyg-editor/angular
+```
+
+Add the stylesheet to `angular.json`, in `"styles": ["node_modules/@open-wysiwyg-editor/angular/style.css"]`. Then use the standalone component. It works with `ngModel` and reactive forms:
+
+```ts
+import { Component } from "@angular/core";
+import { FormsModule } from "@angular/forms";
+import { RichTextEditorComponent } from "@open-wysiwyg-editor/angular";
+
+@Component({
+  selector: "app-article",
+  imports: [FormsModule, RichTextEditorComponent],
+  template: `<owe-rich-text-editor [(ngModel)]="html" placeholder="Write something…" />`,
+})
+export class ArticleComponent {
+  html = "<p>Hello</p>";
+}
+```
+
+It starts in the browser only (safe with Angular SSR) and runs outside the zone. [Full guide →](https://github.com/alhassan73/open-wysiwyg-editor/tree/main/packages/angular#readme)
+
+### Svelte / SvelteKit
+
+```bash
+npm install @open-wysiwyg-editor/svelte
+```
+
+```svelte
+<script>
+  import { richText } from "@open-wysiwyg-editor/svelte";
+  import "@open-wysiwyg-editor/svelte/style.css";
+
+  let html = "<p>Hello</p>";
+</script>
 
-export function RichText({ value, onChange }: { value: string; onChange: (html: string) => void }) {
-  const host = useRef<HTMLDivElement>(null);
-  const editor = useRef<Editor | null>(null);
+<div use:richText={{ content: html, onUpdate: (e) => (html = e.getHTML()) }}></div>
+```
+
+Works with Svelte 3, 4 and 5. Actions never run on the server, so this is safe in SvelteKit. [Full guide →](https://github.com/alhassan73/open-wysiwyg-editor/tree/main/packages/svelte#readme)
+
+### Solid / SolidStart
 
-  useEffect(() => {
-    editor.current = createEditor({
-      element: host.current,
-      content: value,
-      onUpdate: (e) => onChange(e.getHTML()),
-    });
-    return () => editor.current?.destroy();
-  }, []);
+```bash
+npm install @open-wysiwyg-editor/solid
+```
 
-  return <div ref={host} />;
+```tsx
+import { createSignal } from "solid-js";
+import { richText } from "@open-wysiwyg-editor/solid";
+import "@open-wysiwyg-editor/solid/style.css";
+
+export function Article() {
+  const [html, setHtml] = createSignal("<p>Hello</p>");
+  false && richText; // keeps the import from being tree-shaken, so `use:richText` works
+  return <div use:richText={{ content: html(), onUpdate: (e) => setHtml(e.getHTML()) }} />;
 }
 ```
 
-### Headless
+[Full guide →](https://github.com/alhassan73/open-wysiwyg-editor/tree/main/packages/solid#readme)
+
+### Astro
+
+```bash
+npm install @open-wysiwyg-editor/astro
+```
+
+```astro
+---
+import { RichTextEditor } from "@open-wysiwyg-editor/astro";
+---
+
+<form method="post">
+  <RichTextEditor name="body" value="<p>Hello</p>" placeholder="Write something…" />
+  <button>Save</button>
+</form>
+```
+
+The component renders `<owe-editor>` and loads the element and stylesheet in the browser, so it works with plain form posts and no UI framework. [Full guide →](https://github.com/alhassan73/open-wysiwyg-editor/tree/main/packages/astro#readme)
+
+### Others (Lit, Alpine, htmx, Ember, Qwik, WordPress, PHP)
+
+Anything that can write HTML can use the `<owe-editor>` tag from the core package: load the CDN script (or `import "open-wysiwyg-editor/element"`) and the stylesheet, then put the tag in your markup. It dispatches `input` and `change` events and takes part in forms, so htmx, Turbo and plain `<form>` posts work without glue code.
+
+```html
+<!-- Alpine -->
+<owe-editor name="body" x-on:input="html = $event.target.value"></owe-editor>
+
+<!-- htmx: the form field is sent like any other input -->
+<form hx-post="/articles" hx-swap="outerHTML">
+  <owe-editor name="body" value="&lt;p&gt;Hello&lt;/p&gt;"></owe-editor>
+  <button>Save</button>
+</form>
+```
+
+```ts
+// Lit
+import "open-wysiwyg-editor/element";
+import "open-wysiwyg-editor/style.css";
+// html`<owe-editor .value=${this.html} @input=${(e) => (this.html = e.target.value)}></owe-editor>`
+```
+
+In WordPress or any PHP template, add the CDN `<link>` and `<script>` in the page head or footer, and print the tag with an escaped `value` attribute (`esc_attr( $html )`).
+
+### Headless (bring your own UI)
 
 Use the headless entry when you want the engine and every extension without the built-in UI:
 
@@ -108,13 +407,65 @@ editor.subscribe(() => {
 
 From the main entry, `createEditor({ ui: false })` does the same thing.
 
+### Reading and saving content
+
+```js
+editor.getHTML();             // clean, sanitized HTML: save this
+editor.getJSON();             // or ProseMirror JSON
+editor.setContent("<p>…</p>"); // load new content
+```
+
+Still sanitize on the server. To display saved HTML on a page that has no editor, load `content.css` and wrap the HTML in `<div class="owe-content-root">` (see [Styling](#styling)).
+
 ---
 
+## The `<owe-editor>` element
+
+`<owe-editor>` is the full editor as an HTML tag. It is a form-associated custom element that renders in the light DOM, so `style.css` applies as usual (no Shadow DOM, CSP-safe). The CDN script defines it automatically. With a bundler, `import "open-wysiwyg-editor/element"` defines it.
+
+| Attribute | Description |
+| --- | --- |
+| `name` | Form field name. The form submits the editor's HTML under it |
+| `placeholder` | Placeholder text |
+| `readonly` | Makes the content read-only |
+| `disabled` | Disables the editor and leaves it out of the form |
+| `dir` | Base direction of the content (`ltr`, `rtl`, `auto`) |
+| `content-lang` | `lang` of the content (spellcheck and screen readers) |
+| `label` | Accessible name. Or point a `<label for>` at the element's `id` |
+| `value` | Initial content as HTML (read once, when the editor is created) |
+| `language` | UI language, e.g. `ar` (read once). Defaults to `<html lang>` |
+| `toolbar` | Toolbar items separated by spaces (`"bold italic \| link"`), or `none` (read once) |
+
+`placeholder`, `readonly`, `disabled`, `dir`, `content-lang` and `label` follow later changes. `value`, `language` and `toolbar` are only read when the editor starts.
+
+| Property | Description |
+| --- | --- |
+| `editor` | The live `Editor`, or `null` while the element isn't in the document |
+| `value` | The content as HTML. Setting it loads new content |
+| `options` | More `createEditor()` options (`extensions`, `ui`, `labels`, callbacks…). Set it **before** the element is added to the page. Attributes win over it |
+| `form` | The surrounding `<form>`, or `null` |
+
+| Event | When |
+| --- | --- |
+| `input` | On every change. `event.target.value` has the HTML |
+| `change` | When the editor loses focus after a change |
+
+**Initial content** comes from the `value` attribute, else from a `<template>` child, else from the element's own children. Use `value` or `<template>` when the content comes from users: neither can run anything before the editor sanitizes it. Content placed directly as children is parsed by the browser first.
+
+```js
+const el = document.querySelector("owe-editor");
+el.options = { language: "ar", ui: { stickyToolbar: false } };
+el.value = "<p>New content</p>";
+el.editor?.commands.toggleBold();
+```
+
+In Angular, bind the element with `ngDefaultControl [(ngModel)]` (or use the [Angular package](https://github.com/alhassan73/open-wysiwyg-editor/tree/main/packages/angular#readme)).
+
 ## Options
 
 ```ts
 createEditor({
-  element,                 // container or <textarea>; omit to create it detached and append editor.root yourself
+  element,                 // container, CSS selector or <textarea>; omit to create it detached and append editor.root yourself
   content,                 // HTML string (always sanitized) or ProseMirror JSON
   extensions: [StarterKit],
   editable: true,
@@ -189,7 +540,7 @@ Color commands accept hex, `rgb()`, `hsl()` or named colors. Anything else is re
 
 ---
 
-## Features
+## Feature guide
 
 ### Toolbar
 
@@ -355,6 +706,8 @@ Untranslated labels fall back to English, and plurals use `Intl.PluralRules`. Th
 | `open-wysiwyg-editor/style.css` (`.min.css`) | The editor, its UI and its content styles |
 | `open-wysiwyg-editor/content.css` (`.min.css`) | Only the content styles, for published pages: wrap saved HTML in `<div class="owe-content-root">` |
 
+Each framework package ships the same files under its own name, for example `@open-wysiwyg-editor/vue/style.css` and `@open-wysiwyg-editor/vue/content.css`, because package managers like pnpm don't expose the core package to your app.
+
 All rules are in `@layer owe`, so any of your own CSS outside a layer overrides them. To theme the editor, set the design tokens:
 
 ```css
@@ -392,10 +745,93 @@ createEditor({ element, extensions: [StarterKit, Timestamp] });
 
 `defineExtension` also accepts `nodes`, `marks`, `globalAttributes`, `inputRules`, `plugins` (raw ProseMirror plugins), `onCreate` and `onDestroy`. Call `.configure(options)` on any extension to change its options.
 
+## Writing your own integration
+
+The framework packages are thin wrappers around a few helpers that the core package exports, so you can wrap the editor for any other framework in the same way:
+
+| Helper | What it does |
+| --- | --- |
+| `RUNTIME_OPTIONS` | The options an existing editor can change through `setOptions()`: `editable`, `placeholder`, `ariaLabel`, `ariaLabelledBy`, `ariaDescribedBy`, `dir`, `contentLang` |
+| `pickRuntimeOptions(options)` | Returns only those options from an options object |
+| `sameRuntimeOptions(a, b)` | `true` when two such objects hold the same values, so you can skip a `setOptions()` call |
+| `forwardCallbacks(get)` | Returns `onCreate`, `onUpdate`, `onSelectionUpdate`, `onFocus`, `onBlur`, `onDestroy` and `onContentError` handlers that always call the latest options' versions, so changing a callback never recreates the editor |
+| `syncContent(editor, content)` | Loads bound content into the editor, and skips HTML the editor itself just produced, so typing never resets the cursor |
+
+```ts
+import {
+  createEditor, forwardCallbacks, pickRuntimeOptions, sameRuntimeOptions, syncContent,
+  type Editor, type EditorOptions,
+} from "open-wysiwyg-editor";
+
+function mount(element: HTMLElement, initial: Omit<EditorOptions, "element">) {
+  let options = initial;
+  let runtime = pickRuntimeOptions(options);
+  const editor: Editor = createEditor({ ...options, element, ...forwardCallbacks(() => options) });
+
+  return {
+    update(next: Omit<EditorOptions, "element">) {
+      options = next; // callbacks pick this up through forwardCallbacks
+      if (next.content !== undefined) syncContent(editor, next.content);
+      const nextRuntime = pickRuntimeOptions(next);
+      if (!sameRuntimeOptions(runtime, nextRuntime)) editor.setOptions((runtime = nextRuntime));
+    },
+    destroy: () => editor.destroy(),
+  };
+}
+```
+
+Remember the three rules from [Usage](#usage): load the stylesheet, start in the browser only, and destroy the editor when the element goes away. The [Svelte](https://github.com/alhassan73/open-wysiwyg-editor/blob/main/packages/svelte/src/index.ts) and [Solid](https://github.com/alhassan73/open-wysiwyg-editor/blob/main/packages/solid/src/index.ts) packages are small, complete examples.
+
+## Package contents
+
+| Package | Import | Format | Use it for |
+| --- | --- | --- | --- |
+| `open-wysiwyg-editor` | `open-wysiwyg-editor` | ESM + CJS + `.d.ts` | The engine, every extension and the accessible UI |
+| | `open-wysiwyg-editor/headless` | ESM + CJS + `.d.ts` | The engine and extensions without UI code |
+| | `open-wysiwyg-editor/element` | ESM + CJS + `.d.ts` | Defines the `<owe-editor>` element |
+| | `open-wysiwyg-editor/style.css` (`.min.css`) | CSS | Editor, UI and content styles |
+| | `open-wysiwyg-editor/content.css` (`.min.css`) | CSS | Content styles only, for pages that display saved HTML |
+| | `dist/open-wysiwyg-editor.global.js` | IIFE | `<script>` tag; exposes `window.OpenWysiwygEditor` and defines `<owe-editor>` |
+| `@open-wysiwyg-editor/react` | `@open-wysiwyg-editor/react` | ESM + CJS + `.d.ts` | `<RichTextEditor>` and `useEditor()` (React 18+) |
+| `@open-wysiwyg-editor/next` | `@open-wysiwyg-editor/next` | ESM + CJS + `.d.ts` | The React package with `"use client"` for the App Router |
+| `@open-wysiwyg-editor/preact` | `@open-wysiwyg-editor/preact` | ESM + CJS + `.d.ts` | `<RichTextEditor>` and `useEditor()` on `preact/hooks` |
+| `@open-wysiwyg-editor/vue` | `@open-wysiwyg-editor/vue` | ESM + CJS + `.d.ts` | `<RichTextEditor v-model>` (Vue 3.3+) |
+| `@open-wysiwyg-editor/nuxt` | `@open-wysiwyg-editor/nuxt` | Nuxt module | Auto-imported component and stylesheet |
+| `@open-wysiwyg-editor/angular` | `@open-wysiwyg-editor/angular` | Angular package (ng-packagr) | Standalone component with forms support (Angular 21+) |
+| `@open-wysiwyg-editor/svelte` | `@open-wysiwyg-editor/svelte` | ESM + CJS + `.d.ts` | `use:richText` action (Svelte 3, 4, 5) |
+| `@open-wysiwyg-editor/solid` | `@open-wysiwyg-editor/solid` | ESM + CJS + `.d.ts` | `use:richText` directive (Solid 1.6+) |
+| `@open-wysiwyg-editor/astro` | `@open-wysiwyg-editor/astro` | `.astro` component + `.d.ts` | `RichTextEditor.astro`, which renders `<owe-editor>` |
+
+Every framework package re-exports the whole core API and ships `style.css`, `style.min.css`, `content.css` and `content.min.css`.
+
 ## Browser support
 
-The editor targets current versions of Chrome, Edge, Firefox and Safari. Every change is tested end to end in Chromium, Firefox and WebKit, under a strict CSP with Trusted Types and with axe-core accessibility checks.
+The editor targets current versions of Chrome, Edge, Firefox and Safari, on desktop and mobile. Every change is tested end to end in Chromium, Firefox and WebKit, under a strict CSP with Trusted Types and with axe-core accessibility checks.
+
+## Development
+
+```bash
+npm install
+npm run build      # builds every package
+npm run check      # lint + build + typecheck + unit tests
+npm run e2e        # end-to-end + axe tests in Chromium, Firefox and WebKit (Playwright)
+npm run dev        # serve the demo site locally
+```
+
+Layout:
+
+```
+README.md CHANGELOG.md CONTRIBUTING.md SECURITY.md LICENSE
+examples/        the documentation website + live demo (deployed to GitHub Pages)
+test/e2e/        Playwright end-to-end + axe tests
+scripts/         serve-e2e, size-check, license-check, copy-styles, publish, render-banner
+packages/<name>/ core, react, next, preact, vue, nuxt, angular, svelte, solid, astro
+```
+
+Every push to `main` rebuilds `examples/` and deploys it as the [live demo](https://alhassan73.github.io/open-wysiwyg-editor/). This README is the npm page of the core package: it is copied to `packages/core/README.md` when that package is packed.
+
+See [CONTRIBUTING.md](https://github.com/alhassan73/open-wysiwyg-editor/blob/main/CONTRIBUTING.md), [SECURITY.md](https://github.com/alhassan73/open-wysiwyg-editor/blob/main/SECURITY.md) and the [changelog](https://github.com/alhassan73/open-wysiwyg-editor/blob/main/CHANGELOG.md).
 
 ## License
 
-[MIT](https://github.com/alhassan73/open-wysiwyg-editor/blob/main/LICENSE)
+[MIT](https://github.com/alhassan73/open-wysiwyg-editor/blob/main/LICENSE) © alhassan-ahmed