edytor 2.0.0 → 3.0.0

package/README.md

@@ -17,11 +17,11 @@
 
 Edytor aims to be for Svelte what Slate.js is for React: a heavily customizable editor with an API to build any kind of collaborative rich text editor.
 
-> **2.0.** Edytor `2.0.0` is on npm as `edytor`: its API follows semantic versioning, and every change is listed in the changelog. It has no production track record yet: read the [limitations](https://edytor.dev/docs/reference/limitations) before you build on it. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
+> **3.0.** Edytor `3.0.0` is on npm as `edytor`: its API follows semantic versioning, and every change is listed in the changelog. It has no production track record yet: read the [limitations](https://edytor.dev/docs/reference/limitations) before you build on it. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
 
 ## Features
 
-- **Notion-style editing out of the box.** `<Edytor />` alone is a rich text editor with block handles: headings, toggle headings, lists, to-dos, toggles, callouts, quotes, dividers, ten marks and Notion's hotkeys. Add the Notion theme, a block menu (block colours; drag one block, or every block the selection covers), a slash menu, a selection toolbar, markdown shortcuts (`createMarkdownShortcutsPlugin()`) code blocks and images (`createImagePlugin({ upload })`).
+- **Notion-style editing out of the box.** `<Edytor />` alone is a rich text editor: headings, toggle headings, lists, to-dos, toggles, callouts, quotes, dividers, ten marks and Notion's hotkeys. Add the Notion theme and the plugins you want: block handles and a block menu (block colours; drag one block, or every block the selection covers), a slash menu, a selection toolbar, markdown shortcuts (`createMarkdownShortcutsPlugin()`), code blocks and images (`createImagePlugin({ upload })`). The package draws no chrome: each handle and menu is your snippet, or the ready-made registry item.
 - **Pages and a table of contents, opt-in.** `createPagePlugin` links a block to another document (a page per room, opened and named by your app), and `createTocPlugin()` lists the headings live ([Page](https://edytor.dev/docs/plugins/page), [Table of contents](https://edytor.dev/docs/plugins/table-of-contents)).
 - **Columns, opt-in.** List `createColumnsPlugin()` for Notion's multi-column layouts: drag a block to the edge of another to put them side by side, or pick "2 columns" to "5 columns"; drag the gap to resize. Layouts converge across collaborators and the room ([Columns](https://edytor.dev/docs/plugins/columns)).
 - **Tables, opt-in.** List `createTablePlugin()` for Notion's simple table: cells of text, <kbd>Tab</kbd> between them, rows and columns added, moved and deleted from the table's edges and grips, resizable columns, header row and column, HTML tables pasted and copied. Concurrent row and column edits converge on every replica ([Table](https://edytor.dev/docs/plugins/table)).
@@ -35,11 +35,12 @@ Edytor aims to be for Svelte what Slate.js is for React: a heavily customizable
 - **Real-time collaboration.** One `EdytorDocument` shared by any number of views, or none (headless). Presence cursors, identity-preserving moves, splits and merges, and undo that only takes back your own edits.
 - **Offline first.** A local IndexedDB copy and cross-tab sync; offline edits survive reloads and reach the server on reconnect.
 - **A Cloudflare Durable Object room.** `edytor/cloudflare` stores in SQLite, acknowledges after the write, binds identity to the socket and hibernates.
+- **Import and export.** `edytor/export` turns a document into HTML or Markdown and back (`toHTML`, `toMarkdown`, `fromHTML`, `textToBlocks`), by each kind's own forms, in the browser, Node or a Worker; HTML import is sanitized ([Import and export](https://edytor.dev/docs/editor/import-export)).
 - **Headless and Worker-safe.** `edytor/crdt/edytor` runs in Node and Workers without Svelte.
 
 ## Install
 
-The pre-release is on npm under the `next` tag. Name the tag: a bare `edytor` is the old, incompatible `0.0.11`.
+Edytor `3.0.0` is on npm under `latest`:
 
 ```bash
 pnpm add edytor
@@ -65,7 +66,21 @@ pnpm add edytor
 
 `<Edytor>` renders on the server and hydrates, so it works in any route. It includes rich text; each other block kind, block moves from the keyboard (`createArrowMovePlugin()`), and file drops (a media plugin given an `upload`) is a plugin you add, here code blocks; nesting blocks (<kbd>Tab</kbd>, drops inside a block) is the `allowNesting` option, off by default. `onChange` hands you the document after every change ([quick start](https://edytor.dev/docs/getting-started/quick-start)).
 
-The package draws no menu, toolbar or block handle: each is a snippet you pass its plugin ([menus and handles](https://edytor.dev/docs/customization/menus)). The demo's Notion-style ones are in [`src/routes/chrome`](https://github.com/beynar/edytor/tree/master/src/routes/chrome), ready to copy into your app ([ready-made menus](https://edytor.dev/docs/customization/ready-made-menus)).
+The package draws no menu, toolbar or block handle: each is a snippet you pass its plugin ([menus and handles](https://edytor.dev/docs/customization/menus)). Notion-style ones, in shadcn-svelte, are a registry item you add to your app (`npx shadcn-svelte@latest add https://edytor.dev/r/edytor-chrome.json`), as plugins for your `<Edytor>` ([ready-made menus](https://edytor.dev/docs/customization/ready-made-menus)).
+
+The fastest way to a full editor is the starter, a [shadcn-svelte](https://www.shadcn-svelte.com) registry item: every plugin, the ready-made menus and handles, comments, and a page with a cover, an icon, a title and typed properties, in one component copied into your app (Tailwind v4 and `shadcn-svelte init` first; [starter editor](https://edytor.dev/docs/starter)):
+
+```sh
+npx shadcn-svelte@latest add https://edytor.dev/r/starter.json
+```
+
+```svelte
+<script>
+	import { StarterEditor } from '$lib/components/edytor/starter/index.js';
+</script>
+
+<StarterEditor />
+```
 
 To collaborate, name a room and a server running the [`edytor/cloudflare` room](https://edytor.dev/docs/server/quick-start):
 

package/dist/block/block.svelte.js

@@ -1,3 +1,4 @@
+import { cleanups } from '../utils.js';
 import { Text } from '../text/text.svelte.js';
 /** Mark an element inside a block's markup as non-editable chrome (`block.void`, a preview's too). */
 export const voidChrome = (node) => {
@@ -336,10 +337,7 @@ export class Block {
         this.edytor.selection.keep(this);
         // A block laid out again with no commit moves the chrome beside it (the overlay measures).
         const unobserve = this.edytor.overlay.observe(node);
-        const onDestroy = this.edytor.plugins.flatMap((plugin) => {
-            const action = plugin.onBlockAttached?.({ node, block: this });
-            return typeof action === 'function' ? [action] : [];
-        });
+        const onDestroy = cleanups(this.edytor.plugins, (plugin) => plugin.onBlockAttached?.({ node, block: this }));
         return {
             destroy: () => {
                 this.#viewState = read(node);

package/dist/clipboard/htmlFlow.d.ts

@@ -1,10 +1,20 @@
-import type { Edytor } from '../edytor.svelte.js';
 import type { Flow } from '../crdt/flow.js';
-import type { BlockDefinition } from '../plugins.js';
-import { type SerializableContent } from '../utils/json.js';
+import { type JSONBlock, type SerializableContent } from '../utils/json.js';
+import type { AtomForms, BlockForms, MarkForms } from './serializeClipboardFragment.js';
 /** What HTML import reads: the kind, mark and atom records, and the document's default child. */
-export type ImportKinds = Pick<Edytor, 'blocks' | 'marks'> & Partial<Pick<Edytor, 'inlineBlocks'>> & {
-    document: Pick<Edytor['document'], 'defaultChild'>;
+export type ImportKinds = {
+    readonly blocks: ReadonlyMap<string, BlockForms>;
+    readonly marks: ReadonlyMap<string, MarkForms>;
+    readonly inlineBlocks?: ReadonlyMap<string, AtomForms>;
+    readonly document: {
+        defaultChild: (parent: string | null) => string;
+    };
+};
+/** A `DOMParser` constructor: the browser's, or a server's (`linkedom`, `jsdom`, `happy-dom`). */
+export type HtmlParser = new () => {
+    parseFromString(html: string, type: 'text/html'): {
+        body: Node | null;
+    };
 };
 type Values = Record<string, SerializableContent>;
 /**
@@ -13,9 +23,10 @@ type Values = Record<string, SerializableContent>;
  * none: an export form written as one (a callout's `<div data-edytor-callout>`)
  * is found by its `parse` hook only.
  */
-export declare const tagOf: (type: string, kind: BlockDefinition, data: Values) => string | undefined;
+export declare const tagOf: (type: string, kind: BlockForms, data: Values) => string | undefined;
 /**
- * External HTML as a flow: the browser parses (inert: no script
+ * External HTML as lines (JSON blocks; a line without a `type` is its
+ * parent's default child): `parser` parses (inert: no script
  * runs, nothing loads), and the tag tables are the records inverted — a
  * catalogue kind's tag per preset (a content-less container takes its
  * default child's tag, one child per text line), a value-less mark's
@@ -27,5 +38,7 @@ export declare const tagOf: (type: string, kind: BlockDefinition, data: Values)
  * atom, never its text. Unknown
  * elements degrade to text runs; whitespace collapses as HTML renders it. `null` when the HTML carries nothing (`flow.shape`).
  */
+export declare const linesOfHtml: (kinds: ImportKinds, html: string | undefined, parser?: HtmlParser | undefined) => JSONBlock[] | null;
+/** External HTML as a flow (the paste's): {@link linesOfHtml}, with the browser's parser. */
 export declare const flowOfHtml: (kinds: ImportKinds, html: string | undefined) => Flow | null;
 export {};

package/dist/clipboard/htmlFlow.js

@@ -1,6 +1,8 @@
 import { colorsOfClasses } from '../block/colors.js';
 import { isTextPart } from '../block/contentRange.js';
 import { jsonBlockToSpec } from '../utils/json.js';
+/** Element and text nodes by their type, not their realm: a server parser's nodes are not this global's. */
+const isElement = (node) => node?.nodeType === 1;
 /** Never content: their text is code, metadata or form state. */
 const SKIP = /^(script|style|template|noscript|svg|math|iframe|object|embed|canvas|video|audio|img|input|button|select|textarea|head|title|meta|link|base)$/;
 /** HTML's block-level elements: they start a line (a kind's tag does too). */
@@ -21,7 +23,7 @@ const sizeOf = (img, side) => {
  * email's tracking pixel). It is text, its `alt`, never a block.
  */
 const isGlyph = (node) => {
-    if (!(node instanceof HTMLElement) || node.localName !== 'img')
+    if (!isElement(node) || node.localName !== 'img')
         return false;
     const alt = node.getAttribute('alt')?.trim() ?? '';
     if (alt && EMOJI_ALT.test(alt) && /[\p{Extended_Pictographic}\p{Regional_Indicator}]/u.test(alt))
@@ -61,7 +63,8 @@ export const tagOf = (type, kind, data) => {
     return undefined;
 };
 /**
- * External HTML as a flow: the browser parses (inert: no script
+ * External HTML as lines (JSON blocks; a line without a `type` is its
+ * parent's default child): `parser` parses (inert: no script
  * runs, nothing loads), and the tag tables are the records inverted — a
  * catalogue kind's tag per preset (a content-less container takes its
  * default child's tag, one child per text line), a value-less mark's
@@ -73,8 +76,8 @@ export const tagOf = (type, kind, data) => {
  * atom, never its text. Unknown
  * elements degrade to text runs; whitespace collapses as HTML renders it. `null` when the HTML carries nothing (`flow.shape`).
  */
-export const flowOfHtml = (kinds, html) => {
-    if (!html || html.length > 8 * 1024 * 1024 || typeof DOMParser === 'undefined')
+export const linesOfHtml = (kinds, html, parser = globalThis.DOMParser) => {
+    if (!html || html.length > 8 * 1024 * 1024 || !parser)
         return null;
     const { blocks, marks } = kinds;
     const atoms = kinds.inlineBlocks ?? new Map();
@@ -99,8 +102,9 @@ export const flowOfHtml = (kinds, html) => {
             return undefined;
         for (const [type, kind] of blocks) {
             const data = kind.parse?.(element);
+            // A kind of lines (a code block) takes its element's text, one child per line.
             if (data)
-                return { type, kind, data };
+                return { type, kind, data, lines: kind.lines ? kind.defaultChild : undefined };
         }
         return byTag.get(element.localName);
     };
@@ -124,11 +128,10 @@ export const flowOfHtml = (kinds, html) => {
         return found;
     };
     // A kind's hook may claim an element of another namespace (an equation's MathML `<math>`).
-    const isBlock = (node) => (node instanceof HTMLElement && BLOCK.test(node.localName)) ||
-        (node instanceof Element && kindOf(node) !== undefined);
+    const isBlock = (node) => isElement(node) && (BLOCK.test(node.localName) || kindOf(node) !== undefined);
     /** A void kind's element (an image): it shows no text, so a line it is met in ends there. */
     const isVoid = (node) => {
-        const claim = node instanceof Element ? kindOf(node) : undefined;
+        const claim = isElement(node) ? kindOf(node) : undefined;
         return claim?.kind.void === true;
     };
     const text = (line, value, marks, pre) => {
@@ -148,16 +151,16 @@ export const flowOfHtml = (kinds, html) => {
             line.content.push(Object.keys(marks).length ? { text: value, marks } : { text: value });
     };
     const inline = (node, at, marks, pre) => {
-        if (node.nodeType === Node.TEXT_NODE)
+        if (node.nodeType === 3)
             return text(at.line(), node.textContent ?? '', marks, pre);
         if (isGlyph(node))
             return text(at.line(), node.getAttribute('alt') ?? '', marks, pre);
         if (isVoid(node))
             return at.apart(node);
-        const atom = node instanceof Element ? atomOf(node) : undefined;
+        const atom = isElement(node) ? atomOf(node) : undefined;
         if (atom)
             return void at.line().content.push(atom);
-        if (!(node instanceof HTMLElement) || SKIP.test(node.localName))
+        if (!isElement(node) || SKIP.test(node.localName))
             return;
         if (node.localName === 'br')
             return text(at.line(), '\n', marks, true);
@@ -286,12 +289,17 @@ export const flowOfHtml = (kinds, html) => {
         // Split: a text line left empty around a void element is not kept.
         return parts.filter((part) => !texts.has(part) || end(part).content.length > 0 || part.children !== undefined);
     };
-    const body = new DOMParser().parseFromString(html, 'text/html').body;
+    const body = new parser().parseFromString(html, 'text/html').body;
+    if (!body)
+        return null;
     const lines = linesOf(body, undefined);
     const carries = (line) => line.content.length > 0 ||
         Boolean(line.children?.some(carries)) ||
         Boolean(line.type && blocks.get(line.type)?.void);
-    return lines.some(carries)
-        ? { lines: lines.map((line) => jsonBlockToSpec(line, true)) }
-        : null;
+    return lines.some(carries) ? lines : null;
+};
+/** External HTML as a flow (the paste's): {@link linesOfHtml}, with the browser's parser. */
+export const flowOfHtml = (kinds, html) => {
+    const lines = linesOfHtml(kinds, html);
+    return lines ? { lines: lines.map((line) => jsonBlockToSpec(line, true)) } : null;
 };

package/dist/clipboard/serializeClipboardFragment.d.ts

@@ -1,9 +1,42 @@
-import type { Edytor } from '../edytor.svelte.js';
-import type { EdytorClipboardFragment } from './types.js';
-/** The records the export reads: each kind, mark and atom declares its own forms. */
-export type ExportKinds = Pick<Edytor, 'blocks' | 'marks' | 'inlineBlocks'>;
+/**
+ * The document's export forms, one reading for the clipboard and for
+ * `toHTML` / `toMarkdown` (`edytor/export`): each kind, mark and atom
+ * declares its own forms (`html`, `plain`, `markdown`; a mark's `tag` and
+ * `attributes`), and this module only walks the blocks. Pure: no view, no
+ * DOM, no Svelte.
+ */
+import type { JSONBlock, SerializableContent } from '../utils/json.js';
+import type { BlockDefinition, InlineBlockDefinition, MarkDefinition } from '../plugins.js';
+import type { EdytorClipboardFragment, JSONContentPart } from './types.js';
+/** A kind's export and import forms: the fields of its record the export and HTML import read. */
+export type BlockForms = Pick<BlockDefinition, 'html' | 'plain' | 'markdown' | 'parse' | 'element' | 'contentElement' | 'void' | 'island' | 'lines' | 'rendersContent' | 'defaultChild' | 'itemKind'> & {
+    /** The data of each way to create the kind: HTML import finds a preset's tag. */
+    presets?: {
+        data?: Record<string, SerializableContent>;
+    }[];
+};
+/** A mark's export and import forms. */
+export type MarkForms = Pick<MarkDefinition, 'tag' | 'attributes' | 'parse' | 'markdown'>;
+/** An atom's export and import forms. */
+export type AtomForms = Pick<InlineBlockDefinition, 'html' | 'plain' | 'markdown' | 'parse'>;
+/** The records the export reads: each kind, mark and atom declares its own forms (a view is one). */
+export type ExportKinds = {
+    readonly blocks: ReadonlyMap<string, BlockForms>;
+    readonly marks: ReadonlyMap<string, MarkForms>;
+    readonly inlineBlocks: ReadonlyMap<string, AtomForms>;
+};
 export declare const encodeClipboardJson: (value: unknown) => string;
 /** `value` escaped for an HTML text or a double-quoted attribute: every kind's export reads it. */
 export declare const escapeHtml: (value: string) => string;
+/** The content as HTML, or as plain text: an atom by its kind's form (`html`, `plain`). */
+export declare const contentOf: (content: JSONContentPart[] | undefined, kinds: ExportKinds, html: boolean) => string;
+/**
+ * How sibling blocks' HTML joins (`edytor/export` wraps a run of list items
+ * in its list): the blocks, their HTML, and their parent's `html` form.
+ * Without one, one after another (the clipboard's).
+ */
+export type SiblingsHtml = (blocks: JSONBlock[], html: string[], parent?: BlockForms['html']) => string;
+/** Blocks as HTML: the clipboard's and `toHTML`'s one reading of the kinds' forms. */
+export declare const blocksToHtml: (blocks: JSONBlock[], kinds: ExportKinds, wrap: SiblingsHtml) => string;
 export declare const serializeClipboardFragmentToPlainText: (fragment: EdytorClipboardFragment, kinds: ExportKinds) => string;
 export declare const serializeClipboardFragmentToHtml: (fragment: EdytorClipboardFragment, kinds: ExportKinds) => string;

package/dist/clipboard/serializeClipboardFragment.js

@@ -19,7 +19,7 @@ const textHtml = (part, kinds) => {
     return html;
 };
 /** The content as HTML, or as plain text: an atom by its kind's form (`html`, `plain`). */
-const contentOf = (content = [], kinds, html) => content
+export const contentOf = (content = [], kinds, html) => content
     .map((part) => {
     if (isTextPart(part))
         return html ? textHtml(part, kinds) : part.text;
@@ -41,9 +41,9 @@ const withClasses = (html, classes) => classes
     })
     : html;
 /** A block and its subtree as HTML (its colours as Notion's classes), or as plain text. */
-const blockOf = (block, kinds, html) => {
+const blockOf = (block, kinds, html, wrap) => {
     const content = contentOf(block.content, kinds, html);
-    const kids = block.children?.map((child) => blockOf(child, kinds, html)) ?? [];
+    const kids = block.children?.map((child) => blockOf(child, kinds, html, wrap)) ?? [];
     const kind = kinds.blocks.get(block.type);
     if (!html) {
         const children = kids.filter(Boolean).join('\n');
@@ -51,8 +51,8 @@ const blockOf = (block, kinds, html) => {
             ? kind.plain(block, content, children)
             : [content, children].filter(Boolean).join('\n');
     }
-    const children = kids.join('');
     const form = kind?.html;
+    const children = wrap ? wrap(block.children ?? [], kids, form) : kids.join('');
     const out = !form
         ? `<p>${content}</p>${children}`
         : typeof form === 'string'
@@ -61,6 +61,8 @@ const blockOf = (block, kinds, html) => {
     // A block's colours as Notion's export names them (`block-color-red`).
     return withClasses(out, colorClasses(block.data));
 };
+/** Blocks as HTML: the clipboard's and `toHTML`'s one reading of the kinds' forms. */
+export const blocksToHtml = (blocks, kinds, wrap) => wrap(blocks, blocks.map((block) => blockOf(block, kinds, true, wrap)));
 export const serializeClipboardFragmentToPlainText = (fragment, kinds) => fragment.kind === 'blocks'
     ? fragment.blocks.map((block) => blockOf(block, kinds, false)).join('\n')
     : contentOf(fragment.content, kinds, false);

package/dist/clipboard/textBlocks.d.ts

@@ -21,5 +21,13 @@ export type TextToBlocksOptions = {
 };
 /** Whether `text` holds block markdown (one line of it is enough), as a paste reads it. */
 export declare const hasBlockMarkdown: (text: string) => boolean;
+/**
+ * One line's kind, data and text, or `null` for a paragraph line: the one
+ * reading of a markdown line's block marker (`edytor/export`'s full reader
+ * reads its lines with it too).
+ */
+export declare const lineKind: (line: string) => (Omit<JSONBlock, "content"> & {
+    text: string;
+}) | null;
 /** `text` as blocks (see the module comment). */
 export declare const textToBlocks: (text: string, { markdown, type }?: TextToBlocksOptions) => JSONBlock[];

package/dist/clipboard/textBlocks.js

@@ -25,8 +25,12 @@ const runs = (text) => {
 const BLOCK_LINE = /^\s*(?:#{1,6}\s|[-*+]\s|\d+[.)]\s|>|```|(?:-{3,}|\*{3,}|_{3,})\s*$)/;
 /** Whether `text` holds block markdown (one line of it is enough), as a paste reads it. */
 export const hasBlockMarkdown = (text) => text.split(/\r?\n/).some((line) => BLOCK_LINE.test(line));
-/** One line's kind, data and text, or `null` for a paragraph line. */
-const lineKind = (line) => {
+/**
+ * One line's kind, data and text, or `null` for a paragraph line: the one
+ * reading of a markdown line's block marker (`edytor/export`'s full reader
+ * reads its lines with it too).
+ */
+export const lineKind = (line) => {
     let m = /^(#{1,6})\s+(.*)$/.exec(line);
     if (m)
         return { type: 'heading', data: { level: `h${Math.min(3, m[1].length)}` }, text: m[2] };

package/dist/cloudflare/room/admission.js

@@ -11,7 +11,7 @@
  */
 import { Y } from '../../crdt/engine.js';
 import * as E from '../../crdt/protocol.js';
-import { ChunkLimitError, ChunkSequenceError, CLOSE } from '../../crdt/providers/room.js';
+import { ChunkError, CLOSE } from '../../crdt/providers/room.js';
 import { MAX_WAITING_DELETES, noTimers } from './shared.js';
 import { STORAGE_FAILURE, now, sync, tally } from './context.js';
 import { attributionWrites, BINDING_PREFIX, forgedAttributionDeletes, forgedDeletes, forgedWriters } from './forged.js';
@@ -168,7 +168,7 @@ export class Admission {
         }
         catch (error) {
             this.#chunkReaders.delete(ws);
-            if (error instanceof ChunkLimitError) {
+            if (error instanceof ChunkError && error.limit !== undefined) {
                 return this.#overQuota(ws, attachment.user, 'frame', {
                     bytes: error.total,
                     limit: error.limit
@@ -187,7 +187,7 @@ export class Admission {
                 room.presence.depart(ws);
                 return room.close(ws, CLOSE.fault, 'room busy');
             }
-            if (error instanceof ChunkSequenceError) {
+            if (error instanceof ChunkError) {
                 room.note({ reason: 'internal', detail: `chunks: ${error.message}` });
                 room.presence.depart(ws);
                 return room.close(ws, CLOSE.fault, 'chunk sequence lost');

package/dist/cloudflare/room/context.d.ts

@@ -536,7 +536,7 @@ export declare const crdt: {
                 off<NAME extends "refused" | "status" | "failed" | "schema-mismatch" | "message-error" | "protocol-mismatch" | "synced" | "connection-close" | "connection-error" | "saved" | "permission-denied" | "expired" | "unreachable">(name: NAME, f: E.WebsocketProviderEvents[NAME]): void;
             };
         };
-        watchComments: (server: string, roomName: string, listener: (message: E.CommentMessage) => void) => (() => void);
+        watchComments: (server: string | null, roomName: string, listener: (message: E.CommentMessage) => void) => (() => void);
         storeState: (idbPersistence: {
             db: IDBDatabase | null;
             name: string;

package/dist/cloudflare/routeDocumentSocket.d.ts

@@ -50,6 +50,23 @@ export type RouteDocumentOptions = {
      * your page from another site's. Omitted: every origin passes.
      */
     allowedOrigins?: readonly string[] | ((origin: string) => boolean);
+    /**
+     * Answer a page on another origin (the app on `app.example.com`, the
+     * room on `rooms.example.com`): `OPTIONS` preflights are answered `204`
+     * (`GET, POST`, the headers the page asked for), and every HTTP answer
+     * (comments, history, the probes) carries `Access-Control-Allow-Origin`.
+     * The origins are `allowedOrigins`: with a list or a predicate, the
+     * request's `Origin` is echoed (`Vary: Origin`) and `credentials: true`
+     * lets the page send its cookies (`fetch(…, { credentials: 'include' })`);
+     * without one, every origin gets `*` and no credentials. A preflight from
+     * an origin `allowedOrigins` refuses is answered `403`. `maxAge`: how long
+     * a browser keeps a preflight, in seconds (default 600). A WebSocket dial
+     * needs none of it. Omitted: no CORS headers, and `OPTIONS` answers `405`.
+     */
+    cors?: boolean | {
+        credentials?: boolean;
+        maxAge?: number;
+    };
 };
 /** The replica a client asked for in `?replica=<doc.clientID>` (or `param`), or `null`. */
 export declare const requestedReplica: (request: Request, param?: string) => number | null;

package/dist/cloudflare/routeDocumentSocket.js

@@ -28,6 +28,50 @@ import { CLOSE, validRoomId } from '../crdt/providers/room.js';
 import { COMMENTS_HEADER, HISTORY_HEADER, HISTORY_KEY_HEADER, IDENTITY_HEADERS, PROBE_HEADER, closedSocket } from './room/shared.js';
 import { parseReplica } from './room/access.js';
 import { MAX_COMMENT_REQUEST_BYTES } from './room/comments.js';
+/** The CORS headers `options.cors` gives an answer to `request` (none: `null`). */
+const corsHeaders = (request, options) => {
+    const cors = options?.cors;
+    const origin = request.headers.get('Origin');
+    if (!cors || origin === null || !originAllowed(request, options))
+        return null;
+    const headers = new Headers();
+    if (options?.allowedOrigins === undefined) {
+        headers.set('Access-Control-Allow-Origin', '*');
+        return headers;
+    }
+    headers.set('Access-Control-Allow-Origin', origin);
+    headers.set('Vary', 'Origin');
+    if (typeof cors === 'object' && cors.credentials === true)
+        headers.set('Access-Control-Allow-Credentials', 'true');
+    return headers;
+};
+/**
+ * One HTTP route with `options.cors`: a preflight answered here, every other
+ * answer given its CORS headers (a `101` upgrade passes as it is).
+ */
+const withCors = async (request, options, route) => {
+    const cors = options?.cors;
+    if (cors && request.method === 'OPTIONS' && request.headers.has('Origin')) {
+        const headers = corsHeaders(request, options);
+        if (headers === null)
+            return new Response('origin not allowed', { status: 403 });
+        headers.set('Access-Control-Allow-Methods', 'GET, POST');
+        headers.set('Access-Control-Allow-Headers', request.headers.get('Access-Control-Request-Headers') ?? 'Content-Type');
+        headers.set('Access-Control-Max-Age', String((typeof cors === 'object' ? cors.maxAge : undefined) ?? 600));
+        return new Response(null, { status: 204, headers });
+    }
+    const response = await route();
+    const headers = corsHeaders(request, options);
+    if (headers === null || response.status === 101)
+        return response;
+    const merged = new Headers(response.headers);
+    headers.forEach((value, name) => merged.set(name, value));
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: merged
+    });
+};
 /** Is `request`'s `Origin` one `options` allows (no `Origin`, or no list: yes)? */
 const originAllowed = (request, options) => {
     const allowed = options?.allowedOrigins;
@@ -109,6 +153,9 @@ const identityHeaders = (identity) => {
  * `404` (the room keeps no history), `405` (another method).
  */
 export async function routeDocumentHistory(request, rooms, documentId, authorize, options) {
+    return withCors(request, options, () => routeHistory(request, rooms, documentId, authorize, options));
+}
+async function routeHistory(request, rooms, documentId, authorize, options) {
     const query = new URL(request.url).searchParams;
     const op = request.method === 'GET'
         ? query.has('key')
@@ -191,6 +238,9 @@ const bodyWithin = async (request, max) => {
  * comment bytes full), `429` (the user past the room's comment rate).
  */
 export async function routeDocumentComments(request, rooms, documentId, authorize, options) {
+    return withCors(request, options, () => routeComments(request, rooms, documentId, authorize, options));
+}
+async function routeComments(request, rooms, documentId, authorize, options) {
     const op = request.method === 'GET' ? 'list' : request.method === 'POST' ? 'post' : null;
     if (op === null)
         return new Response('method not allowed', { status: 405 });
@@ -215,6 +265,9 @@ export async function routeDocumentComments(request, rooms, documentId, authoriz
         .fetch(new Request(request.url, { method: op === 'post' ? 'POST' : 'GET', headers, body }));
 }
 export async function routeDocumentSocket(request, rooms, documentId, authorize, options) {
+    return withCors(request, options, () => routeSocket(request, rooms, documentId, authorize, options));
+}
+async function routeSocket(request, rooms, documentId, authorize, options) {
     // The probes: a plain GET, authorized like a dial, answered with JSON or
     // an HTTP status — `lastUpdated` and `snapshot` (the document).
     const query = new URL(request.url).searchParams;

package/dist/collaboration/comments/client.d.ts

@@ -48,7 +48,7 @@ export type CommentsClientOptions = {
     /**
      * The websocket sync's server URL (the `server` of `<Edytor>` or
      * `createWebsocketSync`), whose socket hears the room's changes. Default:
-     * `server` read as `ws:`/`wss:`.
+     * every websocket sync of the same room on the page, whatever its URL.
      */
     socket?: string;
     /** Query parameters sent with each request (a token): an object, or a function read at every request. */

package/dist/collaboration/comments/client.js

@@ -34,7 +34,7 @@ export const createCommentsClient = (options) => {
     assertRoomId(options.room);
     const server = options.server.replace(/\/+$/, '');
     const base = `${server.replace(/^ws/, 'http')}/${encodeURIComponent(options.room)}`;
-    const socket = (options.socket ?? server.replace(/^http/, 'ws')).replace(/\/+$/, '');
+    const socket = options.socket?.replace(/\/+$/, '') ?? null;
     const request = async (method, body) => {
         const url = new URL(base);
         const params = typeof options.params === 'function' ? options.params() : options.params;

package/dist/collaboration/remoteSelection.js

@@ -42,8 +42,8 @@ const getCaretRect = (point, origin, editor) => {
     const range = (point.node.ownerDocument ?? editor.ownerDocument).createRange();
     range.setStart(point.node, point.offset);
     range.collapse(true);
-    const rect = typeof range.getBoundingClientRect === 'function' ? range.getBoundingClientRect() : null;
-    if (rect && (rect.width || rect.height)) {
+    const rect = range.getBoundingClientRect();
+    if (rect.width || rect.height) {
         return toRemoteRect(rect, origin);
     }
     return getFallbackRect(point, origin, editor);
@@ -71,7 +71,7 @@ const getSelectionRects = (start, end, origin, editor) => {
         (end.text.node && renderSkipped(end.text.node))) {
         return [getFallbackRect(start, origin, editor)];
     }
-    const clientRects = typeof range.getClientRects === 'function' ? Array.from(range.getClientRects()) : [];
+    const clientRects = Array.from(range.getClientRects());
     const seen = new Set();
     const rects = clientRects
         .filter((rect) => rect.width || rect.height)

package/dist/components/Edytor.svelte

@@ -5,11 +5,9 @@
 	import { Edytor as EdytorClass, useEdytor } from '../edytor.svelte.js';
 	import {
 		SyncRefusedError,
-		type Awareness,
 		type DocChange,
 		type DocumentActor,
-		type EdytorDocument,
-		type YDoc
+		type EdytorDocument
 	} from '../crdt/index.js';
 	import { CLOSE, validRoomId } from '../crdt/providers/room.js';
 	import type { EdytorSync, WebsocketSyncOptions } from '../collaboration/index.js';
@@ -75,8 +73,6 @@
 		edytor?: EdytorClass;
 		/** The assembled document this view renders (see `crdt/document.ts`). */
 		document?: EdytorDocument;
-		doc?: YDoc;
-		awareness?: Awareness;
 		/** The local author (id, name, color) of the document this view owns: attribution and presence. */
 		actor?: DocumentActor;
 		/**
@@ -187,7 +183,6 @@
 		edytor = $bindable(),
 		// Aliased so the DOM `document` global keeps working in this scope.
 		document: edytorDocument,
-		doc,
 		readonly = false,
 		allowNesting = false,
 		value = defaultValue,
@@ -200,7 +195,6 @@
 		onSyncRefused,
 		requireHydration,
 		snapshot,
-		awareness,
 		actor,
 		presence,
 		onChange,
@@ -221,8 +215,6 @@
 		allowNesting,
 		plugins: defaultPlugins ? withDefaults(userPlugins) : userPlugins,
 		document: edytorDocument,
-		doc,
-		awareness,
 		actor,
 		requireHydration,
 		hotkeys,
@@ -294,7 +286,7 @@
 		}
 	});
 
-	// The component owns the Edytor — release its doc/awareness/facade/
+	// The component owns the Edytor — release its facade/
 	// undo-manager listeners so a shared doc doesn't retain dead mounts.
 	// `onDestroy` also runs after a server render: a view-owned document
 	// (and its awareness timer) must not outlive the request.

package/dist/components/Edytor.svelte.d.ts

@@ -1,5 +1,5 @@
 import { Edytor as EdytorClass, useEdytor } from '../edytor.svelte.js';
-import { SyncRefusedError, type Awareness, type DocChange, type DocumentActor, type EdytorDocument, type YDoc } from '../crdt/index.js';
+import { SyncRefusedError, type DocChange, type DocumentActor, type EdytorDocument } from '../crdt/index.js';
 import type { EdytorSync, WebsocketSyncOptions } from '../collaboration/index.js';
 import { type PresenceOptions } from '../collaboration/awarenessSelection.js';
 export { EdytorClass as EdytorContext, useEdytor };
@@ -21,8 +21,6 @@ export type EdytorProps = {
     edytor?: EdytorClass;
     /** The assembled document this view renders (see `crdt/document.ts`). */
     document?: EdytorDocument;
-    doc?: YDoc;
-    awareness?: Awareness;
     /** The local author (id, name, color) of the document this view owns: attribution and presence. */
     actor?: DocumentActor;
     /**