smartrte-react 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.2.0
+
+Additive release; depends on `smartrte-core@1.2.0`.
+
+- **Image captions:** Media details has a new **Caption** field (block images only, after Alt text). The caption shows under the image, and clicking it reopens Media details on that field. Clearing the field removes the caption. Each edit is a single undo step. Content saved by earlier versions as `<img>` followed by a loose `<figcaption>` is repaired into a captioned image on load, and is rewritten as `<figure>` on its first save (see `smartrte-core`'s 1.2.0 entry). Right-clicking an image still opens Media details directly; there's no separate image context menu, so there are no "Add/Edit/Remove caption" menu items.
+- **`insertImage(input, opts)`** on the editor handle, for inserting images from your app (e.g. a side panel). It inserts at the last caret position, using exactly the toolbar insert's placement rules (now shared in `insertion.ts`), or at the end. It does not take focus by default, and returns `{ ok: true, nodeId }` or `{ ok: false, reason: "read_only" | "invalid_image" | "no_valid_position" }` instead of throwing.
+- **`imageMetadataAttributes` prop/runtime option:** an allowlist of host `data-*` attributes kept on block images through loading, paste, file import and `insertImage`. Invalid names are dropped with a development-mode warning. If you call `parseCanonicalListHtml` yourself (e.g. in a `replaceValue` wrapper), pass the same list there.
+- **`getSectionContext()` and `listImages()`** on the editor handle. Both are read-only and allowed in `readOnly` mode.
+- `CanonicalEditorRuntime.setReadOnly()`/`isReadOnly()`; the component keeps it in sync with the `readOnly` prop.
+- `ExecuteOperationsOptions` gains `focus` (default `true`) and `selectNodeId`.
+
+## 1.1.1
+
+- Fix `1.1.0`'s published package listing its `smartrte-core` dependency as the literal string `workspace:^` instead of a real semver range — publishing via plain `npm publish` skips pnpm's workspace-protocol rewrite (that only happens through `pnpm publish`), so any consumer installing `1.1.0` hit `npm error EUNSUPPORTEDPROTOCOL`. No code changes; `1.1.0` should be treated as broken and not installed.
+
 ## 1.1.0
 
 - Right-clicking inside a blockquote now opens a context menu with "Blockquote background colour," "Blockquote text colour," and "Blockquote border options" (style/width/colour for its left border — no per-side toggle, since a blockquote only ever shows one visible side) — previously right-clicking one opened nothing. A table cell nested inside a blockquote still shows cell options, not these. Depends on `smartrte-core@1.1.0`. 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

@@ -17,6 +17,9 @@ It pairs with [`smartrte-core`](https://www.npmjs.com/package/smartrte-core), a
 - [Capability presets](#capability-presets-table-onoff)
 - [Host-owned providers](#host-owned-providers-media-versions-comments-suggestions)
 - [Imperative handle](#imperative-handle-ref)
+- [Image captions](#image-captions)
+- [Inserting images from your app](#inserting-images-from-your-app)
+- [Upgrading to 1.2.0](#upgrading-to-120)
 - [Import & export formats](#import--export-formats)
 - [Theming](#theming)
 - [Standalone / non-React embed](#standalone--non-react-embed)
@@ -88,6 +91,7 @@ The commonly-used `CanonicalAuthorityEditor` props:
 | `authorId` | `string` | `"anonymous"` | Attributed to new comment replies and suggestions. |
 | `renderFormulaHtml` | `boolean` | `false` | Bake real KaTeX-rendered HTML into `onHtmlChange`'s formula markup instead of an empty placeholder — turn this on if you render that HTML anywhere outside the editor (email, PDF export, a read-only view without KaTeX loaded). |
 | `onClipboardDiagnostic` | `(report: ClipboardDiagnosticReport) => void` | `undefined` | Inspect what a paste was parsed as / why it was rejected — useful while debugging a host's own copy sources. |
+| `imageMetadataAttributes` | `string[]` | `[]` | Host-defined `data-*` attributes (e.g. `["data-ai-generated", "data-source"]`) that block images keep through loading, paste, import and `insertImage`, and write back out in HTML. Construction-time only. See [Inserting images from your app](#inserting-images-from-your-app). |
 | `placeholder` | `string` | `undefined` | Placeholder text shown when the editor is empty. |
 | `minHeight` / `maxHeight` | `number \| string` | `undefined` | Editing-surface height bounds. |
 | `readOnly` | `boolean` | `false` | Disables editing; toolbar tools become inert. |
@@ -252,11 +256,96 @@ interface SmartEditorHandle {
   restoreCheckpoint(checkpoint: SmartEditorCheckpoint): void;
   saveVersion(opts?: { label?: string; authorId?: string }): DocumentVersion;
   restoreVersion(version: DocumentVersion, opts?: { keepSelection?: boolean }): void;
+  // 1.2.0
+  insertImage(input: InsertImageInput, opts?: InsertImageOptions): InsertImageResult;
+  getSectionContext(opts?: { maxChars?: number }): SectionContext;
+  listImages(): DocumentImageInfo[];
 }
 ```
 
 `saveVersion`/`restoreVersion` are the same operations the toolbar's Version History panel calls — use them directly if you want your own save-version UI instead of (or alongside) the built-in one.
 
+## Image captions
+
+Any block image can have a plain-text caption. Right-click an image (or use "Edit selected media") to open **Media details** and fill in **Caption**; the caption shows in small muted text under the image, and clicking it reopens Media details on that field. Clear the field to remove the caption. Inline images (inside a line of text) don't take captions.
+
+In saved HTML a captioned image is a standard `<figure>`, with every image attribute still on the `<img>`:
+
+```html
+<figure data-smart-figure="true"><img data-smart-type="block_image" src="…" alt="…"><figcaption>Caption text</figcaption></figure>
+```
+
+Images without a caption are saved exactly as before. Pasting or loading any `<figure>` with one image and a `<figcaption>` (from a web page, a CMS, or SmartRTE itself) gives you a captioned image. Content saved by older versions as a loose `<img>` followed by `<figcaption>` is repaired on load, and the next save writes it back as a `<figure>`. Markdown exports the caption as an italic line under the image, DOCX as a paragraph in Word's Caption style, and plain-text copy as `alt - caption`; see `builtInFormatFidelity` (`image-captions`) for what comes back on import.
+
+## Inserting images from your app
+
+`insertImage` puts an image (optionally captioned) where the user last had the caret — the same place the toolbar's image insert would — without uploading or rewriting `src`, and without taking focus from your own UI unless you ask:
+
+```tsx
+const ref = useRef<SmartEditorHandle>(null);
+
+function onUseFigure(src: string, caption: string) {
+  const result = ref.current?.insertImage(
+    { src, alt: caption, caption, metadata: { "data-ai-generated": "true" } },
+  );
+  if (result && !result.ok) showMessage(result.reason); // "read_only" | "invalid_image" | "no_valid_position"
+}
+
+<CanonicalAuthorityEditor ref={ref} imageMetadataAttributes={["data-ai-generated"]} />
+```
+
+```ts
+interface InsertImageInput {
+  src: string;                 // used as given; must pass the editor's image URL policy
+  alt: string;                 // required unless decorative: true
+  decorative?: boolean;
+  caption?: string;            // plain text, whitespace collapsed, capped at 500 characters
+  width?: number; height?: number;
+  align?: "left" | "center" | "right";
+  metadata?: Record<string, string>;   // only names in imageMetadataAttributes are kept
+}
+interface InsertImageOptions {
+  position?: "selection" | "end";      // default "selection"; falls back to "end" if there's no usable caret
+  focus?: boolean;                     // default false
+}
+type InsertImageResult = { ok: true; nodeId: string } | { ok: false; reason: "read_only" | "invalid_image" | "no_valid_position" };
+```
+
+The insert is one undo step and fires `onChange`/`onHtmlChange` like any edit; the new image is selected afterwards. It returns a result instead of throwing, so you can show a message such as "Unlock the editor to insert" for `read_only`.
+
+**Image metadata.** `imageMetadataAttributes` lists the `data-*` attributes your app wants to attach to images (at most 10; each `data-` + lowercase kebab-case, at most 40 characters, not starting with the reserved `data-smart-`). They round-trip through editing, copy/paste and HTML as plain escaped text and are never shown in the editor UI. If your app parses saved HTML itself with `parseCanonicalListHtml` (from `smartrte-core/foundation`) — for example in a `replaceValue` wrapper — pass the same list there, or metadata is dropped on that path:
+
+```ts
+parseCanonicalListHtml(html, { imageMetadataAttributes: ["data-ai-generated"] });
+```
+
+**Reading context.** For features like "suggest a figure for this section":
+
+```ts
+const { heading, text, truncated } = ref.current!.getSectionContext({ maxChars: 8000 });
+// heading: nearest top-level heading at/above the caret ({ id, level, text }) or null
+// text: that section's plain text; existing figures appear as "[Figure: caption]", tables as tab-separated rows
+const images = ref.current!.listImages(); // [{ nodeId, src, alt, caption?, metadata? }] in document order
+```
+
+Both are read-only and work in `readOnly` mode. The same logic is available without React as `getSectionContext(document, selection)` and `listDocumentImages(document)` from `smartrte-core/foundation`.
+
+## Upgrading to 1.2.0
+
+1.2.0 is additive: no props, handle methods or exports were removed or renamed. Upgrade both packages together, because `smartrte-react@1.2.0` requires `smartrte-core@^1.2.0`.
+
+**What's new**
+- Image captions on block images ([Image captions](#image-captions)).
+- `insertImage`, `getSectionContext` and `listImages` on the editor handle ([Inserting images from your app](#inserting-images-from-your-app)).
+- The `imageMetadataAttributes` prop.
+- New types: `InsertImageInput`, `InsertImageOptions`, `InsertImageResult`, `SectionContext`, `SectionContextOptions` and `DocumentImageInfo` (from `smartrte-react`), and `ParseCanonicalListHtmlOptions` (from `smartrte-core/foundation`).
+
+**On by default: captions.** You don't need to configure anything. Images without a caption save exactly as before, byte for byte. A captioned image saves as `<figure data-smart-figure="true">…<figcaption>…</figcaption></figure>`. If your app renders saved HTML outside the editor, style `figure`/`figcaption` there. One change applies to existing content: HTML saved by earlier versions as `<img>` followed by a loose `<figcaption>` now loads as a captioned image, and the next save rewrites it as a `<figure>`. Stored JSON documents are not repaired; the repair runs only when HTML is parsed.
+
+**Opt-in: image metadata.** `data-*` attributes on images are dropped unless they're listed in `imageMetadataAttributes`, as in 1.1.x. The default is an empty list.
+
+**Caveat: `parseCanonicalListHtml`.** The editor passes the allowlist on every path it owns: initial value, paste, drop, file import and `insertImage`. If your app calls `parseCanonicalListHtml` itself, for example in a `replaceValue` wrapper or server-side, pass `{ imageMetadataAttributes }` there too. Otherwise metadata is silently dropped on that path. Captions need no option there.
+
 ## Import & export formats
 
 The toolbar's "Import" and "Save as ..." tools cover HTML, Markdown, DOCX (Word), PDF, and the package's own JSON document format out of the box — no extra setup. DOCX import preserves real Word styling (fonts, colors, spacing) where possible; PDF export prints the same HTML the editor renders, so formulas, tables, and images all appear as they do live.

package/dist/canonicalEditorRuntime.d.ts

@@ -1,4 +1,4 @@
-import { type CanonicalInputPipeline, type ClipboardDiagnosticReport, type CanonicalSubtreeRenderer, type DocumentVersion, type FoundationEditor, type PersistedEditorDocument, type SmartMark, type SmartOperation, type SmartSelection, type SmartTransaction } from "smartrte-core/foundation";
+import { type CanonicalInputPipeline, type ClipboardDiagnosticReport, type CanonicalSubtreeRenderer, type DocumentImageInfo, type DocumentVersion, type FoundationEditor, type PersistedEditorDocument, type SmartMark, type SmartOperation, type SmartSelection, type SectionContext, type SectionContextOptions, type SmartTransaction } from "smartrte-core/foundation";
 import { type EditorCapabilityPreset } from "./capabilityPresets.js";
 export interface SmartEditorCheckpoint {
     envelope: PersistedEditorDocument;
@@ -27,7 +27,40 @@ export interface SmartEditorHandle {
     restoreVersion(version: DocumentVersion, opts?: {
         keepSelection?: boolean;
     }): void;
+    /** Inserts a block image from the host app (e.g. a side panel) at the last caret position. Never throws for bad input: see InsertImageResult. */
+    insertImage(input: InsertImageInput, opts?: InsertImageOptions): InsertImageResult;
+    /** The section around the last caret position: nearest top-level heading above it and that section's plain text. Allowed in read-only mode. */
+    getSectionContext(opts?: SectionContextOptions): SectionContext;
+    /** Every block and inline image, in document order. */
+    listImages(): DocumentImageInfo[];
 }
+export interface InsertImageInput {
+    /** Used as given - no upload, no data-URL conversion. Must pass the same image URL policy as every other image path. */
+    src: string;
+    /** Required unless `decorative: true`. */
+    alt: string;
+    decorative?: boolean;
+    /** Plain text; normalised (whitespace collapsed) and capped at 500 characters. */
+    caption?: string;
+    width?: number;
+    height?: number;
+    align?: "left" | "center" | "right";
+    /** Filtered by the editor's `imageMetadataAttributes` allowlist; anything else is dropped. */
+    metadata?: Record<string, string>;
+}
+export interface InsertImageOptions {
+    /** "selection" (default) inserts after the block at the last caret position, like the toolbar; "end" appends to the document. */
+    position?: "selection" | "end";
+    /** Default false: the host's own panel keeps focus. */
+    focus?: boolean;
+}
+export type InsertImageResult = {
+    ok: true;
+    nodeId: string;
+} | {
+    ok: false;
+    reason: "read_only" | "invalid_image" | "no_valid_position";
+};
 export interface SaveVersionOptions {
     label?: string;
     authorId?: string;
@@ -40,6 +73,10 @@ export interface ExecuteOperationsOptions {
     /** Put the caret in a newly-created inline owner after the operation. */
     selectionOwnerId?: string;
     selectionOffset?: number;
+    /** Select this (newly inserted) node as a node selection after the operation. */
+    selectNodeId?: string;
+    /** Focus the editor after a history-eligible commit. Default true (the long-standing behaviour); host APIs pass false so the host's panel keeps focus. */
+    focus?: boolean;
 }
 export interface CanonicalEditorRuntimeOptions {
     initialValue?: string | PersistedEditorDocument;
@@ -68,6 +105,15 @@ export interface CanonicalEditorRuntimeOptions {
      * it themselves (e.g. a read-only preview panel built from saved HTML).
      */
     renderFormulaHtml?: boolean;
+    /**
+     * Host-defined `data-*` attributes (e.g. `["data-ai-generated",
+     * "data-source"]`) that block images keep as `attrs.metadata` through
+     * HTML loading, paste and insertImage, and write back out on export.
+     * Names must match `data-[a-z0-9-]+`, may not start with `data-smart-`,
+     * at most 40 characters, at most 10 names; invalid names are dropped with
+     * a development-mode warning. Default: none, so no behaviour changes.
+     */
+    imageMetadataAttributes?: readonly string[];
 }
 /** Persistent, React-independent owner for one product editor instance. */
 export declare class CanonicalEditorRuntime implements SmartEditorHandle {
@@ -84,6 +130,11 @@ export declare class CanonicalEditorRuntime implements SmartEditorHandle {
     private readonly renderFormulaHtml;
     private htmlChangeTimer;
     private pendingHtmlDocument;
+    private readOnly;
+    /** Set only while executeOperations commits with `focus: false` - see the subscribe callback in mount(). */
+    private holdDomSelection;
+    /** The validated `imageMetadataAttributes` allowlist. Hosts that call parseCanonicalListHtml themselves should pass this same list. */
+    readonly imageMetadataAttributes: readonly string[];
     constructor(options?: CanonicalEditorRuntimeOptions);
     setCallbacks(onChange?: (change: SmartEditorChange) => void, onHtmlChange?: (html: string) => void): void;
     private scheduleHtmlChange;
@@ -98,6 +149,14 @@ export declare class CanonicalEditorRuntime implements SmartEditorHandle {
     getRevision(): number;
     focus(): void;
     executeOperations(operations: readonly SmartOperation[], opts?: ExecuteOperationsOptions): void;
+    /** Mirrors the component's `readOnly` prop so host-facing APIs (insertImage) can refuse writes. Does not itself change the editing surface. */
+    setReadOnly(readOnly: boolean): void;
+    isReadOnly(): boolean;
+    insertImage(input: InsertImageInput, opts?: InsertImageOptions): InsertImageResult;
+    /** Builds and validates block_image attrs from host input, or null if they would be invalid. */
+    private imageAttrsFrom;
+    getSectionContext(opts?: SectionContextOptions): SectionContext;
+    listImages(): DocumentImageInfo[];
     createCheckpoint(): SmartEditorCheckpoint;
     restoreCheckpoint(checkpoint: SmartEditorCheckpoint): void;
     /**

package/dist/canonicalEditorRuntime.js

@@ -1,5 +1,10 @@
-import { createFoundationEditor, applyOperations, createInputPipeline, createNodeId, createSubtreeRenderer, createTransactionMap, foundationSchema, isTextNode, parseCanonicalListHtml, serializeCanonicalListHtml, } from "smartrte-core/foundation";
+import { createFoundationEditor, applyOperations, atomDeclarations, filterImageMetadata, getSectionContext as sectionContextOf, listDocumentImages, normalizeImageCaption, normalizeImageMetadataAllowlist, sanitizeAtomSource, createInputPipeline, createNodeId, createSubtreeRenderer, createTransactionMap, foundationSchema, isTextNode, parseCanonicalListHtml, serializeCanonicalListHtml, } from "smartrte-core/foundation";
 import { capabilityPresetRegistry } from "./capabilityPresets.js";
+import { planBlockAtomInsertion } from "./insertion.js";
+const isDevelopment = () => {
+    const global = globalThis;
+    return global.process?.env?.NODE_ENV !== "production";
+};
 const nodeAtPath = (root, path) => {
     let node = root;
     for (const index of path) {
@@ -46,10 +51,10 @@ const firstTextSelection = (document) => {
     const pos = visit(document, []) || { path: [], offset: 0 };
     return { type: "text", anchor: pos, head: pos };
 };
-const envelopeFrom = (value) => {
+const envelopeFrom = (value, imageMetadataAttributes) => {
     if (typeof value === "object" && value)
         return structuredClone(value);
-    const document = parseCanonicalListHtml(typeof value === "string" ? value : "<p></p>");
+    const document = parseCanonicalListHtml(typeof value === "string" ? value : "<p></p>", { imageMetadataAttributes });
     return { schemaVersion: foundationSchema.version, revision: 0, document };
 };
 const sameOperations = (transaction) => transaction.operations.length > 0;
@@ -82,7 +87,15 @@ export class CanonicalEditorRuntime {
         this.unsubscribe = null;
         this.htmlChangeTimer = null;
         this.pendingHtmlDocument = null;
-        const envelope = envelopeFrom(options.initialValue);
+        this.readOnly = false;
+        /** Set only while executeOperations commits with `focus: false` - see the subscribe callback in mount(). */
+        this.holdDomSelection = false;
+        const allowlist = normalizeImageMetadataAllowlist(options.imageMetadataAttributes);
+        if (allowlist.rejected.length && isDevelopment()) {
+            console.warn(`[Smart RTE] imageMetadataAttributes: ignored invalid or excess names: ${allowlist.rejected.join(", ")}. Names must match data-[a-z0-9-]+, must not start with data-smart-, be at most 40 characters, and at most 10 names are kept.`);
+        }
+        this.imageMetadataAttributes = allowlist.names;
+        const envelope = envelopeFrom(options.initialValue, this.imageMetadataAttributes);
         // "full" (the default) intentionally passes no schema/commands/etc., so
         // FoundationEditor's own defaulting (`options.schema || foundationSchema`)
         // applies - every existing consumer who never sets `preset` is
@@ -138,9 +151,12 @@ export class CanonicalEditorRuntime {
         this.unmount();
         this.root = root;
         this.renderer = createSubtreeRenderer(root, { contentVisibility: this.contentVisibility });
-        this.pipeline = createInputPipeline(this.editor, this.renderer, root, { onClipboardDiagnostic: this.onClipboardDiagnostic });
+        this.pipeline = createInputPipeline(this.editor, this.renderer, root, { onClipboardDiagnostic: this.onClipboardDiagnostic, imageMetadataAttributes: this.imageMetadataAttributes });
         this.unsubscribe = this.editor.subscribe((transaction, state) => {
-            this.renderer?.render(this.editor.document, this.editor.selection);
+            // A commit that must not take focus (a host panel calling insertImage)
+            // also must not move the browser selection into the editor: in real
+            // browsers that alone moves focus to the contenteditable.
+            this.renderer?.render(this.editor.document, this.editor.selection, { syncDomSelection: !this.holdDomSelection });
             this.onChange?.({ revision: state.revision, documentChanged: sameOperations(transaction), transaction });
             if (sameOperations(transaction))
                 this.scheduleHtmlChange(state.document);
@@ -211,7 +227,7 @@ export class CanonicalEditorRuntime {
             return;
         const beforeSelection = this.editor.selection;
         let selection = createTransactionMap(operations).mapSelection(beforeSelection);
-        if (opts.selectionOwnerId || opts.preserveSelectionById) {
+        if (opts.selectionOwnerId || opts.preserveSelectionById || opts.selectNodeId) {
             const beforeDocument = this.editor.document;
             const preview = applyOperations(beforeDocument, operations);
             const beforeCellAnchor = beforeSelection.type === "cell" ? cellIdAt(beforeDocument, beforeSelection.anchor) : null;
@@ -240,7 +256,15 @@ export class CanonicalEditorRuntime {
                     return null;
                 return { path, offset: Math.min(forcedId ? opts.selectionOffset ?? 0 : pos.offset, inlineWidth(owner)) };
             };
-            if (preservedCellSelection) {
+            if (opts.selectNodeId) {
+                const path = pathOfNode(preview, opts.selectNodeId);
+                if (path?.length) {
+                    const parentPath = path.slice(0, -1);
+                    const index = path[path.length - 1];
+                    selection = { type: "node", anchor: { path: parentPath, offset: index }, head: { path: parentPath, offset: index + 1 } };
+                }
+            }
+            else if (preservedCellSelection) {
                 // The cell selection was mapped above; do not reinterpret its
                 // structural endpoints as a text selection.
             }
@@ -256,23 +280,88 @@ export class CanonicalEditorRuntime {
                     selection = { ...beforeSelection, anchor, head };
             }
         }
-        this.editor.transact((builder) => {
-            builder.operations.push(...operations);
-            builder.setSelection(selection);
-        }, {
-            source: "toolbar",
-            addToHistory: opts.addToHistory ?? true,
-            ...(opts.historyGroup ? { historyGroup: opts.historyGroup } : {}),
-        });
+        this.holdDomSelection = opts.focus === false;
+        try {
+            this.editor.transact((builder) => {
+                builder.operations.push(...operations);
+                builder.setSelection(selection);
+            }, {
+                source: "toolbar",
+                addToHistory: opts.addToHistory ?? true,
+                ...(opts.historyGroup ? { historyGroup: opts.historyGroup } : {}),
+            });
+        }
+        finally {
+            this.holdDomSelection = false;
+        }
         // Skipped for a non-history (preview) operation: focusing the main
         // editor surface would steal keyboard/pointer focus away from whatever
         // UI is driving the preview (e.g. ColorPickerPopover's native color
         // input mid-drag) on every single preview frame - breaking Escape-to-
         // cancel and, in a real browser, potentially interrupting the drag
         // itself. A real, history-eligible commit still focuses as before.
-        if (opts.addToHistory ?? true)
+        if ((opts.addToHistory ?? true) && opts.focus !== false)
             this.focus();
     }
+    /** Mirrors the component's `readOnly` prop so host-facing APIs (insertImage) can refuse writes. Does not itself change the editing surface. */
+    setReadOnly(readOnly) { this.readOnly = readOnly; }
+    isReadOnly() { return this.readOnly; }
+    insertImage(input, opts = {}) {
+        if (this.readOnly)
+            return { ok: false, reason: "read_only" };
+        const attrs = this.imageAttrsFrom(input);
+        if (!attrs)
+            return { ok: false, reason: "invalid_image" };
+        const nodeId = createNodeId();
+        // An unusable caret position (none yet, or one that can't take a block
+        // here) falls back to appending - still a successful insert.
+        const plan = (opts.position !== "end" ? planBlockAtomInsertion(this.editor, "block_image", attrs, nodeId, "selection") : null)
+            || planBlockAtomInsertion(this.editor, "block_image", attrs, nodeId, "end");
+        if (!plan)
+            return { ok: false, reason: "no_valid_position" };
+        this.executeOperations(plan.operations, { selectNodeId: nodeId, focus: opts.focus === true });
+        return { ok: true, nodeId };
+    }
+    /** Builds and validates block_image attrs from host input, or null if they would be invalid. */
+    imageAttrsFrom(input) {
+        if (!input || typeof input !== "object")
+            return null;
+        const decorative = input.decorative === true;
+        const alt = typeof input.alt === "string" ? input.alt : decorative ? "" : null;
+        const src = typeof input.src === "string" ? sanitizeAtomSource(input.src, { kind: "image" }) : null;
+        if (alt === null || !src)
+            return null;
+        const dimension = (value) => value === undefined || (typeof value === "number" && Number.isFinite(value) && value > 0 && value <= 100000);
+        if (!dimension(input.width) || !dimension(input.height))
+            return null;
+        if (input.align !== undefined && input.align !== "left" && input.align !== "center" && input.align !== "right")
+            return null;
+        const caption = normalizeImageCaption(input.caption);
+        const metadata = input.metadata && typeof input.metadata === "object"
+            ? filterImageMetadata((name) => input.metadata[name], this.imageMetadataAttributes)
+            : undefined;
+        const attrs = {
+            src, alt, status: "ready",
+            ...(decorative ? { decorative: true } : {}),
+            ...(input.width !== undefined ? { width: input.width } : {}),
+            ...(input.height !== undefined ? { height: input.height } : {}),
+            ...(input.align ? { align: input.align } : {}),
+            ...(caption ? { caption } : {}),
+            ...(metadata ? { metadata } : {}),
+        };
+        const spec = this.editor.schema.nodes.block_image;
+        if (!spec)
+            return null;
+        const schemaValid = Object.entries(attrs).every(([name, value]) => spec.attributes?.[name]?.validate?.(value) ?? true);
+        const declaration = atomDeclarations.find((entry) => entry.type === "block_image");
+        return schemaValid && declaration?.validate(attrs) ? attrs : null;
+    }
+    getSectionContext(opts) {
+        return sectionContextOf(this.editor.document, this.editor.selection, opts);
+    }
+    listImages() {
+        return listDocumentImages(this.editor.document);
+    }
     createCheckpoint() {
         return {
             envelope: this.getValue(),

package/dist/components/CanonicalAuthorityEditor.d.ts

@@ -31,6 +31,14 @@ export interface CanonicalAuthorityEditorProps {
      */
     renderFormulaHtml?: boolean;
     onClipboardDiagnostic?: (report: ClipboardDiagnosticReport) => void;
+    /**
+     * Host-defined `data-*` attributes that block images keep as metadata
+     * through loading, paste, file import and `insertImage` - see
+     * canonicalEditorRuntime.ts's CanonicalEditorRuntimeOptions for the
+     * rules. Construction-time only, same contract as `preset`. Default:
+     * none.
+     */
+    imageMetadataAttributes?: readonly string[];
     /** Host-owned upload/search/remove boundary for canonical media insertion. */
     mediaProvider?: MediaProvider;
     /** Replaceable picker; the default only selects a local file. Used for video/audio, and for images when mediaManager is false. */

package/dist/components/CanonicalAuthorityEditor.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
-import { atomDeclarations, continueListNumbering, createList, createNodeId, deleteAtom, executeMarkTool, indentBlockCommand, indentList, inlineToolDeclarations, isTextNode, insertAtom, insertTableColumnCommand, insertTableCommand, insertTableRowCommand, mergeTableCellsCommand, moveListItems, moveTableColumnCommand, moveTableRowCommand, setTableCellAttributesCommand, setTableColumnWidthCommand, setTableRowHeightCommand, parseCanonicalListHtml, parseCanonicalListMarkdown, removeTableColumnCommand, removeTableCommand, removeTableRowCommand, reportMarkApplication, resizeAtom, runAtomUpload, restartListNumbering, serializeCanonicalListHtml, serializeCanonicalListMarkdown, setListChecked, setListPreset, setListStyle, setTableHeaderCommand, setBlockAttributes, setBlockTypeCommand, moveBlockCommand, outdentBlockCommand, splitTableCellCommand, unwrapBlocks, wrapBlocks, unwrapList, updateAtom, outdentList, commentRangeFromSelection, rebaseCommentThreadsThroughTransaction, foundationSchema, resolvePos, suggestDeleteCommand, suggestInsertOperation, acceptSuggestionCommand, rejectSuggestionCommand, structuralSuggestionFromNode, acceptStructuralSuggestionCommand, rebaseStructuralSuggestionsThroughTransaction, } from "smartrte-core/foundation";
+import { atomDeclarations, continueListNumbering, createList, createNodeId, deleteAtom, executeMarkTool, indentBlockCommand, indentList, inlineToolDeclarations, isTextNode, insertAtom, insertTableColumnCommand, insertTableCommand, insertTableRowCommand, mergeTableCellsCommand, moveListItems, moveTableColumnCommand, moveTableRowCommand, normalizeImageCaption, setTableCellAttributesCommand, setTableColumnWidthCommand, setTableRowHeightCommand, parseCanonicalListHtml, parseCanonicalListMarkdown, removeTableColumnCommand, removeTableCommand, removeTableRowCommand, reportMarkApplication, resizeAtom, runAtomUpload, restartListNumbering, serializeCanonicalListHtml, serializeCanonicalListMarkdown, setListChecked, setListPreset, setListStyle, setTableHeaderCommand, setBlockAttributes, setBlockTypeCommand, moveBlockCommand, outdentBlockCommand, splitTableCellCommand, unwrapBlocks, wrapBlocks, unwrapList, updateAtom, outdentList, commentRangeFromSelection, rebaseCommentThreadsThroughTransaction, foundationSchema, resolvePos, suggestDeleteCommand, suggestInsertOperation, acceptSuggestionCommand, rejectSuggestionCommand, structuralSuggestionFromNode, acceptStructuralSuggestionCommand, rebaseStructuralSuggestionsThroughTransaction, } from "smartrte-core/foundation";
 import { FOUNDATION_SMART_LIST_PRESETS as SMART_LIST_PRESETS } from "smartrte-core/foundation";
 import { ensureStyleSheet } from "../theme.js";
 import { VersionHistoryPanel } from "./VersionHistoryPanel.js";
@@ -26,6 +26,7 @@ import { ToolbarButton, ToolbarDropdown, ToolbarGroup, ToolbarMenuItem, MobileMo
 import { resolveToolbarTools } from "../toolbarTools.js";
 import { exportDocxDocument, importStyledDocxDocument, importPdfDocument } from "smartrte-core/foundation";
 import { printSmartDocumentAsPdf } from "../adapters/pdfPrint.js";
+import { planBlockAtomInsertion } from "../insertion.js";
 import { CanonicalEditorRuntime, } from "../canonicalEditorRuntime.js";
 const listSelectionParts = (scope) => {
     if (scope.kind === "list-selection")
@@ -105,7 +106,7 @@ const parseBorderShorthand = (value) => {
 const isCollapsedTextSelection = (selection) => selection.type === "text" && selection.anchor.offset === selection.head.offset
     && selection.anchor.path.length === selection.head.path.length
     && selection.anchor.path.every((part, index) => part === selection.head.path[index]);
-export const CanonicalAuthorityEditor = forwardRef(function CanonicalAuthorityEditor({ defaultValue, preset, renderFormulaHtml, onChange, onHtmlChange, onClipboardDiagnostic, mediaProvider, mediaPicker: MediaPicker = DefaultMediaPicker, mediaManager = true, tools, versionProvider, commentProvider, suggestionProvider, authorId, placeholder = "Type here…", minHeight = 200, maxHeight = 500, readOnly = false, className, onRuntime, }, forwardedRef) {
+export const CanonicalAuthorityEditor = forwardRef(function CanonicalAuthorityEditor({ defaultValue, preset, renderFormulaHtml, onChange, onHtmlChange, onClipboardDiagnostic, imageMetadataAttributes, mediaProvider, mediaPicker: MediaPicker = DefaultMediaPicker, mediaManager = true, tools, versionProvider, commentProvider, suggestionProvider, authorId, placeholder = "Type here…", minHeight = 200, maxHeight = 500, readOnly = false, className, onRuntime, }, forwardedRef) {
     ensureStyleSheet();
     const rootRef = useRef(null);
     const importRef = useRef(null);
@@ -166,10 +167,13 @@ export const CanonicalAuthorityEditor = forwardRef(function CanonicalAuthorityEd
     // selection.head differs from this value.
     const [linkOverlayDismissedAt, setLinkOverlayDismissedAt] = useState(null);
     if (!runtimeRef.current)
-        runtimeRef.current = new CanonicalEditorRuntime({ initialValue: defaultValue, preset, renderFormulaHtml, onChange, onHtmlChange, onClipboardDiagnostic });
+        runtimeRef.current = new CanonicalEditorRuntime({ initialValue: defaultValue, preset, renderFormulaHtml, onChange, onHtmlChange, onClipboardDiagnostic, imageMetadataAttributes });
     const runtime = runtimeRef.current;
     const [, setEditorTick] = useState(0);
     runtime.setCallbacks(onChange, onHtmlChange);
+    // Kept in step on every render (like setCallbacks) so host-facing runtime
+    // APIs such as insertImage refuse writes the moment the prop flips.
+    runtime.setReadOnly(readOnly);
     useImperativeHandle(forwardedRef, () => runtime, [runtime]);
     useEffect(() => {
         const root = rootRef.current;
@@ -1129,70 +1133,12 @@ export const CanonicalAuthorityEditor = forwardRef(function CanonicalAuthorityEd
         root.dispatchEvent(new InputEvent("beforeinput", { inputType: "insertText", data: char, bubbles: true, cancelable: true }));
         runtime.focus();
     };
+    /** Insertion-point rules live in insertion.ts, shared with the host-facing runtime.insertImage. */
     const insertBlockAtom = (type, attrs, nodeId) => {
-        const declaration = atomDeclarations.find((entry) => entry.type === type);
-        const selection = runtime.editor.selection;
-        let parentId;
-        let index;
-        const resolved = runtime.editor.resolve({ pos: selection.head });
-        // A selected atom's own parent is only a legal insertion point for a
-        // *block* atom (image/video/audio/table etc., whose parent is the
-        // document root or a table cell). An inline atom (formula, inline image)
-        // lives inside a paragraph - inserting a block atom there would nest a
-        // block inside a paragraph, which insertAtom's schema validation rejects,
-        // silently no-opping. Fall through to the generic "insert after the
-        // current block" logic below for that case instead.
-        const selectedBlockAtom = (() => {
-            if (selection.type !== "node")
-                return false;
-            const scope = atomScope();
-            const atomType = scope.kind === "atomic-node" ? findNode(runtime.editor.document, scope.nodeId)?.type : undefined;
-            return atomType ? atomDeclarations.find((entry) => entry.type === atomType)?.group === "block" : false;
-        })();
-        if (selection.type === "cell") {
-            // A cell range resolves at the active cell's content boundary. Block
-            // atoms belong inside that cell, never as invalid siblings of the row.
-            parentId = resolved.nodeId;
-            index = resolved.pos.offset;
-        }
-        else if (resolved.kind === "structural" && resolved.pos.path.length === selection.anchor.path.length
-            && resolved.pos.path.every((part, pathIndex) => part === selection.anchor.path[pathIndex])) {
-            // A browser may expose a clicked block atom as a structural text range
-            // (the atom occupies one unit). Keep insertion in that same parent.
-            parentId = resolved.parent.id;
-            index = Math.max(selection.anchor.offset, selection.head.offset);
-        }
-        else if (selectedBlockAtom) {
-            parentId = resolved.parent.id;
-            index = resolved.pos.offset;
-        }
-        else {
-            const location = runtime.editor.positions.positionOf(resolved.nodeId);
-            parentId = location?.parent.id;
-            index = location ? location.pos.offset + 1 : undefined;
-        }
-        if (!parentId || index === undefined)
-            return false;
-        const operations = insertAtom(runtime.editor.document, atomScope(), {
-            declaration, nodeId, parentId, index, attrs,
-        }, blockContext());
-        if (!operations.length)
+        const plan = planBlockAtomInsertion(runtime.editor, type, attrs, nodeId);
+        if (!plan)
             return false;
-        // Block atoms cannot contain a caret. Keep an editable paragraph after a
-        // media node inserted at the end of its container (document root or table
-        // cell), and place the caret there so the next keystroke has a legal owner.
-        const parent = findNode(runtime.editor.document, parentId);
-        const contentRange = runtime.editor.positions.contentRangeOf(parentId);
-        let selectionOwnerId;
-        if (parent?.children && index >= parent.children.length && contentRange) {
-            selectionOwnerId = createNodeId();
-            operations.push({
-                type: "insertNode",
-                pos: { path: [...contentRange.from.path], offset: index + 1 },
-                node: { type: "paragraph", id: selectionOwnerId, children: [] },
-            });
-        }
-        runtime.executeOperations(operations, selectionOwnerId ? { selectionOwnerId, selectionOffset: 0 } : {});
+        runtime.executeOperations(plan.operations, plan.selectionOwnerId ? { selectionOwnerId: plan.selectionOwnerId, selectionOffset: 0 } : {});
         return true;
     };
     const insertMediaFile = async (kind, file) => {
@@ -1438,14 +1384,21 @@ export const CanonicalAuthorityEditor = forwardRef(function CanonicalAuthorityEd
         runtime.focus();
         setLinkPopover(null);
     };
-    const openMediaDetails = (scope, node, element) => {
+    const openMediaDetails = (scope, node, element, focusField) => {
         if (scope.kind !== "atomic-node")
             return;
-        const rect = (element || selectedAtomElement)?.getBoundingClientRect();
+        const anchor = element || selectedAtomElement;
+        // A captioned image's caption sits right under it; open below that, not over it.
+        const caption = anchor?.nextElementSibling?.getAttribute("data-smart-projection") === "image-caption" ? anchor.nextElementSibling : null;
+        const rect = anchor?.getBoundingClientRect();
+        const bottom = caption?.getBoundingClientRect().bottom ?? rect?.bottom;
         setMediaDetailsPopover({
-            x: rect ? rect.left : 0, y: rect ? rect.bottom + 6 : 0, scope,
+            x: rect ? rect.left : 0, y: bottom !== undefined ? bottom + 6 : 0, scope,
+            showCaption: node.type === "block_image",
+            ...(focusField ? { focusField } : {}),
             initial: {
                 alt: String(node.attrs?.alt || ""),
+                caption: typeof node.attrs?.caption === "string" ? node.attrs.caption : "",
                 href: String(node.attrs?.href || ""),
                 openInNewTab: node.attrs?.target === "_blank",
                 width: typeof node.attrs?.width === "number" ? node.attrs.width : undefined,
@@ -1486,7 +1439,7 @@ export const CanonicalAuthorityEditor = forwardRef(function CanonicalAuthorityEd
     const applyMediaDetails = (draft) => {
         if (!mediaDetailsPopover)
             return;
-        const { scope } = mediaDetailsPopover;
+        const { scope, showCaption } = mediaDetailsPopover;
         if (scope.kind !== "atomic-node") {
             setMediaDetailsPopover(null);
             return;
@@ -1504,6 +1457,9 @@ export const CanonicalAuthorityEditor = forwardRef(function CanonicalAuthorityEd
         runtime.executeOperations(updateAtom(runtime.editor.document, scope, {
             attrs: {
                 alt: draft.alt,
+                // Same single updateAtom as every other field, so it's one history
+                // entry and travels through collaboration unchanged. Empty clears it.
+                ...(showCaption ? { caption: normalizeImageCaption(draft.caption) } : {}),
                 href: draft.href || undefined,
                 target: draft.href && draft.openInNewTab ? "_blank" : undefined,
                 width: draft.width ?? currentWidth,
@@ -1541,16 +1497,16 @@ export const CanonicalAuthorityEditor = forwardRef(function CanonicalAuthorityEd
     const runImport = async (file) => {
         if (/\.docx$/i.test(file.name) || file.type === "application/vnd.openxmlformats-officedocument.wordprocessingml.document") {
             const result = await importStyledDocxDocument(await file.arrayBuffer());
-            replaceCanonicalDocument(parseCanonicalListHtml(result.layoutHtml));
+            replaceCanonicalDocument(parseCanonicalListHtml(result.layoutHtml, { imageMetadataAttributes: runtime.imageMetadataAttributes }));
             return;
         }
         if (/\.pdf$/i.test(file.name) || file.type === "application/pdf") {
             const result = await importPdfDocument(await file.arrayBuffer());
-            replaceCanonicalDocument(parseCanonicalListHtml(result.layoutHtml));
+            replaceCanonicalDocument(parseCanonicalListHtml(result.layoutHtml, { imageMetadataAttributes: runtime.imageMetadataAttributes }));
             return;
         }
         const text = await file.text();
-        const document = /\.md(?:own)?$/i.test(file.name) ? parseCanonicalListMarkdown(text) : parseCanonicalListHtml(text);
+        const document = /\.md(?:own)?$/i.test(file.name) ? parseCanonicalListMarkdown(text) : parseCanonicalListHtml(text, { imageMetadataAttributes: runtime.imageMetadataAttributes });
         replaceCanonicalDocument(document);
     };
     const runExport = (format) => {
@@ -1770,7 +1726,7 @@ export const CanonicalAuthorityEditor = forwardRef(function CanonicalAuthorityEd
                 }, onCancel: () => {
                     setTableSizePopover(null);
                     runtime.focus();
-                } }), tableBorderPopover && _jsx(TableBorderPopover, { x: tableBorderPopover.x, y: tableBorderPopover.y, initial: tableBorderPopover.initial, recentColors: recentColors.border, onPreview: previewCellBorder, onApply: applyCellBorderCommit, onCancel: cancelTableBorderPopover }), blockquoteBorderPopover && _jsx(BlockquoteBorderPopover, { x: blockquoteBorderPopover.x, y: blockquoteBorderPopover.y, initial: blockquoteBorderPopover.initial, recentColors: recentColors.border, onPreview: previewBlockquoteBorder, onApply: applyBlockquoteBorderCommit, onCancel: cancelBlockquoteBorderPopover }), mediaDetailsPopover && _jsx(MediaDetailsPopover, { x: mediaDetailsPopover.x, y: mediaDetailsPopover.y, initial: mediaDetailsPopover.initial, onApply: applyMediaDetails, onCancel: () => { setMediaDetailsPopover(null); runtime.focus(); } }), formulaLibraryPopover && _jsx(FormulaLibraryPopover, { x: formulaLibraryPopover.x, y: formulaLibraryPopover.y, onInsert: insertFormulaFromLibrary, onCancel: () => { setFormulaLibraryPopover(null); runtime.focus(); } }), specialCharPopover && _jsx(SpecialCharacterPopover, { x: specialCharPopover.x, y: specialCharPopover.y, recentCharacters: recentSpecialChars, onInsert: insertSpecialCharacter, onCancel: () => { setSpecialCharPopover(null); runtime.focus(); } }), !readOnly && selectedTableElement && _jsx(TableResizeHandles, { tableElement: selectedTableElement, onResizeColumn: resizeTableColumn, onResizeRow: resizeTableRow }), contextMenu && _jsx(ContextMenu, { x: contextMenu.x, y: contextMenu.y, items: resolveContextMenuItems(), onDismiss: () => { setContextMenu(null); runtime.focus(); } }), _jsx("div", { ref: rootRef, className: "srte-editor", "data-placeholder": placeholder, contentEditable: !readOnly, suppressContentEditableWarning: true, role: "textbox", "aria-label": "Smart RTE editing surface", "aria-multiline": "true", onMouseDown: (event) => {
+                } }), tableBorderPopover && _jsx(TableBorderPopover, { x: tableBorderPopover.x, y: tableBorderPopover.y, initial: tableBorderPopover.initial, recentColors: recentColors.border, onPreview: previewCellBorder, onApply: applyCellBorderCommit, onCancel: cancelTableBorderPopover }), blockquoteBorderPopover && _jsx(BlockquoteBorderPopover, { x: blockquoteBorderPopover.x, y: blockquoteBorderPopover.y, initial: blockquoteBorderPopover.initial, recentColors: recentColors.border, onPreview: previewBlockquoteBorder, onApply: applyBlockquoteBorderCommit, onCancel: cancelBlockquoteBorderPopover }), mediaDetailsPopover && _jsx(MediaDetailsPopover, { x: mediaDetailsPopover.x, y: mediaDetailsPopover.y, initial: mediaDetailsPopover.initial, showCaption: mediaDetailsPopover.showCaption, focusField: mediaDetailsPopover.focusField, onApply: applyMediaDetails, onCancel: () => { setMediaDetailsPopover(null); runtime.focus(); } }), formulaLibraryPopover && _jsx(FormulaLibraryPopover, { x: formulaLibraryPopover.x, y: formulaLibraryPopover.y, onInsert: insertFormulaFromLibrary, onCancel: () => { setFormulaLibraryPopover(null); runtime.focus(); } }), specialCharPopover && _jsx(SpecialCharacterPopover, { x: specialCharPopover.x, y: specialCharPopover.y, recentCharacters: recentSpecialChars, onInsert: insertSpecialCharacter, onCancel: () => { setSpecialCharPopover(null); runtime.focus(); } }), !readOnly && selectedTableElement && _jsx(TableResizeHandles, { tableElement: selectedTableElement, onResizeColumn: resizeTableColumn, onResizeRow: resizeTableRow }), contextMenu && _jsx(ContextMenu, { x: contextMenu.x, y: contextMenu.y, items: resolveContextMenuItems(), onDismiss: () => { setContextMenu(null); runtime.focus(); } }), _jsx("div", { ref: rootRef, className: "srte-editor", "data-placeholder": placeholder, contentEditable: !readOnly, suppressContentEditableWarning: true, role: "textbox", "aria-label": "Smart RTE editing surface", "aria-multiline": "true", onMouseDown: (event) => {
                     // A Ctrl/Cmd+click on a link is meant to open it (onClick below),
                     // not move the caret into it - but native mousedown's own default
                     // action *is* the caret-repositioning, and mousedown fires (and
@@ -1802,6 +1758,24 @@ export const CanonicalAuthorityEditor = forwardRef(function CanonicalAuthorityEd
                         window.open(href, "_blank", "noopener,noreferrer");
                         return;
                     }
+                    // Clicking a rendered caption: input.ts has already selected its
+                    // image (the caption is a projection, not part of the model); open
+                    // Media details straight on the Caption field.
+                    const captionTarget = event.target?.closest('[data-smart-projection="image-caption"]');
+                    const captionOwnerId = captionTarget?.getAttribute("data-smart-caption-for");
+                    if (captionOwnerId) {
+                        if (readOnly)
+                            return;
+                        const captionImage = runtime.surface.renderer?.mapping.nodeToDom(captionOwnerId);
+                        const captionNode = findNode(runtime.editor.document, captionOwnerId);
+                        const captionScope = runtime.editor.resolveScope({ want: "atomic-node" });
+                        setMediaContextMenu(null);
+                        if (!captionImage || !captionNode || captionScope.kind !== "atomic-node" || captionScope.nodeId !== captionOwnerId)
+                            return;
+                        setMediaResizeTarget({ nodeId: captionOwnerId });
+                        openMediaDetails(captionScope, captionNode, captionImage, "caption");
+                        return;
+                    }
                     const imageTarget = event.target?.closest("[data-smart-type=\"image\"], [data-smart-type=\"block_image\"]");
                     if (!imageTarget)
                         return;
@@ -1825,7 +1799,10 @@ export const CanonicalAuthorityEditor = forwardRef(function CanonicalAuthorityEd
                     // like right-clicking nothing. Mirrors clickListener's own
                     // atom-selection logic
                     // exactly.
-                    const atomTarget = event.target?.closest("[data-smart-atomic]");
+                    // A right-click on an image's caption projection acts on the image.
+                    const captionOwnerId = event.target?.closest('[data-smart-projection="image-caption"]')?.getAttribute("data-smart-caption-for");
+                    const atomTarget = captionOwnerId ? runtime.surface.renderer?.mapping.nodeToDom(captionOwnerId) ?? null
+                        : event.target?.closest("[data-smart-atomic]");
                     const mapped = atomTarget ? runtime.surface.renderer?.mapping.domToNode(atomTarget) : null;
                     if (mapped && !isTextNode(mapped.node) && runtime.editor.schema.nodes[mapped.node.type]?.selectable === true) {
                         const range = runtime.editor.positions.rangeOf(mapped.nodeId);
@@ -1840,7 +1817,7 @@ export const CanonicalAuthorityEditor = forwardRef(function CanonicalAuthorityEd
                                 const scope = runtime.editor.resolveScope({ want: "atomic-node" });
                                 setMediaResizeTarget({ nodeId: mapped.nodeId });
                                 if (scope.kind === "atomic-node")
-                                    openMediaDetails(scope, mapped.node, atomTarget || undefined);
+                                    openMediaDetails(scope, mapped.node, atomTarget || undefined, captionOwnerId ? "caption" : undefined);
                                 return;
                             }
                             setMediaContextMenu({ x: event.clientX, y: event.clientY, nodeId: mapped.nodeId });

package/dist/components/MediaDetailsPopover.d.ts

@@ -1,6 +1,8 @@
 export type MediaAlign = "left" | "center" | "right" | undefined;
 export interface MediaDetailsDraft {
     alt: string;
+    /** Plain-text caption shown under a block image. Ignored for inline images. */
+    caption: string;
     href: string;
     openInNewTab: boolean;
     width: number | undefined;
@@ -16,6 +18,10 @@ export interface MediaDetailsPopoverProps {
     x: number;
     y: number;
     initial: MediaDetailsDraft;
+    /** Show the Caption field - block images only; a caption under an inline image has no layout meaning. */
+    showCaption?: boolean;
+    /** Field to focus when the panel opens (e.g. from clicking a rendered caption). */
+    focusField?: "caption";
     onApply: (draft: MediaDetailsDraft) => void;
     onCancel: () => void;
 }
@@ -32,4 +38,4 @@ export interface MediaDetailsPopoverProps {
  * is the image editing surface, while resize handles remain available
  * independently around the selected image.
  */
-export declare function MediaDetailsPopover({ x, y, initial, onApply, onCancel }: MediaDetailsPopoverProps): import("react/jsx-runtime").JSX.Element;
+export declare function MediaDetailsPopover({ x, y, initial, showCaption, focusField, onApply, onCancel }: MediaDetailsPopoverProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/MediaDetailsPopover.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { normalizeLinkInput } from "smartrte-core/legacy";
+/** Matches smartrte-core's IMAGE_CAPTION_MAX_LENGTH. */
+const CAPTION_MAX_LENGTH = 500;
 const LICENSE_TYPE_PRESETS = ["CC BY", "CC BY-SA", "CC BY-ND", "CC BY-NC", "CC BY-NC-SA", "CC BY-NC-ND", "CC0 (Public Domain)", "All rights reserved"];
 const inputStyle = {
     width: "100%", height: 34, boxSizing: "border-box", marginTop: 4, padding: "0 9px",
@@ -39,7 +41,7 @@ const alignButton = (current, value, label, onClick) => (_jsx("button", { type:
  * is the image editing surface, while resize handles remain available
  * independently around the selected image.
  */
-export function MediaDetailsPopover({ x, y, initial, onApply, onCancel }) {
+export function MediaDetailsPopover({ x, y, initial, showCaption = false, focusField, onApply, onCancel }) {
     const [draft, setDraft] = useState(initial);
     const [licenseTypeCustom, setLicenseTypeCustom] = useState(!!initial.licenseType && !LICENSE_TYPE_PRESETS.includes(initial.licenseType));
     const [error, setError] = useState("");
@@ -47,6 +49,13 @@ export function MediaDetailsPopover({ x, y, initial, onApply, onCancel }) {
     const [placement, setPlacement] = useState(null);
     const onCancelRef = useRef(onCancel);
     onCancelRef.current = onCancel;
+    const captionInputRef = useRef(null);
+    // Focus only once the panel has been measured and made visible - a
+    // visibility:hidden input can't take focus.
+    useEffect(() => {
+        if (placement && focusField === "caption")
+            captionInputRef.current?.focus();
+    }, [placement !== null, focusField]);
     useLayoutEffect(() => {
         const el = rootRef.current;
         if (!el)
@@ -125,7 +134,7 @@ export function MediaDetailsPopover({ x, y, initial, onApply, onCancel }) {
             display: "flex",
             flexDirection: "column",
             gap: 10,
-        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "center", justifyContent: "space-between" }, children: [_jsx("div", { style: { fontWeight: 650 }, children: "Media details" }), _jsx("button", { type: "button", "aria-label": "Close media details", onClick: onCancel, style: { ...buttonStyle, minWidth: 26, minHeight: 26, padding: 0, border: 0, background: "transparent", fontSize: 18 }, children: "\u00D7" })] }), _jsxs("label", { style: labelStyle, children: ["Alt text", _jsx("input", { "data-srte-media-alt-input": "true", value: draft.alt, onChange: (event) => { update({ alt: event.target.value }); setError(""); }, style: { ...inputStyle, borderColor: error ? "var(--srte-danger)" : "var(--srte-input-border)" } })] }), error && _jsx("div", { role: "alert", style: { color: "var(--srte-danger)", fontSize: 12 }, children: error }), _jsxs("label", { style: labelStyle, children: ["Link", _jsx("input", { "data-srte-media-href-input": "true", value: draft.href, placeholder: "Paste a URL", inputMode: "url", autoCapitalize: "none", autoCorrect: "off", spellCheck: false, onChange: (event) => { update({ href: event.target.value }); setError(""); }, style: { ...inputStyle, borderColor: error ? "var(--srte-danger)" : "var(--srte-input-border)" } })] }), _jsxs("label", { style: { display: "flex", alignItems: "center", gap: 8, fontSize: 13, cursor: "pointer" }, children: [_jsx("input", { "data-srte-media-new-tab-input": "true", type: "checkbox", checked: draft.openInNewTab, disabled: !draft.href.trim(), onChange: (event) => update({ openInNewTab: event.target.checked }) }), "Open in a new tab"] }), _jsxs("div", { style: { display: "flex", gap: 8 }, children: [_jsxs("label", { style: { ...labelStyle, flex: 1 }, children: ["Width (px)", _jsx("input", { "data-srte-media-width-input": "true", type: "number", min: 16, value: draft.width ?? "", onChange: (event) => update({ width: event.target.value === "" ? undefined : Math.max(16, Number(event.target.value)) }), style: inputStyle })] }), _jsxs("label", { style: { ...labelStyle, flex: 1 }, children: ["Corner radius (px)", _jsx("input", { "data-srte-media-radius-input": "true", type: "number", min: 0, value: draft.borderRadius ?? "", onChange: (event) => update({ borderRadius: event.target.value === "" ? undefined : Math.max(0, Number(event.target.value)) }), style: inputStyle })] })] }), _jsxs("div", { style: labelStyle, children: ["Align", _jsxs("div", { style: { display: "flex", gap: 6, marginTop: 4 }, children: [alignButton(draft.align, undefined, "None", () => update({ align: undefined })), alignButton(draft.align, "left", "Left", () => update({ align: "left" })), alignButton(draft.align, "center", "Center", () => update({ align: "center" })), alignButton(draft.align, "right", "Right", () => update({ align: "right" }))] })] }), _jsx("div", { style: sectionHeaderStyle, children: "License" }), _jsxs("label", { style: labelStyle, children: ["Description", _jsx("input", { "data-srte-media-license-description-input": "true", value: draft.licenseDescription, onChange: (event) => update({ licenseDescription: event.target.value }), style: inputStyle })] }), _jsxs("label", { style: labelStyle, children: ["Source URL", _jsx("input", { "data-srte-media-license-source-input": "true", value: draft.licenseSourceUrl, onChange: (event) => update({ licenseSourceUrl: event.target.value }), style: inputStyle })] }), _jsxs("label", { style: labelStyle, children: ["Type", _jsxs("select", { "data-srte-media-license-type-select": "true", value: licenseTypeCustom ? "custom" : draft.licenseType, onChange: (event) => {
+        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "center", justifyContent: "space-between" }, children: [_jsx("div", { style: { fontWeight: 650 }, children: "Media details" }), _jsx("button", { type: "button", "aria-label": "Close media details", onClick: onCancel, style: { ...buttonStyle, minWidth: 26, minHeight: 26, padding: 0, border: 0, background: "transparent", fontSize: 18 }, children: "\u00D7" })] }), _jsxs("label", { style: labelStyle, children: ["Alt text", _jsx("input", { "data-srte-media-alt-input": "true", value: draft.alt, onChange: (event) => { update({ alt: event.target.value }); setError(""); }, style: { ...inputStyle, borderColor: error ? "var(--srte-danger)" : "var(--srte-input-border)" } })] }), error && _jsx("div", { role: "alert", style: { color: "var(--srte-danger)", fontSize: 12 }, children: error }), showCaption && (_jsxs("label", { style: labelStyle, children: ["Caption", _jsx("input", { ref: captionInputRef, "data-srte-media-caption-input": "true", value: draft.caption, maxLength: CAPTION_MAX_LENGTH, "aria-describedby": "srte-media-caption-help", onChange: (event) => update({ caption: event.target.value }), style: inputStyle }), _jsx("span", { id: "srte-media-caption-help", style: { display: "block", marginTop: 4, fontSize: 11, fontWeight: 400, opacity: 0.75 }, children: "Shown under the image. Alt text is read by screen readers." })] })), _jsxs("label", { style: labelStyle, children: ["Link", _jsx("input", { "data-srte-media-href-input": "true", value: draft.href, placeholder: "Paste a URL", inputMode: "url", autoCapitalize: "none", autoCorrect: "off", spellCheck: false, onChange: (event) => { update({ href: event.target.value }); setError(""); }, style: { ...inputStyle, borderColor: error ? "var(--srte-danger)" : "var(--srte-input-border)" } })] }), _jsxs("label", { style: { display: "flex", alignItems: "center", gap: 8, fontSize: 13, cursor: "pointer" }, children: [_jsx("input", { "data-srte-media-new-tab-input": "true", type: "checkbox", checked: draft.openInNewTab, disabled: !draft.href.trim(), onChange: (event) => update({ openInNewTab: event.target.checked }) }), "Open in a new tab"] }), _jsxs("div", { style: { display: "flex", gap: 8 }, children: [_jsxs("label", { style: { ...labelStyle, flex: 1 }, children: ["Width (px)", _jsx("input", { "data-srte-media-width-input": "true", type: "number", min: 16, value: draft.width ?? "", onChange: (event) => update({ width: event.target.value === "" ? undefined : Math.max(16, Number(event.target.value)) }), style: inputStyle })] }), _jsxs("label", { style: { ...labelStyle, flex: 1 }, children: ["Corner radius (px)", _jsx("input", { "data-srte-media-radius-input": "true", type: "number", min: 0, value: draft.borderRadius ?? "", onChange: (event) => update({ borderRadius: event.target.value === "" ? undefined : Math.max(0, Number(event.target.value)) }), style: inputStyle })] })] }), _jsxs("div", { style: labelStyle, children: ["Align", _jsxs("div", { style: { display: "flex", gap: 6, marginTop: 4 }, children: [alignButton(draft.align, undefined, "None", () => update({ align: undefined })), alignButton(draft.align, "left", "Left", () => update({ align: "left" })), alignButton(draft.align, "center", "Center", () => update({ align: "center" })), alignButton(draft.align, "right", "Right", () => update({ align: "right" }))] })] }), _jsx("div", { style: sectionHeaderStyle, children: "License" }), _jsxs("label", { style: labelStyle, children: ["Description", _jsx("input", { "data-srte-media-license-description-input": "true", value: draft.licenseDescription, onChange: (event) => update({ licenseDescription: event.target.value }), style: inputStyle })] }), _jsxs("label", { style: labelStyle, children: ["Source URL", _jsx("input", { "data-srte-media-license-source-input": "true", value: draft.licenseSourceUrl, onChange: (event) => update({ licenseSourceUrl: event.target.value }), style: inputStyle })] }), _jsxs("label", { style: labelStyle, children: ["Type", _jsxs("select", { "data-srte-media-license-type-select": "true", value: licenseTypeCustom ? "custom" : draft.licenseType, onChange: (event) => {
                             if (event.target.value === "custom") {
                                 setLicenseTypeCustom(true);
                                 return;

package/dist/index.d.ts

@@ -6,7 +6,8 @@ export type { EditorCapabilityPreset } from './capabilityPresets.js';
 export type { ToolbarTools } from './toolbarTools.js';
 export { DEFAULT_TOOLBAR_TOOLS, resolveToolbarTools } from './toolbarTools.js';
 export { CanonicalEditorRuntime, createCanonicalEditorRuntime } from './canonicalEditorRuntime.js';
-export type { SmartEditorChange, SmartEditorCheckpoint, SmartEditorHandle } from './canonicalEditorRuntime.js';
+export type { SmartEditorChange, SmartEditorCheckpoint, SmartEditorHandle, InsertImageInput, InsertImageOptions, InsertImageResult } from './canonicalEditorRuntime.js';
+export type { DocumentImageInfo, SectionContext, SectionContextOptions } from 'smartrte-core/foundation';
 export type { MediaManagerAdapter, MediaItem, MediaSearchQuery } from './components/MediaManager.js';
 export type { MediaFilters, MediaKind, MediaProvider, UploadOptions } from './mediaProvider.js';
 export type { VersionListEntry, VersionProvider } from './versionProvider.js';

package/dist/insertion.d.ts

@@ -0,0 +1,22 @@
+import { type FoundationEditor, type SmartOperation } from "smartrte-core/foundation";
+export type BlockAtomType = "block_image" | "video" | "audio" | "divider" | "page_break";
+export interface BlockAtomInsertion {
+    operations: SmartOperation[];
+    /** Set when a trailing paragraph was added (the atom landed at the end of its container): the caret belongs there. */
+    selectionOwnerId?: string;
+}
+/**
+ * Where a block atom goes, shared by the toolbar/media-library insert and the
+ * host-facing `insertImage` API so both behave identically:
+ * - caret inside a paragraph (or any text block) -> after that block;
+ * - a selected block atom -> after it;
+ * - a table cell selection -> inside the cell.
+ * `position: "end"` appends to the document root instead.
+ *
+ * Block atoms cannot hold a caret, so an atom placed at the end of its
+ * container (document root or table cell) is followed by a new empty
+ * paragraph whose id is returned as `selectionOwnerId`.
+ *
+ * Returns null when no legal insertion point exists for that request.
+ */
+export declare const planBlockAtomInsertion: (editor: FoundationEditor, type: BlockAtomType, attrs: Record<string, unknown>, nodeId: string, position?: "selection" | "end") => BlockAtomInsertion | null;

package/dist/insertion.js

@@ -0,0 +1,95 @@
+import { atomDeclarations, createNodeId, insertAtom, isTextNode, } from "smartrte-core/foundation";
+const findNode = (root, id) => {
+    if (isTextNode(root))
+        return null;
+    if (root.id === id)
+        return root;
+    for (const child of root.children || []) {
+        const found = findNode(child, id);
+        if (found)
+            return found;
+    }
+    return null;
+};
+/**
+ * Where a block atom goes, shared by the toolbar/media-library insert and the
+ * host-facing `insertImage` API so both behave identically:
+ * - caret inside a paragraph (or any text block) -> after that block;
+ * - a selected block atom -> after it;
+ * - a table cell selection -> inside the cell.
+ * `position: "end"` appends to the document root instead.
+ *
+ * Block atoms cannot hold a caret, so an atom placed at the end of its
+ * container (document root or table cell) is followed by a new empty
+ * paragraph whose id is returned as `selectionOwnerId`.
+ *
+ * Returns null when no legal insertion point exists for that request.
+ */
+export const planBlockAtomInsertion = (editor, type, attrs, nodeId, position = "selection") => {
+    const declaration = atomDeclarations.find((entry) => entry.type === type);
+    const ctx = { schema: editor.schema, positions: editor.positions };
+    const atomScope = () => editor.resolveScope({ want: "atomic-node" });
+    let parentId;
+    let index;
+    if (position === "end") {
+        parentId = editor.document.id;
+        index = editor.document.children.length;
+    }
+    else {
+        const selection = editor.selection;
+        const resolved = editor.resolve({ pos: selection.head });
+        // A selected atom's own parent is only a legal insertion point for a
+        // *block* atom (image/video/audio/table etc., whose parent is the
+        // document root or a table cell). An inline atom (formula, inline image)
+        // lives inside a paragraph - inserting a block atom there would nest a
+        // block inside a paragraph, which insertAtom's schema validation rejects,
+        // silently no-opping. Fall through to the generic "insert after the
+        // current block" logic below for that case instead.
+        const selectedBlockAtom = (() => {
+            if (selection.type !== "node")
+                return false;
+            const scope = atomScope();
+            const atomType = scope.kind === "atomic-node" ? findNode(editor.document, scope.nodeId)?.type : undefined;
+            return atomType ? atomDeclarations.find((entry) => entry.type === atomType)?.group === "block" : false;
+        })();
+        if (selection.type === "cell") {
+            // A cell range resolves at the active cell's content boundary. Block
+            // atoms belong inside that cell, never as invalid siblings of the row.
+            parentId = resolved.nodeId;
+            index = resolved.pos.offset;
+        }
+        else if (resolved.kind === "structural" && resolved.pos.path.length === selection.anchor.path.length
+            && resolved.pos.path.every((part, pathIndex) => part === selection.anchor.path[pathIndex])) {
+            // A browser may expose a clicked block atom as a structural text range
+            // (the atom occupies one unit). Keep insertion in that same parent.
+            parentId = resolved.parent.id;
+            index = Math.max(selection.anchor.offset, selection.head.offset);
+        }
+        else if (selectedBlockAtom) {
+            parentId = resolved.parent.id;
+            index = resolved.pos.offset;
+        }
+        else {
+            const location = editor.positions.positionOf(resolved.nodeId);
+            parentId = location?.parent.id;
+            index = location ? location.pos.offset + 1 : undefined;
+        }
+    }
+    if (!parentId || index === undefined)
+        return null;
+    const operations = insertAtom(editor.document, atomScope(), { declaration, nodeId, parentId, index, attrs }, ctx);
+    if (!operations.length)
+        return null;
+    const parent = findNode(editor.document, parentId);
+    const contentRange = editor.positions.contentRangeOf(parentId);
+    if (parent?.children && index >= parent.children.length && contentRange) {
+        const selectionOwnerId = createNodeId();
+        operations.push({
+            type: "insertNode",
+            pos: { path: [...contentRange.from.path], offset: index + 1 },
+            node: { type: "paragraph", id: selectionOwnerId, children: [] },
+        });
+        return { operations, selectionOwnerId };
+    }
+    return { operations };
+};

package/dist/theme.d.ts

@@ -1,3 +1,3 @@
 export type SrteTheme = 'light' | 'dark';
-export declare const SRTE_DEFAULT_CSS = "\n.srte-editor {\n  --srte-background: var(--card, #ffffff);\n  --srte-canvas: var(--background, #ffffff);\n  --srte-foreground: var(--foreground, #0f172a);\n  --srte-muted: var(--muted, #f1f5f9);\n  --srte-muted-foreground: var(--muted-foreground, #64748b);\n  --srte-ring: var(--ring, #0284c7);\n  --srte-radius: var(--radius, 0.625rem);\n  --srte-bg: var(--srte-canvas);\n  --srte-text: var(--srte-foreground);\n  --srte-text-muted: var(--srte-muted-foreground);\n  --srte-border: var(--border, #e2e8f0);\n  --srte-border-light: var(--srte-border);\n  --srte-toolbar-bg: var(--srte-background);\n  --srte-input-bg: var(--srte-background);\n  --srte-input-text: var(--srte-foreground);\n  --srte-input-border: var(--srte-border);\n  --srte-modal-backdrop: rgba(0, 0, 0, 0.35);\n  --srte-modal-backdrop-filter: blur(2px);\n  --srte-modal-bg: var(--card, #ffffff);\n  --srte-modal-text: var(--foreground, #000000);\n  --srte-menu-bg: var(--srte-background);\n  --srte-menu-text: var(--srte-foreground);\n  --srte-menu-shadow: 0 8px 24px rgba(0, 0, 0, 0.18);\n  --srte-accent: #0284c7;\n  --srte-accent-bg: rgba(2, 132, 199, 0.12);\n  --srte-danger: #dc2626;\n  --srte-primary: #2563eb;\n  /* --srte-primary on --srte-accent-bg measures 4.43:1, under WCAG AA's\n     4.5:1 for normal text - used only for the pressed toolbar-button state\n     (see .srte-tool-button[aria-pressed=\"true\"]), not a replacement for\n     --srte-primary generally. */\n  --srte-primary-pressed: #1d4ed8;\n  --srte-on-primary: #ffffff;\n  --srte-cancel-bg: #f3f4f6;\n  --srte-code-bg: #f6f8fa;\n  --srte-code-text: #24292f;\n}\n.srte-editor.srte-dark {\n  --srte-background: var(--card, #1e293b);\n  --srte-canvas: var(--background, #0f172a);\n  --srte-foreground: var(--foreground, #f8fafc);\n  --srte-muted: var(--muted, #334155);\n  --srte-muted-foreground: var(--muted-foreground, #94a3b8);\n  --srte-ring: var(--ring, #38bdf8);\n  --srte-bg: var(--srte-canvas);\n  --srte-text: var(--srte-foreground);\n  --srte-text-muted: var(--srte-muted-foreground);\n  --srte-border: var(--border, #334155);\n  --srte-border-light: var(--srte-border);\n  --srte-toolbar-bg: var(--srte-background);\n  --srte-input-bg: var(--srte-background);\n  --srte-input-text: var(--srte-foreground);\n  --srte-input-border: var(--srte-border);\n  --srte-modal-backdrop: rgba(0, 0, 0, 0.22);\n  --srte-modal-backdrop-filter: blur(10px) saturate(0.9);\n  --srte-modal-bg: var(--card, #1e293b);\n  --srte-modal-text: var(--foreground, #e0e0e0);\n  --srte-menu-bg: var(--srte-background);\n  --srte-menu-text: var(--srte-foreground);\n  --srte-menu-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);\n  --srte-accent: #38bdf8;\n  --srte-accent-bg: rgba(56, 189, 248, 0.16);\n  --srte-danger: #ef4444;\n  --srte-primary: #3b82f6;\n  --srte-primary-pressed: var(--srte-primary);\n  --srte-on-primary: #ffffff;\n  --srte-cancel-bg: #333333;\n  --srte-code-bg: #111827;\n  --srte-code-text: #e5e7eb;\n}\n.srte-editor {\n  border-radius: var(--srte-radius);\n  font-family: \"IBM Plex Sans\", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif;\n  container: srte-editor / inline-size;\n}\n.srte-canonical-authority > .srte-editor[contenteditable] {\n  width: 100%;\n  padding: 16px 20px;\n  box-sizing: border-box;\n  border: 1px solid var(--srte-border);\n  border-radius: 0 0 var(--srte-radius) var(--srte-radius);\n  outline: none;\n  background: var(--srte-canvas);\n  color: var(--srte-foreground);\n  caret-color: var(--srte-foreground);\n  line-height: 1.6;\n}\n.srte-toolbar {\n  display: flex;\n  flex-wrap: wrap;\n  align-items: center;\n  gap: 4px;\n  width: 100%;\n  min-height: 48px;\n  padding: 8px;\n  box-sizing: border-box;\n  border-bottom: 1px solid var(--srte-border);\n  background: var(--srte-background);\n  color: var(--srte-foreground);\n  position: sticky;\n  top: 0;\n  z-index: 10;\n}\n.srte-toolbar-group {\n  display: inline-flex;\n  align-items: center;\n  gap: 2px;\n  min-width: 0;\n}\n.srte-toolbar-group + .srte-toolbar-group::before {\n  content: \"\";\n  width: 1px;\n  height: 20px;\n  margin: 0 5px 0 3px;\n  background: var(--srte-border);\n}\n.srte-tool-button,\n.srte-toolbar select {\n  height: 32px;\n  min-width: 32px;\n  box-sizing: border-box;\n  border: 1px solid transparent;\n  border-radius: 8px;\n  background: transparent;\n  color: var(--srte-foreground);\n  font: 500 13px/1 \"IBM Plex Sans\", ui-sans-serif, system-ui, sans-serif;\n}\n.srte-tool-button {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  gap: 3px;\n  padding: 0 7px;\n  cursor: pointer;\n}\n.srte-toolbar select {\n  max-width: 132px;\n  padding: 0 26px 0 9px;\n  border-color: var(--srte-border);\n  background: var(--srte-input-bg);\n  cursor: pointer;\n}\n.srte-tool-button:hover,\n.srte-toolbar select:hover,\n.srte-toolbar-menu[open] > .srte-menu-trigger {\n  background: var(--srte-muted);\n  border-color: var(--srte-border);\n}\n.srte-tool-button.srte-active,\n.srte-tool-button[aria-pressed=\"true\"] {\n  /* var(--srte-primary) (#2563eb) on var(--srte-accent-bg) measured 4.43:1,\n     just under WCAG AA's 4.5:1 for normal text (axe-core, Phase 11 Tier 3) -\n     a dedicated, darker pressed-state color keeps the same hue family\n     while clearing the threshold, without changing --srte-primary's other,\n     already-compliant usages (e.g. against solid backgrounds). */\n  color: var(--srte-primary-pressed);\n  background: var(--srte-accent-bg);\n  border-color: color-mix(in srgb, var(--srte-primary) 35%, transparent);\n}\n.srte-tool-button:focus-visible,\n.srte-toolbar select:focus-visible,\n.srte-menu-item:focus-visible {\n  outline: 2px solid var(--srte-ring);\n  outline-offset: 1px;\n}\n.srte-tool-button:disabled,\n.srte-menu-item:disabled,\n.srte-toolbar select:disabled {\n  cursor: not-allowed;\n  opacity: .4;\n}\n.srte-toolbar-menu {\n  position: relative;\n}\n.srte-toolbar-menu > summary {\n  list-style: none;\n}\n.srte-toolbar-menu > summary::-webkit-details-marker {\n  display: none;\n}\n.srte-menu {\n  position: absolute;\n  top: calc(100% + 6px);\n  left: 0;\n  z-index: 80;\n  min-width: 210px;\n  padding: 4px;\n  overflow: hidden;\n  border: 1px solid var(--srte-border);\n  border-radius: 12px;\n  background: var(--srte-menu-bg);\n  color: var(--srte-menu-text);\n  box-shadow: var(--srte-menu-shadow);\n}\n/*\n * ToolbarDropdown's own menu panel (docs/bugs/\n * toolbar-dropdown-clipped-by-host-overflow-hidden.md): position:fixed with\n * JS-measured left/top (ToolbarPrimitives.tsx) instead of the default\n * position:absolute above, so it always escapes an ancestor host container's\n * own overflow:hidden regardless of DOM depth - MobileMoreMenu's overflow\n * menu (no data-srte-menu-fixed attribute) is unaffected and keeps its\n * existing position:absolute/right-anchored behavior.\n */\n.srte-menu[data-srte-menu-fixed=\"true\"] {\n  position: fixed;\n  top: 0;\n  left: 0;\n}\n.srte-menu-item {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  width: 100%;\n  height: 36px;\n  padding: 0 8px;\n  border: 0;\n  border-radius: 8px;\n  background: transparent;\n  color: inherit;\n  cursor: pointer;\n  font: 500 13px/1 \"IBM Plex Sans\", ui-sans-serif, system-ui, sans-serif;\n  text-align: left;\n  white-space: nowrap;\n}\n.srte-menu-item:hover {\n  background: var(--srte-muted);\n}\n.srte-menu-check {\n  margin-left: auto;\n  color: var(--srte-primary);\n  font-weight: 700;\n}\n.srte-menu-separator {\n  height: 1px;\n  margin: 4px;\n  background: var(--srte-border);\n}\n.srte-mobile-more { display: none; }\n.srte-toolbar .srte-command-proxy { display: none; }\n.srte-split-control {\n  display: inline-flex;\n}\n.srte-split-control > .srte-tool-button:first-child {\n  border-radius: 8px 0 0 8px;\n}\n.srte-split-control > select {\n  width: 27px;\n  padding: 0;\n  border-radius: 0 8px 8px 0;\n  border-left: 0;\n  appearance: none;\n  -webkit-appearance: none;\n  color: transparent;\n  background-color: var(--srte-muted);\n  background-image: url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='14' height='14' viewBox='0 0 24 24' fill='none' stroke='%2364748b' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m7 10 5 5 5-5'/%3E%3C/svg%3E\");\n  background-repeat: no-repeat;\n  background-position: center;\n  cursor: pointer;\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li {\n  display: grid;\n  grid-template-columns: 1.1em minmax(0, 1fr);\n  column-gap: .45em;\n  align-items: start;\n  padding-left: 0;\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal-paren\"][data-srte-list-depth=\"0\"] > li::marker {\n  content: counter(list-item, decimal) \")  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal-paren\"][data-srte-list-depth=\"1\"] > li::marker {\n  content: counter(list-item, lower-alpha) \")  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal-paren\"][data-srte-list-depth=\"2\"] > li::marker,\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal-paren\"][data-srte-list-depth=\"3\"] > li::marker {\n  content: counter(list-item, lower-roman) \")  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal\"][data-srte-list-depth=\"0\"] > li::marker {\n  content: counter(list-item, decimal) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal\"][data-srte-list-depth=\"1\"] > li::marker {\n  content: counter(list-item, lower-alpha) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal\"][data-srte-list-depth=\"2\"] > li::marker,\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal\"][data-srte-list-depth=\"3\"] > li::marker {\n  content: counter(list-item, lower-roman) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-alpha\"][data-srte-list-depth=\"0\"] > li::marker {\n  content: counter(list-item, upper-alpha) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-alpha\"][data-srte-list-depth=\"1\"] > li::marker {\n  content: counter(list-item, lower-alpha) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-alpha\"][data-srte-list-depth=\"2\"] > li::marker,\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-alpha\"][data-srte-list-depth=\"3\"] > li::marker {\n  content: counter(list-item, lower-roman) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-roman\"][data-srte-list-depth=\"0\"] > li::marker {\n  content: counter(list-item, upper-roman) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-roman\"][data-srte-list-depth=\"1\"] > li::marker {\n  content: counter(list-item, upper-alpha) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-roman\"][data-srte-list-depth=\"2\"] > li::marker,\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-roman\"][data-srte-list-depth=\"3\"] > li::marker {\n  content: counter(list-item, decimal) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-leading-zero\"][data-srte-list-depth=\"0\"] > li::marker {\n  content: counter(list-item, decimal-leading-zero) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-leading-zero\"][data-srte-list-depth=\"1\"] > li::marker {\n  content: counter(list-item, lower-alpha) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-leading-zero\"][data-srte-list-depth=\"2\"] > li::marker,\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-leading-zero\"][data-srte-list-depth=\"3\"] > li::marker {\n  content: counter(list-item, lower-roman) \".  \";\n}\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-disc\"][data-srte-list-depth=\"0\"] > li::marker {\n  content: \"\u25CF  \";\n}\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-disc\"][data-srte-list-depth=\"1\"] > li::marker {\n  content: \"\u25CB  \";\n}\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-disc\"][data-srte-list-depth=\"2\"] > li::marker,\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-disc\"][data-srte-list-depth=\"3\"] > li::marker {\n  content: \"\u25A0  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-outline\"] > li::marker {\n  content: counters(list-item, \".\") \".  \";\n}\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-diamond\"][data-srte-list-depth=\"0\"] > li::marker { content: \"\u2756  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-diamond\"][data-srte-list-depth=\"1\"] > li::marker { content: \"\u27A2  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-diamond\"][data-srte-list-depth=\"2\"] > li::marker { content: \"\u25A0  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-square\"][data-srte-list-depth=\"0\"] > li::marker { content: \"\u25A1  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-square\"][data-srte-list-depth=\"1\"] > li::marker { content: \"\u25A3  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-square\"][data-srte-list-depth=\"2\"] > li::marker { content: \"\u25AA  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-arrow\"][data-srte-list-depth=\"0\"] > li::marker { content: \"\u279C  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-arrow\"][data-srte-list-depth=\"1\"] > li::marker { content: \"\u25C6  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-arrow\"][data-srte-list-depth=\"2\"] > li::marker { content: \"\u25CF  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-star\"][data-srte-list-depth=\"0\"] > li::marker { content: \"\u2605  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-star\"][data-srte-list-depth=\"1\"] > li::marker { content: \"\u25CB  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-star\"][data-srte-list-depth=\"2\"] > li::marker { content: \"\u25A0  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-arrow-circle\"][data-srte-list-depth=\"0\"] > li::marker { content: \"\u27A2  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-arrow-circle\"][data-srte-list-depth=\"1\"] > li::marker { content: \"\u25CB  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-arrow-circle\"][data-srte-list-depth=\"2\"] > li::marker { content: \"\u25A0  \"; }\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > [data-srte-check] {\n  display: inline-flex;\n  grid-column: 1;\n  grid-row: 1;\n  align-items: center;\n  justify-content: center;\n  width: 1.1em;\n  height: 1.6em;\n  min-width: 0;\n  box-sizing: border-box;\n  padding: 0;\n  border: 0;\n  border-radius: 0;\n  background: transparent;\n  color: inherit;\n  font: inherit;\n  cursor: pointer;\n  appearance: none;\n  outline: none;\n  margin: 0;\n  line-height: 1.6;\n  vertical-align: top;\n  position: relative;\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > [data-srte-check]:focus-visible {\n  outline: 2px solid var(--srte-ring);\n  outline-offset: 2px;\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > [data-srte-check]::before {\n  content: \"\";\n  width: .9em;\n  height: .9em;\n  box-sizing: border-box;\n  border: 1.5px solid var(--srte-muted-foreground);\n  border-radius: 3px;\n  background: var(--srte-canvas);\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > [data-srte-check][data-checked=\"true\"]::before {\n  border-color: var(--srte-primary);\n  background: var(--srte-primary);\n  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--srte-on-primary) 25%, transparent);\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > [data-srte-check][data-checked=\"true\"]::after {\n  content: \"\";\n  position: absolute;\n  width: .42em;\n  height: .22em;\n  border-left: 1.5px solid var(--srte-on-primary);\n  border-bottom: 1.5px solid var(--srte-on-primary);\n  transform: translateY(-.08em) rotate(-45deg);\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > :is(p,h1,h2,h3,h4,h5,h6,blockquote,pre) {\n  grid-column: 2;\n  min-width: 0;\n  margin-top: 0;\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > :is(ul,ol) {\n  grid-column: 2;\n}\n.srte-editor:focus-within {\n  border-color: var(--srte-ring) !important;\n  box-shadow: 0 0 0 2px color-mix(in srgb, var(--srte-ring) 18%, transparent);\n}\n/*\n * @container (element width), not @media (viewport width): a host can embed\n * the editor at any fraction of the browser window - a split pane next to a\n * preview panel is the case that surfaced this (docs/bugs/\n * toolbar-wide-promotion-fires-on-viewport-width-not-container-width.md). A\n * plain @media breakpoint here would fire based on the *window*, wrongly\n * switching tiers for an editor instance that's actually much narrower (or\n * wider) than the window - .srte-editor already establishes its own\n * container: srte-editor / inline-size (see the .srte-editor rule above),\n * so @container always reflects this specific instance's real rendered width regardless of host\n * layout, with no @media fallback needed (container queries have full\n * support across this project's three target engines).\n */\n@container srte-editor (max-width: 639px) {\n  .srte-toolbar { gap: 3px; padding: 6px; }\n  .srte-tool-button, .srte-toolbar select { height: 40px; min-width: 40px; }\n  .srte-toolbar-group[data-srte-priority=\"3\"],\n  .srte-toolbar-menu[data-srte-priority=\"2\"] { display: none; }\n  .srte-mobile-more { display: block; }\n  /* left/top are no longer set here - ToolbarPrimitives.tsx now computes\n     them via inline style (JS-measured, position:fixed, viewport-clamped;\n     see MobileMoreMenu's own doc comment), which always wins over any\n     value set here regardless of specificity or source order. Sizing/\n     scroll behavior stays defined here since inline positioning doesn't\n     touch those properties. */\n  .srte-mobile-more .srte-menu {\n    width: min(280px, calc(100vw - 16px));\n    min-width: 0;\n    max-height: min(70dvh, 480px);\n    overflow-x: hidden;\n    overflow-y: auto;\n    overscroll-behavior: contain;\n    -webkit-overflow-scrolling: touch;\n  }\n  .srte-menu-item { height: 40px; }\n}\n/*\n * The Bulleted/Numbered list buttons' split-control style picker (a native\n * <select> chevron next to the button - see .srte-split-control) needs\n * ~16px more room than the absolute minimum toolbar width supports.\n * Empirically bisected (not guessed): the toolbar's own \"no button should\n * render narrower than its content\" test only starts failing (Checklist\n * squeezed) at exactly 340-349px container width, and is clean at 350px and\n * every width above it. An earlier version of this fix reused the much\n * wider 639px mobile-tier breakpoint above to hide the select, which \"fixed\"\n * the failing test but also hid the feature across the entire ~340-639px\n * range - it was never actually needed past ~349px, and hiding it that\n * broadly is what caused a live report (\"below 680px it's not showing\n * dropdown icons at list tools\"). Scoped tightly here instead (359px, a\n * small safety margin past the measured 349px floor) so the picker is only\n * absent in the sliver of widths that actually can't fit it - the presets\n * remain reachable via the mobile \"List preset\" control regardless, once\n * .srte-mobile-more takes over at 639px anyway.\n */\n@container srte-editor (max-width: 359px) {\n  .srte-split-control > select { display: none; }\n  .srte-split-control > .srte-tool-button:first-child { border-radius: 8px; }\n}\n/*\n * Below 480px, the block-structure controls (Paragraph/Heading style,\n * Bulleted list, Numbered list, Checklist) drop their text label and show\n * icon-only - \"visible enough to understand\" plus the existing title/\n * aria-label as a real tooltip, not a silent accessibility loss. Scoped to\n * just these four (via data-srte-narrow-icon-only on the buttons, and a\n * dedicated class on the block-type select) rather than every always-\n * visible button, since only these were reported as needing it - Bold/\n * Italic/etc. keep their labels at every width, unchanged.\n *\n * The block-type control is a native <select> (its shown text is the\n * selected option's value, not a separate label node that can be hidden on\n * its own), so it gets the same treatment .srte-split-control's own select\n * already uses: transparent text plus a background-image icon standing in\n * for it - here, the Pilcrow glyph (already in toolbarIcons as\n * \"paragraphStyle\" but otherwise unused). The native option list itself is\n * unaffected and still shows full text when opened.\n */\n@container srte-editor (max-width: 479px) {\n  .srte-tool-button[data-srte-narrow-icon-only=\"true\"] span { display: none; }\n  .srte-toolbar select.srte-block-type-select {\n    appearance: none;\n    -webkit-appearance: none;\n    color: transparent;\n    width: 40px;\n    min-width: 40px;\n    max-width: 40px;\n    padding: 0;\n    background-image: url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='18' height='18' viewBox='0 0 24 24' fill='none' stroke='%2364748b' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M13 4v16'/%3E%3Cpath d='M17 4v16'/%3E%3Cpath d='M19 4H9.5a4.5 4.5 0 0 0 0 9H13'/%3E%3C/svg%3E\");\n    background-repeat: no-repeat;\n    background-position: center;\n  }\n}\n/*\n * Wide-viewport promotion (docs/bugs/toolbar-priority-collapse-fixed-threshold-no-wide-promotion.md):\n * below this, the single 639px breakpoint above was this system's ONLY\n * threshold - every dropdown-grouped tool stayed hidden inside its dropdown\n * at every width from 640px up to and past a 2200px+ desktop, since nothing\n * ever measured or scaled with the extra room. A handful of tools frequent\n * enough to matter once there's genuinely spare room (Superscript,\n * Subscript, Text colour, Background colour, Font size, Font family, Remove\n * link, Insert formula, Special characters) get a standalone always-visible\n * ToolbarButton copy (data-srte-wide-promote, rendered directly in the\n * toolbar row) that appears past this breakpoint, while their existing\n * dropdown/mobile-menu ToolbarMenuItem copy (the exact same\n * data-srte-wide-promote attribute, on the .srte-menu-item element instead)\n * hides so the tool isn't offered twice. Below this breakpoint - including\n * all of mobile AND the 640-1439px tablet/typical-laptop band, which keeps\n * today's grouped-dropdown layout unchanged - the standalone copy stays\n * hidden and the dropdown copy is what's reachable.\n *\n * 1440px, not 1280px: Playwright's own default test viewport is exactly\n * 1280x720, and the vast majority of this suite's toolbar interactions run\n * at that default without ever calling page.setViewportSize - a 1280px\n * threshold would have flipped nearly every existing toolbar test's\n * dropdown-item locators (role=menuitem) over to CSS display:none out from\n * under them. 1440px clears that default with room to spare while still\n * comfortably covering \"wide desktop\" (the ~2264px width the original\n * report was filed against).\n *\n * @container only, no @media fallback - same reasoning as the mobile tier\n * above (docs/bugs/toolbar-wide-promotion-fires-on-viewport-width-not-container-width.md):\n * a plain @media(min-width:1440px) fired whenever the *browser window* was\n * wide, even when this editor instance was embedded in a much narrower\n * split pane - promoting 9 extra buttons into a group with no room for\n * them, which squeezed/overlapped the group's existing buttons instead of\n * wrapping cleanly.\n */\n.srte-tool-button[data-srte-wide-promote=\"true\"] { display: none; }\n@container srte-editor (min-width: 1440px) {\n  .srte-tool-button[data-srte-wide-promote=\"true\"] { display: inline-flex; }\n  .srte-menu-item[data-srte-wide-promote=\"true\"] { display: none; }\n}\n.srte-editor [contenteditable] blockquote {\n  border-left: 4px solid var(--srte-accent);\n  margin: 0.75em 0;\n  padding: 0.5em 1em;\n  /* --srte-muted, not the retired --srte-surface-subtle (docs/bugs/\n     srte-surface-subtle-not-host-theme-aware.md): every other neutral\n     surface/text token here (--srte-background, --srte-foreground,\n     --srte-muted, --srte-border) is defined as var(--host-token, fallback)\n     so it correctly follows a host's OWN light/dark state even if\n     .srte-dark never gets applied for some host-side wiring reason -\n     --srte-surface-subtle was the one exception, a bare hardcoded hex with\n     no host integration, which is exactly what let a real host (dark mode,\n     .srte-dark not reaching this editor instance) render this blockquote\n     with a light-mode background and dark-mode text simultaneously. */\n  background: var(--srte-muted);\n  color: var(--srte-text);\n}\n.srte-editor [contenteditable] p,\n.srte-editor [contenteditable] h1,\n.srte-editor [contenteditable] h2,\n.srte-editor [contenteditable] h3 {\n  color: inherit;\n}\n.srte-editor [contenteditable] p {\n  display: block;\n  margin: 0 0 0.75em;\n  font-size: 1em;\n  font-weight: 400;\n  line-height: 1.6;\n}\n.srte-editor [contenteditable] p[data-srte-caret-boundary=\"true\"] {\n  min-height: 1.6em;\n}\n.srte-editor [contenteditable] h1,\n.srte-editor [contenteditable] h2,\n.srte-editor [contenteditable] h3 {\n  display: block;\n  margin: 0.75em 0 0.4em;\n  font-weight: 700;\n  line-height: 1.25;\n}\n.srte-editor [contenteditable] h1 {\n  font-size: 2em;\n}\n.srte-editor [contenteditable] h2 {\n  font-size: 1.5em;\n}\n.srte-editor [contenteditable] h3 {\n  font-size: 1.25em;\n}\n.srte-editor [contenteditable] > :first-child {\n  margin-top: 0;\n}\n.srte-editor [contenteditable] ul {\n  list-style-type: disc;\n  list-style-position: outside;\n  margin: 0.75em 0;\n  padding-left: 1.75em;\n}\n.srte-editor [contenteditable] ol {\n  list-style-type: decimal;\n  list-style-position: outside;\n  margin: 0.75em 0;\n  padding-left: 1.75em;\n}\n.srte-editor [contenteditable] li {\n  display: list-item;\n  margin: 0.25em 0;\n  padding-left: 0.25em;\n}\n.srte-editor [contenteditable] li::marker {\n  color: currentColor;\n}\n.srte-editor [contenteditable] table {\n  width: 100%;\n  margin: 0.75em 0;\n  border-collapse: collapse;\n}\n.srte-editor [contenteditable] th,\n.srte-editor [contenteditable] td {\n  padding: 8px;\n  border: 1px solid var(--srte-border);\n  vertical-align: top;\n}\n.srte-editor [contenteditable] [data-smart-cell-selected=\"true\"] {\n  background: color-mix(in srgb, var(--srte-primary) 12%, var(--srte-canvas));\n  box-shadow: inset 0 0 0 2px color-mix(in srgb, var(--srte-primary) 65%, transparent);\n}\n.srte-editor [contenteditable][data-smart-cell-selection-active] ::selection {\n  background: transparent;\n  color: inherit;\n}\n.srte-editor [contenteditable] th {\n  background: var(--srte-muted);\n  font-weight: 600;\n  text-align: left;\n}\n.srte-editor [contenteditable] td > h1,\n.srte-editor [contenteditable] td > h2,\n.srte-editor [contenteditable] td > h3,\n.srte-editor [contenteditable] th > h1,\n.srte-editor [contenteditable] th > h2,\n.srte-editor [contenteditable] th > h3 {\n  margin: 0 0 0.4em;\n  overflow-wrap: anywhere;\n}\n.srte-editor [contenteditable] pre {\n  display: block;\n  margin: 0.75em 0;\n  padding: 12px 14px;\n  overflow-x: auto;\n  border: 1px solid var(--srte-border);\n  border-radius: 6px;\n  background: var(--srte-code-bg);\n  color: var(--srte-code-text);\n  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", monospace;\n  font-size: 0.9em;\n  line-height: 1.55;\n  white-space: pre-wrap;\n}\n.srte-editor [contenteditable] pre code {\n  padding: 0;\n  border: 0;\n  background: transparent;\n  color: inherit;\n  font: inherit;\n}\n.srte-editor [contenteditable] code:not(pre code) {\n  padding: 0.1em 0.35em;\n  border-radius: 3px;\n  background: var(--srte-code-bg);\n  color: var(--srte-code-text);\n  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", monospace;\n  font-size: 0.9em;\n}\n.srte-editor [contenteditable] a,\n.srte-editor [contenteditable] a:visited {\n  color: var(--srte-primary) !important;\n  text-decoration: underline !important;\n  text-decoration-thickness: 1px !important;\n  text-underline-offset: 2px !important;\n  cursor: pointer;\n}\n.srte-editor [contenteditable] a:hover {\n  color: var(--srte-accent) !important;\n}\n.srte-editor [contenteditable] a:focus-visible {\n  outline: 2px solid var(--srte-accent);\n  outline-offset: 2px;\n}\n.srte-editor [contenteditable] sub,\n.srte-editor [contenteditable] sup {\n  line-height: 0;\n}\n/*\n * A page break has no native visual meaning in a continuously-scrolling\n * web editor - its entire purpose is what happens at export/print time\n * (see atom/formats.ts's atomToHtml doc comment). This gives it a clearly\n * distinct live-editor appearance from the plain solid <hr> a horizontal\n * line renders as by default, so the two are never confused: a dashed\n * line with an explicit \"Page break\" label, per the feature's own design\n * decision.\n */\n.srte-editor [contenteditable] [data-smart-type=\"page_break\"] {\n  display: block;\n  position: relative;\n  height: 0;\n  margin: 1.5em 0;\n  border: none;\n  border-top: 2px dashed var(--srte-border);\n  cursor: default;\n}\n.srte-editor [contenteditable] [data-smart-type=\"page_break\"]::after {\n  content: \"Page break\";\n  position: absolute;\n  top: -0.7em;\n  left: 50%;\n  transform: translateX(-50%);\n  background: var(--srte-canvas);\n  padding: 0 0.6em;\n  font-size: 11px;\n  font-weight: 600;\n  text-transform: uppercase;\n  letter-spacing: 0.05em;\n  color: var(--srte-text-muted);\n  white-space: nowrap;\n}\n";
+export declare const SRTE_DEFAULT_CSS = "\n.srte-editor {\n  --srte-background: var(--card, #ffffff);\n  --srte-canvas: var(--background, #ffffff);\n  --srte-foreground: var(--foreground, #0f172a);\n  --srte-muted: var(--muted, #f1f5f9);\n  --srte-muted-foreground: var(--muted-foreground, #64748b);\n  --srte-ring: var(--ring, #0284c7);\n  --srte-radius: var(--radius, 0.625rem);\n  --srte-bg: var(--srte-canvas);\n  --srte-text: var(--srte-foreground);\n  --srte-text-muted: var(--srte-muted-foreground);\n  --srte-border: var(--border, #e2e8f0);\n  --srte-border-light: var(--srte-border);\n  --srte-toolbar-bg: var(--srte-background);\n  --srte-input-bg: var(--srte-background);\n  --srte-input-text: var(--srte-foreground);\n  --srte-input-border: var(--srte-border);\n  --srte-modal-backdrop: rgba(0, 0, 0, 0.35);\n  --srte-modal-backdrop-filter: blur(2px);\n  --srte-modal-bg: var(--card, #ffffff);\n  --srte-modal-text: var(--foreground, #000000);\n  --srte-menu-bg: var(--srte-background);\n  --srte-menu-text: var(--srte-foreground);\n  --srte-menu-shadow: 0 8px 24px rgba(0, 0, 0, 0.18);\n  --srte-accent: #0284c7;\n  --srte-accent-bg: rgba(2, 132, 199, 0.12);\n  --srte-danger: #dc2626;\n  --srte-primary: #2563eb;\n  /* --srte-primary on --srte-accent-bg measures 4.43:1, under WCAG AA's\n     4.5:1 for normal text - used only for the pressed toolbar-button state\n     (see .srte-tool-button[aria-pressed=\"true\"]), not a replacement for\n     --srte-primary generally. */\n  --srte-primary-pressed: #1d4ed8;\n  --srte-on-primary: #ffffff;\n  --srte-cancel-bg: #f3f4f6;\n  --srte-code-bg: #f6f8fa;\n  --srte-code-text: #24292f;\n}\n.srte-editor.srte-dark {\n  --srte-background: var(--card, #1e293b);\n  --srte-canvas: var(--background, #0f172a);\n  --srte-foreground: var(--foreground, #f8fafc);\n  --srte-muted: var(--muted, #334155);\n  --srte-muted-foreground: var(--muted-foreground, #94a3b8);\n  --srte-ring: var(--ring, #38bdf8);\n  --srte-bg: var(--srte-canvas);\n  --srte-text: var(--srte-foreground);\n  --srte-text-muted: var(--srte-muted-foreground);\n  --srte-border: var(--border, #334155);\n  --srte-border-light: var(--srte-border);\n  --srte-toolbar-bg: var(--srte-background);\n  --srte-input-bg: var(--srte-background);\n  --srte-input-text: var(--srte-foreground);\n  --srte-input-border: var(--srte-border);\n  --srte-modal-backdrop: rgba(0, 0, 0, 0.22);\n  --srte-modal-backdrop-filter: blur(10px) saturate(0.9);\n  --srte-modal-bg: var(--card, #1e293b);\n  --srte-modal-text: var(--foreground, #e0e0e0);\n  --srte-menu-bg: var(--srte-background);\n  --srte-menu-text: var(--srte-foreground);\n  --srte-menu-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);\n  --srte-accent: #38bdf8;\n  --srte-accent-bg: rgba(56, 189, 248, 0.16);\n  --srte-danger: #ef4444;\n  --srte-primary: #3b82f6;\n  --srte-primary-pressed: var(--srte-primary);\n  --srte-on-primary: #ffffff;\n  --srte-cancel-bg: #333333;\n  --srte-code-bg: #111827;\n  --srte-code-text: #e5e7eb;\n}\n.srte-editor {\n  border-radius: var(--srte-radius);\n  font-family: \"IBM Plex Sans\", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif;\n  container: srte-editor / inline-size;\n}\n.srte-canonical-authority > .srte-editor[contenteditable] {\n  width: 100%;\n  padding: 16px 20px;\n  box-sizing: border-box;\n  border: 1px solid var(--srte-border);\n  border-radius: 0 0 var(--srte-radius) var(--srte-radius);\n  outline: none;\n  background: var(--srte-canvas);\n  color: var(--srte-foreground);\n  caret-color: var(--srte-foreground);\n  line-height: 1.6;\n}\n.srte-toolbar {\n  display: flex;\n  flex-wrap: wrap;\n  align-items: center;\n  gap: 4px;\n  width: 100%;\n  min-height: 48px;\n  padding: 8px;\n  box-sizing: border-box;\n  border-bottom: 1px solid var(--srte-border);\n  background: var(--srte-background);\n  color: var(--srte-foreground);\n  position: sticky;\n  top: 0;\n  z-index: 10;\n}\n.srte-toolbar-group {\n  display: inline-flex;\n  align-items: center;\n  gap: 2px;\n  min-width: 0;\n}\n.srte-toolbar-group + .srte-toolbar-group::before {\n  content: \"\";\n  width: 1px;\n  height: 20px;\n  margin: 0 5px 0 3px;\n  background: var(--srte-border);\n}\n.srte-tool-button,\n.srte-toolbar select {\n  height: 32px;\n  min-width: 32px;\n  box-sizing: border-box;\n  border: 1px solid transparent;\n  border-radius: 8px;\n  background: transparent;\n  color: var(--srte-foreground);\n  font: 500 13px/1 \"IBM Plex Sans\", ui-sans-serif, system-ui, sans-serif;\n}\n.srte-tool-button {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  gap: 3px;\n  padding: 0 7px;\n  cursor: pointer;\n}\n.srte-toolbar select {\n  max-width: 132px;\n  padding: 0 26px 0 9px;\n  border-color: var(--srte-border);\n  background: var(--srte-input-bg);\n  cursor: pointer;\n}\n.srte-tool-button:hover,\n.srte-toolbar select:hover,\n.srte-toolbar-menu[open] > .srte-menu-trigger {\n  background: var(--srte-muted);\n  border-color: var(--srte-border);\n}\n.srte-tool-button.srte-active,\n.srte-tool-button[aria-pressed=\"true\"] {\n  /* var(--srte-primary) (#2563eb) on var(--srte-accent-bg) measured 4.43:1,\n     just under WCAG AA's 4.5:1 for normal text (axe-core, Phase 11 Tier 3) -\n     a dedicated, darker pressed-state color keeps the same hue family\n     while clearing the threshold, without changing --srte-primary's other,\n     already-compliant usages (e.g. against solid backgrounds). */\n  color: var(--srte-primary-pressed);\n  background: var(--srte-accent-bg);\n  border-color: color-mix(in srgb, var(--srte-primary) 35%, transparent);\n}\n.srte-tool-button:focus-visible,\n.srte-toolbar select:focus-visible,\n.srte-menu-item:focus-visible {\n  outline: 2px solid var(--srte-ring);\n  outline-offset: 1px;\n}\n.srte-tool-button:disabled,\n.srte-menu-item:disabled,\n.srte-toolbar select:disabled {\n  cursor: not-allowed;\n  opacity: .4;\n}\n.srte-toolbar-menu {\n  position: relative;\n}\n.srte-toolbar-menu > summary {\n  list-style: none;\n}\n.srte-toolbar-menu > summary::-webkit-details-marker {\n  display: none;\n}\n.srte-menu {\n  position: absolute;\n  top: calc(100% + 6px);\n  left: 0;\n  z-index: 80;\n  min-width: 210px;\n  padding: 4px;\n  overflow: hidden;\n  border: 1px solid var(--srte-border);\n  border-radius: 12px;\n  background: var(--srte-menu-bg);\n  color: var(--srte-menu-text);\n  box-shadow: var(--srte-menu-shadow);\n}\n/*\n * ToolbarDropdown's own menu panel (docs/bugs/\n * toolbar-dropdown-clipped-by-host-overflow-hidden.md): position:fixed with\n * JS-measured left/top (ToolbarPrimitives.tsx) instead of the default\n * position:absolute above, so it always escapes an ancestor host container's\n * own overflow:hidden regardless of DOM depth - MobileMoreMenu's overflow\n * menu (no data-srte-menu-fixed attribute) is unaffected and keeps its\n * existing position:absolute/right-anchored behavior.\n */\n.srte-menu[data-srte-menu-fixed=\"true\"] {\n  position: fixed;\n  top: 0;\n  left: 0;\n}\n.srte-menu-item {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  width: 100%;\n  height: 36px;\n  padding: 0 8px;\n  border: 0;\n  border-radius: 8px;\n  background: transparent;\n  color: inherit;\n  cursor: pointer;\n  font: 500 13px/1 \"IBM Plex Sans\", ui-sans-serif, system-ui, sans-serif;\n  text-align: left;\n  white-space: nowrap;\n}\n.srte-menu-item:hover {\n  background: var(--srte-muted);\n}\n.srte-menu-check {\n  margin-left: auto;\n  color: var(--srte-primary);\n  font-weight: 700;\n}\n.srte-menu-separator {\n  height: 1px;\n  margin: 4px;\n  background: var(--srte-border);\n}\n.srte-mobile-more { display: none; }\n.srte-toolbar .srte-command-proxy { display: none; }\n.srte-split-control {\n  display: inline-flex;\n}\n.srte-split-control > .srte-tool-button:first-child {\n  border-radius: 8px 0 0 8px;\n}\n.srte-split-control > select {\n  width: 27px;\n  padding: 0;\n  border-radius: 0 8px 8px 0;\n  border-left: 0;\n  appearance: none;\n  -webkit-appearance: none;\n  color: transparent;\n  background-color: var(--srte-muted);\n  background-image: url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='14' height='14' viewBox='0 0 24 24' fill='none' stroke='%2364748b' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m7 10 5 5 5-5'/%3E%3C/svg%3E\");\n  background-repeat: no-repeat;\n  background-position: center;\n  cursor: pointer;\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li {\n  display: grid;\n  grid-template-columns: 1.1em minmax(0, 1fr);\n  column-gap: .45em;\n  align-items: start;\n  padding-left: 0;\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal-paren\"][data-srte-list-depth=\"0\"] > li::marker {\n  content: counter(list-item, decimal) \")  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal-paren\"][data-srte-list-depth=\"1\"] > li::marker {\n  content: counter(list-item, lower-alpha) \")  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal-paren\"][data-srte-list-depth=\"2\"] > li::marker,\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal-paren\"][data-srte-list-depth=\"3\"] > li::marker {\n  content: counter(list-item, lower-roman) \")  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal\"][data-srte-list-depth=\"0\"] > li::marker {\n  content: counter(list-item, decimal) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal\"][data-srte-list-depth=\"1\"] > li::marker {\n  content: counter(list-item, lower-alpha) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal\"][data-srte-list-depth=\"2\"] > li::marker,\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-decimal\"][data-srte-list-depth=\"3\"] > li::marker {\n  content: counter(list-item, lower-roman) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-alpha\"][data-srte-list-depth=\"0\"] > li::marker {\n  content: counter(list-item, upper-alpha) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-alpha\"][data-srte-list-depth=\"1\"] > li::marker {\n  content: counter(list-item, lower-alpha) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-alpha\"][data-srte-list-depth=\"2\"] > li::marker,\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-alpha\"][data-srte-list-depth=\"3\"] > li::marker {\n  content: counter(list-item, lower-roman) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-roman\"][data-srte-list-depth=\"0\"] > li::marker {\n  content: counter(list-item, upper-roman) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-roman\"][data-srte-list-depth=\"1\"] > li::marker {\n  content: counter(list-item, upper-alpha) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-roman\"][data-srte-list-depth=\"2\"] > li::marker,\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-upper-roman\"][data-srte-list-depth=\"3\"] > li::marker {\n  content: counter(list-item, decimal) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-leading-zero\"][data-srte-list-depth=\"0\"] > li::marker {\n  content: counter(list-item, decimal-leading-zero) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-leading-zero\"][data-srte-list-depth=\"1\"] > li::marker {\n  content: counter(list-item, lower-alpha) \".  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-leading-zero\"][data-srte-list-depth=\"2\"] > li::marker,\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-leading-zero\"][data-srte-list-depth=\"3\"] > li::marker {\n  content: counter(list-item, lower-roman) \".  \";\n}\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-disc\"][data-srte-list-depth=\"0\"] > li::marker {\n  content: \"\u25CF  \";\n}\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-disc\"][data-srte-list-depth=\"1\"] > li::marker {\n  content: \"\u25CB  \";\n}\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-disc\"][data-srte-list-depth=\"2\"] > li::marker,\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-disc\"][data-srte-list-depth=\"3\"] > li::marker {\n  content: \"\u25A0  \";\n}\n.srte-editor [contenteditable] ol[data-srte-list-preset=\"ordered-outline\"] > li::marker {\n  content: counters(list-item, \".\") \".  \";\n}\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-diamond\"][data-srte-list-depth=\"0\"] > li::marker { content: \"\u2756  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-diamond\"][data-srte-list-depth=\"1\"] > li::marker { content: \"\u27A2  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-diamond\"][data-srte-list-depth=\"2\"] > li::marker { content: \"\u25A0  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-square\"][data-srte-list-depth=\"0\"] > li::marker { content: \"\u25A1  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-square\"][data-srte-list-depth=\"1\"] > li::marker { content: \"\u25A3  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-square\"][data-srte-list-depth=\"2\"] > li::marker { content: \"\u25AA  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-arrow\"][data-srte-list-depth=\"0\"] > li::marker { content: \"\u279C  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-arrow\"][data-srte-list-depth=\"1\"] > li::marker { content: \"\u25C6  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-arrow\"][data-srte-list-depth=\"2\"] > li::marker { content: \"\u25CF  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-star\"][data-srte-list-depth=\"0\"] > li::marker { content: \"\u2605  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-star\"][data-srte-list-depth=\"1\"] > li::marker { content: \"\u25CB  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-star\"][data-srte-list-depth=\"2\"] > li::marker { content: \"\u25A0  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-arrow-circle\"][data-srte-list-depth=\"0\"] > li::marker { content: \"\u27A2  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-arrow-circle\"][data-srte-list-depth=\"1\"] > li::marker { content: \"\u25CB  \"; }\n.srte-editor [contenteditable] ul[data-srte-list-preset=\"bullet-arrow-circle\"][data-srte-list-depth=\"2\"] > li::marker { content: \"\u25A0  \"; }\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > [data-srte-check] {\n  display: inline-flex;\n  grid-column: 1;\n  grid-row: 1;\n  align-items: center;\n  justify-content: center;\n  width: 1.1em;\n  height: 1.6em;\n  min-width: 0;\n  box-sizing: border-box;\n  padding: 0;\n  border: 0;\n  border-radius: 0;\n  background: transparent;\n  color: inherit;\n  font: inherit;\n  cursor: pointer;\n  appearance: none;\n  outline: none;\n  margin: 0;\n  line-height: 1.6;\n  vertical-align: top;\n  position: relative;\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > [data-srte-check]:focus-visible {\n  outline: 2px solid var(--srte-ring);\n  outline-offset: 2px;\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > [data-srte-check]::before {\n  content: \"\";\n  width: .9em;\n  height: .9em;\n  box-sizing: border-box;\n  border: 1.5px solid var(--srte-muted-foreground);\n  border-radius: 3px;\n  background: var(--srte-canvas);\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > [data-srte-check][data-checked=\"true\"]::before {\n  border-color: var(--srte-primary);\n  background: var(--srte-primary);\n  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--srte-on-primary) 25%, transparent);\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > [data-srte-check][data-checked=\"true\"]::after {\n  content: \"\";\n  position: absolute;\n  width: .42em;\n  height: .22em;\n  border-left: 1.5px solid var(--srte-on-primary);\n  border-bottom: 1.5px solid var(--srte-on-primary);\n  transform: translateY(-.08em) rotate(-45deg);\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > :is(p,h1,h2,h3,h4,h5,h6,blockquote,pre) {\n  grid-column: 2;\n  min-width: 0;\n  margin-top: 0;\n}\n.srte-editor [contenteditable] ul[data-srte-checklist=\"true\"] > li > :is(ul,ol) {\n  grid-column: 2;\n}\n.srte-editor:focus-within {\n  border-color: var(--srte-ring) !important;\n  box-shadow: 0 0 0 2px color-mix(in srgb, var(--srte-ring) 18%, transparent);\n}\n/*\n * @container (element width), not @media (viewport width): a host can embed\n * the editor at any fraction of the browser window - a split pane next to a\n * preview panel is the case that surfaced this (docs/bugs/\n * toolbar-wide-promotion-fires-on-viewport-width-not-container-width.md). A\n * plain @media breakpoint here would fire based on the *window*, wrongly\n * switching tiers for an editor instance that's actually much narrower (or\n * wider) than the window - .srte-editor already establishes its own\n * container: srte-editor / inline-size (see the .srte-editor rule above),\n * so @container always reflects this specific instance's real rendered width regardless of host\n * layout, with no @media fallback needed (container queries have full\n * support across this project's three target engines).\n */\n@container srte-editor (max-width: 639px) {\n  .srte-toolbar { gap: 3px; padding: 6px; }\n  .srte-tool-button, .srte-toolbar select { height: 40px; min-width: 40px; }\n  .srte-toolbar-group[data-srte-priority=\"3\"],\n  .srte-toolbar-menu[data-srte-priority=\"2\"] { display: none; }\n  .srte-mobile-more { display: block; }\n  /* left/top are no longer set here - ToolbarPrimitives.tsx now computes\n     them via inline style (JS-measured, position:fixed, viewport-clamped;\n     see MobileMoreMenu's own doc comment), which always wins over any\n     value set here regardless of specificity or source order. Sizing/\n     scroll behavior stays defined here since inline positioning doesn't\n     touch those properties. */\n  .srte-mobile-more .srte-menu {\n    width: min(280px, calc(100vw - 16px));\n    min-width: 0;\n    max-height: min(70dvh, 480px);\n    overflow-x: hidden;\n    overflow-y: auto;\n    overscroll-behavior: contain;\n    -webkit-overflow-scrolling: touch;\n  }\n  .srte-menu-item { height: 40px; }\n}\n/*\n * The Bulleted/Numbered list buttons' split-control style picker (a native\n * <select> chevron next to the button - see .srte-split-control) needs\n * ~16px more room than the absolute minimum toolbar width supports.\n * Empirically bisected (not guessed): the toolbar's own \"no button should\n * render narrower than its content\" test only starts failing (Checklist\n * squeezed) at exactly 340-349px container width, and is clean at 350px and\n * every width above it. An earlier version of this fix reused the much\n * wider 639px mobile-tier breakpoint above to hide the select, which \"fixed\"\n * the failing test but also hid the feature across the entire ~340-639px\n * range - it was never actually needed past ~349px, and hiding it that\n * broadly is what caused a live report (\"below 680px it's not showing\n * dropdown icons at list tools\"). Scoped tightly here instead (359px, a\n * small safety margin past the measured 349px floor) so the picker is only\n * absent in the sliver of widths that actually can't fit it - the presets\n * remain reachable via the mobile \"List preset\" control regardless, once\n * .srte-mobile-more takes over at 639px anyway.\n */\n@container srte-editor (max-width: 359px) {\n  .srte-split-control > select { display: none; }\n  .srte-split-control > .srte-tool-button:first-child { border-radius: 8px; }\n}\n/*\n * Below 480px, the block-structure controls (Paragraph/Heading style,\n * Bulleted list, Numbered list, Checklist) drop their text label and show\n * icon-only - \"visible enough to understand\" plus the existing title/\n * aria-label as a real tooltip, not a silent accessibility loss. Scoped to\n * just these four (via data-srte-narrow-icon-only on the buttons, and a\n * dedicated class on the block-type select) rather than every always-\n * visible button, since only these were reported as needing it - Bold/\n * Italic/etc. keep their labels at every width, unchanged.\n *\n * The block-type control is a native <select> (its shown text is the\n * selected option's value, not a separate label node that can be hidden on\n * its own), so it gets the same treatment .srte-split-control's own select\n * already uses: transparent text plus a background-image icon standing in\n * for it - here, the Pilcrow glyph (already in toolbarIcons as\n * \"paragraphStyle\" but otherwise unused). The native option list itself is\n * unaffected and still shows full text when opened.\n */\n@container srte-editor (max-width: 479px) {\n  .srte-tool-button[data-srte-narrow-icon-only=\"true\"] span { display: none; }\n  .srte-toolbar select.srte-block-type-select {\n    appearance: none;\n    -webkit-appearance: none;\n    color: transparent;\n    width: 40px;\n    min-width: 40px;\n    max-width: 40px;\n    padding: 0;\n    background-image: url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='18' height='18' viewBox='0 0 24 24' fill='none' stroke='%2364748b' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M13 4v16'/%3E%3Cpath d='M17 4v16'/%3E%3Cpath d='M19 4H9.5a4.5 4.5 0 0 0 0 9H13'/%3E%3C/svg%3E\");\n    background-repeat: no-repeat;\n    background-position: center;\n  }\n}\n/*\n * Wide-viewport promotion (docs/bugs/toolbar-priority-collapse-fixed-threshold-no-wide-promotion.md):\n * below this, the single 639px breakpoint above was this system's ONLY\n * threshold - every dropdown-grouped tool stayed hidden inside its dropdown\n * at every width from 640px up to and past a 2200px+ desktop, since nothing\n * ever measured or scaled with the extra room. A handful of tools frequent\n * enough to matter once there's genuinely spare room (Superscript,\n * Subscript, Text colour, Background colour, Font size, Font family, Remove\n * link, Insert formula, Special characters) get a standalone always-visible\n * ToolbarButton copy (data-srte-wide-promote, rendered directly in the\n * toolbar row) that appears past this breakpoint, while their existing\n * dropdown/mobile-menu ToolbarMenuItem copy (the exact same\n * data-srte-wide-promote attribute, on the .srte-menu-item element instead)\n * hides so the tool isn't offered twice. Below this breakpoint - including\n * all of mobile AND the 640-1439px tablet/typical-laptop band, which keeps\n * today's grouped-dropdown layout unchanged - the standalone copy stays\n * hidden and the dropdown copy is what's reachable.\n *\n * 1440px, not 1280px: Playwright's own default test viewport is exactly\n * 1280x720, and the vast majority of this suite's toolbar interactions run\n * at that default without ever calling page.setViewportSize - a 1280px\n * threshold would have flipped nearly every existing toolbar test's\n * dropdown-item locators (role=menuitem) over to CSS display:none out from\n * under them. 1440px clears that default with room to spare while still\n * comfortably covering \"wide desktop\" (the ~2264px width the original\n * report was filed against).\n *\n * @container only, no @media fallback - same reasoning as the mobile tier\n * above (docs/bugs/toolbar-wide-promotion-fires-on-viewport-width-not-container-width.md):\n * a plain @media(min-width:1440px) fired whenever the *browser window* was\n * wide, even when this editor instance was embedded in a much narrower\n * split pane - promoting 9 extra buttons into a group with no room for\n * them, which squeezed/overlapped the group's existing buttons instead of\n * wrapping cleanly.\n */\n.srte-tool-button[data-srte-wide-promote=\"true\"] { display: none; }\n@container srte-editor (min-width: 1440px) {\n  .srte-tool-button[data-srte-wide-promote=\"true\"] { display: inline-flex; }\n  .srte-menu-item[data-srte-wide-promote=\"true\"] { display: none; }\n}\n.srte-editor [contenteditable] blockquote {\n  border-left: 4px solid var(--srte-accent);\n  margin: 0.75em 0;\n  padding: 0.5em 1em;\n  /* --srte-muted, not the retired --srte-surface-subtle (docs/bugs/\n     srte-surface-subtle-not-host-theme-aware.md): every other neutral\n     surface/text token here (--srte-background, --srte-foreground,\n     --srte-muted, --srte-border) is defined as var(--host-token, fallback)\n     so it correctly follows a host's OWN light/dark state even if\n     .srte-dark never gets applied for some host-side wiring reason -\n     --srte-surface-subtle was the one exception, a bare hardcoded hex with\n     no host integration, which is exactly what let a real host (dark mode,\n     .srte-dark not reaching this editor instance) render this blockquote\n     with a light-mode background and dark-mode text simultaneously. */\n  background: var(--srte-muted);\n  color: var(--srte-text);\n}\n.srte-editor [contenteditable] p,\n.srte-editor [contenteditable] h1,\n.srte-editor [contenteditable] h2,\n.srte-editor [contenteditable] h3 {\n  color: inherit;\n}\n.srte-editor [contenteditable] p {\n  display: block;\n  margin: 0 0 0.75em;\n  font-size: 1em;\n  font-weight: 400;\n  line-height: 1.6;\n}\n.srte-editor [contenteditable] p[data-srte-caret-boundary=\"true\"] {\n  min-height: 1.6em;\n}\n.srte-editor [contenteditable] h1,\n.srte-editor [contenteditable] h2,\n.srte-editor [contenteditable] h3 {\n  display: block;\n  margin: 0.75em 0 0.4em;\n  font-weight: 700;\n  line-height: 1.25;\n}\n.srte-editor [contenteditable] h1 {\n  font-size: 2em;\n}\n.srte-editor [contenteditable] h2 {\n  font-size: 1.5em;\n}\n.srte-editor [contenteditable] h3 {\n  font-size: 1.25em;\n}\n.srte-editor [contenteditable] > :first-child {\n  margin-top: 0;\n}\n.srte-editor [contenteditable] ul {\n  list-style-type: disc;\n  list-style-position: outside;\n  margin: 0.75em 0;\n  padding-left: 1.75em;\n}\n.srte-editor [contenteditable] ol {\n  list-style-type: decimal;\n  list-style-position: outside;\n  margin: 0.75em 0;\n  padding-left: 1.75em;\n}\n.srte-editor [contenteditable] li {\n  display: list-item;\n  margin: 0.25em 0;\n  padding-left: 0.25em;\n}\n.srte-editor [contenteditable] li::marker {\n  color: currentColor;\n}\n.srte-editor [contenteditable] table {\n  width: 100%;\n  margin: 0.75em 0;\n  border-collapse: collapse;\n}\n.srte-editor [contenteditable] th,\n.srte-editor [contenteditable] td {\n  padding: 8px;\n  border: 1px solid var(--srte-border);\n  vertical-align: top;\n}\n.srte-editor [contenteditable] [data-smart-cell-selected=\"true\"] {\n  background: color-mix(in srgb, var(--srte-primary) 12%, var(--srte-canvas));\n  box-shadow: inset 0 0 0 2px color-mix(in srgb, var(--srte-primary) 65%, transparent);\n}\n.srte-editor [contenteditable][data-smart-cell-selection-active] ::selection {\n  background: transparent;\n  color: inherit;\n}\n.srte-editor [contenteditable] th {\n  background: var(--srte-muted);\n  font-weight: 600;\n  text-align: left;\n}\n.srte-editor [contenteditable] td > h1,\n.srte-editor [contenteditable] td > h2,\n.srte-editor [contenteditable] td > h3,\n.srte-editor [contenteditable] th > h1,\n.srte-editor [contenteditable] th > h2,\n.srte-editor [contenteditable] th > h3 {\n  margin: 0 0 0.4em;\n  overflow-wrap: anywhere;\n}\n.srte-editor [contenteditable] pre {\n  display: block;\n  margin: 0.75em 0;\n  padding: 12px 14px;\n  overflow-x: auto;\n  border: 1px solid var(--srte-border);\n  border-radius: 6px;\n  background: var(--srte-code-bg);\n  color: var(--srte-code-text);\n  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", monospace;\n  font-size: 0.9em;\n  line-height: 1.55;\n  white-space: pre-wrap;\n}\n.srte-editor [contenteditable] pre code {\n  padding: 0;\n  border: 0;\n  background: transparent;\n  color: inherit;\n  font: inherit;\n}\n.srte-editor [contenteditable] code:not(pre code) {\n  padding: 0.1em 0.35em;\n  border-radius: 3px;\n  background: var(--srte-code-bg);\n  color: var(--srte-code-text);\n  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", monospace;\n  font-size: 0.9em;\n}\n.srte-editor [contenteditable] a,\n.srte-editor [contenteditable] a:visited {\n  color: var(--srte-primary) !important;\n  text-decoration: underline !important;\n  text-decoration-thickness: 1px !important;\n  text-underline-offset: 2px !important;\n  cursor: pointer;\n}\n.srte-editor [contenteditable] a:hover {\n  color: var(--srte-accent) !important;\n}\n.srte-editor [contenteditable] a:focus-visible {\n  outline: 2px solid var(--srte-accent);\n  outline-offset: 2px;\n}\n.srte-editor [contenteditable] sub,\n.srte-editor [contenteditable] sup {\n  line-height: 0;\n}\n/*\n * A page break has no native visual meaning in a continuously-scrolling\n * web editor - its entire purpose is what happens at export/print time\n * (see atom/formats.ts's atomToHtml doc comment). This gives it a clearly\n * distinct live-editor appearance from the plain solid <hr> a horizontal\n * line renders as by default, so the two are never confused: a dashed\n * line with an explicit \"Page break\" label, per the feature's own design\n * decision.\n */\n/*\n * A block image's caption (a renderer projection placed right after the\n * <img>, see surface/renderer.ts's syncImageCaptions). Small and muted,\n * close under the image, following its alignment; max-width is set inline\n * to the image's width when known. A left/right image floats, so its\n * caption floats the same way and clears that side to stack underneath.\n */\n.srte-editor [contenteditable] [data-smart-projection=\"image-caption\"] {\n  display: block;\n  box-sizing: border-box;\n  margin: 4px 0 0.75em;\n  color: var(--srte-text-muted);\n  font-size: 0.85em;\n  line-height: 1.4;\n  overflow-wrap: anywhere;\n  cursor: pointer;\n  user-select: none;\n}\n.srte-editor [contenteditable] [data-smart-projection=\"image-caption\"][data-smart-align=\"center\"] {\n  margin-left: auto;\n  margin-right: auto;\n  text-align: center;\n}\n.srte-editor [contenteditable] [data-smart-projection=\"image-caption\"][data-smart-align=\"left\"] {\n  float: left;\n  clear: left;\n  margin-right: 8px;\n}\n.srte-editor [contenteditable] [data-smart-projection=\"image-caption\"][data-smart-align=\"right\"] {\n  float: right;\n  clear: right;\n  margin-left: 8px;\n  text-align: right;\n}\n.srte-editor [contenteditable] [data-smart-type=\"page_break\"] {\n  display: block;\n  position: relative;\n  height: 0;\n  margin: 1.5em 0;\n  border: none;\n  border-top: 2px dashed var(--srte-border);\n  cursor: default;\n}\n.srte-editor [contenteditable] [data-smart-type=\"page_break\"]::after {\n  content: \"Page break\";\n  position: absolute;\n  top: -0.7em;\n  left: 50%;\n  transform: translateX(-50%);\n  background: var(--srte-canvas);\n  padding: 0 0.6em;\n  font-size: 11px;\n  font-weight: 600;\n  text-transform: uppercase;\n  letter-spacing: 0.05em;\n  color: var(--srte-text-muted);\n  white-space: nowrap;\n}\n";
 export declare function ensureStyleSheet(): void;

package/dist/theme.js

@@ -701,6 +701,40 @@ export const SRTE_DEFAULT_CSS = `
  * line with an explicit "Page break" label, per the feature's own design
  * decision.
  */
+/*
+ * A block image's caption (a renderer projection placed right after the
+ * <img>, see surface/renderer.ts's syncImageCaptions). Small and muted,
+ * close under the image, following its alignment; max-width is set inline
+ * to the image's width when known. A left/right image floats, so its
+ * caption floats the same way and clears that side to stack underneath.
+ */
+.srte-editor [contenteditable] [data-smart-projection="image-caption"] {
+  display: block;
+  box-sizing: border-box;
+  margin: 4px 0 0.75em;
+  color: var(--srte-text-muted);
+  font-size: 0.85em;
+  line-height: 1.4;
+  overflow-wrap: anywhere;
+  cursor: pointer;
+  user-select: none;
+}
+.srte-editor [contenteditable] [data-smart-projection="image-caption"][data-smart-align="center"] {
+  margin-left: auto;
+  margin-right: auto;
+  text-align: center;
+}
+.srte-editor [contenteditable] [data-smart-projection="image-caption"][data-smart-align="left"] {
+  float: left;
+  clear: left;
+  margin-right: 8px;
+}
+.srte-editor [contenteditable] [data-smart-projection="image-caption"][data-smart-align="right"] {
+  float: right;
+  clear: right;
+  margin-left: 8px;
+  text-align: right;
+}
 .srte-editor [contenteditable] [data-smart-type="page_break"] {
   display: block;
   position: relative;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smartrte-react",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A powerful, feature-rich Rich Text Editor for React with support for tables, mathematical formulas (LaTeX/KaTeX), and media management",
   "type": "module",
   "main": "dist/index.js",
@@ -52,16 +52,6 @@
   },
   "author": "Smart RTE Contributors",
   "license": "MIT",
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build",
-    "dev": "pnpm build",
-    "lint": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run --passWithNoTests",
-    "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build",
-    "e2e": "pnpm --filter smartrte-core build && pnpm build && playwright test --pass-with-no-tests"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -94,6 +84,15 @@
     "lucide-react": "^1.35.0",
     "mammoth": "^1.11.0",
     "pdfjs-dist": "^5.4.530",
-    "smartrte-core": "workspace:^"
+    "smartrte-core": "^1.2.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "dev": "pnpm build",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "e2e": "pnpm --filter smartrte-core build && pnpm build && playwright test --pass-with-no-tests"
   }
-}
+}