smartrte-core 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.2.0
+
+All changes are additive: documents without captions or metadata export byte-identically to 1.1.x (HTML, clipboard HTML/plain text, Markdown, DOCX), checked against golden output from the 1.1.x source.
+
+- **Image captions.** `block_image` gains an optional plain-text `caption` attribute (normalised: control characters stripped, whitespace collapsed, at most 500 characters). A captioned image exports as `<figure data-smart-figure="true">(<a>)<img …><figcaption>…</figcaption></figure>`, with every attribute still on the `<img>`. It also exports to Markdown (an italic line under the image), DOCX (a Caption-style paragraph) and plain text (`alt - caption`). On import, any `<figure>` with one image and one `<figcaption>` becomes a captioned image; marks inside the caption are flattened. A figcaption with no image becomes a paragraph instead of `[Unsupported: figcaption]`. The live renderer shows the caption as a non-editable projection directly under the image. See `docs/bugs/pasted-web-images-and-hr-render-as-unsupported.md`.
+- **Heads-up, changes how existing content parses:** HTML that earlier versions saved as a loose `<img>` followed by `<figcaption>` (a pasted `<figure>` flattened on save) is now repaired on load. The figcaption becomes the image's caption, and the next save rewrites it as a `<figure>`. See `docs/bugs/figure-wrapper-lost-on-save.md`. Stored JSON documents still hold the old `unknown` figcaption node; the repair runs on HTML parsing only.
+- **Host image metadata.** `block_image` gains an optional `metadata` map of host-defined `data-*` attributes (at most 10; values at most 500 characters; the `data-smart-` namespace is reserved). It's exported as escaped attributes on the `<img>`. `parseCanonicalListHtml(html, { imageMetadataAttributes })` (a new optional options parameter, also threaded through paste/drop via `CanonicalInputPipelineOptions.imageMetadataAttributes`) keeps only the names you allowlist; the default keeps none, as before.
+- **Document queries:** `getSectionContext(document, selection, { maxChars })` returns the nearest top-level heading at the caret and that section's plain text. `listDocumentImages(document)` lists every image in document order.
+- `CanonicalSubtreeRenderer.render` takes an optional `{ syncDomSelection }`, which renders without moving the browser selection (and therefore focus) into the editor.
+- Fix: a block image's alignment was lost on every HTML save → reload (`data-smart-align` was written but never read back). See `docs/bugs/block-image-align-lost-on-html-reload.md`.
+- Fix (latent): model/DOM offset mapping counted renderer projections (table caption/colgroup, checklist controls) as block children. See `docs/bugs/block-boundary-offsets-counted-renderer-projections.md`.
+- New `image-captions` row in `builtInFormatFidelity`.
+
 ## 1.1.0
 
 - Add `backgroundColor`, `textColor`, and `borderLeft` attrs to `blockquote` (the last a single composed CSS shorthand, since a blockquote only ever shows one visible border side, unlike `table_cell`'s 4-sided borders) — rendered as real CSS in the same change, alongside the existing `align`/`indentLevel`/`lineHeight` block attrs. See `docs/bugs/blockquote-styling-context-menu.md`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Smart RTE Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -30,6 +30,7 @@ import {
 - **Browser input surface** (`surface/`) — the `beforeinput`/paste/cut/drop/composition handling layer a real contentEditable-backed UI wires up to; this is what `smartrte-react` builds its editing surface on.
 - **Format adapters** (`formats/`) — HTML, Markdown, DOCX (via `mammoth`/`@xmldom`), and PDF (`pdfjs-dist`) import/export, each declaring an explicit fidelity contract (`builtInFormatFidelity`) for exactly what's lossless vs. lossy per format/feature pair.
 - **Diff, versioning, comments, suggestions, plugin system** (`diff/`, `versioning/`, `comments/`, `suggestions/`, `plugin/`) — the primitives `smartrte-react`'s version history, comment threads, and track-changes UI are built on. A `PluginRegistry` (`createPluginRegistry`, `builtInPlugins`) is how new commands, keyboard shortcuts, toolbar contributions, and renderer behavior are added — see [`docs/PLUGIN_ARCHITECTURE.md`](https://github.com/ayush1852017/smart-rte/blob/master/docs/PLUGIN_ARCHITECTURE.md) in the repository.
+- **Images: captions, host metadata, document queries** (`atom/imageExtras`, `query/`) — `block_image` takes an optional plain-text `caption` (exported as `<figure>`/`<figcaption>`) and an optional `metadata` map of host-defined `data-*` attributes. `parseCanonicalListHtml(html, { imageMetadataAttributes: ["data-source"] })` keeps only the attributes you allowlist (none by default). `getSectionContext(document, selection)` returns the nearest top-level heading at the caret plus that section's plain text, and `listDocumentImages(document)` lists every image in document order.
 - **Collab contract** (`collab/`) — the operation-transform machinery (`mapOperation`) a real-time transport would rebase concurrent edits through. A contract for hosts building multi-writer collaboration against; no transport implementation ships here.
 
 ## Subpath exports

package/dist/foundation/atom/formats.d.ts

@@ -4,17 +4,6 @@ export declare const atomToHtml: (node: SmartElementNode, options?: {
     renderFormulaHtml?: boolean;
 }) => string;
 export declare const atomFromHtmlElement: (rawElement: Element) => SmartElementNode | null;
-/**
- * page_break: Markdown has no pagination concept at all (declared
- * `unsupported` in formats/fidelity.ts) - emitting nothing would silently
- * delete the marker with no trace, the same class of bug this project has
- * hit before for images/formulas (see formats/fidelity.ts's own
- * images-media/formulas notes on that history). An HTML comment is inert
- * in every real Markdown renderer (so it never appears as visible garbage
- * text) but keeps the marker's *position* recorded in the exported file -
- * genuinely honest `unsupported`, not a round-trippable format: nothing
- * parses this comment back into a page_break node on import.
- */
 export declare const atomToMarkdown: (node: SmartElementNode) => string;
 export interface AtomDocxRun {
     readonly kind: "image" | "text" | "pageBreak";

package/dist/foundation/atom/formats.js

@@ -8,6 +8,7 @@ import "katex/contrib/mhchem";
 import { createNodeId } from "../identity.js";
 import { sanitizeLinkHref, sanitizeLinkTarget } from "../security/urlPolicy.js";
 import { sanitizeAtomSource } from "./security.js";
+import { isValidImageMetadataName, normalizeImageCaption } from "./imageExtras.js";
 const escape = (value) => String(value ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 const attr = (name, value) => value === undefined ? "" : ` ${name}="${escape(value)}"`;
 const dimensions = (node) => `${attr("width", node.attrs?.width)}${attr("height", node.attrs?.height)}`;
@@ -23,6 +24,15 @@ const renderFormulaToHtml = (source) => {
         return escape(source);
     }
 };
+/** Host metadata (atom/imageExtras.ts) as plain escaped `data-*` attributes, in stored order. Only `block_image` carries it; the stored map is already shape-validated by the schema. */
+const imageMetadataAttributes = (node) => {
+    const metadata = node.type === "block_image" ? node.attrs?.metadata : undefined;
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+        return "";
+    return Object.entries(metadata)
+        .filter(([name, value]) => isValidImageMetadataName(name) && typeof value === "string")
+        .map(([name, value]) => attr(name, value)).join("");
+};
 export const atomToHtml = (node, options) => {
     if (node.type === "image" || node.type === "block_image") {
         const src = sanitizeAtomSource(String(node.attrs?.src || ""), { kind: "image", allowBlobPreview: node.attrs?.status === "pending" }) || "";
@@ -32,17 +42,24 @@ export const atomToHtml = (node, options) => {
         // running the live surface renderer's own style logic against it
         // wouldn't see visual rounding either way, same as align today; that's
         // a deliberate, pre-existing scope boundary this doesn't change.
-        const img = `<img data-smart-id="${escape(node.id)}" data-smart-type="${node.type}" src="${escape(src)}" alt="${escape(node.attrs?.alt)}"${dimensions(node)}${attr("data-smart-status", node.attrs?.status || "ready")}${node.attrs?.decorative === true ? ' data-smart-decorative="true"' : ""}${attr("data-smart-align", node.attrs?.align)}${attr("data-smart-radius", node.attrs?.borderRadius)}${attr("data-smart-license-description", node.attrs?.licenseDescription)}${attr("data-smart-license-source-url", node.attrs?.licenseSourceUrl)}${attr("data-smart-license-type", node.attrs?.licenseType)}${attr("data-smart-license-version", node.attrs?.licenseVersion)}${attr("data-smart-license-attribution", node.attrs?.licenseAttribution)}${attr("data-smart-href", node.attrs?.href)}${attr("data-smart-target", node.attrs?.target)}>`;
+        const img = `<img data-smart-id="${escape(node.id)}" data-smart-type="${node.type}" src="${escape(src)}" alt="${escape(node.attrs?.alt)}"${dimensions(node)}${attr("data-smart-status", node.attrs?.status || "ready")}${node.attrs?.decorative === true ? ' data-smart-decorative="true"' : ""}${attr("data-smart-align", node.attrs?.align)}${attr("data-smart-radius", node.attrs?.borderRadius)}${attr("data-smart-license-description", node.attrs?.licenseDescription)}${attr("data-smart-license-source-url", node.attrs?.licenseSourceUrl)}${attr("data-smart-license-type", node.attrs?.licenseType)}${attr("data-smart-license-version", node.attrs?.licenseVersion)}${attr("data-smart-license-attribution", node.attrs?.licenseAttribution)}${attr("data-smart-href", node.attrs?.href)}${attr("data-smart-target", node.attrs?.target)}${imageMetadataAttributes(node)}>`;
         // A real <a> wrapper, unlike the live surface renderer's plain data
         // attributes on the bare <img> - see surface/renderer.ts's own
         // reasoning (stable-element-per-id constraint that doesn't apply to
         // this string-based export) and modelDom.ts's identical choice for the
         // one-shot clipboard/print DOM builder.
         const linkHref = sanitizeLinkHref(typeof node.attrs?.href === "string" ? node.attrs.href : undefined);
-        if (!linkHref)
-            return img;
-        const target = sanitizeLinkTarget(typeof node.attrs?.target === "string" ? node.attrs.target : undefined);
-        return `<a href="${escape(linkHref)}"${target ? ` target="${escape(target)}"` : ""}>${img}</a>`;
+        const target = linkHref ? sanitizeLinkTarget(typeof node.attrs?.target === "string" ? node.attrs.target : undefined) : undefined;
+        const linked = linkHref ? `<a href="${escape(linkHref)}"${target ? ` target="${escape(target)}"` : ""}>${img}</a>` : img;
+        // A captioned block image becomes a real <figure>/<figcaption> - the
+        // accessible caption for any static HTML consumer. Every attribute stays
+        // on the <img> itself, so a pre-1.2 parser (which unwraps <figure> as a
+        // transparent container) still reads the image correctly. The link, if
+        // any, wraps only the <img>. data-smart-figure is a debugging marker;
+        // list/formats.ts's parser never depends on it, since third-party
+        // figures don't carry it. Uncaptioned output is unchanged.
+        const caption = node.type === "block_image" && typeof node.attrs?.caption === "string" ? node.attrs.caption : "";
+        return caption ? `<figure data-smart-figure="true">${linked}<figcaption>${escape(caption)}</figcaption></figure>` : linked;
     }
     if (node.type === "formula" || node.type === "block_formula") {
         const tag = node.type === "formula" ? "span" : "div";
@@ -82,7 +99,13 @@ export const atomFromHtmlElement = (rawElement) => {
     // (which still carries every attribute, including data-smart-href,
     // directly) before parsing, matching what a single element's own
     // attributes already fully describe.
-    const element = rawElement.tagName === "A" && rawElement.children.length === 1 ? rawElement.children[0] : rawElement;
+    // A captioned block image exports as <figure>(<a>)<img><figcaption>; the
+    // image element still carries every attribute, so unwrap to it and read
+    // the caption from the figcaption.
+    const figureImage = rawElement.tagName === "FIGURE" ? rawElement.querySelector(":scope > img, :scope > a > img") : null;
+    const figureCaption = figureImage ? normalizeImageCaption(rawElement.querySelector(":scope > figcaption")?.textContent) : undefined;
+    const unwrapped = figureImage || rawElement;
+    const element = unwrapped.tagName === "A" && unwrapped.children.length === 1 ? unwrapped.children[0] : unwrapped;
     const declared = element.getAttribute("data-smart-type");
     const type = declared || (element.tagName === "IMG" ? "image" : element.tagName.toLowerCase());
     const id = element.getAttribute("data-smart-id") || createNodeId();
@@ -105,6 +128,7 @@ export const atomFromHtmlElement = (rawElement) => {
                 ...(element.getAttribute("data-smart-license-type") ? { licenseType: element.getAttribute("data-smart-license-type") } : {}),
                 ...(element.getAttribute("data-smart-license-version") ? { licenseVersion: element.getAttribute("data-smart-license-version") } : {}),
                 ...(element.getAttribute("data-smart-license-attribution") ? { licenseAttribution: element.getAttribute("data-smart-license-attribution") } : {}),
+                ...(type === "block_image" && figureCaption ? { caption: figureCaption } : {}),
             } };
     }
     if (type === "formula" || type === "block_formula") {
@@ -133,9 +157,15 @@ export const atomFromHtmlElement = (rawElement) => {
  * genuinely honest `unsupported`, not a round-trippable format: nothing
  * parses this comment back into a page_break node on import.
  */
+const escapeMarkdownText = (value) => value.replace(/[\\`*_[\]<>]/g, (character) => `\\${character}`);
 export const atomToMarkdown = (node) => {
-    if (node.type === "image" || node.type === "block_image")
-        return `![${String(node.attrs?.alt || "")}](${String(node.attrs?.src || "")})`;
+    if (node.type === "image" || node.type === "block_image") {
+        const image = `![${String(node.attrs?.alt || "")}](${String(node.attrs?.src || "")})`;
+        // Markdown has no caption syntax; an italic line straight after the
+        // image is the common convention. Not parsed back into a caption.
+        const caption = node.type === "block_image" && typeof node.attrs?.caption === "string" ? node.attrs.caption : "";
+        return caption ? `${image}\n*${escapeMarkdownText(caption)}*` : image;
+    }
     if (node.type === "formula" || node.type === "block_formula")
         return node.type === "formula" ? `$${String(node.attrs?.source || "")}$` : `$$\n${String(node.attrs?.source || "")}\n$$`;
     // Media is unsupported in Markdown. Preserve a readable link instead of dropping content.

package/dist/foundation/atom/imageExtras.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Block-image captions and host-defined metadata (1.2.0). Shared by the
+ * schema (shape validation), the HTML parser (normalisation on import), the
+ * exporters and the React insert/edit paths, so every entry point agrees on
+ * what a valid caption or metadata entry is.
+ *
+ * Both are `block_image`-only: a caption under an image that sits inside a
+ * line of text has no layout meaning, and keeping the inline `image` node
+ * unchanged keeps the risk of this feature contained.
+ */
+export declare const IMAGE_CAPTION_MAX_LENGTH = 500;
+export declare const IMAGE_METADATA_MAX_ENTRIES = 10;
+export declare const IMAGE_METADATA_MAX_NAME_LENGTH = 40;
+export declare const IMAGE_METADATA_MAX_VALUE_LENGTH = 500;
+/**
+ * Plain text, control characters stripped, whitespace collapsed to single
+ * spaces, trimmed, capped at IMAGE_CAPTION_MAX_LENGTH. Returns `undefined`
+ * for anything that normalises to empty, so callers delete the attribute
+ * instead of storing `""` (an absent caption must export byte-identically
+ * to a pre-1.2 document).
+ */
+export declare const normalizeImageCaption: (value: unknown) => string | undefined;
+/** Schema check: only an already-normalised, non-empty caption is valid. */
+export declare const isValidImageCaption: (value: unknown) => boolean;
+/** `data-*` in lowercase kebab-case, at most 40 characters, never in the reserved `data-smart-` namespace. */
+export declare const isValidImageMetadataName: (name: unknown) => name is string;
+/**
+ * Schema check for `block_image.attrs.metadata`. Shape only - the schema is
+ * static, so it cannot know a host's allowlist. Allowlist enforcement lives
+ * at the entry points (parser option, insertImage).
+ */
+export declare const isValidImageMetadata: (value: unknown) => boolean;
+export interface ImageMetadataAllowlist {
+    readonly names: readonly string[];
+    readonly rejected: readonly string[];
+}
+/**
+ * Validates a host-supplied `imageMetadataAttributes` list: invalid names
+ * are dropped (reported in `rejected` so the caller can warn), duplicates
+ * collapse, and at most IMAGE_METADATA_MAX_ENTRIES names are kept.
+ */
+export declare const normalizeImageMetadataAllowlist: (names: readonly unknown[] | undefined) => ImageMetadataAllowlist;
+/**
+ * Keeps only allowlisted names with string values, truncating each value to
+ * IMAGE_METADATA_MAX_VALUE_LENGTH. Returns `undefined` when nothing
+ * survives, so the attribute is omitted rather than stored as `{}`.
+ */
+export declare const filterImageMetadata: (read: (name: string) => unknown, allowlist: readonly string[]) => Record<string, string> | undefined;

package/dist/foundation/atom/imageExtras.js

@@ -0,0 +1,88 @@
+/**
+ * Block-image captions and host-defined metadata (1.2.0). Shared by the
+ * schema (shape validation), the HTML parser (normalisation on import), the
+ * exporters and the React insert/edit paths, so every entry point agrees on
+ * what a valid caption or metadata entry is.
+ *
+ * Both are `block_image`-only: a caption under an image that sits inside a
+ * line of text has no layout meaning, and keeping the inline `image` node
+ * unchanged keeps the risk of this feature contained.
+ */
+export const IMAGE_CAPTION_MAX_LENGTH = 500;
+export const IMAGE_METADATA_MAX_ENTRIES = 10;
+export const IMAGE_METADATA_MAX_NAME_LENGTH = 40;
+export const IMAGE_METADATA_MAX_VALUE_LENGTH = 500;
+// C0/C1 control characters other than the whitespace ones collapsed below.
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARACTERS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
+/**
+ * Plain text, control characters stripped, whitespace collapsed to single
+ * spaces, trimmed, capped at IMAGE_CAPTION_MAX_LENGTH. Returns `undefined`
+ * for anything that normalises to empty, so callers delete the attribute
+ * instead of storing `""` (an absent caption must export byte-identically
+ * to a pre-1.2 document).
+ */
+export const normalizeImageCaption = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.replace(CONTROL_CHARACTERS, "").replace(/\s+/g, " ").trim().slice(0, IMAGE_CAPTION_MAX_LENGTH).trim();
+    return normalized || undefined;
+};
+/** Schema check: only an already-normalised, non-empty caption is valid. */
+export const isValidImageCaption = (value) => typeof value === "string" && value.length > 0 && normalizeImageCaption(value) === value;
+const METADATA_NAME = /^data-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** `data-*` in lowercase kebab-case, at most 40 characters, never in the reserved `data-smart-` namespace. */
+export const isValidImageMetadataName = (name) => typeof name === "string" && name.length <= IMAGE_METADATA_MAX_NAME_LENGTH
+    && METADATA_NAME.test(name) && !name.startsWith("data-smart-");
+/**
+ * Schema check for `block_image.attrs.metadata`. Shape only - the schema is
+ * static, so it cannot know a host's allowlist. Allowlist enforcement lives
+ * at the entry points (parser option, insertImage).
+ */
+export const isValidImageMetadata = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const entries = Object.entries(value);
+    return entries.length > 0 && entries.length <= IMAGE_METADATA_MAX_ENTRIES
+        && entries.every(([name, entry]) => isValidImageMetadataName(name)
+            && typeof entry === "string" && entry.length <= IMAGE_METADATA_MAX_VALUE_LENGTH);
+};
+/**
+ * Validates a host-supplied `imageMetadataAttributes` list: invalid names
+ * are dropped (reported in `rejected` so the caller can warn), duplicates
+ * collapse, and at most IMAGE_METADATA_MAX_ENTRIES names are kept.
+ */
+export const normalizeImageMetadataAllowlist = (names) => {
+    const accepted = [];
+    const rejected = [];
+    (names || []).forEach((name) => {
+        if (!isValidImageMetadataName(name)) {
+            rejected.push(String(name));
+            return;
+        }
+        if (accepted.includes(name))
+            return;
+        if (accepted.length >= IMAGE_METADATA_MAX_ENTRIES) {
+            rejected.push(name);
+            return;
+        }
+        accepted.push(name);
+    });
+    return { names: accepted, rejected };
+};
+/**
+ * Keeps only allowlisted names with string values, truncating each value to
+ * IMAGE_METADATA_MAX_VALUE_LENGTH. Returns `undefined` when nothing
+ * survives, so the attribute is omitted rather than stored as `{}`.
+ */
+export const filterImageMetadata = (read, allowlist) => {
+    const output = {};
+    allowlist.forEach((name) => {
+        if (!isValidImageMetadataName(name))
+            return;
+        const value = read(name);
+        if (typeof value === "string")
+            output[name] = value.slice(0, IMAGE_METADATA_MAX_VALUE_LENGTH);
+    });
+    return Object.keys(output).length ? output : undefined;
+};

package/dist/foundation/atom/index.d.ts

@@ -8,3 +8,4 @@ export * from "./persistence.js";
 export * from "./lifecycle.js";
 export * from "./selection.js";
 export * from "./formats.js";
+export * from "./imageExtras.js";

package/dist/foundation/atom/index.js

@@ -8,3 +8,4 @@ export * from "./persistence.js";
 export * from "./lifecycle.js";
 export * from "./selection.js";
 export * from "./formats.js";
+export * from "./imageExtras.js";

package/dist/foundation/atom/schema.js

@@ -1,4 +1,5 @@
 import { normalizeLinkInput } from "../security/urlPolicy.js";
+import { isValidImageCaption, isValidImageMetadata } from "./imageExtras.js";
 const optionalString = { validate: (value) => typeof value === "string" };
 const requiredString = { required: true, validate: (value) => typeof value === "string" };
 const dimension = { validate: (value) => Number.isFinite(value) && Number(value) > 0 && Number(value) <= 100000 };
@@ -36,6 +37,24 @@ const imageAttrs = {
     licenseDescription: optionalString, licenseSourceUrl: optionalString,
     licenseType: optionalString, licenseVersion: optionalString, licenseAttribution: optionalString,
 };
+/**
+ * block_image only (atom/imageExtras.ts explains why the inline `image`
+ * stays unchanged). `caption` is plain text; `metadata` is a host-defined
+ * map of allowlisted `data-*` attributes, shape-checked here and
+ * allowlist-checked at every entry point. Both are absent - never "" or {} -
+ * when unset, so a pre-1.2 document exports byte-identically.
+ */
+const blockImageAttrs = {
+    ...imageAttrs,
+    caption: { validate: isValidImageCaption },
+    metadata: { validate: isValidImageMetadata },
+};
+/** The schema otherwise ignores unknown attributes; these two are explicitly rejected on the inline image so repair() strips them instead of carrying block-only data on an inline node. */
+const inlineImageAttrs = {
+    ...imageAttrs,
+    caption: { validate: () => false },
+    metadata: { validate: () => false },
+};
 const formulaAttrs = {
     source: requiredString,
     notation: { required: true, default: "latex", validate: (value) => value === "latex" || value === "mathml" },
@@ -44,8 +63,8 @@ const formulaAttrs = {
 const mediaAttrs = { src: requiredString, poster: optionalString, width: dimension, height: dimension, status, uploadId: optionalString, error: optionalString };
 /** Inline and block variants are distinct because schema groups are static. */
 export const atomNodeSpecs = [
-    { type: "image", group: "inline", atomic: true, selectable: true, marks: "", attributes: imageAttrs },
-    { type: "block_image", group: "block", atomic: true, selectable: true, marks: "", attributes: imageAttrs },
+    { type: "image", group: "inline", atomic: true, selectable: true, marks: "", attributes: inlineImageAttrs },
+    { type: "block_image", group: "block", atomic: true, selectable: true, marks: "", attributes: blockImageAttrs },
     { type: "formula", group: "inline", atomic: true, selectable: true, marks: "", attributes: formulaAttrs },
     { type: "block_formula", group: "block", atomic: true, selectable: true, marks: "", attributes: formulaAttrs },
     { type: "video", group: "block", atomic: true, selectable: true, marks: "", attributes: mediaAttrs },

package/dist/foundation/clipboard/pipeline.js

@@ -52,7 +52,7 @@ export const parseClipboardPayload = (payload, options) => {
     const normalized = normalizer.normalize(sanitized);
     const parsed = detection.source === "native" && payload.native
         ? parseNativeClipboardDocument(payload.native)
-        : parseCanonicalListHtml(normalized.html);
+        : parseCanonicalListHtml(normalized.html, { imageMetadataAttributes: options.imageMetadataAttributes });
     const repaired = repair({ ...parsed, id: parsed.id || createNodeId() }, options.schema ?? foundationSchema);
     return { source: detection.source, document: repaired.doc, repairs: [...normalized.repairs, ...repaired.repairs] };
 };

package/dist/foundation/clipboard/serialization.js

@@ -6,8 +6,11 @@ const nodeText = (node) => {
         return node.text;
     if (node.type === "hard_break")
         return "\n";
-    if (node.type === "image" || node.type === "block_image")
-        return String(node.attrs?.alt || "");
+    if (node.type === "image" || node.type === "block_image") {
+        const alt = String(node.attrs?.alt || "");
+        const caption = node.type === "block_image" && typeof node.attrs?.caption === "string" ? node.attrs.caption : "";
+        return caption ? (alt ? `${alt} - ${caption}` : caption) : alt;
+    }
     if (node.type === "formula" || node.type === "block_formula")
         return String(node.attrs?.source || "");
     const separator = node.type === "table_cell" ? "\t" : node.type === "paragraph" || node.type === "heading"

package/dist/foundation/clipboard/types.d.ts

@@ -45,6 +45,8 @@ export interface ClipboardRepresentations {
 }
 export interface ClipboardPipelineOptions {
     readonly ownerDocument: Document;
+    /** Passed to parseCanonicalListHtml for HTML payloads. Native SmartRTE fragments keep their stored metadata as-is. */
+    readonly imageMetadataAttributes?: readonly string[];
     readonly normalizers?: readonly SourceNormalizer[];
     /** Test/audit switch proving detection is never required for correctness. */
     readonly normalizerMode?: "detected" | "generic";

package/dist/foundation/formats/docx/export.js

@@ -243,8 +243,18 @@ const blockXml = (block, context, listLevel = 0) => {
     }
     if (block.type === "table")
         return tableXml(block, context);
-    if (block.type === "block_image")
-        return paragraphXml([{ ...block, type: "image" }], block, context);
+    if (block.type === "block_image") {
+        const image = paragraphXml([{ ...block, type: "image" }], block, context);
+        const caption = typeof block.attrs?.caption === "string" ? block.attrs.caption : "";
+        if (!caption)
+            return image;
+        // Word's built-in "Caption" paragraph style, aligned like the image.
+        // This package writes no styles.xml (headings reference Heading1-6 the
+        // same undefined way), so the run also carries the caption look
+        // directly - italic, 9pt - and reads as a caption even where the style
+        // id resolves to Normal.
+        return `${image}<w:p><w:pPr>${paragraphProperties(block, '<w:pStyle w:val="Caption"/>')}</w:pPr><w:r><w:rPr><w:i/><w:sz w:val="18"/></w:rPr><w:t xml:space="preserve">${xmlEscape(caption)}</w:t></w:r></w:p>`;
+    }
     if (block.type === "block_formula")
         return paragraphXml([{ ...block, type: "formula" }], block, context);
     // Previously fell through to the generic fallback below (an empty

package/dist/foundation/formats/fidelity.d.ts

@@ -1,7 +1,7 @@
 import type { FormatFidelityLevel, FormatId } from "./codec.js";
 export type FidelityFormat = FormatId;
 export type FidelityLevel = FormatFidelityLevel;
-export type FidelityFeature = "inline-marks" | "colors-fonts-sizes" | "headings-alignment" | "blockquote-code" | "lists" | "checklists" | "tables" | "links" | "images-media" | "formulas" | "special-characters" | "page-break" | "line-height";
+export type FidelityFeature = "inline-marks" | "colors-fonts-sizes" | "headings-alignment" | "blockquote-code" | "lists" | "checklists" | "tables" | "links" | "images-media" | "formulas" | "special-characters" | "page-break" | "line-height" | "image-captions";
 export interface FormatFidelityCapability {
     level: FidelityLevel;
     note: string;

package/dist/foundation/formats/fidelity.js

@@ -95,7 +95,7 @@ export const builtInFormatFidelity = [
     {
         feature: "images-media",
         formats: {
-            html: capability("semantic", "Images, audio, and video round-trip; host-only metadata may be lossy."),
+            html: capability("semantic", "Images, audio, and video round-trip. Host-defined block-image metadata (`data-*` attributes) is exported as stored, but on import is kept only for names in the `imageMetadataAttributes` allowlist passed to the parser; anything else is dropped."),
             markdown: capability("lossy", "Inline and block images round-trip as ![alt](src) (SS2.3: fixed a real silent-data-loss bug - markdownInlineText/markdownBlock's fallback for any atom node was an empty string, deleting images with no trace; images are now routed through atomToMarkdown/parsed back via a real image AST case). Audio and video degrade to a readable [video: url](url) link on export - the link and URL survive, but re-import produces a generic link, not a video/audio atom."),
             docx: capability("semantic", "Data-URL PNG/JPEG/GIF images embed as native Word media relationships; remote or unsupported sources fall back to a portable text marker recovered on import (SS2.1, re-verified). No canonical DOCX projection exists yet for video/audio (block_image only)."),
             pdf: capability("lossy", "Export is visual; semantic media import is unsupported."),
@@ -137,5 +137,14 @@ export const builtInFormatFidelity = [
             pdf: capability("full", "This package's actual 'Save as PDF' is a real browser print of the same HTML export, so it inherits the html row's real, correctly-spaced layout exactly - verified against the real print document's computed styles, not assumed."),
         },
     },
+    {
+        feature: "image-captions",
+        formats: {
+            html: capability("full", "A captioned block image exports as <figure data-smart-figure=\"true\"><img ...><figcaption>text</figcaption></figure> with every image attribute still on the <img>; any <figure> holding one image plus one <figcaption> (third-party or our own) imports back as one captioned block_image. Uncaptioned images export unchanged. Captions are plain text: marks and links inside an imported figcaption are flattened."),
+            markdown: capability("lossy", "Exported as an italic line directly under the image (`![alt](src)` then `*caption*`). Markdown has no caption syntax, so re-import yields an image followed by an italic paragraph, not a caption."),
+            docx: capability("lossy", "Exported as a paragraph in Word's built-in Caption style (plus direct italic 9pt formatting, since this exporter writes no styles.xml) directly after the image paragraph. DOCX import does not reconstruct the caption: mammoth places images inline inside paragraphs, so the caption returns as an ordinary paragraph."),
+            pdf: capability("full", "'Save as PDF' prints the HTML export, so the <figcaption> prints under the image exactly as in the html row."),
+        },
+    },
 ];
 export const getFormatFidelity = (feature, format) => builtInFormatFidelity.find((entry) => entry.feature === feature).formats[format];

package/dist/foundation/index.d.ts

@@ -28,3 +28,4 @@ export * from "./comments/index.js";
 export * from "./suggestions/index.js";
 export * from "./plugin/index.js";
 export * from "./collab/index.js";
+export * from "./query/index.js";

package/dist/foundation/index.js

@@ -28,3 +28,4 @@ export * from "./comments/index.js";
 export * from "./suggestions/index.js";
 export * from "./plugin/index.js";
 export * from "./collab/index.js";
+export * from "./query/index.js";

package/dist/foundation/list/formats.d.ts

@@ -4,7 +4,18 @@ export declare const serializeCanonicalListHtml: (document: SmartDocument, optio
     fragment?: boolean;
     renderFormulaHtml?: boolean;
 }) => string;
-export declare const parseCanonicalListHtml: (html: string) => SmartDocument;
+export interface ParseCanonicalListHtmlOptions {
+    /**
+     * Host-defined `data-*` attributes to keep from each block image as
+     * `attrs.metadata` (atom/imageExtras.ts). Invalid names are ignored.
+     * Omitted or empty (the default): nothing is collected, exactly as
+     * before this option existed. A host that persists HTML and reloads it
+     * through this function directly must pass the same list it gives the
+     * editor, or the metadata is dropped on that path.
+     */
+    readonly imageMetadataAttributes?: readonly string[];
+}
+export declare const parseCanonicalListHtml: (html: string, options?: ParseCanonicalListHtmlOptions) => SmartDocument;
 /** Alignment and indent are unsupported in Markdown; block content survives semantically. */
 export declare const serializeCanonicalListMarkdown: (document: SmartDocument) => string;
 export declare const parseCanonicalListMarkdown: (markdown: string) => SmartDocument;

package/dist/foundation/list/formats.js

@@ -7,6 +7,7 @@ import { canonicalMarkAttrs, canonicalMarkOrder } from "../marks/canonical.js";
 import { occupancyGridFor } from "../table/grid.js";
 import { atomToHtml, atomToMarkdown } from "../atom/formats.js";
 import { sanitizeAtomSource } from "../atom/security.js";
+import { filterImageMetadata, normalizeImageCaption, normalizeImageMetadataAllowlist } from "../atom/imageExtras.js";
 import { foundationListStyleForPresetDepth, isFoundationSmartListPreset } from "./presets.js";
 const escapeHtml = (value) => String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 const attr = (node, name) => node.attrs?.find((candidate) => candidate.name === name)?.value;
@@ -39,6 +40,14 @@ const imageStyleAndLicenseAttrs = (node) => {
 };
 /** See serializeCanonicalListHtml's own doc comment for why this is a module-scoped flag rather than a threaded parameter. */
 let renderFormulaHtmlMode = false;
+/** parseCanonicalListHtml's `imageMetadataAttributes` option - module-scoped for the same reason as renderFormulaHtmlMode, restored in `finally`. Empty (the default) collects nothing, matching pre-1.2 behaviour. */
+let imageMetadataAllowlist = [];
+const parsedImageMetadata = (node) => {
+    if (!imageMetadataAllowlist.length)
+        return {};
+    const metadata = filterImageMetadata((name) => attr(node, name), imageMetadataAllowlist);
+    return metadata ? { metadata } : {};
+};
 const serializeInline = (node) => {
     if (!isTextNode(node)) {
         if (node.type === "hard_break")
@@ -443,7 +452,14 @@ const parseBlock = (node) => {
                 // third-party block-level image paste, not just this app's own.
                 ...(attr(node, "data-smart-href") ? { href: attr(node, "data-smart-href") } : {}),
                 ...(attr(node, "data-smart-target") ? { target: attr(node, "data-smart-target") } : {}),
+                // atomToHtml has always written data-smart-align for a block image,
+                // but this branch never read it back, so an aligned image lost its
+                // alignment on every HTML save -> reload (docs/bugs/
+                // block-image-align-lost-on-html-reload.md). Same allowed values as
+                // the schema's own align validator.
+                ...(["left", "center", "right"].includes(attr(node, "data-smart-align") || "") ? { align: attr(node, "data-smart-align") } : {}),
                 ...imageStyleAndLicenseAttrs(node),
+                ...parsedImageMetadata(node),
             } };
     }
     if (declaredAtom === "block_formula")
@@ -477,6 +493,7 @@ const parseBlock = (node) => {
             return { type: "block_image", id: generatedId(node, "image"), attrs: {
                     src, alt: attr(node, "alt") || "", status: "ready",
                     ...(width !== null ? { width } : {}), ...(height !== null ? { height } : {}),
+                    ...parsedImageMetadata(node),
                 } };
         }
     }
@@ -712,9 +729,48 @@ const GENERIC_INLINE_TAGS = ["span", "strong", "b", "em", "i", "u", "s", "strike
  * block image - so it's tried as a block first and only folded into the
  * inline run if that doesn't apply.
  */
-const parseMixedBlockContent = (nodes, blockTags) => {
+const isWhitespaceText = (node) => node.nodeName === "#text" && !(node.value || "").trim();
+const isImageSource = (node) => node.tagName === "img"
+    || node.tagName === "a" && elementChildren(node).length === 1 && elementChildren(node)[0].tagName === "img"
+        && (node.childNodes || []).every((child) => child.tagName || isWhitespaceText(child));
+/**
+ * A captioned figure - exactly one image source (`<img>`, `<a><img></a>`, or
+ * this app's own `img[data-smart-type="block_image"]`) plus at most one
+ * `<figcaption>`, in either order, ignoring whitespace - becomes ONE
+ * block_image with `caption`. The image itself goes through parseBlock, so
+ * every existing attribute/width/license rule applies unchanged; the
+ * caption is the figcaption's plain text (marks and links flattened).
+ * Returns null for any other figure shape (several images, a table, no
+ * image, stray text) so the caller falls back to the transparent-container
+ * path. Deliberately does NOT depend on atomToHtml's data-smart-figure
+ * marker - third-party figures never carry it.
+ */
+const parseFigure = (node) => {
+    const significant = (node.childNodes || []).filter((child) => !isWhitespaceText(child) && !isEditorUiNode(child));
+    const images = significant.filter(isImageSource);
+    const captions = significant.filter((child) => child.tagName === "figcaption");
+    if (images.length !== 1 || captions.length > 1 || images.length + captions.length !== significant.length)
+        return null;
+    const image = parseBlock(images[0]);
+    if (!image || image.type !== "block_image")
+        return null;
+    const caption = captions.length ? normalizeImageCaption(rawText(captions[0])) : undefined;
+    return caption ? { ...image, attrs: { ...image.attrs, caption } } : image;
+};
+/** A figcaption that has no image to attach to keeps its text as an ordinary paragraph instead of an "[Unsupported: figcaption]" placeholder. */
+const figcaptionParagraph = (node) => {
+    const children = (node.childNodes || []).flatMap((child) => textWithMarks(child));
+    return children.some((child) => !isTextNode(child) || child.text.trim() !== "")
+        ? { type: "paragraph", id: generatedId(node, "p"), children }
+        : null;
+};
+const parseMixedBlockContent = (nodes, blockTags, insideUnrecognizedFigure = false) => {
     const result = [];
     let inlineRun = [];
+    // Index (in `result`) of a block_image that a directly following
+    // <figcaption> sibling may still attach to - see the figcaption branch
+    // below. Cleared by anything other than whitespace in between.
+    let captionTarget = -1;
     const flushInlineRun = () => {
         if (!inlineRun.length)
             return;
@@ -731,11 +787,16 @@ const parseMixedBlockContent = (nodes, blockTags) => {
         if (hasContent)
             result.push({ type: "paragraph", id: createNodeId(), children });
     };
+    const pushParsed = (parsed) => {
+        if (!parsed)
+            return;
+        result.push(parsed);
+        if (parsed.type === "block_image" && parsed.attrs?.caption === undefined)
+            captionTarget = result.length - 1;
+    };
     const pushBlock = (node) => {
         flushInlineRun();
-        const parsed = parseBlock(node);
-        if (parsed)
-            result.push(parsed);
+        pushParsed(parseBlock(node));
     };
     nodes.forEach((node) => {
         // Matches textWithMarks's own first check - a UI-only element (e.g. a
@@ -746,10 +807,45 @@ const parseMixedBlockContent = (nodes, blockTags) => {
         if (isEditorUiNode(node))
             return;
         const tag = node.tagName;
+        const target = captionTarget;
+        if (!isWhitespaceText(node))
+            captionTarget = -1;
         if (!tag) {
             inlineRun.push(node);
             return;
         }
+        if (tag === "figcaption") {
+            // Legacy repair: before 1.2, a <figure> was unwrapped and its
+            // <figcaption> survived only as a verbatim "unknown" node, so every
+            // save wrote `<img ...><figcaption>...</figcaption>` as loose
+            // siblings (docs/bugs/figure-wrapper-lost-on-save.md). A figcaption
+            // directly after a still-uncaptioned block image (whitespace aside)
+            // is re-attached as that image's caption. Not inside a figure this
+            // parser already declined to treat as one captioned image (e.g. two
+            // images): there the caption describes the whole group, so it stays
+            // a paragraph rather than being pinned to the last image.
+            flushInlineRun();
+            const caption = normalizeImageCaption(rawText(node));
+            const image = target >= 0 && target === result.length - 1 ? result[target] : null;
+            if (!insideUnrecognizedFigure && image?.type === "block_image" && caption) {
+                result[target] = { ...image, attrs: { ...image.attrs, caption } };
+            }
+            else {
+                pushParsed(figcaptionParagraph(node));
+            }
+            return;
+        }
+        if (tag === "figure" && !attr(node, "data-smart-type")) {
+            const figure = parseFigure(node);
+            if (figure) {
+                flushInlineRun();
+                result.push(figure);
+                return;
+            }
+            flushInlineRun();
+            result.push(...parseMixedBlockContent(node.childNodes || [], blockTags, true));
+            return;
+        }
         // A bare third-party <div> (no data-smart-type) is genuinely
         // meaningless wrapping and should be unwrapped - but this app's own
         // round-tripped div-tagged atoms (block_formula, page_break; see
@@ -763,7 +859,7 @@ const parseMixedBlockContent = (nodes, blockTags) => {
         // children back.
         if (TRANSPARENT_CONTAINER_TAGS.includes(tag) && !attr(node, "data-smart-type")) {
             flushInlineRun();
-            result.push(...parseMixedBlockContent(node.childNodes || [], blockTags));
+            result.push(...parseMixedBlockContent(node.childNodes || [], blockTags, insideUnrecognizedFigure));
             return;
         }
         if (blockTags.includes(tag))
@@ -773,7 +869,7 @@ const parseMixedBlockContent = (nodes, blockTags) => {
                 const parsed = parseBlock(node);
                 if (parsed && parsed.type !== "unknown") {
                     flushInlineRun();
-                    result.push(parsed);
+                    pushParsed(parsed);
                     return;
                 }
             }
@@ -785,13 +881,20 @@ const parseMixedBlockContent = (nodes, blockTags) => {
     flushInlineRun();
     return result;
 };
-export const parseCanonicalListHtml = (html) => {
-    const fragment = parseFragment(html);
-    const wrapper = elementChildren(fragment).find((node) => attr(node, "data-smart-document") === "true");
-    const source = wrapper || fragment;
-    const rootBlockTags = ["p", "h1", "h2", "h3", "h4", "h5", "h6", "ul", "ol", "blockquote", "pre", "table", "hr", "img", "video", "audio"];
-    const children = parseMixedBlockContent(source.childNodes || [], rootBlockTags);
-    return { type: "doc", id: attr(source, "data-smart-id") || createNodeId(), children: children.length ? children : [{ type: "paragraph", id: createNodeId(), children: [] }] };
+export const parseCanonicalListHtml = (html, options = {}) => {
+    const previous = imageMetadataAllowlist;
+    imageMetadataAllowlist = normalizeImageMetadataAllowlist(options.imageMetadataAttributes).names;
+    try {
+        const fragment = parseFragment(html);
+        const wrapper = elementChildren(fragment).find((node) => attr(node, "data-smart-document") === "true");
+        const source = wrapper || fragment;
+        const rootBlockTags = ["p", "h1", "h2", "h3", "h4", "h5", "h6", "ul", "ol", "blockquote", "pre", "table", "hr", "img", "video", "audio"];
+        const children = parseMixedBlockContent(source.childNodes || [], rootBlockTags);
+        return { type: "doc", id: attr(source, "data-smart-id") || createNodeId(), children: children.length ? children : [{ type: "paragraph", id: createNodeId(), children: [] }] };
+    }
+    finally {
+        imageMetadataAllowlist = previous;
+    }
 };
 const plainText = (node) => (node.children || []).map((child) => isTextNode(child) ? child.text : child.type === "hard_break" ? "\n" : "").join("");
 const markdownInlineText = (node) => (node.children || []).map((child) => {

package/dist/foundation/modelDom.d.ts

@@ -33,6 +33,18 @@ export declare class FoundationModelDomMapping implements ModelDomMapping {
         node: Node;
         offset: number;
     } | null;
+    /**
+     * Model offsets between block children count model children only; a
+     * renderer projection sitting between blocks (a block image's caption,
+     * a table's caption/colgroup, a checklist control) must not shift them.
+     * Offset k maps to just before the k-th model child. The end offset maps
+     * past the last model child and past any image caption trailing it, so a
+     * caret "after the image" lands below its caption, not between the two.
+     */
+    private blockBoundaryDomOffset;
+    private isImageCaptionProjection;
+    /** A DOM point inside (or on) a block image's caption projection reads as the boundary right after that image. */
+    private captionBoundaryPos;
     domToPos(node: Node, offset: number): SmartPos | null;
     isEditorUiNode(node: Node): boolean;
 }

package/dist/foundation/modelDom.js

@@ -248,7 +248,9 @@ export class FoundationModelDomMapping {
             return null;
         if (!this.isInlineOwner(model)) {
             const children = this.modelDomChildren(element);
-            return pos.offset <= children.length ? { node: element, offset: pos.offset } : null;
+            if (pos.offset > children.length)
+                return null;
+            return { node: element, offset: this.blockBoundaryDomOffset(element, children, pos.offset) };
         }
         let remaining = pos.offset;
         const domChildren = this.modelDomChildren(element);
@@ -284,9 +286,46 @@ export class FoundationModelDomMapping {
             offset: lastModelChild ? [...element.childNodes].indexOf(lastModelChild) + 1 : 0,
         };
     }
+    /**
+     * Model offsets between block children count model children only; a
+     * renderer projection sitting between blocks (a block image's caption,
+     * a table's caption/colgroup, a checklist control) must not shift them.
+     * Offset k maps to just before the k-th model child. The end offset maps
+     * past the last model child and past any image caption trailing it, so a
+     * caret "after the image" lands below its caption, not between the two.
+     */
+    blockBoundaryDomOffset(element, children, offset) {
+        const all = [...element.childNodes];
+        if (offset < children.length)
+            return all.indexOf(children[offset]);
+        if (!children.length)
+            return 0;
+        let index = all.indexOf(children[children.length - 1]) + 1;
+        while (index < all.length && this.isImageCaptionProjection(all[index]))
+            index += 1;
+        return index;
+    }
+    isImageCaptionProjection(node) {
+        return node instanceof Element && node.getAttribute(SMART_PROJECTION_ATTRIBUTE) === "image-caption";
+    }
+    /** A DOM point inside (or on) a block image's caption projection reads as the boundary right after that image. */
+    captionBoundaryPos(node) {
+        const element = node.nodeType === node.ELEMENT_NODE ? node : node.parentElement;
+        const caption = element?.closest(`[${SMART_PROJECTION_ATTRIBUTE}="image-caption"]`);
+        if (!caption || !this.root?.contains(caption))
+            return null;
+        const imageId = caption.getAttribute("data-smart-caption-for");
+        const imagePath = imageId ? this.pathById.get(imageId) : undefined;
+        if (!imagePath?.length)
+            return null;
+        return { path: imagePath.slice(0, -1), offset: imagePath[imagePath.length - 1] + 1 };
+    }
     domToPos(node, offset) {
         if (!this.root || !this.document || this.isEditorUiNode(node))
             return null;
+        const captionPos = this.captionBoundaryPos(node);
+        if (captionPos)
+            return captionPos;
         const owner = this.domToNode(node);
         if (!owner)
             return null;
@@ -298,14 +337,17 @@ export class FoundationModelDomMapping {
         if (!path || !element)
             return null;
         if (!this.isInlineOwner(ownerNode)) {
+            const children = this.modelDomChildren(element);
             if (node !== element) {
                 const direct = node.nodeType === node.ELEMENT_NODE ? node : node.parentElement;
                 const child = direct?.closest(`[${SMART_NODE_ID_ATTRIBUTE}]`);
-                const children = [...element.children].filter((candidate) => !this.isEditorUiNode(candidate));
                 const index = child ? children.indexOf(child) : -1;
                 return index >= 0 ? { path: [...path], offset: index + (offset > 0 ? 1 : 0) } : null;
             }
-            return { path: [...path], offset };
+            // A raw DOM offset counts projections too; count only model children
+            // before it (see blockBoundaryDomOffset for the inverse).
+            const all = [...element.childNodes];
+            return { path: [...path], offset: children.filter((child) => all.indexOf(child) < offset).length };
         }
         if (node === element) {
             const direct = this.modelDomChildren(element);

package/dist/foundation/query/index.d.ts

@@ -0,0 +1 @@
+export * from "./sectionContext.js";

package/dist/foundation/query/index.js

@@ -0,0 +1 @@
+export * from "./sectionContext.js";

package/dist/foundation/query/sectionContext.d.ts

@@ -0,0 +1,41 @@
+import type { SmartDocument, SmartSelection } from "../types.js";
+/**
+ * Read-only document queries for host apps (1.2.0) - "which section is the
+ * cursor in, and what does it say?" and "which images does this document
+ * already have?". Pure functions of (document, selection); the React
+ * runtime's getSectionContext/listImages are thin wrappers over these.
+ */
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export interface SectionContext {
+    /** Nearest top-level heading at or above the cursor, or null when the cursor precedes every heading. */
+    heading: {
+        id: string;
+        level: HeadingLevel;
+        text: string;
+    } | null;
+    /** Plain text from that heading (exclusive) to the next top-level heading of the same or higher level. */
+    text: string;
+    /** True when `text` was cut to `maxChars`. */
+    truncated: boolean;
+}
+export interface SectionContextOptions {
+    /** Default 8000. */
+    maxChars?: number;
+}
+export interface DocumentImageInfo {
+    nodeId: string;
+    src: string;
+    alt: string;
+    caption?: string;
+    metadata?: Record<string, string>;
+}
+export declare const DEFAULT_SECTION_CONTEXT_MAX_CHARS = 8000;
+/**
+ * Only top-level blocks start or end a section; a heading nested inside a
+ * table, list or blockquote is ordinary text of the section it sits in.
+ * With no meaningful cursor (`type: "none"` or an empty path) the start of
+ * the document is used.
+ */
+export declare const getSectionContext: (document: SmartDocument, selection: SmartSelection | null | undefined, options?: SectionContextOptions) => SectionContext;
+/** Every inline `image` and `block_image`, in document order. */
+export declare const listDocumentImages: (document: SmartDocument) => DocumentImageInfo[];

package/dist/foundation/query/sectionContext.js

@@ -0,0 +1,94 @@
+import { isTextNode } from "../identity.js";
+export const DEFAULT_SECTION_CONTEXT_MAX_CHARS = 8000;
+const headingLevel = (node) => {
+    const level = Number(node.attrs?.level);
+    return (Number.isInteger(level) && level >= 1 && level <= 6 ? level : 1);
+};
+const inlineText = (node) => (node.children || []).map((child) => isTextNode(child) ? child.text : child.type === "hard_break" ? "\n" : "").join("");
+/**
+ * Text extraction skips atoms, except that a captioned block image becomes
+ * `[Figure: caption]` so a host sees the figures a section already has.
+ * Tables become tab-separated cells, one row per line.
+ */
+const blockText = (node) => {
+    if (isTextNode(node))
+        return node.text;
+    if (node.type === "paragraph" || node.type === "heading" || node.type === "code_block")
+        return inlineText(node);
+    if (node.type === "block_image") {
+        return typeof node.attrs?.caption === "string" && node.attrs.caption ? `[Figure: ${node.attrs.caption}]` : "";
+    }
+    if (node.type === "table") {
+        return (node.children || []).map((row) => isTextNode(row) ? ""
+            : (row.children || []).map((cell) => isTextNode(cell) ? cell.text : childBlocksText(cell, " ")).join("\t")).join("\n");
+    }
+    if (node.type === "table_cell")
+        return childBlocksText(node, " ");
+    return childBlocksText(node, "\n");
+};
+const childBlocksText = (node, separator) => (node.children || []).map(blockText).filter((text) => text !== "").join(separator);
+/**
+ * Only top-level blocks start or end a section; a heading nested inside a
+ * table, list or blockquote is ordinary text of the section it sits in.
+ * With no meaningful cursor (`type: "none"` or an empty path) the start of
+ * the document is used.
+ */
+export const getSectionContext = (document, selection, options = {}) => {
+    const blocks = document.children;
+    const requested = Number(options.maxChars);
+    const maxChars = Number.isFinite(requested) && requested >= 0 ? Math.floor(requested) : DEFAULT_SECTION_CONTEXT_MAX_CHARS;
+    const cursor = selection && selection.type !== "none" && selection.head.path.length
+        ? Math.min(Math.max(0, selection.head.path[0]), Math.max(0, blocks.length - 1))
+        : 0;
+    let headingIndex = -1;
+    for (let index = cursor; index >= 0; index -= 1) {
+        const block = blocks[index];
+        if (block && !isTextNode(block) && block.type === "heading") {
+            headingIndex = index;
+            break;
+        }
+    }
+    const headingNode = headingIndex >= 0 ? blocks[headingIndex] : null;
+    const level = headingNode ? headingLevel(headingNode) : 6;
+    const parts = [];
+    for (let index = headingIndex + 1; index < blocks.length; index += 1) {
+        const block = blocks[index];
+        // With no heading above the cursor the "section" is the preamble, which
+        // any heading ends.
+        if (!isTextNode(block) && block.type === "heading" && headingLevel(block) <= level)
+            break;
+        const text = blockText(block);
+        if (text !== "")
+            parts.push(text);
+    }
+    const full = parts.join("\n\n");
+    const truncated = full.length > maxChars;
+    return {
+        heading: headingNode ? { id: headingNode.id, level, text: inlineText(headingNode) } : null,
+        text: truncated ? full.slice(0, maxChars) : full,
+        truncated,
+    };
+};
+/** Every inline `image` and `block_image`, in document order. */
+export const listDocumentImages = (document) => {
+    const images = [];
+    const visit = (node) => {
+        if (isTextNode(node))
+            return;
+        if (node.type === "image" || node.type === "block_image") {
+            const caption = typeof node.attrs?.caption === "string" && node.attrs.caption ? node.attrs.caption : undefined;
+            const metadata = node.attrs?.metadata && typeof node.attrs.metadata === "object" && !Array.isArray(node.attrs.metadata)
+                ? { ...node.attrs.metadata } : undefined;
+            images.push({
+                nodeId: node.id,
+                src: String(node.attrs?.src || ""),
+                alt: String(node.attrs?.alt || ""),
+                ...(caption ? { caption } : {}),
+                ...(metadata ? { metadata } : {}),
+            });
+        }
+        node.children?.forEach(visit);
+    };
+    document.children.forEach(visit);
+    return images;
+};

package/dist/foundation/surface/input.js

@@ -511,7 +511,13 @@ export class FoundationInputPipeline {
                 this.renderer.render(this.editor.document, this.editor.selection);
                 return;
             }
-            const target = event.target instanceof Element ? event.target.closest("[data-smart-atomic]") : null;
+            // A block image's caption is a renderer projection after the <img>, not
+            // part of it; clicking the caption selects its image, the same as
+            // clicking the image itself.
+            const caption = event.target instanceof Element ? event.target.closest('[data-smart-projection="image-caption"]') : null;
+            const captionOwner = caption?.getAttribute("data-smart-caption-for");
+            const target = captionOwner ? this.renderer.mapping.nodeToDom(captionOwner)
+                : event.target instanceof Element ? event.target.closest("[data-smart-atomic]") : null;
             const mapped = target ? this.renderer.mapping.domToNode(target) : null;
             if (!mapped || isTextNode(mapped.node) || this.editor.schema.nodes[mapped.node.type]?.selectable !== true)
                 return;
@@ -629,7 +635,7 @@ export class FoundationInputPipeline {
         }
         const payload = this.payloadFromTransfer(event.clipboardData);
         try {
-            const parsed = parseClipboardPayload(payload, { ownerDocument: this.ownerDocument, schema: this.editor.schema });
+            const parsed = parseClipboardPayload(payload, { ownerDocument: this.ownerDocument, schema: this.editor.schema, imageMetadataAttributes: this.options.imageMetadataAttributes });
             this.options.onClipboardDiagnostic?.(reportParsedClipboard(payload, parsed));
             const fragment = remintClipboardFragmentIds(parsed.document, createNodeId);
             const result = insertClipboardFragment(this.editor.document, this.editor.selection, fragment, {
@@ -695,7 +701,7 @@ export class FoundationInputPipeline {
             this.commitClipboard({ ...insertion, operations: [...deletion.operations, ...insertion.operations] }, "drop");
             return;
         }
-        const parsed = parseClipboardPayload(this.payloadFromTransfer(event.dataTransfer), { ownerDocument: this.ownerDocument, schema: this.editor.schema });
+        const parsed = parseClipboardPayload(this.payloadFromTransfer(event.dataTransfer), { ownerDocument: this.ownerDocument, schema: this.editor.schema, imageMetadataAttributes: this.options.imageMetadataAttributes });
         const fragment = remintClipboardFragmentIds(parsed.document, createNodeId);
         const result = insertClipboardFragment(this.editor.document, targetSelection, fragment, {
             schema: this.editor.schema, positions: this.editor.positions, idFactory: createNodeId,

package/dist/foundation/surface/renderer.d.ts

@@ -56,10 +56,30 @@ export declare class FoundationSubtreeRenderer implements CanonicalSubtreeRender
      * must not leave a stale checkbox projection behind.  Reconcile these
      * projections from the current model after every render; attribute writes
      * remain idempotent.
+     *
+     * The same single document walk also collects every captioned block
+     * image for syncImageCaptions, so captions add no second traversal.
      */
     private syncListProjections;
+    /**
+     * A block image's caption is a renderer projection - a non-editable
+     * sibling element placed immediately after the <img>, since an <img> can't
+     * hold children the way <table> holds its caption projection. Projection
+     * elements are already excluded from modelChildren/modelDomChildren, so
+     * the caption never enters the model or the selection mapping.
+     *
+     * diffElement moves, replaces and removes model elements without knowing
+     * about this sibling, so instead of patching every one of those paths this
+     * re-asserts the invariant after each render pass: every captioned image
+     * is followed directly by exactly one caption projection with the current
+     * text, and no other caption projection exists. Reuses (moves) an
+     * existing projection element rather than recreating it.
+     */
+    private syncImageCaptions;
     private announceSelectedLevel;
-    render(document: SmartDocument, selection: SmartSelection): void;
+    render(document: SmartDocument, selection: SmartSelection, options?: {
+        syncDomSelection?: boolean;
+    }): void;
     /**
      * Renderer-integrated content-visibility (Phase 11 Tier 3): the naive
      * per-block experiment (stamping content-visibility:auto on every

package/dist/foundation/surface/renderer.js

@@ -840,12 +840,12 @@ export class FoundationSubtreeRenderer {
         return selection.anchorNode === anchor.node && selection.anchorOffset === anchor.offset
             && selection.focusNode === head.node && selection.focusOffset === head.offset;
     }
-    restoreSelection(model) {
+    restoreSelection(model, syncDom = true) {
         const selection = this.root.ownerDocument.getSelection();
         if (!selection)
             return;
         if (model.type === "none") {
-            if (selection.rangeCount)
+            if (syncDom && selection.rangeCount)
                 selection.removeAllRanges();
             return;
         }
@@ -853,7 +853,7 @@ export class FoundationSubtreeRenderer {
         const head = this.mapping.posToDom(model.head);
         if (!anchor || !head)
             return;
-        if (!this.selectionMatches(selection, anchor, head)) {
+        if (syncDom && !this.selectionMatches(selection, anchor, head)) {
             if (typeof selection.setBaseAndExtent === "function") {
                 selection.setBaseAndExtent(anchor.node, anchor.offset, head.node, head.offset);
             }
@@ -958,8 +958,12 @@ export class FoundationSubtreeRenderer {
      * must not leave a stale checkbox projection behind.  Reconcile these
      * projections from the current model after every render; attribute writes
      * remain idempotent.
+     *
+     * The same single document walk also collects every captioned block
+     * image for syncImageCaptions, so captions add no second traversal.
      */
     syncListProjections(document) {
+        const captions = new Map();
         const visit = (node, listDepth = 0) => {
             if (isTextNode(node))
                 return;
@@ -968,10 +972,76 @@ export class FoundationSubtreeRenderer {
                 if (element)
                     this.syncNodeAttributes(element, node, listDepth);
             }
+            else if (node.type === "block_image" && typeof node.attrs?.caption === "string" && node.attrs.caption) {
+                captions.set(node.id, node);
+            }
             const childListDepth = node.type === "list" ? listDepth + 1 : listDepth;
             node.children?.forEach((child) => visit(child, childListDepth));
         };
         visit(document);
+        this.syncImageCaptions(captions);
+    }
+    /**
+     * A block image's caption is a renderer projection - a non-editable
+     * sibling element placed immediately after the <img>, since an <img> can't
+     * hold children the way <table> holds its caption projection. Projection
+     * elements are already excluded from modelChildren/modelDomChildren, so
+     * the caption never enters the model or the selection mapping.
+     *
+     * diffElement moves, replaces and removes model elements without knowing
+     * about this sibling, so instead of patching every one of those paths this
+     * re-asserts the invariant after each render pass: every captioned image
+     * is followed directly by exactly one caption projection with the current
+     * text, and no other caption projection exists. Reuses (moves) an
+     * existing projection element rather than recreating it.
+     */
+    syncImageCaptions(captions) {
+        const existing = new Map();
+        this.root.querySelectorAll(`[${SMART_PROJECTION_ATTRIBUTE}="image-caption"]`).forEach((element) => {
+            const owner = element.getAttribute("data-smart-caption-for") || "";
+            if (!captions.has(owner) || existing.has(owner)) {
+                element.remove();
+                this.recordWrite(owner);
+            }
+            else
+                existing.set(owner, element);
+        });
+        captions.forEach((node, id) => {
+            const image = this.mapping.nodeToDom(id);
+            if (!image?.parentNode || image === this.root)
+                return;
+            let caption = existing.get(id);
+            if (!caption) {
+                caption = image.ownerDocument.createElement("div");
+                caption.setAttribute(SMART_PROJECTION_ATTRIBUTE, "image-caption");
+                caption.setAttribute("data-smart-caption-for", id);
+                caption.setAttribute("aria-hidden", "true");
+                caption.setAttribute("contenteditable", "false");
+                this.recordWrite(id);
+            }
+            if (image.nextSibling !== caption) {
+                image.after(caption);
+                this.recordWrite(id);
+            }
+            const text = String(node.attrs?.caption);
+            if (caption.textContent !== text) {
+                caption.textContent = text;
+                this.recordWrite(id);
+            }
+            const align = node.attrs?.align === "left" || node.attrs?.align === "center" || node.attrs?.align === "right" ? String(node.attrs.align) : null;
+            if (align)
+                this.setAttribute(caption, "data-smart-align", align, id);
+            else
+                this.removeAttribute(caption, "data-smart-align", id);
+            // Wrap to the image's own width when it has one, so a narrow image
+            // doesn't get a page-wide caption line.
+            const width = Number(node.attrs?.width);
+            const maxWidth = Number.isFinite(width) && width > 0 ? `${width}px` : "";
+            if (caption.style.maxWidth !== maxWidth) {
+                caption.style.maxWidth = maxWidth;
+                this.recordWrite(id);
+            }
+        });
     }
     announceSelectedLevel(before, after, selection) {
         const previous = this.listItemDepths(before);
@@ -1004,7 +1074,8 @@ export class FoundationSubtreeRenderer {
         }
         this.liveRegion.textContent = `List level ${active[1].depth + 1}`;
     }
-    render(document, selection) {
+    render(document, selection, options = {}) {
+        const syncDom = options.syncDomSelection !== false;
         if (!this.current) {
             this.mapping.beginUpdate(document);
             document.children.forEach((node, index) => this.root.appendChild(this.createNode(node, [index])));
@@ -1013,12 +1084,12 @@ export class FoundationSubtreeRenderer {
             this.syncListProjections(document);
             this.syncTableAccessibility();
             this.modelById.set(document.id, document);
-            this.restoreSelection(selection);
+            this.restoreSelection(selection, syncDom);
             this.syncCellSelectionProjection(selection);
             return;
         }
         if (this.current === document) {
-            this.restoreSelection(selection);
+            this.restoreSelection(selection, syncDom);
             this.syncCellSelectionProjection(selection);
             this.syncContentVisibility(document, document, selection);
             return;
@@ -1033,7 +1104,7 @@ export class FoundationSubtreeRenderer {
         this.syncListProjections(document);
         if (structural)
             this.syncTableAccessibility();
-        this.restoreSelection(selection);
+        this.restoreSelection(selection, syncDom);
         this.syncCellSelectionProjection(selection);
         this.syncContentVisibility(before, document, selection);
         this.announceSelectedLevel(before, document, selection);

package/dist/foundation/surface/types.d.ts

@@ -6,7 +6,15 @@ export interface CanonicalSubtreeRenderer {
     readonly composingNodeId: string | null;
     readonly domWriteCount: number;
     readonly composingDomWriteCount: number;
-    render(document: SmartDocument, selection: SmartSelection): void;
+    /**
+     * `syncDomSelection: false` renders and scrolls the selection into view
+     * without moving the browser selection into the editor - setting it
+     * would pull focus out of a host's own UI (e.g. a side panel calling
+     * insertImage). Default true.
+     */
+    render(document: SmartDocument, selection: SmartSelection, options?: {
+        syncDomSelection?: boolean;
+    }): void;
     beginComposition(nodeId: string): void;
     endComposition(): void;
     resetWriteCounters(): void;
@@ -45,4 +53,6 @@ export interface CanonicalInputPipelineOptions {
     onFiles?: (files: readonly File[], position: SmartSelection) => void;
     /** Privacy-safe clipboard telemetry; reports hashes and structure, never text. */
     onClipboardDiagnostic?: (report: ClipboardDiagnosticReport) => void;
+    /** Host-defined `data-*` attributes kept on pasted block images (see parseCanonicalListHtml's option of the same name). Default: none. */
+    imageMetadataAttributes?: readonly string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smartrte-core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Framework-agnostic document model and editing primitives for Smart RTE",
   "repository": {
     "type": "git",
@@ -36,12 +36,6 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build",
-    "test": "vitest run",
-    "lint": "tsc -p tsconfig.json --noEmit"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -63,5 +57,10 @@
   "devDependencies": {
     "typescript": "^5.6.2",
     "vitest": "^2.1.4"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit"
   }
-}
+}