@rathkit/rte-core 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/model.d.ts

@@ -31,7 +31,17 @@ export interface Image {
     readonly caption?: string;
 }
 export type ImageAlign = "left" | "right" | "center";
-export type Inline = TextRun | LineBreak | Image;
+/**
+ * A footnote reference: one character in the text, shown as the note's number. The note itself is an item of the document's notes
+ * list (`List.notes`) with the same `id`. Numbers are never stored: they come from the order of the references.
+ */
+export interface Note {
+    readonly type: "note";
+    readonly id: string;
+}
+export type Inline = TextRun | LineBreak | Image | Note;
+/** What an id of a note may be. Anything else is replaced when read, so an id is always safe in an attribute. */
+export declare const NOTE_ID: RegExp;
 export type Align = "left" | "center" | "right" | "justify";
 /** The most a block can be indented, in steps. */
 export declare const MAX_INDENT = 8;
@@ -56,17 +66,35 @@ export interface Heading {
 }
 export interface ListItem {
     readonly content: readonly Inline[];
-    readonly sublists: readonly List[];
+    /**
+     * What follows the item's own text, in order: nested lists, and also paragraphs, headings, code, quotes and rules. A paragraph
+     * that follows the text with nothing between is not a child but a paragraph break inside `content` (`br` with `paragraph`);
+     * a paragraph is a child only after another child (text, code, then more text).
+     */
+    readonly children: readonly ItemChild[];
     /** Present when the item is a task: whether it is done. Absent for an ordinary item. */
     readonly checked?: boolean;
+    /** In a notes list: the id of the reference this note belongs to. */
+    readonly id?: string;
+    /**
+     * Set on an item that has no text and holds only a nested list, and shows no marker of its own: the nested list sits under it
+     * without a bullet or number above it. Without this an item with no text still shows its marker. Ignored once the item has text.
+     */
+    readonly bare?: true;
 }
+/** What a list item may hold besides its own text. Tables and definition lists are not allowed in an item. */
+export type ItemChild = List | Paragraph | Heading | CodeBlock | Quote | Rule;
 export interface List {
     readonly type: "ul" | "ol";
     readonly start?: number;
     /** A CSS list-style-type keyword such as `circle` or `lower-alpha`. Absent means the default for the depth. */
     readonly style?: string;
+    /** The footnotes of the document: a numbered list whose items are the notes, kept in the order of their references. */
+    readonly notes?: true;
     readonly items: readonly ListItem[];
 }
+/** The marker a list has when it names none: numbers for an ordered list, and a bullet by depth for the rest. */
+export declare const DEFAULT_MARKER: (type: "ul" | "ol", depth: number) => string;
 export interface DefinitionEntry {
     /** A term (`dt`) or the detail that describes it (`dd`). */
     readonly kind: "term" | "detail";

package/dist/model.js

@@ -1,4 +1,6 @@
+export const NOTE_ID = /^[A-Za-z0-9_-]{1,40}$/;
 export const MAX_INDENT = 8;
+export const DEFAULT_MARKER = (type, depth) => (type === "ol" ? "decimal" : ["disc", "circle", "square"][Math.min(depth, 2)]);
 export const ROW_HEIGHT = /^\d{1,4}(\.\d{1,2})?px$/;
 export const COLOR_VALUE = /^(#[0-9a-f]{3,8}|[a-z]{3,20}|(?:rgb|hsl)a?\([\d\s.,%/-]+\))$/i;
 export const COLUMN_WIDTH = /^\d{1,5}(\.\d{1,2})?(px|%)$/;

package/dist/notes.d.ts

@@ -0,0 +1,6 @@
+import type { Block, Doc, List } from "./model.ts";
+export declare const isNotes: (block: Block | undefined) => block is List & {
+    notes: true;
+};
+/** The ids of every reference in the document, in reading order. */
+export declare const noteIds: (doc: Doc) => string[];

package/dist/notes.js

@@ -0,0 +1,49 @@
+export const isNotes = (block) => block?.type === "ol" && block.notes === true;
+function collect(block, out) {
+    const inline = (content) => { for (const n of content)
+        if (n.type === "note")
+            out.push(n.id); };
+    switch (block.type) {
+        case "p":
+        case "h":
+            inline(block.content);
+            break;
+        case "ul":
+        case "ol":
+            for (const item of block.items) {
+                inline(item.content);
+                for (const child of item.children)
+                    collect(child, out);
+            }
+            break;
+        case "dl":
+            for (const entry of block.entries)
+                inline(entry.content);
+            break;
+        case "table":
+            for (const row of block.rows)
+                for (const cell of row)
+                    for (const inner of cell.blocks)
+                        collect(inner, out);
+            break;
+        case "quote":
+            for (const inner of block.blocks)
+                collect(inner, out);
+            break;
+        default: break;
+    }
+}
+const found = new WeakMap();
+const NONE = [];
+function idsOf(block) {
+    if (isNotes(block))
+        return NONE;
+    let ids = found.get(block);
+    if (!ids) {
+        const out = [];
+        collect(block, out);
+        found.set(block, (ids = out.length === 0 ? NONE : out));
+    }
+    return ids;
+}
+export const noteIds = (doc) => doc.blocks.flatMap(idsOf);

package/dist/ops.d.ts

@@ -3,6 +3,7 @@ import { deleteBackward, deleteForward, deleteSelection, extractSelection, inser
 import { exportBlock, exportHtml, exportInline } from "./export.ts";
 import { importBlocks, importHtml, importText } from "./import.ts";
 import { setLink } from "./links.ts";
+import { isNotes, noteIds } from "./notes.ts";
 import { decodeBase64, encodeBase64 } from "./base64.ts";
 import { escapeAttribute, escapeText } from "./html/entities.ts";
 import { checkImageSrc, parseStyle } from "./import.ts";
@@ -10,8 +11,11 @@ import { imageSelection, selectedImage } from "./imageselect.ts";
 import { sameLine, sidesOf, withSides } from "./cellborder.ts";
 import { extent, fromGrid, inRow, locateCell, meets, selectedCells, selectedRect, toGrid } from "./tablegrid.ts";
 import { inlineLength, inlineText, normalizeInline } from "./model.ts";
-import { caret, clampPos, containerPaths, fixup, getBlock, getContent, isCollapsed, kindAt, mapBlockList, pathKey, selectedContainers, setContent } from "./path.ts";
+import { asChildren, caret, clampPos, containerPaths, fixup, getBlock, getContent, isCollapsed, kindAt, mapBlockList, pathKey, selectedContainers, setContent } from "./path.ts";
 export declare const ops: {
+    readonly isNotes: typeof isNotes;
+    readonly noteIds: typeof noteIds;
+    readonly asChildren: typeof asChildren;
     readonly caret: typeof caret;
     readonly clampPos: typeof clampPos;
     readonly containerPaths: typeof containerPaths;
@@ -28,6 +32,7 @@ export declare const ops: {
     readonly inlineText: typeof inlineText;
     readonly normalizeInline: typeof normalizeInline;
     readonly sliceInline: typeof sliceInline;
+    readonly NOTE_ID: RegExp;
     readonly COLUMN_WIDTH: RegExp;
     readonly COLOR_VALUE: RegExp;
     readonly ROW_HEIGHT: RegExp;

package/dist/ops.js

@@ -3,17 +3,18 @@ import { deleteBackward, deleteForward, deleteSelection, extractSelection, inser
 import { exportBlock, exportHtml, exportInline } from "./export.js";
 import { importBlocks, importHtml, importText } from "./import.js";
 import { setLink } from "./links.js";
+import { isNotes, noteIds } from "./notes.js";
 import { decodeBase64, encodeBase64 } from "./base64.js";
 import { escapeAttribute, escapeText } from "./html/entities.js";
 import { checkImageSrc, parseStyle } from "./import.js";
 import { imageSelection, selectedImage } from "./imageselect.js";
 import { sameLine, SIDES, sidesOf, withSides } from "./cellborder.js";
 import { extent, fromGrid, inRow, locateCell, meets, selectedCells, selectedRect, toGrid } from "./tablegrid.js";
-import { COLOR_VALUE, COLUMN_WIDTH, ROW_HEIGHT, inlineLength, inlineText, normalizeInline } from "./model.js";
-import { caret, clampPos, containerPaths, fixup, getBlock, getContent, isCollapsed, kindAt, mapBlockList, pathKey, selectedContainers, setContent, } from "./path.js";
+import { NOTE_ID, COLOR_VALUE, COLUMN_WIDTH, ROW_HEIGHT, inlineLength, inlineText, normalizeInline } from "./model.js";
+import { asChildren, caret, clampPos, containerPaths, fixup, getBlock, getContent, isCollapsed, kindAt, mapBlockList, pathKey, selectedContainers, setContent, } from "./path.js";
 export const ops = {
-    caret, clampPos, containerPaths, selectedContainers, getContent, setContent, getBlock, kindAt, mapBlockList, fixup, pathKey, isCollapsed,
-    inlineLength, inlineText, normalizeInline, sliceInline, COLUMN_WIDTH, COLOR_VALUE, ROW_HEIGHT, imageSelection, selectedImage, sameLine, SIDES, sidesOf, withSides,
+    isNotes, noteIds, asChildren, caret, clampPos, containerPaths, selectedContainers, getContent, setContent, getBlock, kindAt, mapBlockList, fixup, pathKey, isCollapsed,
+    inlineLength, inlineText, normalizeInline, sliceInline, NOTE_ID, COLUMN_WIDTH, COLOR_VALUE, ROW_HEIGHT, imageSelection, selectedImage, sameLine, SIDES, sidesOf, withSides,
     toGrid, fromGrid, inRow, extent, meets, selectedRect, selectedCells, locateCell,
     parseStyle, checkImageSrc, escapeText, escapeAttribute, encodeBase64, decodeBase64,
     insertText, insertBlocks, insertLineBreak, splitBlock, deleteSelection, deleteBackward, deleteForward, moveSelection,

package/dist/paste.js

@@ -1,4 +1,5 @@
 import { importBlocks, importText } from "./import.js";
+import { CONTENT_PROFILES } from "./policy.js";
 const START = "<!--StartFragment-->";
 const END = "<!--EndFragment-->";
 export function extractFragment(html) {
@@ -17,11 +18,17 @@ function unwrapSingleCell(blocks) {
 }
 export function defaultPaste(data, importOptions = {}) {
     if (data.html && data.html.trim() !== "") {
-        const blocks = importBlocks(data.html, { ...importOptions, styles: "semantic" });
+        const blocks = importBlocks(data.html, { ...importOptions, styles: "semantic", relativeImages: importOptions.pasteRelativeImages ?? false });
         if (blocks.length > 0)
             return unwrapSingleCell(blocks);
     }
-    return importText(data.text ?? "");
+    const text = data.text ?? "";
+    const max = importOptions.maxInputLength ?? CONTENT_PROFILES.standard.maxInputLength;
+    if (text.length > max) {
+        importOptions.onLimit?.({ limit: "maxInputLength", max, length: text.length });
+        return [];
+    }
+    return importText(text);
 }
 export function pasteBlocks(data, handlers = [], importOptions = {}) {
     for (const handler of handlers) {

package/dist/path.d.ts

@@ -1,4 +1,4 @@
-import { type Block, type Doc, type Inline, type List } from "./model.ts";
+import { type Block, type Doc, type Inline, type ItemChild, type List } from "./model.ts";
 export type Path = readonly number[];
 export interface Pos {
     readonly path: Path;
@@ -21,11 +21,18 @@ export declare const pathKey: (path: Path) => string;
  * nested under it, rows run left to right then top to bottom, and so on. Negative when `a` comes first.
  */
 export declare function comparePath(a: Path, b: Path): number;
+/** A horizontal rule: where it is, and how many containers come before it in reading order. */
+export interface RuleAt {
+    readonly path: Path;
+    readonly before: number;
+}
 /**
  * Every container in the document, in reading order. Documents are never changed once made, so the answer is remembered
  * per document. The array is shared: do not change it.
  */
 export declare function containerPaths(doc: Doc): Path[];
+/** Every horizontal rule, in reading order, with the number of containers before it. A rule between container n-1 and n has `before` n. The array is shared. */
+export declare function rulePaths(doc: Doc): RuleAt[];
 export declare function blockContainers(block: Block, prefix: readonly number[]): Path[];
 /** True when the path leads to a container that exists. Cheap: it follows the path instead of listing every container. */
 export declare function hasContainer(doc: Doc, path: Path): boolean;
@@ -35,6 +42,8 @@ export declare function kindAt(doc: Doc, path: Path): "p" | "h" | "pre" | "li" |
 export declare const setContent: (doc: Doc, path: Path, content: readonly Inline[]) => Doc;
 /** Replaces the block that holds a container (a paragraph, heading or code block) in its parent list of blocks. */
 export declare function mapBlockList(doc: Doc, path: Path, fn: (blocks: readonly Block[], index: number) => readonly Block[]): Doc;
+/** Blocks as list item children: a table or definition list cannot sit in an item, so its text stays as paragraphs. */
+export declare function asChildren(blocks: readonly Block[]): ItemChild[];
 /** The block at a path that ends at a block: `[b]`, `[b, n]` inside a quote, `[b, r, c, n]` inside a table cell. */
 export declare function getBlock(doc: Doc, path: Path): Block | undefined;
 /** True when the container is a direct child of a list of blocks (so blocks can be inserted beside it). */

package/dist/path.js

@@ -11,13 +11,13 @@ export function comparePath(a, b) {
     }
     return a.length - b.length;
 }
-function listPaths(list, prefix, out) {
+function listPaths(list, prefix, out, rules) {
     list.items.forEach((item, i) => {
         out.push([...prefix, i]);
-        item.sublists.forEach((sub, k) => listPaths(sub, [...prefix, i, k], out));
+        item.children.forEach((child, k) => blockPaths(child, [...prefix, i, k], out, rules));
     });
 }
-function blockPaths(block, prefix, out) {
+function blockPaths(block, prefix, out, rules) {
     switch (block.type) {
         case "p":
         case "h":
@@ -26,18 +26,20 @@ function blockPaths(block, prefix, out) {
             break;
         case "ul":
         case "ol":
-            listPaths(block, prefix, out);
+            listPaths(block, prefix, out, rules);
             break;
         case "dl":
             block.entries.forEach((_, i) => out.push([...prefix, i]));
             break;
         case "table":
-            block.rows.forEach((row, r) => row.forEach((cell, c) => cell.blocks.forEach((inner, n) => blockPaths(inner, [...prefix, r, c, n], out))));
+            block.rows.forEach((row, r) => row.forEach((cell, c) => cell.blocks.forEach((inner, n) => blockPaths(inner, [...prefix, r, c, n], out, rules))));
             break;
         case "quote":
-            block.blocks.forEach((inner, n) => blockPaths(inner, [...prefix, n], out));
+            block.blocks.forEach((inner, n) => blockPaths(inner, [...prefix, n], out, rules));
+            break;
+        case "hr":
+            rules?.push({ path: prefix, before: out.length });
             break;
-        case "hr": break;
     }
 }
 const containerCache = new WeakMap();
@@ -50,6 +52,17 @@ export function containerPaths(doc) {
     containerCache.set(doc, out);
     return out;
 }
+const ruleCache = new WeakMap();
+export function rulePaths(doc) {
+    const hit = ruleCache.get(doc);
+    if (hit)
+        return hit;
+    const out = [];
+    const containers = [];
+    doc.blocks.forEach((block, b) => blockPaths(block, [b], containers, out));
+    ruleCache.set(doc, out);
+    return out;
+}
 export function blockContainers(block, prefix) {
     const out = [];
     blockPaths(block, prefix, out);
@@ -83,8 +96,8 @@ function slotInList(list, rest) {
         return undefined;
     if (k === undefined)
         return { content: item.content, item };
-    const sub = item.sublists[k];
-    return sub ? slotInList(sub, more) : undefined;
+    const child = item.children[k];
+    return child ? slotInBlock(child, more) : undefined;
 }
 function slotInBlocks(blocks, rest) {
     const [n, ...more] = rest;
@@ -114,7 +127,7 @@ function updateList(list, rest, content) {
             return item;
         if (k === undefined)
             return { ...item, content };
-        return { ...item, sublists: item.sublists.map((sub, s) => (s === k ? updateList(sub, more, content) : sub)) };
+        return { ...item, children: item.children.map((child, s) => (s === k ? updateBlock(child, more, content) : child)) };
     });
     return { ...list, items };
 }
@@ -143,6 +156,28 @@ function updateBlocks(blocks, rest, content) {
 }
 export const setContent = (doc, path, content) => ({ blocks: updateBlocks(doc.blocks, path, content) });
 export function mapBlockList(doc, path, fn) {
+    const applyList = (list, rest) => {
+        const [i, k, ...more] = rest;
+        if (i === undefined || k === undefined)
+            return list;
+        return { ...list, items: list.items.map((item, idx) => (idx !== i ? item : { ...item, children: applyChildren(item.children, [k, ...more]) })) };
+    };
+    const applyChildren = (children, rest) => {
+        const [k, ...more] = rest;
+        if (k === undefined)
+            return [...children];
+        if (more.length === 0)
+            return asChildren(fn(children, k));
+        return children.map((child, idx) => {
+            if (idx !== k)
+                return child;
+            if (child.type === "ul" || child.type === "ol")
+                return applyList(child, more);
+            if (child.type === "quote")
+                return { ...child, blocks: apply(child.blocks, more) };
+            return child;
+        });
+    };
     const apply = (blocks, rest) => {
         const [n, ...more] = rest;
         if (n === undefined)
@@ -154,6 +189,8 @@ export function mapBlockList(doc, path, fn) {
                 return block;
             if (block.type === "quote")
                 return { ...block, blocks: apply(block.blocks, more) };
+            if (block.type === "ul" || block.type === "ol")
+                return applyList(block, more);
             if (block.type === "table") {
                 const [r, c, ...inner] = more;
                 return { ...block, rows: block.rows.map((row, ri) => (ri !== r ? row : row.map((cell, ci) => (ci !== c ? cell : { ...cell, blocks: apply(cell.blocks, inner) })))) };
@@ -163,6 +200,15 @@ export function mapBlockList(doc, path, fn) {
     };
     return { blocks: apply(doc.blocks, path) };
 }
+export function asChildren(blocks) {
+    return blocks.flatMap((block) => {
+        switch (block.type) {
+            case "table": return block.rows.flatMap((row) => row.flatMap((cell) => asChildren(cell.blocks)));
+            case "dl": return block.entries.map((entry) => ({ type: "p", content: entry.content }));
+            default: return [block];
+        }
+    });
+}
 export function getBlock(doc, path) {
     const find = (blocks, rest) => {
         const [n, ...more] = rest;
@@ -171,6 +217,8 @@ export function getBlock(doc, path) {
             return block;
         if (block.type === "quote")
             return find(block.blocks, more);
+        if (block.type === "ul" || block.type === "ol")
+            return findInList(block, more);
         if (block.type === "table") {
             const [r, c, ...inner] = more;
             const cell = r === undefined || c === undefined ? undefined : block.rows[r]?.[c];
@@ -178,6 +226,17 @@ export function getBlock(doc, path) {
         }
         return undefined;
     };
+    const findInList = (list, rest) => {
+        const [i, k, ...inner] = rest;
+        const child = i === undefined || k === undefined ? undefined : list.items[i]?.children[k];
+        if (!child)
+            return undefined;
+        if (inner.length === 0)
+            return child;
+        if (child.type === "ul" || child.type === "ol")
+            return findInList(child, inner);
+        return child.type === "quote" ? find(child.blocks, inner) : undefined;
+    };
     return find(doc.blocks, path);
 }
 export function inBlockList(doc, path) {
@@ -193,7 +252,18 @@ export function mapListOf(doc, path, fn) {
             return fn(list, i);
         return {
             ...list,
-            items: list.items.map((item, idx) => idx !== i ? item : { ...item, sublists: item.sublists.flatMap((sub, s) => (s === k ? [apply(sub, more)].filter((x) => x !== undefined) : [sub])) }),
+            items: list.items.map((item, idx) => idx !== i ? item : {
+                ...item,
+                children: item.children.flatMap((sub, s) => {
+                    if (s !== k)
+                        return [sub];
+                    if (sub.type === "ul" || sub.type === "ol") {
+                        const next = apply(sub, more);
+                        return next ? [next] : [];
+                    }
+                    return sub.type === "quote" ? [{ ...sub, blocks: walk(sub.blocks, more) }] : [sub];
+                }),
+            }),
         };
     };
     const walk = (blocks, rest) => {
@@ -226,10 +296,27 @@ export function fixup(doc) {
             if (block.type === "table") {
                 return [{ ...block, rows: block.rows.map((row) => row.map((cell) => ({ ...cell, blocks: fixBlocks(cell.blocks, true) }))) }];
             }
+            if (block.type === "ul" || block.type === "ol")
+                return [fixList(block)];
             return [block];
         });
         return out.length === 0 && needOne ? [{ type: "p", content: [] }] : out;
     };
+    const fixList = (list) => ({
+        ...list,
+        items: list.items.map((item) => ({
+            ...item,
+            children: item.children.flatMap((child) => {
+                if (child.type === "ul" || child.type === "ol")
+                    return [fixList(child)];
+                if (child.type === "quote") {
+                    const inner = fixBlocks(child.blocks, false);
+                    return inner.length > 0 ? [{ ...child, blocks: inner }] : [];
+                }
+                return [child];
+            }),
+        })),
+    });
     return { blocks: fixBlocks(doc.blocks, true) };
 }
 export function clampPos(doc, pos) {
@@ -258,6 +345,8 @@ export function cellChain(doc, path) {
             return;
         if (block.type === "quote")
             walk(block.blocks, more, [...prefix, n]);
+        else if (block.type === "ul" || block.type === "ol")
+            walkList(block, more, [...prefix, n]);
         else if (block.type === "table") {
             const [r, c, ...inner] = more;
             if (r === undefined || c === undefined)
@@ -268,6 +357,16 @@ export function cellChain(doc, path) {
                 walk(cell.blocks, inner, [...prefix, n, r, c]);
         }
     };
+    const walkList = (list, rest, prefix) => {
+        const [i, k, ...inner] = rest;
+        const child = i === undefined || k === undefined ? undefined : list.items[i]?.children[k];
+        if (i === undefined || k === undefined || !child)
+            return;
+        if (child.type === "ul" || child.type === "ol")
+            walkList(child, inner, [...prefix, i, k]);
+        else if (child.type === "quote")
+            walk(child.blocks, inner, [...prefix, i, k]);
+    };
     walk(doc.blocks, path, []);
     return chain;
 }

package/dist/plugin.d.ts

@@ -3,13 +3,58 @@ import type { CommandDef, Unsubscribe } from "./commands.ts";
 import type { Engine } from "./engine.ts";
 import type { ImportOptions } from "./import.ts";
 import type { KeyBinding } from "./keymap.ts";
-import type { Block } from "./model.ts";
+import type { Block, Doc } from "./model.ts";
+import type { EditResult, Pos, Selection } from "./path.ts";
 import type { UiItem, UiSlot } from "./ui.ts";
 import type { Ops } from "./ops.ts";
 import type { PasteHandler } from "./paste.ts";
 export declare const PLUGIN_API_VERSION = 1;
 /** Looks at blocks about to be pasted and returns the blocks to insert. May take time (an upload); then the paste waits. */
 export type PasteTransform = (blocks: readonly Block[]) => readonly Block[] | Promise<readonly Block[]>;
+/**
+ * Gives the formats a copy, cut or drag writes besides the editor's own HTML and plain text: `{ "text/markdown": "..." }`.
+ * Return a format the editor already writes (`text/plain`, `text/html`) to replace it. Return undefined to add nothing.
+ * Called once per copy with the selected blocks; it must be quick and must not change the document.
+ */
+export type CopyFormatter = (blocks: readonly Block[]) => Readonly<Record<string, string>> | undefined;
+/**
+ * Puts right what an edit left, such as a footnote whose reference was deleted. Runs after every edit that changes the document, on
+ * the result, and returns the document and selection to use; the repair is part of the same undo step. It must be quick, and
+ * must return the same document when there is nothing to put right.
+ */
+export type Normalizer = (doc: Doc, selection: Selection) => EditResult;
+/** What changed in the editor, as the page-facing part of a plugin hears of it. */
+export interface ViewChange {
+    readonly docChanged: boolean;
+    readonly selectionChanged: boolean;
+    /** The editor gained or lost the focus. */
+    readonly focusMoved: boolean;
+}
+/**
+ * What the browser view gives the page-facing part of a plugin. Types that name the page (`HTMLElement`, `Node`) are written
+ * as `object` here so this file stays free of the DOM; the plugin's view file knows what they are.
+ */
+export interface ViewHost {
+    /** The element the editor is drawn in (an `HTMLElement`). */
+    readonly element: object;
+    readonly engine: Engine;
+    readonly ops: Ops;
+    /** Adds an event listener that is taken away again when the editor or the plugin is. */
+    listen(target: object, type: string, handler: (event: never) => void): void;
+    /** Called after the page was changed by the plugin itself, so the editor does not take it for a change from outside. */
+    quiet(): void;
+    /** Called after the editor has drawn each change. */
+    onChange(listener: (change: ViewChange) => void): Unsubscribe;
+    /** The position in the document for a place in the page (`Node`, offset), or null. */
+    posFromDom(node: object, offset: number): Pos | null;
+    /** The place in the page (`Node`, offset) for a position in the document, or null. */
+    domFromPos(pos: Pos): {
+        readonly node: object;
+        readonly offset: number;
+    } | null;
+}
+/** The page-facing part of a plugin: set up once the editor has a page, returns what takes it away again. */
+export type ViewExtension = (host: ViewHost) => void | Unsubscribe;
 /** What a plugin needs of a file that was pasted or dropped. A browser `File` fits. */
 export interface BlobLike {
     readonly type: string;
@@ -24,7 +69,7 @@ export interface FileLike extends BlobLike {
 /** Turns pasted or dropped files into blocks, or returns undefined if it does not handle them. */
 export type FileHandler = (files: readonly FileLike[]) => readonly Block[] | undefined | Promise<readonly Block[] | undefined>;
 /** What a plugin sees of the editor: the same object a host gets, nothing more. */
-export type EditorHandle = Pick<Engine, "snapshot" | "apply" | "commands" | "subscribe" | "select" | "keymap" | "warn" | "importOptions" | "ui">;
+export type EditorHandle = Pick<Engine, "snapshot" | "apply" | "commands" | "subscribe" | "select" | "keymap" | "warn" | "report" | "importOptions" | "ui">;
 export interface PluginHost {
     readonly editor: EditorHandle;
     /** The editing operations, so a plugin does not import the editor to use them. */
@@ -32,6 +77,10 @@ export interface PluginHost {
     command<A, V>(def: CommandDef<A, V>): void;
     keybinding(binding: KeyBinding): void;
     pasteHandler(handler: PasteHandler): void;
+    /** Adds a repair that runs after every edit that changes the document. */
+    normalize(normalizer: Normalizer): void;
+    /** Adds formats to what copy, cut and drag write to the clipboard. Later plugins win when two give the same type. */
+    copyFormat(formatter: CopyFormatter): void;
     /** Takes over Enter, Backspace at the start, and paste inside a kind of container the plugin owns. One plugin per kind. */
     behavior(kind: ContainerKind, behavior: ContainerBehavior): void;
     /** Watches typed text before it is inserted, to turn a shortcut into something else. */
@@ -51,6 +100,8 @@ export interface Plugin {
     /** The plugin API versions it supports: `1`, `1.x`, or a range such as `>=1 <3`. A mismatch fails when it is added. */
     readonly api: string;
     setup(host: PluginHost): void | Unsubscribe;
+    /** Only in a browser: the part that draws and handles things on the page (table handles, say). The engine never calls it. */
+    readonly view?: ViewExtension;
 }
 /** Whether a version satisfies a range written as `N`, `N.x`, `>=N`, `<N` or a pair like `>=1 <3`. */
 export declare function satisfiesApi(range: string, version: number): boolean;

package/dist/policy.d.ts

@@ -0,0 +1,41 @@
+/** Elements that are dropped together with everything inside them. */
+export declare const DROPPED_ELEMENTS: ReadonlySet<string>;
+/** Elements that only group blocks: they end the paragraph before and after, and what is inside is kept. */
+export declare const GROUPING_ELEMENTS: ReadonlySet<string>;
+export declare const DEFAULT_LINK_SCHEMES: readonly string[];
+/** Schemes an image address may use. Not configurable: a `data:` address is checked separately. */
+export declare const IMAGE_SCHEMES: readonly string[];
+/** The `data:` image types kept, with the first bytes (base64) their data must start with: the bytes are trusted, not the declared type. */
+export declare const DATA_IMAGE_SIGNATURES: readonly (readonly [string, string])[];
+/** The limits on what is read. */
+export interface ContentLimits {
+    /** Longest markup read, in characters. Longer is refused whole: nothing is read and `onLimit` is told. */
+    readonly maxInputLength: number;
+    /** Deepest nesting of elements. An element nested deeper is dropped and what is inside it stays at the deepest allowed level. */
+    readonly maxDepth: number;
+    /** Longest `data:` image address, in characters. 0 refuses every `data:` image. */
+    readonly maxDataImageLength: number;
+}
+/** A profile: the limits and the choices a host makes. */
+export interface ContentPolicy extends ContentLimits {
+    /** URL schemes a link may use besides relative and fragment addresses. */
+    readonly linkSchemes: readonly string[];
+    /** `semantic` keeps meaning only; `allowlist` also keeps text color, background and alignment. (Pasting is always `semantic`.) */
+    readonly styles: "semantic" | "allowlist";
+    /** Keep relative image addresses (`a.png`, `/a.png`) when pasting. Loading always keeps them. Default false in every profile. */
+    readonly pasteRelativeImages: boolean;
+}
+/** The name of a profile in `CONTENT_PROFILES`. */
+export type ContentProfile = "strict" | "standard" | "loose";
+/** The three profiles. `standard` is the default; `strict` is for hosts that take content from people they do not trust; `loose` for hosts that trust theirs. */
+export declare const CONTENT_PROFILES: Readonly<Record<ContentProfile, ContentPolicy>>;
+/** What a host may say: a profile to start from, then single choices on top of it. */
+export type ContentOptions = {
+    readonly profile?: ContentProfile;
+} & Partial<ContentPolicy>;
+/**
+ * The policy for the options: the profile (`standard` when none is named), with each given choice laid over it. A choice that
+ * cannot be used (an unknown profile, a limit that is not a whole number of at least 0, a list that is not strings) is left out, the
+ * profile's value is used, and `complain` is told.
+ */
+export declare function contentPolicy(options?: ContentOptions, complain?: (message: string) => void): ContentPolicy;

package/dist/policy.js

@@ -0,0 +1,40 @@
+export const DROPPED_ELEMENTS = new Set([
+    "script", "style", "link", "meta", "base", "object", "embed", "iframe", "frame", "frameset", "noscript", "template",
+    "head", "textarea", "input", "select", "option", "button", "canvas", "audio", "video", "applet", "xml",
+]);
+export const GROUPING_ELEMENTS = new Set([
+    "div", "section", "article", "header", "footer", "aside", "nav", "figure", "figcaption", "address", "main", "form",
+    "body", "html", "center", "details", "summary", "dd", "dt", "fieldset", "hgroup",
+]);
+export const DEFAULT_LINK_SCHEMES = ["http", "https", "mailto", "tel"];
+export const IMAGE_SCHEMES = ["http", "https"];
+export const DATA_IMAGE_SIGNATURES = [
+    ["image/png", "iVBORw0KGgo"], ["image/jpeg", "/9j/"], ["image/gif", "R0lGOD"], ["image/webp", "UklGR"], ["image/bmp", "Qk"],
+];
+export const CONTENT_PROFILES = {
+    strict: { pasteRelativeImages: false, linkSchemes: ["http", "https", "mailto"], styles: "semantic", maxDataImageLength: 0, maxDepth: 32, maxInputLength: 1_000_000 },
+    standard: { pasteRelativeImages: false, linkSchemes: DEFAULT_LINK_SCHEMES, styles: "allowlist", maxDataImageLength: 12_000_000, maxDepth: 100, maxInputLength: 50_000_000 },
+    loose: { pasteRelativeImages: false, linkSchemes: ["http", "https", "mailto", "tel", "sms", "ftp", "ftps"], styles: "allowlist", maxDataImageLength: 25_000_000, maxDepth: 200, maxInputLength: 200_000_000 },
+};
+export function contentPolicy(options = {}, complain = () => undefined) {
+    const { profile = "standard", ...rest } = options;
+    if (!Object.hasOwn(CONTENT_PROFILES, profile))
+        complain(`content.profile "${String(profile)}" is not a profile: using standard (strict, standard or loose).`);
+    const base = Object.hasOwn(CONTENT_PROFILES, profile) ? CONTENT_PROFILES[profile] : CONTENT_PROFILES.standard;
+    const given = {};
+    for (const [key, value] of Object.entries(rest)) {
+        if (value === undefined)
+            continue;
+        const ok = key === "linkSchemes" ? Array.isArray(value) && value.every((v) => typeof v === "string" && /^[a-z][a-z0-9+.-]*$/i.test(v))
+            : key === "styles" ? value === "semantic" || value === "allowlist"
+                : key === "pasteRelativeImages" ? typeof value === "boolean"
+                    : key === "maxDepth" ? Number.isInteger(value) && value >= 1
+                        : (key === "maxInputLength" || key === "maxDataImageLength") ? Number.isInteger(value) && value >= 0
+                            : false;
+        if (ok)
+            given[key] = value;
+        else
+            complain(`content.${key} cannot be ${JSON.stringify(value)}: using the ${profile in CONTENT_PROFILES ? profile : "standard"} profile's value.`);
+    }
+    return { ...base, ...given };
+}