@aicayzer/inkkit 0.0.14 → 0.0.15

package/dist/comments.js

@@ -1,6 +1,7 @@
 import { $node, $prose, $remark } from '@milkdown/kit/utils';
 import { Fragment } from '@milkdown/kit/prose/model';
 import { Plugin, PluginKey } from '@milkdown/kit/prose/state';
+import { isImageBlock } from './image-blocks.js';
 import { fromMarkdown } from 'mdast-util-from-markdown';
 const lineEnding = (code) => code === -3 || code === -4 || code === -5;
 const whitespace = (code) => code === 32 || code === -1 || code === -2;
@@ -418,6 +419,12 @@ export function shareableFragment(content) {
     content.forEach((node) => {
         if (isComment(node))
             return;
+        // Shared output treats a standalone image as the paragraph its Markdown holds.
+        if (isImageBlock(node)) {
+            const { paragraph, image } = node.type.schema.nodes;
+            filtered.push(paragraph.create(null, image.create(node.attrs)));
+            return;
+        }
         if (node.type.name === 'reference_definition' &&
             labelHasComments(node.attrs.label))
             return;

package/dist/dialect.js

@@ -8,6 +8,7 @@ import { linkedSyntax, wikiLinkSchema, namedFileMarkdown, fileReference, } from
 import { normalizeTableAlignment, normalizeTableColumnAlignment, } from './table-alignment.js';
 import { preservingCodeBlocks, remarkCodeFences, fencedCodeHandler, } from './code-fences.js';
 import { literalBlock, createLiteralPreservation } from './literals.js';
+import { imageAttrs, imageBlocks, markdownImageAttrs, readParagraph, } from './image-blocks.js';
 import { references, remarkReferencesPlugin } from './references.js';
 import { callouts, remarkCalloutsPlugin } from './callouts.js';
 import { inlineHighlight } from './inline-highlight.js';
@@ -110,6 +111,12 @@ const preserveSpacerParagraphs = paragraphSchema.extendSchema((base) => (ctx) =>
     const schema = base(ctx);
     return {
         ...schema,
+        parseMarkdown: {
+            ...schema.parseMarkdown,
+            runner(state, node, type) {
+                readParagraph(state, node, type);
+            },
+        },
         toMarkdown: {
             ...schema.toMarkdown,
             runner(state, node) {
@@ -174,19 +181,11 @@ const visibleSoftbreaks = hardbreakSchema.extendSchema((base) => (ctx) => {
             ],
     };
 });
-// Remark represents a missing title as null; the image schema accepts strings.
 const normalizedImages = imageSchema.extendSchema((base) => (ctx) => {
     const schema = base(ctx);
     return {
         ...schema,
-        attrs: {
-            ...schema.attrs,
-            inkkitFileRaw: { default: null },
-            inkkitFileTarget: { default: null },
-            inkkitFileFragment: { default: null },
-            inkkitFileWidth: { default: null },
-            inkkitFileInTable: { default: false },
-        },
+        attrs: imageAttrs,
         parseDOM: [
             {
                 tag: 'img[src]',
@@ -202,16 +201,7 @@ const normalizedImages = imageSchema.extendSchema((base) => (ctx) => {
         parseMarkdown: {
             ...schema.parseMarkdown,
             runner(state, node, type) {
-                state.addNode(type, {
-                    src: String(node.url ?? ''),
-                    alt: String(node.alt ?? ''),
-                    title: String(node.title ?? ''),
-                    inkkitFileRaw: node.inkkitFileRaw ?? null,
-                    inkkitFileTarget: node.inkkitFileTarget ?? null,
-                    inkkitFileFragment: node.inkkitFileFragment ?? null,
-                    inkkitFileWidth: node.inkkitFileWidth ?? null,
-                    inkkitFileInTable: node.inkkitFileInTable ?? false,
-                });
+                state.addNode(type, markdownImageAttrs(node));
             },
         },
         toMarkdown: {
@@ -324,6 +314,7 @@ export function createDialect(images, wikiLinks = false, files = false) {
         preserveSpacerParagraphs,
         visibleSoftbreaks,
         normalizedImages,
+        imageBlocks,
         autolinkInputRule,
         extendListItemSchemaForTask,
         strikethroughAttr,

package/dist/editor.d.ts

@@ -179,6 +179,9 @@ export declare class InkKitEditor {
         focus?: boolean;
         reveal?: boolean;
     }): void;
+    /** Throws when a document reached by an edit, after every appended normalisation, cannot be
+     *  saved as preserved Markdown. Dispatch and the replacement commands share this check. */
+    private assertPreserved;
     replaceTextRange(range: TextRange, text: string): boolean;
     textRangeRects(range: TextRange): readonly TextRect[];
     textRangesRects(ranges: readonly TextRange[]): readonly (readonly TextRect[])[];

package/dist/editor.js

@@ -21,6 +21,8 @@ import { sourceAttribute, cleanSourceDoc, editedPlainSource, sourceSelection, ra
 import { normaliseLabel, referenceDefinitions, footnoteDefinitions, } from './references.js';
 import { selectionMarkdown, selectionContent, referenceMetadata, withReferenceMetadata, } from './reference-clipboard.js';
 import { imageView } from './images.js';
+import { isImage, isImageBlock } from './image-blocks.js';
+import { GapCursor } from '@milkdown/kit/prose/gapcursor';
 import { wikiLinkView } from './wiki-view.js';
 import { withFileSignal } from './files.js';
 import { tablePlugins, tableCommand, tableCommands, tableAvailability, tableContext, configureTableMovement, } from './tables.js';
@@ -991,7 +993,7 @@ export class InkKitEditor {
             const parsed = this.editor.ctx.get(parserCtx)(selected.shareable);
             let portable = false;
             parsed.descendants((node) => {
-                if (node.type.name === 'image' || isMermaid(node))
+                if (isImage(node) || isMermaid(node))
                     portable = true;
             });
             const cut = event.type === 'cut' && this.writable;
@@ -1091,13 +1093,9 @@ export class InkKitEditor {
                 ...options,
                 dispatchTransaction: function (tr) {
                     const next = this.state.apply(tr);
-                    if (!instance.loading &&
-                        instance.preservation &&
-                        !instance.literalSurface &&
-                        !next.doc.eq(this.state.doc)) {
+                    if (!instance.loading) {
                         try {
-                            // Validate the final state, including dialect normalisation transactions.
-                            instance.currentText(next.doc);
+                            instance.assertPreserved(this.state.doc, next.doc);
                         }
                         catch (error) {
                             this.updateState(this.state);
@@ -1319,7 +1317,7 @@ export class InkKitEditor {
             const expanded = selectionContent(view.state.doc, fragment);
             let hasImages = false;
             expanded.descendants((node) => {
-                if (node.type.name === 'image' || isMermaid(node))
+                if (isImage(node) || isMermaid(node))
                     hasImages = true;
             });
             if (!hasImages) {
@@ -1606,6 +1604,12 @@ export class InkKitEditor {
             this.revealTextRange(range);
         this.publishCommandState();
     }
+    /** Throws when a document reached by an edit, after every appended normalisation, cannot be
+     *  saved as preserved Markdown. Dispatch and the replacement commands share this check. */
+    assertPreserved(before, after) {
+        if (this.preservation && !this.literalSurface && !after.eq(before))
+            this.currentText(after);
+    }
     replaceTextRange(range, text) {
         const projection = this.validateTextRange(range);
         this.assertMutation();
@@ -1631,9 +1635,8 @@ export class InkKitEditor {
             throw new InkKitError('invalid-range', 'Replacement cannot remove embedded content or structural separators');
         const from = projectionPosition(projection, range.from, 1);
         const to = projectionPosition(projection, range.to, range.from === range.to ? 1 : -1);
-        return replaceFormattedRange(this.editor.ctx.get(editorViewCtx), from, to, text, (doc) => {
-            this.currentText(doc);
-        });
+        const view = this.editor.ctx.get(editorViewCtx);
+        return replaceFormattedRange(view, from, to, text, (tr) => this.assertPreserved(view.state.doc, view.state.apply(tr).doc));
     }
     textRangeRects(range) {
         return this.textRangesRects([range])[0];
@@ -1804,10 +1807,12 @@ export class InkKitEditor {
         const view = this.editor.ctx.get(editorViewCtx);
         // A caret at the end, where writing carries on; at the start it would sit in a first-line heading and
         // show its marks. The last place text can go, so a document ending in a rule takes a caret above it
-        // rather than selecting the rule itself.
+        // rather than selecting the rule itself. After a final image, typing opens a paragraph below it.
         const { doc } = view.state;
-        const end = Selection.findFrom(doc.resolve(doc.content.size), -1, true) ??
-            Selection.atEnd(doc);
+        const $end = doc.resolve(doc.content.size);
+        const end = isImageBlock(doc.lastChild)
+            ? new GapCursor($end)
+            : (Selection.findFrom($end, -1, true) ?? Selection.atEnd(doc));
         view.dispatch(setSearchState(view.state.tr.setSelection(end), new SearchQuery({ search: '' })));
     }
     find(text, expectedGeneration) {
@@ -1875,9 +1880,8 @@ export class InkKitEditor {
             this.plainSearch = search;
             return result.count;
         }
-        return replaceFormatted(this.editor.ctx.get(editorViewCtx), search, replacement, (doc) => {
-            this.currentText(doc);
-        }, all);
+        const view = this.editor.ctx.get(editorViewCtx);
+        return replaceFormatted(view, search, replacement, (tr) => this.assertPreserved(view.state.doc, view.state.apply(tr).doc), all);
     }
     outlineContext() {
         return {
@@ -2098,22 +2102,34 @@ export class InkKitEditor {
             throw new InkKitError('image-unavailable', 'This editor has no image adapter');
         const view = this.editor.ctx.get(editorViewCtx);
         const { schema } = view.state;
-        const nodes = images.map((image) => schema.nodes.image.create({
+        // One paragraph per image: each is read back as a standalone image block where one fits.
+        const blocks = images.map((image) => schema.nodes.paragraph.create(null, schema.nodes.image.create({
             src: image.path,
             alt: image.alt,
             title: image.title ?? '',
-        }));
-        if (x != null && y != null)
-            this.insertBlocks(nodes.map((node) => schema.nodes.paragraph.create(null, node)), x, y);
-        else
-            view.dispatch(view.state.tr
-                .replaceSelectionWith(schema.nodes.paragraph.create(null, nodes))
-                .scrollIntoView());
+        })));
+        if (x != null && y != null) {
+            this.insertBlocks(blocks, x, y);
+            return;
+        }
+        const tr = view.state.tr.replaceSelection(new Slice(Fragment.fromArray(blocks), 0, 0));
+        // After the last image, so typing continues below it rather than in the block that follows.
+        const last = blocks.at(-1).firstChild;
+        let after;
+        tr.doc.descendants((node, pos) => {
+            if (node === last)
+                after = pos + node.nodeSize;
+            return after == null;
+        });
+        if (after != null)
+            tr.setSelection(TextSelection.create(tr.doc, after));
+        view.dispatch(tr.scrollIntoView());
     }
     insertBlocks(blocks, x, y) {
         const view = this.editor.ctx.get(editorViewCtx);
         const { state } = view;
-        const $pos = state.doc.resolve(view.posAtCoords({ left: x, top: y })?.pos ?? state.selection.from);
+        const hit = view.posAtCoords({ left: x, top: y });
+        const $pos = state.doc.resolve(hit?.pos ?? state.selection.from);
         const tr = state.tr;
         let at;
         if ($pos.depth === 1 &&
@@ -2123,7 +2139,16 @@ export class InkKitEditor {
             tr.replaceWith(at, $pos.after(1), blocks);
         }
         else {
-            at = $pos.depth > 0 ? $pos.after(1) : $pos.pos;
+            // A point over a top-level leaf, such as an image, resolves beside it rather than inside.
+            const leaf = $pos.depth === 0 && hit && hit.inside >= 0
+                ? state.doc.resolve(hit.inside)
+                : undefined;
+            at =
+                $pos.depth > 0
+                    ? $pos.after(1)
+                    : leaf?.depth === 0
+                        ? hit.inside + state.doc.nodeAt(hit.inside).nodeSize
+                        : $pos.pos;
             tr.insert(at, blocks);
         }
         const end = at + blocks.reduce((size, node) => size + node.nodeSize, 0) - 1;

package/dist/image-blocks.d.ts

@@ -0,0 +1,71 @@
+import type { MilkdownPlugin } from '@milkdown/kit/ctx';
+import { type Node as ProseNode, type NodeType } from '@milkdown/kit/prose/model';
+import type { ParserState } from '@milkdown/kit/transformer';
+export declare const imageBlockName = "image_block";
+/** Attributes shared by an inline image and a standalone image block. */
+export declare const imageAttrs: {
+    src: {
+        default: string;
+        validate: string;
+    };
+    alt: {
+        default: string;
+        validate: string;
+    };
+    title: {
+        default: string;
+        validate: string;
+    };
+    inkkitFileRaw: {
+        default: null;
+    };
+    inkkitFileTarget: {
+        default: null;
+    };
+    inkkitFileFragment: {
+        default: null;
+    };
+    inkkitFileWidth: {
+        default: null;
+    };
+    inkkitFileInTable: {
+        default: boolean;
+    };
+};
+interface MarkdownParagraph {
+    children?: unknown[];
+    value?: unknown;
+}
+interface MarkdownImage {
+    type: string;
+    url?: unknown;
+    alt?: unknown;
+    title?: unknown;
+    inkkitFileRaw?: unknown;
+    inkkitFileTarget?: unknown;
+    inkkitFileFragment?: unknown;
+    inkkitFileWidth?: unknown;
+    inkkitFileInTable?: unknown;
+}
+export declare function markdownImageAttrs(node: MarkdownImage): {
+    src: string;
+    alt: string;
+    title: string;
+    inkkitFileRaw: {} | null;
+    inkkitFileTarget: {} | null;
+    inkkitFileFragment: {} | null;
+    inkkitFileWidth: {} | null;
+    inkkitFileInTable: {};
+};
+/** Whether a node displays an authored image, inline or as its own block. */
+export declare function isImage(node: ProseNode): boolean;
+export declare function isImageBlock(node: ProseNode | null | undefined): boolean;
+/** The image a paragraph holds as its only content, without marks, which makes the paragraph a
+ *  standalone image block. A linked or emphasised image stays inline so its marks are kept. */
+export declare function standaloneImage(children: readonly ProseNode[]): ProseNode | undefined;
+/** Reads a Markdown paragraph, as an image block when it holds a standalone image and the enclosing
+ *  block accepts one. */
+export declare function readParagraph(state: ParserState, node: MarkdownParagraph, paragraph: NodeType): void;
+export declare const imageBlockSchema: import("@milkdown/kit/utils").$NodeSchema<"image_block">;
+export declare const imageBlocks: MilkdownPlugin[];
+export {};

package/dist/image-blocks.js

@@ -0,0 +1,286 @@
+import { keydownHandler } from '@milkdown/kit/prose/keymap';
+import { GapCursor } from '@milkdown/kit/prose/gapcursor';
+import { Fragment, } from '@milkdown/kit/prose/model';
+import { NodeSelection, Plugin, PluginKey, Selection, TextSelection, } from '@milkdown/kit/prose/state';
+import { $nodeSchema, $prose } from '@milkdown/kit/utils';
+export const imageBlockName = 'image_block';
+/** Attributes shared by an inline image and a standalone image block. */
+export const imageAttrs = {
+    src: { default: '', validate: 'string' },
+    alt: { default: '', validate: 'string' },
+    title: { default: '', validate: 'string' },
+    inkkitFileRaw: { default: null },
+    inkkitFileTarget: { default: null },
+    inkkitFileFragment: { default: null },
+    inkkitFileWidth: { default: null },
+    inkkitFileInTable: { default: false },
+};
+// Remark represents a missing title as null; the image schema accepts strings.
+export function markdownImageAttrs(node) {
+    return {
+        src: String(node.url ?? ''),
+        alt: String(node.alt ?? ''),
+        title: String(node.title ?? ''),
+        inkkitFileRaw: node.inkkitFileRaw ?? null,
+        inkkitFileTarget: node.inkkitFileTarget ?? null,
+        inkkitFileFragment: node.inkkitFileFragment ?? null,
+        inkkitFileWidth: node.inkkitFileWidth ?? null,
+        inkkitFileInTable: node.inkkitFileInTable ?? false,
+    };
+}
+/** Whether a node displays an authored image, inline or as its own block. */
+export function isImage(node) {
+    return node.type.name === 'image' || node.type.name === imageBlockName;
+}
+export function isImageBlock(node) {
+    return node?.type.name === imageBlockName;
+}
+function accepts(parent, index, type) {
+    return parent.canReplaceWith(index, index + 1, type);
+}
+/** The image a paragraph holds as its only content, without marks, which makes the paragraph a
+ *  standalone image block. A linked or emphasised image stays inline so its marks are kept. */
+export function standaloneImage(children) {
+    const [image] = children;
+    return children.length === 1 &&
+        image.type.name === 'image' &&
+        !image.marks.length
+        ? image
+        : undefined;
+}
+/** Reads a Markdown paragraph, as an image block when it holds a standalone image and the enclosing
+ *  block accepts one. */
+export function readParagraph(state, node, paragraph) {
+    state.openNode(paragraph);
+    if (node.children)
+        state.next(node.children);
+    else
+        state.addText(String(node.value ?? ''));
+    const type = state.schema.nodes[imageBlockName];
+    const element = state.top();
+    const image = standaloneImage(element.content);
+    state.close();
+    const parent = state.top();
+    if (image &&
+        type &&
+        parent?.type.contentMatch
+            .matchFragment(Fragment.fromArray(parent.content))
+            ?.matchType(type))
+        state.addNode(type, image.attrs);
+    else {
+        state.openNode(paragraph);
+        for (const child of element.content)
+            state.top().push(child);
+        state.closeNode();
+    }
+}
+// A standalone image is a block with no inside, so no edit can put text beside it. In Markdown it
+// remains a paragraph holding the image, which is how it is read and written.
+export const imageBlockSchema = $nodeSchema(imageBlockName, () => ({
+    group: 'block',
+    atom: true,
+    selectable: true,
+    draggable: true,
+    marks: '',
+    attrs: imageAttrs,
+    toDOM: (node) => [
+        'p',
+        { class: 'inkkit-image-block' },
+        [
+            'img',
+            {
+                src: String(node.attrs.src),
+                alt: String(node.attrs.alt),
+                title: String(node.attrs.title),
+            },
+        ],
+    ],
+    parseMarkdown: { match: () => false, runner: () => undefined },
+    toMarkdown: {
+        match: (node) => node.type.name === imageBlockName,
+        runner: (state, node) => {
+            state.openNode('paragraph');
+            state.next(node.type.schema.nodes.image.create(node.attrs));
+            state.closeNode();
+        },
+    },
+}));
+// An edit can leave a paragraph holding only an image, which reading its Markdown again would give
+// as an image block. The caret keeps its side of the image.
+const normalise = $prose(() => new Plugin({
+    key: new PluginKey('inkkitImageBlockNormalise'),
+    appendTransaction(transactions, old, state) {
+        const type = state.schema.nodes[imageBlockName];
+        if (!type || !transactions.some((tr) => tr.docChanged))
+            return null;
+        // Compare the documents, as mark and attribute steps change no positions.
+        const start = old.doc.content.findDiffStart(state.doc.content);
+        const end = old.doc.content.findDiffEnd(state.doc.content);
+        if (start == null || !end)
+            return null;
+        const found = new Map();
+        state.doc.nodesBetween(Math.min(start, end.b), Math.max(start, end.b), (node, pos, parent, index) => {
+            if (!node.isTextblock)
+                return true;
+            const children = [];
+            node.forEach((child) => children.push(child));
+            if (node.type.name === 'paragraph' &&
+                standaloneImage(children) &&
+                parent &&
+                accepts(parent, index, type))
+                found.set(pos, node);
+            return false;
+        });
+        if (!found.size)
+            return null;
+        const tr = state.tr;
+        const { head } = state.selection;
+        let caret;
+        for (const [pos, node] of [...found].sort(([a], [b]) => b - a)) {
+            const end = pos + node.nodeSize;
+            if (head > pos && head < end)
+                caret = head > pos + 1 ? { pos: end, side: 1 } : { pos, side: -1 };
+            tr.replaceWith(pos, end, type.create(node.firstChild.attrs));
+        }
+        if (caret)
+            tr.setSelection(new GapCursor(tr.doc.resolve(tr.mapping.map(caret.pos, caret.side))));
+        return tr;
+    },
+}));
+/** The image block a selection rests beside or selects, as the position for a new paragraph. */
+function newParagraphAt(state) {
+    const { selection } = state;
+    if (selection instanceof NodeSelection && isImageBlock(selection.node))
+        return selection.to;
+    if (selection instanceof GapCursor &&
+        (isImageBlock(selection.$head.nodeBefore) ||
+            isImageBlock(selection.$head.nodeAfter)))
+        return selection.head;
+    return undefined;
+}
+/** Opens an empty paragraph beside a selected image block, or at a gap beside one. */
+function openParagraph(state) {
+    const pos = newParagraphAt(state);
+    const paragraph = state.schema.nodes.paragraph;
+    if (pos == null || !paragraph)
+        return undefined;
+    const $pos = state.doc.resolve(pos);
+    if (!accepts($pos.parent, $pos.index(), paragraph))
+        return undefined;
+    const tr = state.tr.insert(pos, paragraph.create());
+    return tr.setSelection(TextSelection.create(tr.doc, pos + 1));
+}
+const enter = (state, dispatch) => {
+    const tr = openParagraph(state);
+    if (!tr)
+        return false;
+    dispatch?.(tr.scrollIntoView());
+    return true;
+};
+/** Backspace or Delete toward an image block selects it before anything is deleted; from a gap beside
+ *  one toward text, the caret moves into the text. An empty paragraph next to one is removed. */
+function towardImage(dir) {
+    return (state, dispatch) => {
+        const { selection, doc } = state;
+        if (!selection.empty)
+            return false;
+        const $head = selection.$head;
+        if (selection instanceof GapCursor) {
+            const node = dir < 0 ? $head.nodeBefore : $head.nodeAfter;
+            const other = dir < 0 ? $head.nodeAfter : $head.nodeBefore;
+            if (!node || !(isImageBlock(other) || isImageBlock(node)))
+                return false;
+            const next = isImageBlock(node)
+                ? NodeSelection.create(doc, dir < 0 ? $head.pos - 1 : $head.pos)
+                : Selection.findFrom($head, dir, true);
+            if (!next)
+                return false;
+            dispatch?.(state.tr.setSelection(next).scrollIntoView());
+            return true;
+        }
+        if (!$head.parent.isTextblock || $head.depth === 0)
+            return false;
+        const atEdge = dir < 0
+            ? $head.parentOffset === 0
+            : $head.parentOffset === $head.parent.content.size;
+        if (!atEdge)
+            return false;
+        const index = $head.index(-1) + dir;
+        const parent = $head.node(-1);
+        const neighbour = index >= 0 && index < parent.childCount ? parent.child(index) : undefined;
+        if (!isImageBlock(neighbour))
+            return false;
+        const block = dir < 0 ? $head.before() - 1 : $head.after();
+        // An empty paragraph goes, unless its parent needs it, such as a list item's first line.
+        if ($head.parent.content.size === 0 &&
+            $head.parent.type.name === 'paragraph' &&
+            parent.canReplace($head.index(-1), $head.index(-1) + 1)) {
+            const tr = state.tr.delete($head.before(), $head.after());
+            dispatch?.(tr
+                .setSelection(new GapCursor(tr.doc.resolve($head.before())))
+                .scrollIntoView());
+            return true;
+        }
+        if (!dispatch)
+            return true;
+        dispatch(state.tr.setSelection(NodeSelection.create(doc, block)).scrollIntoView());
+        return true;
+    };
+}
+const keys = keydownHandler({
+    Enter: enter,
+    'Shift-Enter': enter,
+    Backspace: towardImage(-1),
+    Delete: towardImage(1),
+});
+const interaction = $prose(() => new Plugin({
+    key: new PluginKey('inkkitImageBlocks'),
+    props: {
+        handleKeyDown: (view, event) => !view.composing && view.editable && keys(view, event),
+        handleTextInput(view, _from, _to, text) {
+            const tr = openParagraph(view.state);
+            if (!tr)
+                return false;
+            view.dispatch(tr.insertText(text).scrollIntoView());
+            return true;
+        },
+        // A click beside an image card, not on it, puts the caret after the image.
+        handleClickOn(view, _pos, node, nodePos, event, direct) {
+            if (!direct ||
+                !view.editable ||
+                !isImageBlock(node) ||
+                !(event.target instanceof Element) ||
+                event.target.closest('.image'))
+                return false;
+            view.dispatch(view.state.tr.setSelection(new GapCursor(view.state.doc.resolve(nodePos + node.nodeSize))));
+            return true;
+        },
+        handleDOMEvents: {
+            // ProseMirror replaces a selection when composition starts; a selected image is kept and
+            // the composed text goes after it.
+            compositionstart(view) {
+                const { selection } = view.state;
+                if (view.editable &&
+                    selection instanceof NodeSelection &&
+                    isImageBlock(selection.node))
+                    view.dispatch(view.state.tr.setSelection(new GapCursor(view.state.doc.resolve(selection.to))));
+                return false;
+            },
+            // Composed text needs a paragraph to land in before the browser writes it, as the gap
+            // cursor plugin does for its own gaps.
+            beforeinput(view, event) {
+                if (event.inputType !== 'insertCompositionText' || !view.editable)
+                    return false;
+                const tr = openParagraph(view.state);
+                if (tr)
+                    view.dispatch(tr);
+                return false;
+            },
+        },
+    },
+}));
+export const imageBlocks = [
+    imageBlockSchema,
+    normalise,
+    interaction,
+].flat();

package/dist/images.d.ts

@@ -17,6 +17,8 @@ declare class ImageView implements NodeView {
     private readonly runtime?;
     private readonly canMutate;
     dom: HTMLElement;
+    /** The card or picture, which a standalone image's block row holds. */
+    private element;
     private image?;
     private media?;
     private pdf?;
@@ -45,5 +47,5 @@ declare class ImageView implements NodeView {
     private commit;
     private canResize;
 }
-export declare function imageView(adapter?: ImageAdapter, runtime?: FileViewRuntime, canMutate?: () => boolean): import("@milkdown/kit/utils").$View<import("@milkdown/kit/utils").$Node, (node: ProseNode, view: EditorView, getPos: () => number | undefined) => ImageView>;
+export declare function imageView(adapter?: ImageAdapter, runtime?: FileViewRuntime, canMutate?: () => boolean): import("@milkdown/kit/utils").$View<import("@milkdown/kit/utils").$Node, (node: ProseNode, view: EditorView, getPos: () => number | undefined) => ImageView>[];
 export {};

package/dist/images.js

@@ -3,6 +3,7 @@ import { closeHistory } from '@milkdown/kit/prose/history';
 import { $view } from '@milkdown/kit/utils';
 import { FileResolution } from './files.js';
 import { fileReference } from './linked-syntax.js';
+import { imageBlockSchema } from './image-blocks.js';
 /** A width rides in the alt text, as `![a picture|400](images/….png)`. Other Markdown readers
  *  show the picture and keep the number without requiring a private extension. */
 export function splitAlt(alt) {
@@ -23,6 +24,8 @@ class ImageView {
     runtime;
     canMutate;
     dom;
+    /** The card or picture, which a standalone image's block row holds. */
+    element;
     image;
     media;
     pdf;
@@ -37,8 +40,15 @@ class ImageView {
         this.adapter = adapter;
         this.runtime = runtime;
         this.canMutate = canMutate;
-        this.dom = document.createElement('span');
-        this.dom.className = 'image';
+        this.element = document.createElement('span');
+        this.element.className = 'image';
+        if (node.isBlock) {
+            this.dom = document.createElement('div');
+            this.dom.className = 'inkkit-image-block';
+            this.dom.append(this.element);
+        }
+        else
+            this.dom = this.element;
         this.view.dom.addEventListener('inkkit-cancel-resize', this.cancelResize);
         this.view.dom.addEventListener('inkkit-media-policy', this.mediaPolicy);
         if (runtime) {
@@ -145,11 +155,22 @@ class ImageView {
     card(label, status, retry = false) {
         const footer = document.createElement('span');
         footer.className = 'inkkit-file-footer';
+        const name = document.createElement('span');
+        name.className = 'inkkit-file-name';
         const text = document.createElement('span');
         text.className = 'inkkit-file-label';
         text.textContent = label;
         text.title = label;
-        footer.append(text);
+        name.append(text);
+        if (this.runtime?.adapter.open) {
+            const open = this.button('', this.activate);
+            open.classList.add('inkkit-file-open');
+            open.setAttribute('aria-label', `${this.runtime.labels.fileOpen} ${label}`);
+            open.title = this.runtime.labels.fileOpen;
+            open.append(openArrow());
+            name.append(open);
+        }
+        footer.append(name);
         if (status) {
             const description = document.createElement('span');
             description.className = 'inkkit-file-status';
@@ -159,12 +180,7 @@ class ImageView {
         }
         if (retry && this.runtime)
             footer.append(this.button(this.runtime.labels.fileRetry, () => this.resolution?.retry()));
-        if (this.runtime?.adapter.open) {
-            const open = this.button(this.runtime.labels.fileOpen, this.activate);
-            open.setAttribute('aria-label', `${this.runtime.labels.fileOpen} ${label}`);
-            footer.append(open);
-        }
-        this.dom.append(footer);
+        this.element.append(footer);
     }
     failPreview() {
         this.previewFailed = true;
@@ -183,11 +199,11 @@ class ImageView {
             }
             : splitAlt(String(this.node.attrs.alt ?? ''));
         this.width = width;
-        this.dom.textContent = '';
+        this.element.textContent = '';
         this.image = undefined;
         if (this.runtime) {
-            this.dom.classList.add('inkkit-file');
-            this.dom.oncontextmenu = (event) => {
+            this.element.classList.add('inkkit-file');
+            this.element.oncontextmenu = (event) => {
                 if (!this.runtime?.adapter.contextMenu || !this.active())
                     return;
                 const captured = this.runtime.capture();
@@ -205,11 +221,11 @@ class ImageView {
             const label = state.status === 'resolved'
                 ? state.presentation.label || alt || reference.reference
                 : alt || reference.reference;
-            this.dom.setAttribute('aria-label', label);
-            this.dom.dataset.inkkitFileState = this.previewFailed
+            this.element.setAttribute('aria-label', label);
+            this.element.dataset.inkkitFileState = this.previewFailed
                 ? 'error'
                 : state.status;
-            this.dom.dataset.inkkitFileKind =
+            this.element.dataset.inkkitFileKind =
                 state.status === 'resolved' ? state.presentation.kind : 'file';
             if (this.previewFailed) {
                 this.card(label, this.runtime.labels.filePreviewUnavailable, true);
@@ -247,7 +263,7 @@ class ImageView {
                 });
                 media.src = presentation.url;
                 this.media = media;
-                this.dom.append(media);
+                this.element.append(media);
                 this.card(label);
             }
             else if (presentation.kind === 'pdf') {
@@ -263,7 +279,7 @@ class ImageView {
                 });
                 pdf.src = presentation.url;
                 this.pdf = pdf;
-                this.dom.append(pdf);
+                this.element.append(pdf);
                 this.card(label, this.runtime.labels.filePDFPreview);
             }
             else
@@ -272,11 +288,11 @@ class ImageView {
         }
         const presentation = this.adapter?.presentation(String(this.node.attrs.src ?? ''));
         if (!presentation) {
-            this.dom.classList.add('image-absent');
-            this.dom.textContent = alt || String(this.node.attrs.src ?? '');
+            this.element.classList.add('image-absent');
+            this.element.textContent = alt || String(this.node.attrs.src ?? '');
             return;
         }
-        this.dom.classList.remove('image-absent');
+        this.element.classList.remove('image-absent');
         this.renderImage(presentation.url, alt, width);
     }
     renderImage(url, alt, width) {
@@ -295,11 +311,12 @@ class ImageView {
         this.image = image;
         const preview = document.createElement('span');
         preview.className = 'inkkit-image-preview';
+        preview.append(image);
+        // The grip sits on the whole card, so it centres on the picture and its name together.
         const handle = document.createElement('span');
         handle.className = 'image-handle';
         handle.addEventListener('pointerdown', this.startResize);
-        preview.append(image, handle);
-        this.dom.append(preview);
+        this.element.append(preview, handle);
     }
     startResize = (event) => {
         event.preventDefault();
@@ -364,6 +381,18 @@ class ImageView {
         return this.view.editable && !this.view.composing && this.canMutate();
     }
 }
+const svg = 'http://www.w3.org/2000/svg';
+function openArrow() {
+    const icon = document.createElementNS(svg, 'svg');
+    icon.setAttribute('viewBox', '0 0 12 12');
+    icon.setAttribute('aria-hidden', 'true');
+    icon.setAttribute('focusable', 'false');
+    const path = document.createElementNS(svg, 'path');
+    path.setAttribute('d', 'M4 2.5h5.5V8M9.5 2.5 2.5 9.5');
+    icon.append(path);
+    return icon;
+}
 export function imageView(adapter, runtime, canMutate = () => true) {
-    return $view(imageSchema.node, () => (node, view, getPos) => new ImageView(node, view, getPos, adapter, runtime, canMutate));
+    const view = (schema) => $view(schema.node, () => (node, view, getPos) => new ImageView(node, view, getPos, adapter, runtime, canMutate));
+    return [view(imageSchema), view(imageBlockSchema)];
 }

package/dist/paste.js

@@ -3,6 +3,7 @@ import { DOMParser as ProseParser, DOMSerializer, Fragment, Slice, } from '@milk
 import { Plugin, PluginKey } from '@milkdown/kit/prose/state';
 import { $prose } from '@milkdown/kit/utils';
 import { pasteSpreadsheet } from './spreadsheet.js';
+import { isImage } from './image-blocks.js';
 import { avoidReferenceCollisions, markdownFromHTML, } from './reference-clipboard.js';
 import { InkKitError, } from './types.js';
 export class PasteController {
@@ -334,14 +335,18 @@ export class PasteController {
                     const parsed = ctx.get(parserCtx)(markdown);
                     let imageIndex = 0;
                     const hydrate = (node) => {
-                        if (node.type.name === 'image') {
+                        if (isImage(node)) {
                             const slot = /^inkkit-clipboard-image:(\d+)$/.exec(String(node.attrs.src));
                             const position = slot ? Number(slot[1]) : imageIndex++;
                             const element = elements.some((element) => element.hasAttribute('data-inkkit-image-slot'))
                                 ? elements.find((element) => Number(element.getAttribute('data-inkkit-authored-image-slot') ?? element.getAttribute('data-inkkit-image-slot')) === position)
                                 : elements[position];
-                            if (!element || !container.contains(element))
-                                return schema.text(`[${node.attrs.alt || 'Image'}: image unavailable]`);
+                            if (!element || !container.contains(element)) {
+                                const text = schema.text(`[${node.attrs.alt || 'Image'}: image unavailable]`);
+                                return node.isBlock
+                                    ? schema.nodes.paragraph.create(null, text)
+                                    : text;
+                            }
                             return node.type.create({ ...node.attrs, src: element.getAttribute('src') }, null, node.marks);
                         }
                         if (node.isText)

package/dist/search.d.ts

@@ -1,4 +1,4 @@
-import type { Node as ProseNode } from '@milkdown/kit/prose/model';
+import { type Transaction } from '@milkdown/kit/prose/state';
 import type { EditorView } from '@milkdown/kit/prose/view';
 export interface TextMatch {
     from: number;
@@ -11,5 +11,5 @@ export interface LiteralReplacement extends TextMatch {
 export declare function findLiteral(text: string, search: string, from?: number): TextMatch | undefined;
 export declare function replaceLiteral(text: string, search: string, replacement: string, selection: TextMatch, all?: boolean): LiteralReplacement;
 export declare function findFormatted(view: EditorView, text: string): boolean;
-export declare function replaceFormatted(view: EditorView, search: string, replacement: string, preflight: (doc: ProseNode) => void, all?: boolean): number;
-export declare function replaceFormattedRange(view: EditorView, from: number, to: number, replacement: string, preflight: (doc: ProseNode) => void): boolean;
+export declare function replaceFormatted(view: EditorView, search: string, replacement: string, preflight: (tr: Transaction) => void, all?: boolean): number;
+export declare function replaceFormattedRange(view: EditorView, from: number, to: number, replacement: string, preflight: (tr: Transaction) => void): boolean;

package/dist/search.js

@@ -162,7 +162,7 @@ export function replaceFormatted(view, search, replacement, preflight, all = fal
         tr = tr.setSelection(TextSelection.create(tr.doc, match.from, tr.mapping.map(match.to, 1)));
     }
     try {
-        preflight(tr.doc);
+        preflight(tr);
     }
     catch (error) {
         if (error instanceof InkKitError)
@@ -189,7 +189,7 @@ export function replaceFormattedRange(view, from, to, replacement, preflight) {
     const tr = closeHistory(view.state.tr.replace(from, to, replacementSlice(view.state, from, to, value)));
     tr.setSelection(TextSelection.create(tr.doc, from, tr.mapping.map(to, 1)));
     try {
-        preflight(tr.doc);
+        preflight(tr);
     }
     catch (error) {
         if (error instanceof InkKitError)

package/dist/style.css

@@ -201,6 +201,54 @@
   max-width: 100%;
   vertical-align: bottom;
 }
+/* A standalone image is its own block; the row is full width so a click beside the card lands on it. */
+.inkkit-root .ProseMirror .inkkit-image-block {
+  display: block;
+  margin: 0 0
+    var(--inkkit-paragraph-spacing, calc(var(--inkkit-font-size, 15px) * 0.667));
+  line-height: 0;
+}
+.inkkit-root .ProseMirror .inkkit-image-block > .image {
+  line-height: normal;
+}
+/* A card that shares its paragraph with text sits on its own line within it. */
+.inkkit-root .ProseMirror :not(.inkkit-image-block) > .image.inkkit-file {
+  display: block;
+  width: fit-content;
+}
+.inkkit-root .ProseMirror .inkkit-image-block.ProseMirror-selectednode {
+  outline: none;
+}
+.inkkit-root
+  .ProseMirror
+  .inkkit-image-block.ProseMirror-selectednode
+  > .image {
+  outline: 2px solid color-mix(in srgb, var(--_inkkit-accent) 60%, transparent);
+  outline-offset: 2px;
+  border-radius: 6px;
+}
+.inkkit-root .ProseMirror-gapcursor {
+  display: none;
+  pointer-events: none;
+  position: absolute;
+}
+.inkkit-root .ProseMirror-gapcursor::after {
+  content: '';
+  display: block;
+  position: absolute;
+  top: -2px;
+  width: 20px;
+  border-top: 2px solid var(--_inkkit-accent);
+  animation: inkkit-gapcursor-blink 1.1s steps(2, start) infinite;
+}
+@keyframes inkkit-gapcursor-blink {
+  to {
+    visibility: hidden;
+  }
+}
+.inkkit-root .ProseMirror-focused .ProseMirror-gapcursor {
+  display: block;
+}
 .inkkit-root .ProseMirror .image img {
   display: block;
   max-width: 100%;
@@ -222,6 +270,7 @@
   position: absolute;
   right: 0;
   top: 50%;
+  z-index: 1;
   transform: translateY(-50%);
   width: 20px;
   height: 32px;
@@ -255,7 +304,7 @@
   vertical-align: middle;
   border: 1px solid var(--_inkkit-rule);
   border-radius: 6px;
-  padding: 8px;
+  padding: 6px;
   white-space: normal;
 }
 
@@ -263,13 +312,30 @@
   display: flex;
   flex-wrap: wrap;
   align-items: center;
-  gap: 0.5em;
+  gap: 0.25em 0.5em;
   font-size: 0.9em;
   line-height: 1.4;
   color: var(--_inkkit-muted);
 }
 .inkkit-root .ProseMirror .inkkit-file-footer:not(:first-child) {
-  margin-block-start: 0.5em;
+  margin-block-start: 0.25em;
+}
+/* Below a picture, the name takes the picture's width rather than widening the card, so the grip
+   stays at the picture's edge; a short picture still leaves room for a few characters. */
+.inkkit-root .ProseMirror .inkkit-image-preview ~ .inkkit-file-footer {
+  width: 0;
+  min-width: 100%;
+}
+.inkkit-root .ProseMirror .image.inkkit-file:has(> .inkkit-image-preview) {
+  min-width: min(100%, 8em);
+}
+/* The name truncates; the open arrow stays visible right after it. */
+.inkkit-root .ProseMirror .inkkit-file-name {
+  display: flex;
+  flex: 1 1 auto;
+  align-items: center;
+  gap: 0.25em;
+  min-width: 0;
 }
 
 .inkkit-root .ProseMirror .inkkit-file audio,
@@ -290,7 +356,7 @@
 }
 
 .inkkit-root .ProseMirror .inkkit-file-label {
-  flex: 1 1 auto;
+  flex: 0 1 auto;
   min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
@@ -313,6 +379,34 @@
   border-radius: 3px;
   cursor: pointer;
 }
+.inkkit-root .ProseMirror .inkkit-file-open {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 1.5em;
+  min-height: 1.5em;
+  padding: 0;
+  color: var(--_inkkit-muted);
+  background: transparent;
+  border-color: transparent;
+}
+.inkkit-root .ProseMirror .inkkit-file-open:hover {
+  color: var(--_inkkit-text);
+  background: var(--_inkkit-code-bg);
+}
+.inkkit-root .ProseMirror .inkkit-file-open:focus-visible {
+  outline: 2px solid var(--_inkkit-accent);
+  outline-offset: 1px;
+}
+.inkkit-root .ProseMirror .inkkit-file-open svg {
+  width: 0.85em;
+  height: 0.85em;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.5;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
 
 .inkkit-root .ProseMirror {
   /* The viewport, not the wrapper Milkdown adds, so a click below the text still places the caret. */

package/dist/text-ranges.js

@@ -1,5 +1,6 @@
 import { InkKitError } from './types.js';
 import { fileReference } from './linked-syntax.js';
+import { imageBlockName } from './image-blocks.js';
 export function readableProjection(doc) {
     const result = { text: '', spans: [] };
     let blocks = 0;
@@ -24,6 +25,11 @@ export function readableProjection(doc) {
                 String(node.attrs.kind).replace(/^./, (value) => value.toUpperCase()), position, position + 1, 'embed');
             return true;
         }
+        if (name === imageBlockName) {
+            block(position);
+            append(fileReference(node).label || 'Image', position, position + node.nodeSize, 'embed');
+            return false;
+        }
         if (node.isTextblock) {
             block(position + 1);
             if (!node.content.size)
@@ -128,9 +134,12 @@ export function formattedRects(view, projection, from, to) {
         if (span.kind === 'embed' || span.kind === 'break') {
             const node = view.nodeDOM(span.start);
             if (node instanceof Element) {
+                // A standalone image's node is its full-width row; the card is what shows.
                 const label = node.matches('.inkkit-callout')
                     ? (node.querySelector(':scope > .inkkit-callout-header > .inkkit-callout-title') ?? node)
-                    : node;
+                    : node.matches('.inkkit-image-block')
+                        ? (node.firstElementChild ?? node)
+                        : node;
                 rects.push(...Array.from(label.getClientRects(), textRect));
             }
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicayzer/inkkit",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "A preserving Markdown editor for offline web views and the web",
   "license": "MIT",
   "type": "module",