@meowdown/core 0.63.1 → 0.64.1

package/dist/index.d.ts

@@ -21,12 +21,18 @@ import { VirtualElement } from "@floating-ui/dom";
  * - `lossy`: content changed - a non-blank line differs, or the re-parsed doc does.
  */
 type RoundTripFidelity = 'exact' | 'normalizing' | 'lossy';
-/** Options for {@link checkRoundTrip}. */
+/**
+ * Options for {@link checkRoundTrip}.
+ */
 interface CheckRoundTripOptions {
-  /** Whether to handle a leading `---` frontmatter block. Off by default. */
+  /**
+   * Whether to handle a leading `---` frontmatter block. Off by default.
+   */
   frontmatter?: boolean;
 }
-/** Classify how `markdown` survives the editor's parse-then-serialize round trip. */
+/**
+ * Classify how `markdown` survives the editor's parse-then-serialize round trip.
+ */
 declare function checkRoundTrip(markdown: string, options?: CheckRoundTripOptions): RoundTripFidelity;
 //#endregion
 //#region src/extensions/frontmatter.d.ts
@@ -175,19 +181,33 @@ declare function defineHTMLComment(): HTMLCommentExtension;
  * (plus an optional trailing size comment) or a resolved wiki image embed.
  */
 interface MdImageAttrs {
-  /** The image destination, exactly as written in the source. */
+  /**
+   * The image destination, exactly as written in the source.
+   */
   src: string;
-  /** The image alt text. */
+  /**
+   * The image alt text.
+   */
   alt: string;
-  /** The image title, or `''` when the source has none. */
+  /**
+   * The image title, or `''` when the source has none.
+   */
   title: string;
-  /** Display width in CSS pixels from the trailing comment, or `null`. */
+  /**
+   * Display width in CSS pixels from the trailing comment, or `null`.
+   */
   width: number | null;
-  /** Display height in CSS pixels from the trailing comment, or `null`. */
+  /**
+   * Display height in CSS pixels from the trailing comment, or `null`.
+   */
   height: number | null;
-  /** `wikiEmbed` when the source is `![[target]]`; otherwise `null`. */
+  /**
+   * `wikiEmbed` when the source is `![[target]]`; otherwise `null`.
+   */
   syntax: 'wikiEmbed' | null;
-  /** Original wiki-embed target used when persisting a resized image, or `null`. */
+  /**
+   * Original wiki-embed target used when persisting a resized image, or `null`.
+   */
   wikiTarget: string | null;
 }
 interface MdLinkTextAttrs {
@@ -202,11 +222,17 @@ interface MdWikilinkAttrs {
  * `resolveFileLink` claimed as a file attachment, rendered as a file pill.
  */
 interface MdFileAttrs {
-  /** The link destination, exactly as written in the source. */
+  /**
+   * The link destination, exactly as written in the source.
+   */
   href: string;
-  /** The display name: the raw label slice, or the `href` basename when the label is empty. */
+  /**
+   * The display name: the raw label slice, or the `href` basename when the label is empty.
+   */
   name: string;
-  /** The link title, or `''` when the source has none. */
+  /**
+   * The link title, or `''` when the source has none.
+   */
   title: string;
 }
 /**
@@ -214,34 +240,37 @@ interface MdFileAttrs {
  * math expression, rendered by `MathMarkView`.
  */
 interface MdMathAttrs {
-  /** The TeX source between the dollar delimiters. */
+  /**
+   * The TeX source between the dollar delimiters.
+   */
   formula: string;
 }
-/** mdPack keys for units that store no extra data; the syntax marks carry it. */
-type MdPackSimpleKey = 'bold' | 'italic' | 'code' | 'strike' | 'highlight' | 'autolink' | 'math';
+/**
+ * mdPack keys for units that store no extra data; their own marks carry it.
+ */
+type MdPackSimpleKey = 'bold' | 'italic' | 'code' | 'strike' | 'highlight' | 'autolink' | 'math' | 'wikilink' | 'image' | 'file';
 /**
  * Content-derived identity of one inline syntax unit. Adjacent units of the
  * same kind are kept apart by it (so they do not merge into one mark run), and
  * it stays stable when unrelated text in the block is edited, so editing one
  * unit never re-marks the others. `data` carries the unit's parsed payload (a
- * link's `href`/`title`, an image's `src`) so callers read it off the mark
- * instead of re-parsing the text.
+ * link's `href`/`title`) so callers read it off the mark instead of re-parsing
+ * the text. The parser sets `slot: 1` on a unit whose pack would otherwise
+ * equal the pack of the unit ending exactly where it starts; equal packs would
+ * merge the two units into one mark run and one mark view.
  */
-type MdPackAttrs = {
+type MdPackAttrs = ({
   key: 'link';
   data: {
     href: string;
     title: string;
     reference?: true;
   };
-} | {
-  key: 'image';
-  data: {
-    src: string;
-  };
 } | {
   key: MdPackSimpleKey;
   data?: null;
+}) & {
+  slot?: 1 | null;
 };
 //#endregion
 //#region src/utils/range.d.ts
@@ -252,7 +281,9 @@ interface PositionRange {
 //#endregion
 //#region src/extensions/get-link-unit-at.d.ts
 interface LinkUnit {
-  /** Whole inline link, reference link, or autolink range. */
+  /**
+   * Whole inline link, reference link, or autolink range.
+   */
   unit: PositionRange;
   /**
    * The visible text of the link: the `[ ]` interior for a full link, the URL
@@ -261,13 +292,21 @@ interface LinkUnit {
    * whose collapsed glyphs measure at bogus coordinates.
    */
   text: PositionRange;
-  /** Interior of `[ ]`. Absent for an autolink. */
+  /**
+   * Interior of `[ ]`. Absent for an autolink.
+   */
   label?: PositionRange;
-  /** Interior of `( )`. What `updateLink` rewrites. Absent for an autolink. */
+  /**
+   * Interior of `( )`. What `updateLink` rewrites. Absent for an autolink.
+   */
   dest?: PositionRange;
-  /** The link URL. Could be an empty string. */
+  /**
+   * The link URL. Could be an empty string.
+   */
   href: string;
-  /** The link title, unquoted. Could be an empty string. */
+  /**
+   * The link title, unquoted. Could be an empty string.
+   */
   title: string;
 }
 /**
@@ -292,9 +331,13 @@ interface InsertLinkOptions {
   wrapText?: boolean;
 }
 declare function insertLink({ href, title, wrapText }?: InsertLinkOptions): Command;
-/** Rewrite the `( ... )` of the link at the caret/selection. */
+/**
+ * Rewrite the `( ... )` of the link at the caret/selection.
+ */
 declare function updateLink(attrs: LinkAttrs): Command;
-/** Unwrap the link at the caret: keep the label text, drop the syntax. */
+/**
+ * Unwrap the link at the caret: keep the label text, drop the syntax.
+ */
 declare function removeLink(): Command;
 declare function defineLinkCommands(): Extension<{
   Commands: {
@@ -312,9 +355,13 @@ type LinkEditHandler = (options: LinkEditOptions) => void;
 declare function defineLinkEditKeymap(onLinkEdit: LinkEditHandler): PlainExtension;
 //#endregion
 //#region src/extensions/pending-replacement.d.ts
-/** Where an accepted replacement lands relative to the source range. */
+/**
+ * Where an accepted replacement lands relative to the source range.
+ */
 type PendingReplacementMode = 'replace' | 'append';
-/** How a pending replacement ended. */
+/**
+ * How a pending replacement ended.
+ */
 type PendingReplacementOutcome = 'accepted' | 'discarded';
 /**
  * A staged replacement: Markdown text accumulating over `[from, to]` that is
@@ -322,27 +369,45 @@ type PendingReplacementOutcome = 'accepted' | 'discarded';
  * untouched; discarding is a no-op.
  */
 interface PendingReplacement {
-  /** Start of the source range the replacement targets. */
+  /**
+   * Start of the source range the replacement targets.
+   */
   from: number;
-  /** End of the source range the replacement targets. */
+  /**
+   * End of the source range the replacement targets.
+   */
   to: number;
-  /** The Markdown accumulated so far (e.g. streamed from an AI provider). */
+  /**
+   * The Markdown accumulated so far (e.g. streamed from an AI provider).
+   */
   text: string;
-  /** Whether accepting replaces the source range or inserts after its block. */
+  /**
+   * Whether accepting replaces the source range or inserts after its block.
+   */
   mode: PendingReplacementMode;
 }
-/** The active pending replacement, or null when there is none. */
+/**
+ * The active pending replacement, or null when there is none.
+ */
 declare function getPendingReplacement(state: EditorState): PendingReplacement | null;
-/** Options for the `startPendingReplacement` command. */
+/**
+ * Options for the `startPendingReplacement` command.
+ */
 interface StartPendingReplacementOptions extends PositionRange {
   mode: PendingReplacementMode;
 }
-/** Options for the `acceptPendingReplacement` command. */
+/**
+ * Options for the `acceptPendingReplacement` command.
+ */
 interface AcceptPendingReplacementOptions {
-  /** Overrides the staged mode for this accept (e.g. "Insert below" on a replace stage). */
+  /**
+   * Overrides the staged mode for this accept (e.g. "Insert below" on a replace stage).
+   */
   mode?: PendingReplacementMode;
 }
-/** A pending-replacement change: text/range updates, or how the stage ended. */
+/**
+ * A pending-replacement change: text/range updates, or how the stage ended.
+ */
 type PendingReplacementEvent = {
   type: 'update';
   pending: PendingReplacement;
@@ -378,37 +443,63 @@ interface ReferenceDefinitionIndex {
 declare function collectReferenceDefinitions(doc: EditorNode): ReferenceDefinitionIndex;
 //#endregion
 //#region src/extensions/wiki-embed.d.ts
-/** The parsed source payload of an Obsidian-style `![[target]]` embed. */
+/**
+ * The parsed source payload of an Obsidian-style `![[target]]` embed.
+ */
 interface ParsedWikiEmbed {
-  /** Target before an optional alias or size suffix. */
+  /**
+   * Target before an optional alias or size suffix.
+   */
   target: string;
-  /** Non-size suffix after `|`, or `''` when absent. */
+  /**
+   * Non-size suffix after `|`, or `''` when absent.
+   */
   display: string;
-  /** Requested display width in CSS pixels, or `null`. */
+  /**
+   * Requested display width in CSS pixels, or `null`.
+   */
   width: number | null;
-  /** Requested display height in CSS pixels, or `null`. */
+  /**
+   * Requested display height in CSS pixels, or `null`.
+   */
   height: number | null;
 }
-/** A resolved wiki embed rendered through Meowdown's existing atom views. */
+/**
+ * A resolved wiki embed rendered through Meowdown's existing atom views.
+ */
 type WikiEmbedResolution = {
   kind: 'image';
-  /** Source passed to `resolveImageUrl` and image click handlers. Defaults to `target`. */
+  /**
+   * Source passed to `resolveImageUrl` and image click handlers. Defaults to `target`.
+   */
   src?: string;
-  /** Image alt text. Defaults to the alias or target basename. */
+  /**
+   * Image alt text. Defaults to the alias or target basename.
+   */
   alt?: string;
 } | {
   kind: 'file';
-  /** Destination passed to file metadata and click handlers. Defaults to `target`. */
+  /**
+   * Destination passed to file metadata and click handlers. Defaults to `target`.
+   */
   href?: string;
-  /** File pill label. Defaults to the alias or target basename. */
+  /**
+   * File pill label. Defaults to the alias or target basename.
+   */
   name?: string;
-  /** Optional file title. */
+  /**
+   * Optional file title.
+   */
   title?: string;
 } | {
   kind: 'note';
-  /** Target passed to wikilink click handlers. Defaults to the source target. */
+  /**
+   * Target passed to wikilink click handlers. Defaults to the source target.
+   */
   target?: string;
-  /** Chip label. Defaults to the source alias or resolved target. */
+  /**
+   * Chip label. Defaults to the source alias or resolved target.
+   */
   display?: string;
 };
 /**
@@ -417,25 +508,41 @@ type WikiEmbedResolution = {
  * so it must be pure: the same payload must always return the same result.
  */
 type WikiEmbedResolver = (embed: ParsedWikiEmbed) => WikiEmbedResolution | undefined;
-/** Host options for wiki-embed parsing. */
+/**
+ * Host options for wiki-embed parsing.
+ */
 interface WikiEmbedOptions {
   resolveWikiEmbed?: WikiEmbedResolver;
 }
-/** Parse `![[target]]`, `![[target|alias]]`, `![[target|width]]`, or `![[target|widthxheight]]`. */
+/**
+ * Parse `![[target]]`, `![[target|alias]]`, `![[target|width]]`, or `![[target|widthxheight]]`.
+ */
 declare function parseWikiEmbed(source: string): ParsedWikiEmbed;
-/** Rewrite a wiki image embed with a persisted display size. */
+/**
+ * Rewrite a wiki image embed with a persisted display size.
+ */
 declare function formatSizedWikiEmbed(target: string, width: number, height: number): string;
-/** Last path component of a target, with a note heading/block fragment removed. */
+/**
+ * Last path component of a target, with a note heading/block fragment removed.
+ */
 declare function wikiEmbedBasename(target: string): string;
 //#endregion
 //#region src/extensions/inline-text-to-mark-chunks.d.ts
-/** What {@link FileLinkResolver} sees for one `[label](url)` link. */
+/**
+ * What {@link FileLinkResolver} sees for one `[label](url)` link.
+ */
 interface FileLinkPayload {
-  /** The link destination, exactly as written in the source. */
+  /**
+   * The link destination, exactly as written in the source.
+   */
   href: string;
-  /** The raw label slice between the brackets; may be empty or contain nested syntax. */
+  /**
+   * The raw label slice between the brackets; may be empty or contain nested syntax.
+   */
   label: string;
-  /** The link title, or `''` when the source has none. */
+  /**
+   * The link title, or `''` when the source has none.
+   */
   title: string;
 }
 /**
@@ -446,18 +553,32 @@ interface FileLinkPayload {
  * so the same input must always produce the same answer.
  */
 type FileLinkResolver = (link: FileLinkPayload) => boolean;
-/** Host options that influence inline parsing. */
+/**
+ * Host options that influence inline parsing.
+ */
 interface FileLinkOptions {
+  /**
+   * Claim `[label](url)` links as file attachments; see {@link FileLinkResolver}.
+   * Read once when the editor is created.
+   */
   resolveFileLink?: FileLinkResolver;
 }
-/** Host options that influence source-backed inline atom parsing. */
+/**
+ * Host options that influence source-backed inline atom parsing.
+ */
 type InlineMarkOptions = FileLinkOptions & WikiEmbedOptions;
 interface InlineMarkContext {
-  /** Effective document-wide definitions, keyed by normalized reference label. */
+  /**
+   * Effective document-wide definitions, keyed by normalized reference label.
+   */
   referenceDefinitions?: ReferenceDefinitions;
-  /** Prevent this definition block's own label from resolving as a shortcut reference. */
+  /**
+   * Prevent this definition block's own label from resolving as a shortcut reference.
+   */
   isReferenceDefinition?: boolean;
-  /** Receives every normalized key read by this block, including unresolved references. */
+  /**
+   * Receives every normalized key read by this block, including unresolved references.
+   */
   referencedKeys?: Set<string>;
 }
 /**
@@ -466,11 +587,17 @@ interface InlineMarkContext {
  * Callers shift the chunks into the document's coordinate space.
  */
 declare function inlineTextToMarkChunks(
-/** Typed mark builders bound to the target schema. */
+/**
+ * Typed mark builders bound to the target schema.
+ */
 marks: TypedMarkBuilders,
-/** The raw inline text of one textblock (no block prefix). */
+/**
+ * The raw inline text of one textblock (no block prefix).
+ */
 text: string,
-/** Host options; omit for the default parse. */
+/**
+ * Host options; omit for the default parse.
+ */
 options?: InlineMarkOptions): MarkChunk[];
 declare function inlineTextToMarkChunksWithContext(marks: TypedMarkBuilders, text: string, options?: InlineMarkOptions, context?: InlineMarkContext): MarkChunk[];
 //#endregion
@@ -681,15 +808,23 @@ type TypedEditor = Editor<EditorExtension>;
 //#region src/extensions/schema.d.ts
 type TypedNodeBuilders = ExtractNodeBuilders<EditorExtension>;
 type TypedMarkBuilders = ExtractMarkBuilders<EditorExtension>;
-/** Typed mark builders bound to the shared schema. */
+/**
+ * Typed mark builders bound to the shared schema.
+ */
 declare const getMarkBuilders: () => TypedMarkBuilders;
 //#endregion
 //#region src/converters/md-to-pm.d.ts
-/** Options for {@link markdownToDoc}. */
+/**
+ * Options for {@link markdownToDoc}.
+ */
 interface MarkdownToDocOptions {
-  /** Node builders to build the document with. Defaults to the shared schema's builders. */
+  /**
+   * Node builders to build the document with. Defaults to the shared schema's builders.
+   */
   nodes?: TypedNodeBuilders;
-  /** Whether to peel a leading `---` frontmatter block onto the doc's `frontmatter` attribute. Off by default. */
+  /**
+   * Whether to peel a leading `---` frontmatter block onto the doc's `frontmatter` attribute. Off by default.
+   */
   frontmatter?: boolean;
 }
 /**
@@ -709,9 +844,13 @@ interface MarkdownToDocOptions {
 declare function markdownToDoc(markdown: string, options?: MarkdownToDocOptions): ProseMirrorNode;
 //#endregion
 //#region src/converters/pm-to-md.d.ts
-/** Options for {@link docToMarkdown}. */
+/**
+ * Options for {@link docToMarkdown}.
+ */
 interface DocToMarkdownOptions {
-  /** Whether to serialize the doc's `frontmatter` attribute as a leading `---` block. Off by default. */
+  /**
+   * Whether to serialize the doc's `frontmatter` attribute as a leading `---` block. Off by default.
+   */
   frontmatter?: boolean;
 }
 /**
@@ -747,7 +886,9 @@ declare function defineBulletAfterHeading(): PlainExtension;
  * `tok-*` classes; the default theme colors them per color scheme.
  */
 declare function defineCodeBlockSyntaxHighlight(): Extension;
-/** A highlighted span of code: `[from, to)` carries the `@lezer/highlight` classes. */
+/**
+ * A highlighted span of code: `[from, to)` carries the `@lezer/highlight` classes.
+ */
 type CodeToken = readonly [from: number, to: number, classes: string];
 /**
  * Highlight `code` in `language` into `tok-*` token spans, the same classes the
@@ -790,17 +931,29 @@ interface EmbedDescriptor {
    * keys the React element, so the embed never reloads.
    */
   readonly key: string;
-  /** The iframe `src`. */
+  /**
+   * The iframe `src`.
+   */
   readonly src: string;
-  /** The iframe `title`. */
+  /**
+   * The iframe `title`.
+   */
   readonly title: string;
-  /** The iframe `class`, e.g. `md-embed md-embed-tweet`. */
+  /**
+   * The iframe `class`, e.g. `md-embed md-embed-tweet`.
+   */
   readonly className: string;
-  /** The iframe `data-testid`. */
+  /**
+   * The iframe `data-testid`.
+   */
   readonly testid: string;
-  /** The iframe `allow` policy, when the embed needs one. */
+  /**
+   * The iframe `allow` policy, when the embed needs one.
+   */
   readonly allow?: string;
-  /** Whether the iframe is fullscreen-capable. */
+  /**
+   * Whether the iframe is fullscreen-capable.
+   */
   readonly allowFullscreen?: boolean;
 }
 //#endregion
@@ -815,15 +968,23 @@ interface EmbedDescriptor {
 declare function listenForTweetHeight(iframe: HTMLIFrameElement, onHeight?: (height: number) => void): () => void;
 //#endregion
 //#region src/extensions/embed.d.ts
-/** Detect a tweet/YouTube embed in an image `src`, or `undefined` for a plain image. */
+/**
+ * Detect a tweet/YouTube embed in an image `src`, or `undefined` for a plain image.
+ */
 declare function matchEmbed(src: string): EmbedDescriptor | undefined;
 //#endregion
 //#region src/extensions/exit-boundary.d.ts
-/** Payload for {@link ExitBoundaryHandler}. */
+/**
+ * Payload for {@link ExitBoundaryHandler}.
+ */
 interface ExitBoundaryOptions {
-  /** The boundary the caret would leave: `up` at the document start, `down` at the end. */
+  /**
+   * The boundary the caret would leave: `up` at the document start, `down` at the end.
+   */
   direction: 'up' | 'down';
-  /** The originating arrow key press. */
+  /**
+   * The originating arrow key press.
+   */
   event: KeyboardEvent;
 }
 /**
@@ -832,15 +993,23 @@ interface ExitBoundaryOptions {
  * other return value consumes it.
  */
 type ExitBoundaryHandler = (options: ExitBoundaryOptions) => boolean | void;
-/** Call `onExitBoundary` when an arrow key press would leave the document boundary. */
+/**
+ * Call `onExitBoundary` when an arrow key press would leave the document boundary.
+ */
 declare function defineExitBoundaryHandler(onExitBoundary: ExitBoundaryHandler): PlainExtension;
 //#endregion
 //#region src/extensions/file-click.d.ts
-/** Payload for {@link FileClickHandler}. */
+/**
+ * Payload for {@link FileClickHandler}.
+ */
 interface FileClickPayload {
-  /** The resolved destination from `[name](href)` or a claimed `![[target]]`. */
+  /**
+   * The resolved destination from `[name](href)` or a claimed `![[target]]`.
+   */
   href: string;
-  /** The file name shown on the pill. */
+  /**
+   * The file name shown on the pill.
+   */
   name: string;
   /**
    * The originating click, or the `Enter`/`Mod-Enter` key press that followed the
@@ -859,7 +1028,9 @@ declare function defineFileClickHandler(onClick: FileClickHandler): PlainExtensi
 //#region src/extensions/file-paste.d.ts
 type FilePasteHandler = (file: File) => string | undefined | Promise<string | undefined>;
 type FileSaveErrorHandler = (error: unknown, file: File) => void;
-/** Options for {@link defineFilePaste}. */
+/**
+ * Options for {@link defineFilePaste}.
+ */
 interface FilePasteOptions {
   /**
    * Persist a pasted/dropped file and return its markdown destination, or
@@ -868,7 +1039,9 @@ interface FilePasteOptions {
    * inserts `![](src)`; any other file inserts a `[name](src)` link.
    */
   onFilePaste?: FilePasteHandler;
-  /** Called when persisting a pasted/dropped file throws. Defaults to `console.error`. */
+  /**
+   * Called when persisting a pasted/dropped file throws. Defaults to `console.error`.
+   */
   onFileSaveError?: FileSaveErrorHandler;
 }
 /**
@@ -890,9 +1063,13 @@ declare function buildFileMarkdown(file: {
 declare function defineFilePaste(options?: FilePasteOptions): PlainExtension;
 //#endregion
 //#region src/extensions/file-view.d.ts
-/** Metadata a host resolves for one file link, shown on its pill. */
+/**
+ * Metadata a host resolves for one file link, shown on its pill.
+ */
 interface FileInfo {
-  /** File size in bytes, shown as a human-readable suffix (e.g. `1.4 MB`). */
+  /**
+   * File size in bytes, shown as a human-readable suffix (e.g. `1.4 MB`).
+   */
   size?: number;
 }
 /**
@@ -903,12 +1080,18 @@ interface FileInfo {
  * resolve repeatedly: cache in the host when resolving is expensive.
  */
 type FileInfoResolver = (href: string) => FileInfo | undefined | Promise<FileInfo | undefined>;
-/** Options for {@link defineFileView}. */
+/**
+ * Options for {@link defineFileView}.
+ */
 interface FileViewOptions {
-  /** Resolve the metadata (file size) shown on a pill. Omit to show none. */
+  /**
+   * Resolve the metadata (file size) shown on a pill. Omit to show none.
+   */
   resolveFileInfo?: FileInfoResolver;
 }
-/** Classify a file destination for the pill's `data-file-kind` attribute. */
+/**
+ * Classify a file destination for the pill's `data-file-kind` attribute.
+ */
 declare function getFileKind(href: string): string;
 /**
  * Render a claimed file link or wiki embed (the `mdFile` mark) as an inline
@@ -921,7 +1104,9 @@ declare function defineFileView(options?: FileViewOptions): PlainExtension;
 //#region src/extensions/link-click.d.ts
 interface LinkClickPayload {
   href: string;
-  /** The originating click, or the `Enter`/`Mod-Enter` key press that followed the link. */
+  /**
+   * The originating click, or the `Enter`/`Mod-Enter` key press that followed the link.
+   */
   event: MouseEvent | KeyboardEvent;
 }
 type LinkClickHandler = (payload: LinkClickPayload) => void;
@@ -929,11 +1114,18 @@ interface LinkCopyPayload {
   href: string;
 }
 type LinkCopyHandler = (payload: LinkCopyPayload) => void;
+/**
+ * Call `onClick` when the user clicks a rendered Markdown link
+ * (`[text](url)`), or presses `Mod-Enter` with the caret on one. The `event`
+ * is the originating `MouseEvent` or `KeyboardEvent`.
+ */
 declare function defineLinkClickHandler(onClick: LinkClickHandler): PlainExtension;
 //#endregion
 //#region src/extensions/tag-click.d.ts
 interface TagClickPayload {
-  /** The tag name, without the leading `#`. */
+  /**
+   * The tag name, without the leading `#`.
+   */
   tag: string;
   /**
    * The originating click, or the `Enter`/`Mod-Enter` key press that followed the tag.
@@ -942,6 +1134,11 @@ interface TagClickPayload {
   event: MouseEvent | KeyboardEvent;
 }
 type TagClickHandler = (payload: TagClickPayload) => void;
+/**
+ * Call `onClick` when the user clicks a rendered `#tag`, or presses
+ * `Mod-Enter` with the caret on one. The `tag` is read from the rendered text
+ * without the leading `#`.
+ */
 declare function defineTagClickHandler(onClick: TagClickHandler): PlainExtension;
 //#endregion
 //#region src/extensions/wikilink-click.d.ts
@@ -952,10 +1149,17 @@ interface WikilinkHit {
 }
 interface WikilinkClickPayload {
   target: string;
-  /** The originating click, or the `Enter`/`Mod-Enter` key press that followed the link. */
+  /**
+   * The originating click, or the `Enter`/`Mod-Enter` key press that followed the link.
+   */
   event: MouseEvent | KeyboardEvent;
 }
 type WikilinkClickHandler = (payload: WikilinkClickPayload) => void;
+/**
+ * Call `onClick` when the user clicks a rendered wikilink label, or presses
+ * `Mod-Enter` with the caret on one. The `event` is the originating
+ * `MouseEvent` or `KeyboardEvent`.
+ */
 declare function defineWikilinkClickHandler(onClick: WikilinkClickHandler): PlainExtension;
 //#endregion
 //#region src/extensions/follow-link.d.ts
@@ -976,11 +1180,17 @@ interface FollowLinkHandlers {
 declare function defineFollowLinkHandler(handlers: FollowLinkHandlers): PlainExtension;
 //#endregion
 //#region src/extensions/image-click.d.ts
-/** Payload for {@link ImageClickHandler}. */
+/**
+ * Payload for {@link ImageClickHandler}.
+ */
 interface ImageClickPayload {
-  /** The resolved source from `![alt](src)` or a claimed `![[target]]`. */
+  /**
+   * The resolved source from `![alt](src)` or a claimed `![[target]]`.
+   */
   src: string;
-  /** The image alt text. */
+  /**
+   * The image alt text.
+   */
   alt: string;
   /**
    * The originating click or touch tap. Read the target or position a popover
@@ -1004,7 +1214,9 @@ declare function defineImageClickHandler(onClick: ImageClickHandler): PlainExten
 //#endregion
 //#region src/extensions/image.d.ts
 type ImageUrlResolver = (src: string) => string | undefined;
-/** Options for {@link defineImage}. */
+/**
+ * Options for {@link defineImage}.
+ */
 interface ImageOptions {
   /**
    * Map a markdown `src` to a displayable URL, or `undefined` to skip rendering
@@ -1019,13 +1231,23 @@ interface ImageOptions {
    */
   persistTweetHeight?: boolean;
 }
-/** Show an `src` as-is when it is an http(s) URL, otherwise skip rendering it. */
+/**
+ * Show an `src` as-is when it is an http(s) URL, otherwise skip rendering it.
+ */
 declare function defaultResolveImageUrl(src: string): string | undefined;
-/** Inline image/embed rendering: a mark view on the `mdImage` mark. */
+/**
+ * Inline image/embed rendering: a mark view on the `mdImage` mark. Images
+ * render in place from their literal Markdown source. Drag a rendered image's
+ * corner handle to write the size back into the source as a trailing comment,
+ * `![alt](src)<!-- {"width":320,"height":240} -->`, which round-trips as
+ * plain Markdown.
+ */
 declare function defineImage(options?: ImageOptions): PlainExtension;
 //#endregion
 //#region src/extensions/key-bindings.d.ts
-/** Human-readable descriptions of the editor's formatting and heading shortcuts. */
+/**
+ * Human-readable descriptions of the editor's formatting and heading shortcuts.
+ */
 declare const EDITOR_KEY_BINDINGS: {
   readonly 'Mod-b': "Bold";
   readonly 'Mod-i': "Italic";
@@ -1087,7 +1309,9 @@ type MarkName = (typeof MARK_NAMES)[number];
 declare function isMarkOfType(mark: Mark, name: MarkName): boolean;
 //#endregion
 //#region src/extensions/math.d.ts
-/** Inline math rendering: a KaTeX preview on the `mdMath` mark. */
+/**
+ * Inline math rendering: a KaTeX preview on the `mdMath` mark.
+ */
 declare function defineMath(): PlainExtension;
 //#endregion
 //#region src/extensions/node-names.d.ts
@@ -1102,7 +1326,9 @@ declare function isNodeOfType(node: ProseMirrorNode, name: NodeName): boolean;
 declare function defineSpellCheckPlugin(spellCheck: boolean): PlainExtension;
 //#endregion
 //#region src/extensions/substitution.d.ts
-/** Apply the editor's automatic plain-text substitutions. */
+/**
+ * Apply the editor's automatic plain-text substitutions.
+ */
 declare function defineSubstitution(): PlainExtension;
 //#endregion
 //#region src/extensions/table.d.ts
@@ -1131,6 +1357,12 @@ declare function defineViewAttributes(attributes: {
  * so IME, clicks, and typing keep their native behavior; only the caret pixels
  * are ours. Applies to every mark mode.
  *
+ * On a touch screen, while the last input was a finger or pen
+ * ({@link getIsTouchInput}), the roles flip: the native caret stays visible
+ * (it carries the system touch affordances: the drag magnifier, the caret-drag
+ * long-press mode) and the virtual caret draws only at positions where the
+ * native caret has no geometry, such as beside hidden Markdown syntax.
+ *
  * `layer` is the element the caret draws into. The host owns its placement:
  * it must live outside the contenteditable and scroll together with the
  * content.
@@ -1138,12 +1370,18 @@ declare function defineViewAttributes(attributes: {
 declare function defineVirtualCaret(layer: HTMLElement): PlainExtension;
 //#endregion
 //#region src/extensions/wikilink-hover.d.ts
-/** A wikilink currently under the pointer. */
+/**
+ * A wikilink currently under the pointer.
+ */
 interface WikilinkHoverHit extends WikilinkHit {
-  /** The rendered wikilink label used as the popup anchor. */
+  /**
+   * The rendered wikilink label used as the popup anchor.
+   */
   element: HTMLElement;
 }
-/** Called once on wikilink enter and with `undefined` on leave or invalidation. */
+/**
+ * Called once on wikilink enter and with `undefined` on leave or invalidation.
+ */
 type WikilinkHoverHandler = (hit: WikilinkHoverHit | undefined) => void;
 /**
  * Track the wikilink under the pointer without attaching per-link listeners.