edytor 0.1.0-next.32 → 0.1.0-next.36

package/README.md

@@ -3,6 +3,7 @@
 
 <p>A collaborative block editor for Svelte 5, on a Yjs v14 engine</p>
 
+[![CI](https://github.com/beynar/edytor/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/beynar/edytor/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Svelte v5](https://img.shields.io/badge/Svelte-v5-FF3E00.svg)](https://svelte.dev)
 
@@ -15,13 +16,16 @@
 
 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.
 
-> **Work in progress.** Edytor is a pre-release (`0.1.0-next.32`, `edytor@next` on npm) and not ready for production; the API changes between releases without a compatibility layer. The untagged `edytor@0.0.11` on npm predates the current API. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
+> **Work in progress.** Edytor is a pre-release (`0.1.0-next.36`, `edytor@next` on npm) and not ready for production; the API changes between releases without a compatibility layer. The untagged `edytor@0.0.11` on npm predates the current API. 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 images and block handles: headings, lists, to-dos, toggles, callouts, quotes, dividers, ten marks and Notion's hotkeys. Add the Notion theme, a block menu (drag one block, or every block the selection covers), a slash menu, a selection toolbar, markdown shortcuts (`markdownShortcutsPlugin`) and code blocks.
+- **Notion-style editing out of the box.** `<Edytor />` alone is a rich text editor with images and 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 (`markdownShortcutsPlugin`) and code blocks.
+- **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 `tocPlugin` 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 `columnsPlugin` 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)).
+- **Mentions, page links and your own triggers.** `createMentionPlugin` (`@` people) and `createPageLinkPlugin` (`[[` pages) take your app's search; a plugin's `inputRules` (`:smile:` → 😄) and `triggers` (a menu on a typed character) declare the rest ([Input rules and triggers](https://edytor.dev/docs/plugins/input-rules)).
 - **Your markup.** Blocks, marks and inline atoms render through your Svelte snippets; the slash menu, toolbar, block menu and handles take a snippet and keep their behavior.
+- **Your language.** Every word the chrome shows or says, slash keywords included, comes from a labels dictionary each plugin takes; English by default ([Localization](https://edytor.dev/docs/customization/localization)).
 - **Synced properties.** `block.data`, `atom.data` and `edytor.data` read and write like plain objects (`bind:value={block.data.title}`); each property and each array item syncs on its own, so concurrent edits of different properties, or of different items of one array, merge.
 - **AI suggestions.** `edytor.suggestions.add(position, content)` proposes text, paragraphs, lists, to-dos or images after, before or inside a block, at the end of its text, or in place of the selection; it streams in, shows only on your screen, and becomes one undo step when accepted ([Suggestions](https://edytor.dev/docs/editor/suggestions)).
 - **Plugins that can veto anything.** Every command is prepared before it writes; plugins see the command and each planned step and can refuse or replace it.
@@ -38,7 +42,7 @@ The pre-release is on npm under the `next` tag. Name the tag: a bare `edytor` is
 pnpm add edytor@next
 ```
 
-`svelte@^5` is a peer dependency. Do not install `yjs`: the v14 engine is vendored (`edytor/crdt`). See [installation](https://edytor.dev/docs/getting-started).
+`svelte@^5` is a peer dependency. Do not install `yjs`: the v14 engine is vendored (`edytor/crdt`). See [installation](https://edytor.dev/docs/getting-started) and [platform support](https://edytor.dev/docs/reference/platform-support) (Chrome, Edge, Firefox and Safari; real phones are not tested yet).
 
 ## Quick start
 
@@ -78,7 +82,7 @@ pnpm add edytor@next
 </div>
 ```
 
-`<Edytor>` adds the rich text, image, arrow-move and suggestions plugins after yours, and block handles. To collaborate, name a room and a server running the [`edytor/cloudflare` room](https://edytor.dev/docs/server/quick-start):
+An editable editor is client-only: in SvelteKit, mount it once the page has hydrated ([quick start](https://edytor.dev/docs/getting-started/quick-start#mount-it-in-a-page)). `<Edytor>` adds the rich text, image, arrow-move and suggestions plugins after yours, and block handles. To collaborate, name a room and a server running the [`edytor/cloudflare` room](https://edytor.dev/docs/server/quick-start):
 
 ```svelte
 <Edytor
@@ -98,11 +102,11 @@ The [documentation site](https://edytor.dev/docs) is the single source for the A
 - [Editor](https://edytor.dev/docs/editor/edytor-component): the component, commands, selection, history, clipboard, readonly
 - [Plugins](https://edytor.dev/docs/plugins) and [customization](https://edytor.dev/docs/customization/blocks): bundled plugins, custom blocks and marks, [hotkeys and editing behavior](https://edytor.dev/docs/customization/hotkeys)
 - [Collaboration](https://edytor.dev/docs/collaboration) and [server](https://edytor.dev/docs/server/quick-start): documents, providers, presence, the Durable Object room and its protocol
-- [Reference](https://edytor.dev/docs/reference/document-api): the document API, [troubleshooting](https://edytor.dev/docs/reference/troubleshooting), [migration from 0.0.11](https://edytor.dev/docs/reference/migration), limitations
+- [Reference](https://edytor.dev/docs/reference/document-api): the document API, [troubleshooting](https://edytor.dev/docs/reference/troubleshooting), [migration from 0.0.11](https://edytor.dev/docs/reference/migration), limitations, [platform support](https://edytor.dev/docs/reference/platform-support)
 
 ## Contributing
 
-`AGENTS.md` describes the architecture (one owner per fact), where to fix what, and the test lanes. The docs live in `site/content/docs`; a change to public behavior updates them in the same commit.
+`CONTRIBUTING.md` lists the test lanes, what CI runs, and the pull request checklist; `AGENTS.md` describes the architecture (one owner per fact) and where to fix what. The docs live in `site/content/docs`; a change to public behavior updates them in the same commit.
 
 ```bash
 pnpm install

package/dist/block/block.svelte.d.ts

@@ -45,18 +45,16 @@ export declare class Block {
     setData: (data: Record<string, unknown>) => void;
     get selected(): boolean;
     get focused(): boolean;
-    /** May this block move at all — R5 `canPlace` without a destination (drag handles). */
+    /** May this block move at all: `canPlace` without a destination (drag handles). */
     get movable(): boolean;
     /**
      * May text-level structural commands (convert, markdown shortcut, slash
      * menu) apply: the block is movable — or the virtual paragraph of an
      * emptied document, which a conversion creates with its kind
-     * (SW10-lists-3) — has no role of its own and renders its own content —
-     * a container (a list) is never converted, its items are (ZW-02).
+     * — has no role of its own and renders its own content —
+     * a container (a list) is never converted, its items are.
      */
     get convertible(): boolean;
-    get firstEditableText(): Text | undefined;
-    get lastEditableText(): Text | undefined;
     get index(): number;
     get depth(): number;
     get path(): number[];
@@ -79,14 +77,14 @@ export declare class Block {
     /** It holds nothing: no content and no children (the emptiness Turn into reads, `holdsNothing`). */
     get isEmpty(): boolean;
     get isNested(): boolean;
-    /** This block's JSON — the document's one serializer (`facade.blockJSON`, L14). */
+    /** This block's JSON — the document's one serializer (`facade.blockJSON`). */
     get value(): JSONBlock;
     isChildOf(block: Block): boolean;
-    /** Whether this kind renders its own content slot — the adopted capability (R5, O22). */
+    /** Whether this kind renders its own content slot — the adopted capability. */
     get rendersContent(): boolean;
     /**
      * A container: it shows only its children (a list), neither void nor an
-     * island — the document's container rule (YW-02). Its items hold what it
+     * island — the document's container rule. Its items hold what it
      * shows; it is never converted (`convertible`).
      */
     get isContainer(): boolean;
@@ -100,7 +98,7 @@ export declare class Block {
     /**
      * The list this block shows in: its container when it is an item
      * (`isListItem`), or — an item outdented out of a nested list into the
-     * item holding it (SW8-roles-4) — the list of the items of its kind it
+     * item holding it — the list of the items of its kind it
      * sits under. <kbd>Enter</kbd> in an empty one outdents it; the menus
      * name it by the list's `itemKind`.
      */
@@ -114,58 +112,64 @@ export declare class Block {
     get firstText(): Text | undefined;
     /** The last text of this block's own content (see {@link firstText}). */
     get lastText(): Text | undefined;
-    addChildBlock: (args_0: {
+    addChildBlock: (payload: {
         block: JSONBlock;
         index: number;
     }) => Block;
-    addChildBlocks: (args_0: {
+    addChildBlocks: (payload: {
         blocks: JSONBlock[];
         index: number;
     }) => Block[];
     insertBlockAfter: (payload: {
         block: JSONBlock;
-    }, plan?: import("../crdt/index.js").Prepared | undefined) => Block | null | undefined;
+    }) => Block | null | undefined;
     insertBlockBefore: (payload: {
         block: JSONBlock;
-    }, plan?: import("../crdt/index.js").Prepared | undefined) => Block | null | undefined;
+    }) => Block | null | undefined;
     splitBlock: (payload: {
         index: number;
         text: Text;
-    }, plan?: import("../crdt/index.js").Prepared | undefined) => Block | null | undefined;
-    duplicateBlock: (_?: {} | undefined, plan?: import("../crdt/index.js").Prepared | undefined) => Block | null | undefined;
+    }) => Block | null | undefined;
+    duplicateBlock: (payload?: {} | undefined) => Block | null | undefined;
     removeBlock: (payload?: {
         keepChildren?: boolean;
-    } | undefined, plan?: import("../crdt/index.js").Prepared | undefined) => void;
-    unNestBlock: (this: Block, _?: {} | undefined, plan?: import("../crdt/index.js").Prepared | undefined) => Block | null;
-    mergeBlockBackward: (_?: {} | undefined, plan?: import("../crdt/index.js").Prepared | undefined) => Block | null | undefined;
-    mergeBlockForward: (_?: {} | undefined, plan?: import("../crdt/index.js").Prepared | undefined) => Block | null | undefined;
-    nestBlock: (this: Block, _?: {} | undefined, plan?: import("../crdt/index.js").Prepared | undefined) => Block | null;
+    } | undefined) => void;
+    unNestBlock: (this: Block, payload?: {} | undefined) => Block | null;
+    mergeBlockBackward: (payload?: {} | undefined) => Block | null | undefined;
+    mergeBlockForward: (payload?: {} | undefined) => Block | null | undefined;
+    nestBlock: (this: Block, payload?: {} | undefined) => Block | null;
     setBlock: (payload: {
         value: Partial<JSONBlock>;
-    }, plan?: import("../crdt/index.js").Prepared | undefined) => void;
+    }) => void;
     moveBlock: (this: Block, payload: {
         path: number[];
         beside?: import("./block.utils.js").BlockBeside;
-    }, plan?: import("../crdt/index.js").Prepared | undefined) => Block | null;
+    }) => Block | null;
     moveBlocks: (this: Block, payload: {
         blocks: Block[];
         path: number[];
         beside?: import("./block.utils.js").BlockBeside;
-    }, plan?: import("../crdt/index.js").Prepared | undefined) => Block[];
-    pushContentIntoBlock: (args_0: {
+    }) => Block[];
+    pushContentIntoBlock: (payload: {
         value: (Text | InlineBlock)[];
     }) => void;
     removeInlineBlock: (payload: {
         index: number;
-    }, plan?: import("../crdt/index.js").Prepared | undefined) => void;
+    }) => void;
     patchData: (payload: {
         ops: import("../crdt/index.js").DataPatch[];
         atom?: string;
-    }, plan?: import("../crdt/index.js").Prepared | undefined) => void;
-    addInlineBlock: (args_0: {
-        index: number;
+    }) => void;
+    /**
+     * Insert an inline atom: at `offset` of the block's content (block
+     * offsets, an inline atom counting 1; a caret's), or at `index` of the
+     * text segment `text`. One `addInlineBlock` operation (its payload names
+     * the segment). Answers the text segment right after the atom, where a
+     * caret goes (`null` when it was not written, `undefined` when refused).
+     */
+    addInlineBlock: (payload: BlockOperations["addInlineBlock"] | {
+        offset: number;
         block: JSONInlineBlock;
-        text: Text;
     }) => Text | null | undefined;
     normalizeContent: () => void;
     normalizeChildren: () => void;
@@ -176,7 +180,7 @@ export declare class Block {
     deleteContentAtRange: (payload: {
         start: [number, number];
         end: [number, number];
-    }, plan?: import("../crdt/index.js").Prepared | undefined) => void;
+    }) => void;
     /** Mark an element inside the block's markup as non-editable chrome (a header, a caption bar). */
     void: (node: HTMLElement) => void;
     /**
@@ -201,12 +205,4 @@ export declare class Block {
      * each entry is a text's runs or an atom, as JSON.
      */
     insertParts: (index: number, parts: (JSONText[] | JSONInlineBlock)[]) => void;
-    /**
-     * Register the element the core rendered for this block (O45) and run the
-     * attach hooks. A re-rendered block (moved, re-parented) keeps its declared
-     * view state (R11): an open toggle stays open.
-     */
-    attach: (node: HTMLElement) => {
-        destroy: () => void;
-    };
 }

package/dist/block/block.svelte.js

@@ -94,7 +94,7 @@ export class Block {
     get focused() {
         return this.edytor.selection.focusedBlocks.has(this) && !this.selected;
     }
-    /** May this block move at all — R5 `canPlace` without a destination (drag handles). */
+    /** May this block move at all: `canPlace` without a destination (drag handles). */
     get movable() {
         return this.edytor.facade.canPlace([this.id]);
     }
@@ -102,14 +102,15 @@ export class Block {
      * May text-level structural commands (convert, markdown shortcut, slash
      * menu) apply: the block is movable — or the virtual paragraph of an
      * emptied document, which a conversion creates with its kind
-     * (SW10-lists-3) — has no role of its own and renders its own content —
-     * a container (a list) is never converted, its items are (ZW-02).
+     * — has no role of its own and renders its own content —
+     * a container (a list) is never converted, its items are.
      */
     get convertible() {
         const { facade } = this.edytor;
         const placeable = this.movable || facade.virtual() === this.id;
         return placeable && this.rendersContent && !facade.isVoid(this.id) && !facade.isIsland(this.id);
     }
+    /** @internal */
     get firstEditableText() {
         // Only a RENDERED text part is editable — a container's phantom
         // content slot holds a Text with no `node`. Scan ALL children: the
@@ -125,6 +126,7 @@ export class Block {
         }
         return undefined;
     }
+    /** @internal */
     get lastEditableText() {
         const own = this.content.findLast((part) => part instanceof Text && part.node != null);
         if (own)
@@ -207,7 +209,7 @@ export class Block {
     get isNested() {
         return (this.parent && this.parent.type !== 'root') || false;
     }
-    /** This block's JSON — the document's one serializer (`facade.blockJSON`, L14). */
+    /** This block's JSON — the document's one serializer (`facade.blockJSON`). */
     get value() {
         if (!this.isRoot)
             return this.edytor.facade.blockJSON(this.id);
@@ -220,13 +222,13 @@ export class Block {
                 return true;
         return false;
     }
-    /** Whether this kind renders its own content slot — the adopted capability (R5, O22). */
+    /** Whether this kind renders its own content slot — the adopted capability. */
     get rendersContent() {
         return this.edytor.document.rendersContent(this.type);
     }
     /**
      * A container: it shows only its children (a list), neither void nor an
-     * island — the document's container rule (YW-02). Its items hold what it
+     * island — the document's container rule. Its items hold what it
      * shows; it is never converted (`convertible`).
      */
     get isContainer() {
@@ -249,7 +251,7 @@ export class Block {
     /**
      * The list this block shows in: its container when it is an item
      * (`isListItem`), or — an item outdented out of a nested list into the
-     * item holding it (SW8-roles-4) — the list of the items of its kind it
+     * item holding it — the list of the items of its kind it
      * sits under. <kbd>Enter</kbd> in an empty one outdents it; the menus
      * name it by the list's `itemKind`.
      */
@@ -292,7 +294,20 @@ export class Block {
     pushContentIntoBlock = batch('pushContentIntoBlock', pushContentIntoBlock);
     removeInlineBlock = batch('removeInlineBlock', removeInlineBlock, prepareRemoveInline);
     patchData = batch('patchData', patchData, preparePatch);
-    addInlineBlock = batch('addInlineBlock', addInlineBlock, undefined, textAfterAtom);
+    #addInline = batch('addInlineBlock', addInlineBlock, undefined, textAfterAtom);
+    /**
+     * Insert an inline atom: at `offset` of the block's content (block
+     * offsets, an inline atom counting 1; a caret's), or at `index` of the
+     * text segment `text`. One `addInlineBlock` operation (its payload names
+     * the segment). Answers the text segment right after the atom, where a
+     * caret goes (`null` when it was not written, `undefined` when refused).
+     */
+    addInlineBlock = (payload) => {
+        if (!('offset' in payload))
+            return this.#addInline(payload);
+        const at = this.textAtOffset(Math.max(0, payload.offset));
+        return at ? this.#addInline({ index: at.offset, text: at.text, block: payload.block }) : null;
+    };
     normalizeContent = batch('normalizeContent', normalizeContent);
     normalizeChildren = batch('normalizeChildren', normalizeChildren);
     /** @deprecated `edytor.suggestions.add({ end: block.id }, …)`. */
@@ -373,6 +388,7 @@ export class Block {
      * Register the element the core rendered for this block (O45) and run the
      * attach hooks. A re-rendered block (moved, re-parented) keeps its declared
      * view state (R11): an open toggle stays open.
+     * @internal
      */
     attach = (node) => {
         const names = this.definition.viewState ?? [];

package/dist/block/block.utils.d.ts

@@ -122,6 +122,19 @@ export type BlockOperations = {
             content: readonly JSONBlock[];
         };
     };
+    /**
+     * Find and replace (`plugins/find`): each match's text replaced by
+     * `replacement`, one plan, one undo step (its steps: a
+     * `deleteContentAtRange` and an `insertText` per match).
+     */
+    replaceMatches: {
+        matches: {
+            block: string;
+            offset: number;
+            length: number;
+        }[];
+        replacement: string;
+    };
     deleteContentAtRange: {
         start: [number, number];
         end: [number, number];
@@ -153,7 +166,12 @@ export type BlockOperations = {
  * and answers the op's document result; `resolve` turns it into wrappers
  * after the commit patched them.
  */
-export declare function batch<T extends (...args: any[]) => any, O extends keyof BlockOperations, R = ReturnType<T>>(operation: O, func: T, prepare?: (payload: BlockOperations[O]) => Prepared, resolve?: (this: any, out: ReturnType<T> | undefined, payload: Parameters<T>[0]) => R): (...args: Parameters<T>) => R;
+export declare function batch<T extends (...args: any[]) => any, O extends keyof BlockOperations, R = ReturnType<T>>(operation: O, func: T, prepare?: (payload: BlockOperations[O]) => Prepared, resolve?: (this: any, out: ReturnType<T> | undefined, payload: Parameters<T>[0]) => R): (...args: PayloadOf<Parameters<T>>) => R;
+/**
+ * A mutator's public parameters: its payload alone (optional when the op's
+ * is). The plan the dispatcher passes the op is not the caller's.
+ */
+export type PayloadOf<A extends unknown[]> = A extends [] ? [] : A extends [infer P, ...unknown[]] ? [payload: P] : A extends [(infer P)?, ...unknown[]] ? [payload?: P] : [];
 /**
  * The handle of block `id` (null: refused at preparation, or gone; undefined:
  * the command did not run). Inside an outer transaction too: the index shows

package/dist/block/block.utils.js

@@ -12,7 +12,8 @@ import { InlineBlock } from './inlineBlock.svelte.js';
 export function batch(operation, func, prepare, resolve) {
     return function (...[payload]) {
         const out = this.edytor.dispatcher.dispatch(operation, payload, { block: this }, (p, plan) => func.call(this, p, plan), prepare && ((p) => prepare.call(this, p)));
-        return resolve ? resolve.call(this, out, payload) : out;
+        const value = resolve ? resolve.call(this, out, payload) : out;
+        return this.edytor.dispatcher.answer(value);
     };
 }
 /**

package/dist/block/colors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Block colours (Notion's "Color" in the block menu): a block's text colour
+ * and background, by palette name, in two data leaves, `data.color` and
+ * `data.background`. Each is one property of the block, so two people
+ * colouring it at once keep one value each (per-leaf last writer), and
+ * Turn into keeps them (a retype sets only the leaves it names).
+ *
+ * The core renders a valid name as `data-edytor-color` and
+ * `data-edytor-background` on the block element (`Block.svelte`, owned by
+ * the attribute table), and its stylesheet paints the bundled names from
+ * theme tokens (`--edytor-color-<name>`, `--edytor-background-<name>`).
+ */
+import type { Block } from './block.svelte.js';
+import type { Edytor } from '../edytor.svelte.js';
+/** Notion's palette: the colour names a block may hold, in menu order ("Default" is none). */
+export declare const BLOCK_COLORS: readonly ["gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red"];
+/**
+ * Notion's light values of the palette: the fallbacks of the theme tokens
+ * (`--edytor-color-<name>`, `--edytor-background-<name>`), as the core's
+ * stylesheet (`Block.svelte`) and the Notion theme write them.
+ */
+export declare const BLOCK_PALETTE: Record<(typeof BLOCK_COLORS)[number], {
+    color: string;
+    background: string;
+}>;
+/** A block's colour fields: its text colour and its background. */
+export type BlockColorField = 'color' | 'background';
+/** `value` as a colour name, or `undefined`. */
+export declare const colorName: (value: unknown) => string | undefined;
+/** The block element's colour attributes for `data` (absent when it holds none). */
+export declare const colorAttributes: (data: Readonly<Record<string, unknown>> | undefined) => {
+    'data-edytor-color': string | undefined;
+    'data-edytor-background': string | undefined;
+};
+/**
+ * Whether `block` takes a colour: a block showing its own text (a
+ * paragraph, a heading, a list item, a toggle, a callout), not a void (a
+ * divider, an image), an island (a code block) or one of its lines.
+ */
+export declare const colorable: (block: Block) => boolean;
+/**
+ * Set `field` of every colourable block of `blocks` to `value` (`null`
+ * removes it: the default), as one command and one undo step; each block
+ * is its own data write (`patchData`), so an extension vetoing one keeps
+ * that block as it was. Answers whether any block changed.
+ */
+export declare const setBlockColor: (edytor: Edytor, blocks: Iterable<Block>, field: BlockColorField, value: string | null) => boolean;

package/dist/block/colors.js

@@ -0,0 +1,74 @@
+/** Notion's palette: the colour names a block may hold, in menu order ("Default" is none). */
+export const BLOCK_COLORS = [
+    'gray',
+    'brown',
+    'orange',
+    'yellow',
+    'green',
+    'blue',
+    'purple',
+    'pink',
+    'red'
+];
+/**
+ * Notion's light values of the palette: the fallbacks of the theme tokens
+ * (`--edytor-color-<name>`, `--edytor-background-<name>`), as the core's
+ * stylesheet (`Block.svelte`) and the Notion theme write them.
+ */
+export const BLOCK_PALETTE = {
+    gray: { color: '#7d7a75', background: '#f0efed' },
+    brown: { color: '#9f765a', background: '#f5ede9' },
+    orange: { color: '#d27b2d', background: '#fbebde' },
+    yellow: { color: '#cb9434', background: '#f9f3dc' },
+    green: { color: '#50946e', background: '#e8f1ec' },
+    blue: { color: '#387dc9', background: '#e5f2fc' },
+    purple: { color: '#9a6bb4', background: '#f3ebf9' },
+    pink: { color: '#c14c8a', background: '#fae9f1' },
+    red: { color: '#cf5148', background: '#fce9e7' }
+};
+/**
+ * A colour name the core renders: lowercase letters, digits and hyphens,
+ * starting with a letter (an app's own name, such as `teal`, renders too,
+ * and its stylesheet paints it). Anything else renders nothing.
+ */
+const NAME = /^[a-z][a-z0-9-]{0,31}$/;
+/** `value` as a colour name, or `undefined`. */
+export const colorName = (value) => typeof value === 'string' && NAME.test(value) ? value : undefined;
+/** The block element's colour attributes for `data` (absent when it holds none). */
+export const colorAttributes = (data) => ({
+    'data-edytor-color': colorName(data?.color),
+    'data-edytor-background': colorName(data?.background)
+});
+/**
+ * Whether `block` takes a colour: a block showing its own text (a
+ * paragraph, a heading, a list item, a toggle, a callout), not a void (a
+ * divider, an image), an island (a code block) or one of its lines.
+ */
+export const colorable = (block) => {
+    const { facade } = block.edytor;
+    const line = block.parent && !block.parent.isRoot && facade.isLines(block.parent.id);
+    return (!block.isRoot &&
+        block.rendersContent &&
+        !facade.isVoid(block.id) &&
+        !facade.isIsland(block.id) &&
+        !line);
+};
+/**
+ * Set `field` of every colourable block of `blocks` to `value` (`null`
+ * removes it: the default), as one command and one undo step; each block
+ * is its own data write (`patchData`), so an extension vetoing one keeps
+ * that block as it was. Answers whether any block changed.
+ */
+export const setBlockColor = (edytor, blocks, field, value) => {
+    const name = value === null ? undefined : colorName(value);
+    if (value !== null && name === undefined)
+        return false;
+    const painted = [...blocks].filter((block) => colorable(block) && edytor.facade.blockDataOf(block.id)?.[field] !== name);
+    if (!painted.length)
+        return false;
+    const applied = edytor.dispatcher.each('setBlockColor', painted, (block) => {
+        block.patchData({ ops: [{ path: [field], value: name }] });
+        return edytor.dispatcher.last?.status === 'applied';
+    });
+    return applied.some(Boolean);
+};

package/dist/block/inlineBlock.svelte.d.ts

@@ -3,7 +3,7 @@ import type { InlineBlockDefinition } from '../plugins.js';
 import type { JSONInlineBlock } from '../utils/json.js';
 import type { Block } from './block.svelte.js';
 /**
- * An id-only inline-atom handle (§2.4 "Handles", R4): atom `id`, shown in
+ * An id-only inline-atom handle: atom `id`, shown in
  * block `blockId`. Getters read the document index; `node` is the element
  * that renders it (a Surface fact).
  */
@@ -31,7 +31,4 @@ export declare class InlineBlock {
     /** The atom is shown by a live block. */
     get isInDocument(): boolean;
     get value(): JSONInlineBlock;
-    attach: (node: HTMLElement) => {
-        destroy: () => void;
-    };
 }

package/dist/block/inlineBlock.svelte.js

@@ -3,7 +3,7 @@ import { propsProxy } from '../session/props.js';
 const INLINE_EDGE_CARET_THRESHOLD_PX = 4;
 const isTextPart = (part) => part !== undefined && !(part instanceof InlineBlock);
 /**
- * An id-only inline-atom handle (§2.4 "Handles", R4): atom `id`, shown in
+ * An id-only inline-atom handle: atom `id`, shown in
  * block `blockId`. Getters read the document index; `node` is the element
  * that renders it (a Surface fact).
  */
@@ -61,6 +61,7 @@ export class InlineBlock {
     get value() {
         return { id: this.id, type: this.type, data: { ...this.#item?.data } };
     }
+    /** @internal */
     attach = (node) => {
         node.setAttribute('contenteditable', 'false');
         node.dataset.edytorId = this.id;

package/dist/clipboard/htmlFlow.d.ts

@@ -15,8 +15,10 @@ export declare const tagOf: (type: string, kind: BlockDefinition, data: Values)
  * 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
  * `tag`, and each record's `parse` hook first (aliases, sanitized values).
- * Unknown elements degrade to text runs; whitespace collapses as HTML
- * renders it. `null` when the HTML carries nothing (`flow.shape`, F-P10).
+ * A void kind with a `parse` hook (an image, an embed, a video) is found
+ * by its hook only, and a void takes only its `figcaption`'s text; an
+ * `iframe`, `video` or `audio` no hook claims carries nothing. Unknown
+ * elements degrade to text runs; whitespace collapses as HTML renders it. `null` when the HTML carries nothing (`flow.shape`, F-P10).
  */
 export declare const flowOfHtml: (kinds: ImportKinds, html: string | undefined) => Flow | null;
 export {};