edytor 1.0.0 → 3.0.0

package/dist/plugins/triggers/place.js

@@ -11,8 +11,7 @@ export const caretRect = (edytor) => {
     if (selection?.rangeCount && editor.contains(selection.anchorNode)) {
         const range = selection.getRangeAt(0).cloneRange();
         range.collapse(false);
-        if (typeof range.getBoundingClientRect === 'function')
-            rect = range.getBoundingClientRect();
+        rect = range.getBoundingClientRect();
     }
     if (!rect || (!rect.width && !rect.height)) {
         rect = edytor.selection.textRange().startText?.node?.getBoundingClientRect();

package/dist/plugins/triggers/triggers.d.ts

@@ -9,9 +9,14 @@
  * none of it.
  */
 import type { Edytor } from '../../edytor.svelte.js';
-import type { InitializedPlugin, InputRule, Trigger } from '../../plugins.js';
+import type { InitializedPlugin, InputRule, TextRuleContext, Trigger } from '../../plugins.js';
 import { type TextTriggerController } from './TriggerController.svelte.js';
 import { type HeldList } from '../list.svelte.js';
+/**
+ * Write `atom` where the matched text starts (`ctx.from`: a trigger's pick,
+ * an input rule's replacement), the caret after it; whether it was written.
+ */
+export declare const placeAtom: ({ edytor, block, from, caret }: TextRuleContext, atom: Parameters<Edytor["insertInline"]>[2]) => boolean;
 /**
  * `plugin` with `inputRules` (text typed at the caret that a rule
  * replaces: markdown, `:smile:` → 😄) and `triggers` (characters that open

package/dist/plugins/triggers/triggers.js

@@ -1,7 +1,5 @@
 import { inputRulesHook } from '../../session/inputRules.js';
 import { TriggerMenuController } from './TriggerController.svelte.js';
-import { caretRect } from './place.js';
-import { placeNear } from '../../surface/overlay.js';
 import { listHotkeys } from '../list.svelte.js';
 import { mountChrome } from '../chrome.js';
 /** Two bindings of one chord, `first`'s claim ending the key. */
@@ -11,6 +9,16 @@ const both = (first, then) => (payload) => {
 };
 /** The triggers each view numbered so far: a trigger's popup owner name. */
 const counts = new WeakMap();
+/**
+ * Write `atom` where the matched text starts (`ctx.from`: a trigger's pick,
+ * an input rule's replacement), the caret after it; whether it was written.
+ */
+export const placeAtom = ({ edytor, block, from, caret }, atom) => {
+    const written = edytor.insertInline(block.id, from, atom).status === 'applied';
+    if (written)
+        caret(from + 1);
+    return written;
+};
 /**
  * `plugin` with `inputRules` (text typed at the caret that a rule
  * replaces: markdown, `:smile:` → 😄) and `triggers` (characters that open
@@ -47,17 +55,8 @@ export const withRulesAndTriggers = (edytor, plugin, { inputRules = [], triggers
             : undefined,
         close: () => controller.close()
     }), 
-    // Below the caret (above it when there is no room), kept in the viewport.
-    (controller) => mountChrome(edytor, controller.trigger.menu, controller, () => controller.isOpen, {
-        name: 'edytor-trigger-menu-host',
-        zIndex: 50,
-        measure: (host) => {
-            if (!controller.isOpen)
-                return;
-            const rect = caretRect(edytor);
-            return rect && placeNear(host, rect, [280, 240]);
-        }
-    }, () => controller.close()));
+    // Its markup places itself by the controller's `anchor` (the caret).
+    (controller) => mountChrome(edytor, controller.trigger.menu, controller, () => controller.isOpen, { name: 'edytor-trigger-menu-host', zIndex: 50 }, () => controller.close()));
 };
 /**
  * `plugin` with trigger menus wired into its hooks (a plugin's `triggers`,

package/dist/plugins/uploads.svelte.d.ts

@@ -1,5 +1,8 @@
 import type { Edytor } from '../edytor.svelte.js';
-import type { Plugin, PluginOperations } from '../plugins.js';
+import type { PluginDefinitions, PluginOperations } from '../plugins.js';
+import type { DropAt } from '../session/attempt.js';
+import { type ViewUploads } from '../session/uploads.js';
+import { FileDrag } from './fileDrop.js';
 /** What an `upload` may report while it runs. */
 export type UploadReport = {
     /** The share sent so far, `0` to `1`: the block shows it as a bar. */
@@ -17,8 +20,14 @@ export type Uploader = (file: File, report: UploadReport) => Promise<string>;
  */
 export type FileUpload = {
     readonly status: 'uploading';
-    /** The file, shown while it uploads (a `blob:` URL; `null` where there is none). */
+    /**
+     * The file, shown while it uploads: its object URL (`blob:`), this
+     * view's only, never stored; `null` where there is none.
+     */
     readonly preview: string | null;
+    /** The file's name and size in bytes, shown at once. */
+    readonly name: string;
+    readonly size: number;
     /** The share sent, `0` to `1`; `null` until `upload` reports one. */
     readonly progress: number | null;
 } | {
@@ -29,10 +38,12 @@ export type FileUpload = {
 };
 /**
  * What files a kind takes (its record's `upload`, `BlockDefinition`): which,
- * and the data an upload's answer writes. The view's uploader, if the
- * uploads plugin is listed, sends them.
+ * who sends them (`send`, its plugin's `upload` option) and the data an
+ * upload's answer writes. A kind without it takes no files.
  */
 export type KindUpload = {
+    /** Upload a file of this kind and answer its URL (its plugin's `upload`). */
+    send: Uploader;
     /** Whether it takes `file`. */
     accepts: (file: File) => boolean;
     /** It takes any file no other kind takes (the file block): asked last. */
@@ -41,14 +52,13 @@ export type KindUpload = {
     data: (file: File, answer: string) => Record<string, unknown> | null;
     /** Whether the block has a source already (a peer's, a link's): its upload then writes nothing. */
     filled: (data: Record<string, unknown>) => boolean;
-    /** Show the file while it uploads (an image's `blob:` preview). */
-    preview?: boolean;
 };
 /**
- * The view's uploads (`media.files`), one per view, the uploads plugin's:
- * its uploader (`upload`, an empty block's Upload too) and the uploads of
- * pasted and dropped files, session state, never in the document. A kind
- * takes files by its record's `upload`; a paste or a drop (a drop replays
+ * The view's uploads (`media.files`), one per view, claimed by the first
+ * media plugin listed with an `upload`: the uploads of pasted, dropped and
+ * picked files (an empty block's Upload), session state, never in the
+ * document. A kind takes files by its record's `upload`, and sends them
+ * with its `send` (its plugin's uploader); a paste or a drop (a drop replays
  * the paste hooks) of files the kinds take places one empty block per
  * file, each of the kind that takes it (`fallback` last), in the
  * clipboard's order, as one paste (one command, one undo step), and each
@@ -62,14 +72,16 @@ export type KindUpload = {
  * (`fill`, asked by the empty block's render), so a redo brings it back
  * whole.
  */
-export declare class FileUploads {
+export declare class FileUploads implements ViewUploads {
     #private;
     private edytor;
-    /** The view's uploader. */
-    readonly upload: Uploader;
-    constructor(edytor: Edytor, 
-    /** The view's uploader. */
-    upload: Uploader);
+    constructor(edytor: Edytor);
+    /** The kind that takes `file`, if any. */
+    kindOf: (file: File) => string | undefined;
+    /** The types of the kinds that take files. */
+    get types(): string[];
+    /** Files dragged from outside: the drop indicator and the placement (`fileDrop.ts`). */
+    readonly drop: FileDrag;
     /** The upload of block `id` in this view (reactive), if any. */
     of: (id: string) => FileUpload | undefined;
     /**
@@ -78,8 +90,20 @@ export declare class FileUploads {
      * clipboard).
      */
     paste: NonNullable<PluginOperations['onPaste']>;
-    /** Place a block per file at the selection (one paste), then upload each. */
-    insert: (files: readonly File[]) => void;
+    /**
+     * Place a block per file at the selection (one paste), or at a drop's
+     * placement (`at`: beside, before, after or inside a block, one command),
+     * then upload each.
+     */
+    insert: (files: readonly File[], at?: DropAt) => void;
+    /**
+     * Upload `file`, picked on the empty block `id` (its Upload), with its
+     * kind's uploader, the block showing it meanwhile, and hand the answer to
+     * `land` before the preview goes (so the block never shows nothing
+     * between them): `false` when it failed (the block then shows no
+     * upload; the caller says why).
+     */
+    pick: (id: string, file: File, land: (answer: string) => void) => Promise<boolean>;
     /** Forget the block's upload (a source was embedded: its error, or held data, no longer applies). */
     clear: (id: string) => void;
     /**
@@ -91,20 +115,12 @@ export declare class FileUploads {
     /** Release every preview. */
     destroy: () => void;
 }
-/** The view's uploads, when it lists the uploads plugin. */
+/** The view's uploads, when a media plugin with an `upload` is listed. */
 export declare const fileUploads: (edytor: Edytor | undefined) => FileUploads | undefined;
-export type UploadsOptions = {
-    /**
-     * Upload a file and answer its URL: an empty image or media block's
-     * Upload, and the pasted and dropped files a kind takes, each placed as a
-     * block of that kind at once (one undo step) and filled with the URL this
-     * answers (the block shows the progress it reports).
-     */
-    upload: Uploader;
-};
 /**
- * File uploads (Notion's): the view's one uploader, for every kind whose
- * record takes files (`upload`: the image, file, video and audio kinds).
- * Without it, only links are embedded. The first listed claims the view.
+ * The hooks of a media plugin given an `upload` (its kind's record carries
+ * it, `KindUpload.send`): the first such plugin listed in a view claims the
+ * view's one `FileUploads` and runs its paste hook (a drop replays it) and
+ * teardown; the others add none.
  */
-export declare const createUploadsPlugin: ({ upload }: UploadsOptions) => Plugin;
+export declare const uploadHooks: (edytor: Edytor | undefined, upload: Uploader | undefined) => PluginOperations & PluginDefinitions;

package/dist/plugins/uploads.svelte.js

@@ -2,11 +2,20 @@ import { SvelteMap } from 'svelte/reactivity';
 import { pasteFlow } from '../clipboard/insertClipboardFragment.js';
 import { jsonBlockToSpec } from '../utils/json.js';
 import { id as mint } from '../utils.js';
+import { placeNew } from '../session/moves.js';
+import { claimUploads, viewUploads } from '../session/uploads.js';
+import { FileDrag } from './fileDrop.js';
+/** An upload's object URL, while it uploads, released. */
+const revoke = (upload) => {
+    if (upload?.status === 'uploading' && upload.preview)
+        URL.revokeObjectURL(upload.preview);
+};
 /**
- * The view's uploads (`media.files`), one per view, the uploads plugin's:
- * its uploader (`upload`, an empty block's Upload too) and the uploads of
- * pasted and dropped files, session state, never in the document. A kind
- * takes files by its record's `upload`; a paste or a drop (a drop replays
+ * The view's uploads (`media.files`), one per view, claimed by the first
+ * media plugin listed with an `upload`: the uploads of pasted, dropped and
+ * picked files (an empty block's Upload), session state, never in the
+ * document. A kind takes files by its record's `upload`, and sends them
+ * with its `send` (its plugin's uploader); a paste or a drop (a drop replays
  * the paste hooks) of files the kinds take places one empty block per
  * file, each of the kind that takes it (`fallback` last), in the
  * clipboard's order, as one paste (one command, one undo step), and each
@@ -22,13 +31,10 @@ import { id as mint } from '../utils.js';
  */
 export class FileUploads {
     edytor;
-    upload;
     #uploads = new SvelteMap();
-    constructor(edytor, 
-    /** The view's uploader. */
-    upload) {
+    constructor(edytor) {
         this.edytor = edytor;
-        this.upload = upload;
+        this.drop = new FileDrag(edytor, this);
     }
     /** The kinds that take files (their records' `upload`), in registration order. */
     get #kinds() {
@@ -37,6 +43,14 @@ export class FileUploads {
     /** The kind that takes `file`, if any. */
     #kindOf = (file) => this.#kinds.find((kind) => !kind.fallback && kind.accepts(file)) ??
         this.#kinds.find((kind) => kind.fallback && kind.accepts(file));
+    /** The kind that takes `file`, if any. */
+    kindOf = (file) => this.#kindOf(file)?.type;
+    /** The types of the kinds that take files. */
+    get types() {
+        return this.#kinds.map((kind) => kind.type);
+    }
+    /** Files dragged from outside: the drop indicator and the placement (`fileDrop.ts`). */
+    drop;
     /** The upload of block `id` in this view (reactive), if any. */
     of = (id) => this.#uploads.get(id);
     /**
@@ -44,15 +58,19 @@ export class FileUploads {
      * shows text (an office app puts a picture of copied text on the
      * clipboard).
      */
-    paste = ({ e, prevent }) => {
+    paste = ({ e, prevent, at }) => {
         if (this.edytor.readonly)
             return;
         const files = Array.from(e.clipboardData?.files ?? []).filter((file) => this.#kindOf(file));
         if (files.length && !showsText(e.clipboardData?.getData('text/html')))
-            prevent(() => this.insert(files));
+            prevent(() => this.insert(files, at));
     };
-    /** Place a block per file at the selection (one paste), then upload each. */
-    insert = (files) => {
+    /**
+     * Place a block per file at the selection (one paste), or at a drop's
+     * placement (`at`: beside, before, after or inside a block, one command),
+     * then upload each.
+     */
+    insert = (files, at) => {
         const { edytor } = this;
         const placed = files.flatMap((file) => {
             const kind = this.#kindOf(file);
@@ -61,16 +79,38 @@ export class FileUploads {
         if (!placed.length)
             return;
         const lines = placed.map(({ kind, id }) => jsonBlockToSpec({ id, type: kind.type, data: {}, content: [] }));
-        edytor.dispatcher.run('insertFromPaste', () => pasteFlow(edytor, { lines }));
+        const target = at && edytor.idToBlock.get(at.block);
+        if (at && target)
+            edytor.dispatcher.run('insertFromDrop', () => placeNew(edytor, placed.map(({ kind, id }) => ({ id, type: kind.type })), target, at.position));
+        else
+            edytor.dispatcher.run('insertFromPaste', () => pasteFlow(edytor, { lines }));
         for (const { file, kind, id } of placed) {
             // Refused, or placed as no such block (a code line takes plain lines, `flow.lines`).
             if (!edytor.facade.isVisibleBlock(id) || edytor.facade.blockTypeOf(id) !== kind.type)
                 continue;
-            const preview = kind.preview && typeof URL.createObjectURL === 'function'
-                ? URL.createObjectURL(file)
-                : null;
-            this.#uploads.set(id, { status: 'uploading', preview, progress: null });
-            void this.#send(id, kind, file, preview);
+            void this.#send(id, kind, file);
+        }
+    };
+    /**
+     * Upload `file`, picked on the empty block `id` (its Upload), with its
+     * kind's uploader, the block showing it meanwhile, and hand the answer to
+     * `land` before the preview goes (so the block never shows nothing
+     * between them): `false` when it failed (the block then shows no
+     * upload; the caller says why).
+     */
+    pick = async (id, file, land) => {
+        const kind = this.edytor.idToBlock.get(id)?.definition.upload;
+        if (!kind)
+            return false;
+        try {
+            land(await this.#run(id, kind, file));
+            return true;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            this.#settle(id);
         }
     };
     /** Forget the block's upload (a source was embedded: its error, or held data, no longer applies). */
@@ -99,12 +139,24 @@ export class FileUploads {
     };
     /** Release every preview. */
     destroy = () => {
-        for (const upload of this.#uploads.values())
-            if (upload.status === 'uploading' && upload.preview)
-                URL.revokeObjectURL(upload.preview);
+        this.#uploads.forEach(revoke);
         this.#uploads.clear();
     };
-    #send = async (id, kind, file, preview) => {
+    /**
+     * Send `file` with the kind's uploader, block `id` showing it meanwhile
+     * (`uploading`: its object URL, name, size and progress): the answer.
+     * The object URL stays until `#settle` (after the answer is stored, so
+     * the block never shows nothing between them).
+     */
+    #run = (id, kind, file) => {
+        const preview = typeof URL.createObjectURL === 'function' ? URL.createObjectURL(file) : null;
+        this.#uploads.set(id, {
+            status: 'uploading',
+            preview,
+            name: file.name,
+            size: file.size,
+            progress: null
+        });
         const report = {
             progress: (fraction) => {
                 const upload = this.#uploads.get(id);
@@ -113,28 +165,40 @@ export class FileUploads {
                 this.#uploads.set(id, { ...upload, progress: Math.min(1, Math.max(0, fraction)) });
             }
         };
+        return kind.send(file, report);
+    };
+    /** The upload of `id` ended: revoke its object URL and forget it, if it still runs. */
+    #settle = (id) => {
+        const upload = this.#uploads.get(id);
+        if (upload?.status !== 'uploading')
+            return;
+        revoke(upload);
+        this.#uploads.delete(id);
+    };
+    #send = async (id, kind, file) => {
         let data;
         try {
-            data = kind.data(file, await this.upload(file, report));
+            data = kind.data(file, await this.#run(id, kind, file));
         }
         catch {
             data = null;
         }
         const { edytor } = this;
-        if (preview)
-            URL.revokeObjectURL(preview);
         if (edytor.destroyed)
             return;
         const block = edytor.idToBlock.get(id);
+        const upload = this.#uploads.get(id);
         // Given a source meanwhile (a peer, the link field): nothing to fill.
         if (block?.isInTree && kind.filled(block.data))
-            return this.#uploads.delete(id);
-        if (!data)
-            return this.#uploads.set(id, { status: 'failed' });
+            this.#uploads.delete(id);
+        else if (!data)
+            this.#uploads.set(id, { status: 'failed' });
         // Not shown (undone, deleted): held until it shows again (`fill`).
-        if (!block?.isInTree)
-            return this.#uploads.set(id, { status: 'landed', data });
-        this.#write(id, data);
+        else if (!block?.isInTree)
+            this.#uploads.set(id, { status: 'landed', data });
+        else
+            this.#write(id, data);
+        revoke(upload);
     };
     /** The data's write, outside the history; refused (readonly), it is held for the next show. */
     #write = (id, data) => {
@@ -150,18 +214,30 @@ export class FileUploads {
 const showsText = (html) => !!html &&
     typeof DOMParser !== 'undefined' &&
     !!new DOMParser().parseFromString(html, 'text/html').body.textContent?.trim();
-const views = new WeakMap();
-/** The view's uploads, when it lists the uploads plugin. */
-export const fileUploads = (edytor) => edytor && views.get(edytor);
+/** The view's uploads, when a media plugin with an `upload` is listed. */
+export const fileUploads = (edytor) => {
+    const uploads = viewUploads(edytor);
+    return uploads instanceof FileUploads ? uploads : undefined;
+};
 /**
- * File uploads (Notion's): the view's one uploader, for every kind whose
- * record takes files (`upload`: the image, file, video and audio kinds).
- * Without it, only links are embedded. The first listed claims the view.
+ * The hooks of a media plugin given an `upload` (its kind's record carries
+ * it, `KindUpload.send`): the first such plugin listed in a view claims the
+ * view's one `FileUploads` and runs its paste hook (a drop replays it) and
+ * teardown; the others add none.
  */
-export const createUploadsPlugin = ({ upload }) => (edytor) => {
-    if (!edytor || views.has(edytor))
+export const uploadHooks = (edytor, upload) => {
+    if (!edytor || !upload || viewUploads(edytor))
         return {};
-    const uploads = new FileUploads(edytor, upload);
-    views.set(edytor, uploads);
-    return { onPaste: uploads.paste, onEdytorAttached: () => uploads.destroy };
+    const uploads = new FileUploads(edytor);
+    claimUploads(edytor, uploads);
+    return {
+        onPaste: uploads.paste,
+        onEdytorAttached: ({ node }) => {
+            const detach = uploads.drop.attach(node);
+            return () => {
+                detach();
+                uploads.destroy();
+            };
+        }
+    };
 };

package/dist/plugins.d.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { Edytor } from './edytor.svelte.js';
 import type { Block } from './block/block.svelte.js';
+import type { BlockMovePosition } from './session/moves.js';
 import type { JSONBlock, JSONDoc, JSONInlineBlock, JSONText } from './utils/json.js';
 import type { Text } from './text/text.svelte.js';
 import type { TextTransform } from './surface/cells.js';
@@ -42,7 +43,12 @@ export type { Prevent };
 export type BlockView<D = Record<string, any>> = {
     readonly id: string;
     readonly type: string;
-    readonly data: Readonly<D>;
+    /**
+     * The block's data as plain state (`block.data`): reactive at any depth,
+     * and writable, each write a dispatched `patchData`. In a suggestion's
+     * preview it is a copy: a write there changes nothing.
+     */
+    readonly data: D;
     readonly selected: boolean;
     readonly focused: boolean;
     /**
@@ -241,7 +247,10 @@ export type TextRuleContext = {
 };
 /** What an input rule's `replace` receives besides the match. */
 export type InputRuleContext = TextRuleContext & {
-    /** The typed text that completed the match: part of the match, not in the document. */
+    /**
+     * The typed text that completed the match: the end of the match, already
+     * in the document as its own undo step (`to` is after it).
+     */
     typed: string;
     /**
      * Remove the matched text (`from` to `to`) in the same plan as the first
@@ -267,13 +276,14 @@ export type InputRule = {
      */
     find: RegExp;
     /**
-     * The replacement. Return a string to replace the whole match with it
-     * (one command and one undo step with the matched text's removal; the
-     * caret after it), or write it yourself and return `true`, usually
-     * through `ctx.remove(() => …)`. Return `false` or `null`, writing
-     * nothing, to decline: the next rule is asked, then the typed text is
-     * inserted as usual, as it is when the replacement is refused (by the
-     * document, readonly or a plugin's veto).
+     * The replacement, run once the typed text is in the document (its own
+     * undo step, so the first undo gives the typed text back). Return a
+     * string to replace the whole match with it (one command and one undo
+     * step with the matched text's removal; the caret after it), or write it
+     * yourself and return `true`, usually through `ctx.remove(() => …)`.
+     * Return `false` or `null`, writing nothing, to decline: the next rule is
+     * asked, and the typed text stays as typed, as it does when the
+     * replacement is refused (by the document, readonly or a plugin's veto).
      */
     replace: (match: RegExpExecArray, ctx: InputRuleContext) => string | boolean | null | void;
 };
@@ -292,6 +302,11 @@ export type TriggerContext = TextRuleContext & {
 export type Trigger<T = any> = {
     /** The text that opens the menu (one or two characters: `@`, `[[`). */
     char: string;
+    /**
+     * The menu's name, read by its markup as `controller.trigger.name` (the
+     * mention plugin's `kind`: one menu snippet can serve several triggers).
+     */
+    name?: string;
     /** The rows for `query`, at once or as a promise (a search); the newest query wins. */
     items: (query: string, ctx: TriggerContext) => readonly T[] | Promise<readonly T[]>;
     /**
@@ -397,10 +412,18 @@ export type PluginOperations = {
         prevent: Prevent;
         e: ClipboardEvent;
     }) => void;
-    /** Called when a paste event is detected */
+    /**
+     * Called when a paste event is detected, and for a drop (its data as the
+     * clipboard's). `at`: where files dropped from outside land, the drop
+     * indicator's placement (beside, before, after or inside `block`).
+     */
     onPaste?: (payload: {
         prevent: Prevent;
         e: ClipboardEvent;
+        at?: {
+            block: string;
+            position: BlockMovePosition;
+        };
     }) => void;
 };
 /**
@@ -493,9 +516,11 @@ export type BlockDefinition = {
      */
     rendersContent?: boolean;
     /**
-     * The files the kind takes (the image's `image/*`, the file block's any):
-     * with the uploads plugin listed, an empty block's Upload sends one and a
-     * pasted or dropped file becomes a block of this kind (`media.files`).
+     * The files the kind takes (the image's `image/*`, the file block's any)
+     * and who sends them (`send`: the media plugins set it from their
+     * `upload` option): an empty block's Upload sends one, and a pasted or
+     * dropped file becomes a block of this kind (`media.files`). A kind
+     * without it takes no files.
      */
     upload?: KindUpload;
     /**
@@ -556,6 +581,15 @@ export type BlockDefinition = {
     html?: string | ((block: JSONBlock, content: string, children: string) => string);
     /** Clipboard plain-text form; default content then children, one per line. */
     plain?: (block: JSONBlock, content: string, children: string) => string;
+    /**
+     * Markdown form (`toMarkdown`): `content` is the block's text as inline
+     * markdown (marks by their own `markdown` forms), `children` its children's
+     * markdown, blocks apart by a blank line (indent them yourself:
+     * {@link MarkdownContext.indent}). Default: the bundled kind's of that
+     * name (`edytor/export` holds them; the bundled records carry none), else
+     * the `plain` form when the kind has one, else the content, then the children.
+     */
+    markdown?: (block: JSONBlock, content: string, children: string, context: MarkdownContext) => string;
     /**
      * HTML import: the block's data when `element` is this kind, else
      * `undefined`. Checked before the tag tables (a preset's export form or
@@ -609,7 +643,8 @@ export type BlockDefinition = {
 export type InlineBlockView<D = Record<string, any>> = {
     readonly id: string;
     readonly type: string;
-    readonly data: Readonly<D>;
+    /** The atom's data as plain state (`atom.data`), writable; a suggested atom's is a copy. */
+    readonly data: D;
     readonly selected: boolean;
     /** The atom's id-only handle; a suggested atom has none. */
     readonly handle: InlineBlock | undefined;
@@ -626,6 +661,8 @@ export type InlineBlockDefinition = {
      * an empty `<span data-edytor-inline-block>`.
      */
     html?: (data: JSONInlineBlock['data']) => string;
+    /** Markdown form of the atom (`toMarkdown`, escaped by you); default its `plain` form. */
+    markdown?: (data: JSONInlineBlock['data']) => string;
     /**
      * HTML import: the atom's data when `element`, met in a line's inline
      * content, is this atom, else `undefined`. Its contents are then not read
@@ -652,6 +689,12 @@ export type MarkDefinition = {
      * matches its bare `tag` (value `true`).
      */
     parse?: (element: HTMLElement) => SerializableContent | undefined;
+    /**
+     * Markdown form (`toMarkdown`): the delimiters around the marked text
+     * (`['**', '**']`), or a function of the value giving them (a link's
+     * `['[', '](href)']`). Without one the text is exported unmarked.
+     */
+    markdown?: readonly [string, string] | ((value: any) => readonly [string, string] | undefined);
     void?: boolean;
     /** Whether typing at the mark's edges extends it (`marksForInsertion`); default `inclusive`. */
     edge?: MarkEdge;
@@ -729,3 +772,12 @@ export type EditorCommand = {
     searchOnly?: boolean;
 };
 export type InitializedPlugin = ReturnType<Plugin>;
+/** What a kind's `markdown` form is given beside its block, content and children. */
+export type MarkdownContext = {
+    /** The block's position in its run of same-kind siblings, from 1 (a numbered item's number). */
+    index: number;
+    /** Every line of `text` prefixed with `prefix` (`'  '` under a list item, `'> '` in a quote). */
+    indent: (text: string, prefix: string) => string;
+    /** Rich text as inline markdown, by the marks' and atoms' forms (a table cell's). */
+    inline: (content: JSONBlock['content']) => string;
+};

package/dist/plugins.js

@@ -1,25 +1 @@
 export {};
-// Extension-surface note (replaces stale TODOs): the gaps this used to
-// list are all covered by the contract above —
-//   * `onBeforeInput` is a PluginOperations hook (line ~111).
-//   * Block focus/selection lifecycle is `onFocus`/`onBlur`/`onSelect`/
-//     `onDeselect` on BlockDefinition.
-//   * Arrow-key and select-all behavior are hotkeys, not dedicated
-//     events: `mod+a` select-all lives in hotkeys.ts and arrow handling
-//     ships in the arrowMove plugin — plugins can override either via
-//     the `hotkeys` definition map (prevention is first-win).
-// A dedicated raw-key event hook does not exist; add one only if a real
-// consumer needs more than hotkey overrides.
-// ISLAND BLOCKS
-// Island blocks are blocks that are independent of the document.
-// They are editable
-// They can be nested inside other blocks
-// But their children can not be nested or merged with other blocks
-// Their structure will remain as if or will not.
-// In case of a merge operation, the island block will be merged with the parent block and all its children will ne unnest and set to the default block type without being added as children of the merge destination block. The same wil happen to the island's content.
-// VOID BLOCKS
-// Void blocks are blocks that are not editable
-// They can be nested inside other blocks
-// They can not accept children nor be merged with other blocks
-// If the content of the void block is rendered, it will still be editable. This to allow for rendering caption of the void block. I
-// In void blocks the content is treated as an island