@portone/docx-editor 0.4.0 → 0.5.0

package/dist/editor/plugins/documentProjection.d.ts

@@ -0,0 +1,31 @@
+/**
+ * One convention for a value the whole document decides: the comments beside it, the notes under
+ * it, the list markers drawn over it.
+ *
+ * Such a value is worked out by walking the document, and what it is worked out from changes only
+ * when the document does. Held here, it is derived once per edit rather than once per read, and a
+ * caret moving, a menu opening or a component rendering again all read back the value the last
+ * edit left. What a caller writes is unchanged: `read` answers with a value either way.
+ *
+ * A projection derives from the document alone. Anything that also depends on the selection, the
+ * protection or another plugin belongs in that plugin, which is asked again after every
+ * transaction rather than after an edit alone.
+ */
+import type { Node as PMNode } from "prosemirror-model";
+import { type EditorState, Plugin, type PluginSpec } from "prosemirror-state";
+export interface DocumentProjection<T> {
+    plugin: Plugin<T>;
+    /**
+     * The derived value. A state built without the plugin - one a consumer assembled itself, or one
+     * a test made out of a bare document - is answered by deriving on the spot, so a public reader
+     * standing on a projection keeps answering whoever asks it.
+     */
+    read(state: EditorState): T;
+}
+export declare function documentProjection<T>(name: string, derive: (doc: PMNode) => T, 
+/**
+ * The view props drawn from the derived value, which is how a projection that paints what it
+ * derived - comment ranges over the text they were written for - stays one plugin. `this` in
+ * such a prop is the plugin, so it reads the value back with `this.getState(state)`.
+ */
+props?: PluginSpec<T>["props"]): DocumentProjection<T>;

package/dist/editor/plugins/documentProjection.js

@@ -0,0 +1,22 @@
+// src/editor/plugins/documentProjection.ts
+import {
+  Plugin,
+  PluginKey
+} from "prosemirror-state";
+function documentProjection(name, derive, props) {
+  const key = new PluginKey(name);
+  return {
+    plugin: new Plugin({
+      key,
+      state: {
+        init: (_config, state) => derive(state.doc),
+        apply: (tr, held) => tr.docChanged ? derive(tr.doc) : held
+      },
+      props
+    }),
+    read: (state) => key.getState(state) ?? derive(state.doc)
+  };
+}
+export {
+  documentProjection
+};

package/dist/editor/plugins/imagePaste.js

@@ -3,12 +3,14 @@ import { isHistoryTransaction } from "prosemirror-history";
 import { Plugin, PluginKey } from "prosemirror-state";
 import { Decoration, DecorationSet } from "prosemirror-view";
 import { editShut, selectionIntents } from "../../schema/guards.js";
+import { readHtmlSlice, withPastedContent } from "../clipboard/htmlReader.js";
 import {
   hasResolvableClipboardImages,
   resolveClipboardImages
 } from "../clipboard/images.js";
-import { documentBodyHeightPx, documentBodyWidthPx } from "../documentStyles.js";
-import { richHtmlSlice, withPastedContent } from "../externalClipboard.js";
+import { plainTextPaste } from "../clipboard/parser.js";
+import { readContextOf } from "../clipboard/readContext.js";
+import { documentBodyWidthPx, sectionBodyHeightPx } from "../documentStyles.js";
 import { insertPlainTextAt } from "../plainText.js";
 var LOAD_TIMEOUT_MS = 15e3;
 var imagePasteKey = new PluginKey("docxImagePaste");
@@ -87,11 +89,13 @@ function imagePaste() {
     if (!range) return;
     removeMarker(task);
     if (task.view.isDestroyed) return;
-    const content = resolved === null || resolved.images.size === 0 ? null : richHtmlSlice(
-      task.view.state,
-      task.view.dom.ownerDocument,
-      resolved.source,
-      resolved.images
+    const content = resolved === null || resolved.images.size === 0 ? null : readHtmlSlice(
+      readContextOf(
+        task.view.state,
+        task.view.dom.ownerDocument,
+        resolved.images
+      ),
+      resolved.source
     );
     if (content !== null) {
       task.view.dispatch(
@@ -225,6 +229,7 @@ function imagePaste() {
     props: {
       decorations: (state) => imagePasteKey.getState(state)?.decorations,
       handlePaste(view, event) {
+        if (plainTextPaste(view, event)) return false;
         if (selectionIntents(view.state.selection, "replace").some(
           (intent) => editShut(view.state, intent)
         )) {
@@ -256,8 +261,10 @@ function imagePaste() {
           view,
           html,
           text,
+          // One sheet is drawn at one width, the first section's, and a pasted image is fitted
+          // to it; how tall a page is, though, is the paper of the section it lands in
           maxWidthPx: documentBodyWidthPx(view.state),
-          maxHeightPx: documentBodyHeightPx(view.state),
+          maxHeightPx: sectionBodyHeightPx(view.state, from),
           canceled: false,
           controller: null
         });

package/dist/editor/plugins/linkPanel.d.ts

@@ -9,15 +9,19 @@
  * It closes on the document changing, which is what applying a link or taking one off does: the
  * panel is about the selection it opened over, and after an edit that selection has been answered.
  */
-import { type Command, type EditorState, Plugin } from "prosemirror-state";
+import type { Command, EditorState, Plugin } from "prosemirror-state";
+/** The panel is about the selection it opened over, so standing open is all there is to hold */
+declare const OPEN = true;
 /** Whether the link panel is open */
 export declare function isLinkPanelOpen(state: EditorState): boolean;
 /**
  * Opens the panel. It reports false where a link could not go on anyway - a caret standing in no
  * link, a selection a lock leaves nothing of - so that Cmd+K there is a key this editor did not
- * take, and a control drawn from it is drawn dead.
+ * take, and a control drawn from it is drawn dead. A panel already open is one more such place:
+ * the button that opened it has nothing left to do while it stands.
  */
 export declare const openLinkPanel: Command;
 /** Closes it. Called on applying, on Escape, and on a click outside */
 export declare const closeLinkPanel: Command;
-export declare function linkPanel(): Plugin<boolean>;
+export declare function linkPanel(): Plugin<typeof OPEN | null>;
+export {};

package/dist/editor/plugins/linkPanel.js

@@ -1,35 +1,21 @@
 // src/editor/plugins/linkPanel.ts
-import {
-  Plugin,
-  PluginKey
-} from "prosemirror-state";
 import { canSetLink } from "../commands/linkCommands.js";
-var panelKey = new PluginKey("docxEditorLinkPanel");
+import { panelPlugin } from "./panelState.js";
+var OPEN = true;
+var panel = panelPlugin({
+  name: "docxEditorLinkPanel",
+  isAnchor: (value) => value === OPEN,
+  // An edit answers the panel: the link went on, came off, or the text it was about moved
+  onDocChange: "close",
+  canOpen: (state) => canSetLink(state)
+});
 function isLinkPanelOpen(state) {
-  return panelKey.getState(state) === true;
+  return panel.anchor(state) === OPEN;
 }
-var openLinkPanel = (state, dispatch) => {
-  if (isLinkPanelOpen(state) || !canSetLink(state)) return false;
-  if (dispatch) dispatch(state.tr.setMeta(panelKey, true));
-  return true;
-};
-var closeLinkPanel = (state, dispatch) => {
-  if (!isLinkPanelOpen(state)) return false;
-  if (dispatch) dispatch(state.tr.setMeta(panelKey, false));
-  return true;
-};
+var openLinkPanel = (state, dispatch) => !isLinkPanelOpen(state) && panel.open(OPEN)(state, dispatch);
+var closeLinkPanel = panel.close;
 function linkPanel() {
-  return new Plugin({
-    key: panelKey,
-    state: {
-      init: () => false,
-      apply: (tr, open) => {
-        const meta = tr.getMeta(panelKey);
-        if (typeof meta === "boolean") return meta;
-        return tr.docChanged ? false : open;
-      }
-    }
-  });
+  return panel.plugin;
 }
 export {
   closeLinkPanel,

package/dist/editor/plugins/panelState.d.ts

@@ -0,0 +1,67 @@
+/**
+ * One convention for every panel the editor opens over a spot in the document: a link panel, a
+ * right click menu, the comment composer.
+ *
+ * Each of them holds the same thing - where it stands, or nothing when it is shut - and answers the
+ * same three questions: open it here, close it, where does it stand. What differs between them is
+ * what "here" is and what an edit or a change of protection does to a panel already open, and those
+ * are the options below rather than four copies of a plugin.
+ *
+ * The anchor is whatever the panel is about: a point on the screen for a menu, a stretch of the
+ * document for the composer. It is read back out of the state as it was put in, so a panel that
+ * needs nothing but "open" carries an anchor that says just that.
+ *
+ * A panel that reads other plugins in `canOpen` or `closeWhen` must be registered after them:
+ * the state a plugin is handed while the transaction is being applied holds the fields of the
+ * plugins ahead of it and nothing of the ones behind it.
+ */
+import { type Command, type EditorState, Plugin, type PluginSpec, type Transaction } from "prosemirror-state";
+/**
+ * What a document change does to an open panel: shut it, or move the anchor along with the change.
+ * Answering null from the mapping shuts it, which is what a stretch the edit swallowed comes to.
+ */
+export type PanelDocChange<Anchor> = "close" | ((anchor: Anchor, tr: Transaction, state: EditorState) => Anchor | null);
+export interface PanelOptions<Anchor> {
+    /** The plugin key's name, which is what a state debugger and a duplicate registration report */
+    name: string;
+    /**
+     * Whether this is an anchor of this panel's. The opening goes through the transaction metadata,
+     * which anything may write, so what is read back is judged rather than trusted
+     */
+    isAnchor(value: unknown): value is Anchor;
+    onDocChange: PanelDocChange<Anchor>;
+    /** Whether the panel may open here. `open` reports false where it says no */
+    canOpen?(state: EditorState, anchor: Anchor): boolean;
+    /**
+     * Whether the panel must shut where the state now stands, asked after every transaction rather
+     * than after an edit alone: a protection switch changes no text (`./documentProtection`), so
+     * `onDocChange` never sees it, and a panel that only a commenter is offered has to go with it.
+     */
+    closeWhen?(state: EditorState, anchor: Anchor): boolean;
+    /**
+     * The view props the panel needs of its own, which is how a panel opened by a DOM event - a
+     * right click - stays one plugin. What that handler does with the event is the panel's business;
+     * all this factory asks is that the opening go through `opening` so the state stays this one.
+     */
+    props?: PluginSpec<Anchor | null>["props"];
+}
+export interface PanelPlugin<Anchor> {
+    plugin: Plugin<Anchor | null>;
+    /**
+     * Opens the panel over this anchor, or moves an open one there. False where `canOpen` says the
+     * panel has nothing to do here, so that a control drawn from it is drawn dead and a key bound to
+     * it is a key this editor did not take.
+     */
+    open(anchor: Anchor): Command;
+    /**
+     * The same opening recorded on a transaction already being built, for an opener that moves the
+     * selection in the same step. `canOpen` is not asked here: an opener holding the event that
+     * asked - a right click landing where the menu belongs - has decided that already.
+     */
+    opening(tr: Transaction, anchor: Anchor): Transaction;
+    /** Closes it. False where it stands closed already, so a key press falls through to what is behind it */
+    close: Command;
+    /** Where the panel stands. Null when it is shut, and for a state built without the plugin */
+    anchor(state: EditorState): Anchor | null;
+}
+export declare function panelPlugin<Anchor>({ name, isAnchor, onDocChange, canOpen, closeWhen, props, }: PanelOptions<Anchor>): PanelPlugin<Anchor>;

package/dist/editor/plugins/panelState.js

@@ -0,0 +1,54 @@
+// src/editor/plugins/panelState.ts
+import {
+  Plugin,
+  PluginKey
+} from "prosemirror-state";
+var CLOSE = /* @__PURE__ */ Symbol("panelClose");
+function panelPlugin({
+  name,
+  isAnchor,
+  onDocChange,
+  canOpen,
+  closeWhen,
+  props
+}) {
+  const key = new PluginKey(name);
+  const anchor = (state) => key.getState(state) ?? null;
+  const moved = (tr, held, next) => {
+    const meta = tr.getMeta(key);
+    if (meta === CLOSE) return null;
+    if (isAnchor(meta)) return meta;
+    if (held === null || !tr.docChanged) return held;
+    return onDocChange === "close" ? null : onDocChange(held, tr, next);
+  };
+  const opening = (tr, over) => tr.setMeta(key, over);
+  return {
+    plugin: new Plugin({
+      key,
+      state: {
+        init: () => null,
+        apply: (tr, held, _before, next) => {
+          const standing = moved(tr, held, next);
+          if (standing === null) return null;
+          return closeWhen?.(next, standing) ? null : standing;
+        }
+      },
+      props
+    }),
+    open: (over) => (state, dispatch) => {
+      if (canOpen && !canOpen(state, over)) return false;
+      dispatch?.(opening(state.tr, over));
+      return true;
+    },
+    opening,
+    close: (state, dispatch) => {
+      if (anchor(state) === null) return false;
+      dispatch?.(state.tr.setMeta(key, CLOSE));
+      return true;
+    },
+    anchor
+  };
+}
+export {
+  panelPlugin
+};

package/dist/editor/plugins/tableContextMenu.d.ts

@@ -8,7 +8,7 @@
  * selected text is taken first by the text menu (`editor/textContextMenu`), which stands ahead
  * of this one and hands back a click with nothing selected inside a cell.
  */
-import { type Command, type EditorState, Plugin } from "prosemirror-state";
+import { type Command, type EditorState, type Plugin } from "prosemirror-state";
 /** Where the menu should stand (viewport coordinates) */
 export interface TableMenuAnchor {
     clientX: number;

package/dist/editor/plugins/tableContextMenu.js

@@ -1,29 +1,14 @@
 // src/editor/plugins/tableContextMenu.ts
 import {
-  Plugin,
-  PluginKey,
   TextSelection
 } from "prosemirror-state";
 import { editsShut } from "../../schema/protectionState.js";
-var CLOSE = "close";
-var menuKey = new PluginKey("docxEditorTableMenu");
-function isRecord(value) {
-  return typeof value === "object" && value !== null;
-}
-function toAnchor(value) {
-  if (!isRecord(value)) return null;
+import { panelPlugin } from "./panelState.js";
+function isTableMenuAnchor(value) {
+  if (typeof value !== "object" || value === null) return false;
   const { clientX, clientY } = value;
-  if (typeof clientX !== "number" || typeof clientY !== "number") return null;
-  return { clientX, clientY };
-}
-function tableMenuAnchor(state) {
-  return menuKey.getState(state) ?? null;
+  return typeof clientX === "number" && typeof clientY === "number";
 }
-var closeTableMenu = (state, dispatch) => {
-  if (tableMenuAnchor(state) === null) return false;
-  if (dispatch) dispatch(state.tr.setMeta(menuKey, CLOSE));
-  return true;
-};
 function cellStart($pos) {
   for (let depth = $pos.depth; depth > 0; depth -= 1) {
     if ($pos.node(depth).type.spec.tableRole === "cell") {
@@ -46,41 +31,39 @@ function selectionCovers(state, cellPos) {
 }
 function openMenu(view, cellPos, anchor) {
   const state = view.state;
-  const tr = state.tr.setMeta(menuKey, anchor);
+  const tr = menu.opening(state.tr, anchor);
   if (!selectionCovers(state, cellPos)) {
     tr.setSelection(TextSelection.near(tr.doc.resolve(cellPos + 1)));
   }
   view.dispatch(tr);
 }
-function tableContextMenu() {
-  return new Plugin({
-    key: menuKey,
-    state: {
-      init: () => null,
-      apply: (tr, current) => {
-        const meta = tr.getMeta(menuKey);
-        if (meta === CLOSE) return null;
-        const anchor = toAnchor(meta);
-        if (anchor) return anchor;
-        return tr.docChanged ? null : current;
-      }
-    },
-    props: {
-      handleDOMEvents: {
-        contextmenu(view, event) {
-          if (editsShut(view.state)) return false;
-          const cellPos = cellAtEvent(view, event.target);
-          if (cellPos === null) return false;
-          event.preventDefault();
-          openMenu(view, cellPos, {
-            clientX: event.clientX,
-            clientY: event.clientY
-          });
-          return true;
-        }
+var menu = panelPlugin({
+  name: "docxEditorTableMenu",
+  isAnchor: isTableMenuAnchor,
+  // Once the document changes, the cell the menu pointed at may no longer be there
+  onDocChange: "close",
+  props: {
+    handleDOMEvents: {
+      contextmenu(view, event) {
+        if (editsShut(view.state)) return false;
+        const cellPos = cellAtEvent(view, event.target);
+        if (cellPos === null) return false;
+        event.preventDefault();
+        openMenu(view, cellPos, {
+          clientX: event.clientX,
+          clientY: event.clientY
+        });
+        return true;
       }
     }
-  });
+  }
+});
+function tableMenuAnchor(state) {
+  return menu.anchor(state);
+}
+var closeTableMenu = menu.close;
+function tableContextMenu() {
+  return menu.plugin;
 }
 export {
   closeTableMenu,

package/dist/editor/plugins/textContextMenu.d.ts

@@ -2,7 +2,7 @@
  * Replaces the native text context menu and moves the selection to the clicked position. Unselected
  * table cells are left to the table context-menu plugin.
  */
-import { type Command, type EditorState, Plugin } from "prosemirror-state";
+import { type Command, type EditorState, type Plugin } from "prosemirror-state";
 /** Where the menu should stand (viewport coordinates) */
 export interface TextMenuAnchor {
     clientX: number;

package/dist/editor/plugins/textContextMenu.js

@@ -1,30 +1,15 @@
 // src/editor/plugins/textContextMenu.ts
 import {
-  Plugin,
-  PluginKey,
   TextSelection
 } from "prosemirror-state";
 import { CellSelection } from "prosemirror-tables";
 import { editingProtection, editsShut } from "../../schema/protectionState.js";
-var CLOSE = "close";
-var menuKey = new PluginKey("docxEditorTextMenu");
-function isRecord(value) {
-  return typeof value === "object" && value !== null;
-}
-function toAnchor(value) {
-  if (!isRecord(value)) return null;
+import { panelPlugin } from "./panelState.js";
+function isTextMenuAnchor(value) {
+  if (typeof value !== "object" || value === null) return false;
   const { clientX, clientY } = value;
-  if (typeof clientX !== "number" || typeof clientY !== "number") return null;
-  return { clientX, clientY };
-}
-function textMenuAnchor(state) {
-  return menuKey.getState(state) ?? null;
+  return typeof clientX === "number" && typeof clientY === "number";
 }
-var closeTextMenu = (state, dispatch) => {
-  if (textMenuAnchor(state) === null) return false;
-  if (dispatch) dispatch(state.tr.setMeta(menuKey, CLOSE));
-  return true;
-};
 function isInEditor(view, target) {
   return target instanceof Node && view.dom.contains(target);
 }
@@ -50,43 +35,41 @@ function forTableMenu(view, target, spot) {
   return aboutCells && isInTableCell(view, target);
 }
 function openMenu(state, event, spot) {
-  const tr = state.tr.setMeta(menuKey, {
+  const tr = menu.opening(state.tr, {
     clientX: event.clientX,
     clientY: event.clientY
   });
   if (isInSelection(state, spot)) return tr;
   return tr.setSelection(TextSelection.near(tr.doc.resolve(spot)));
 }
-function textContextMenu() {
-  return new Plugin({
-    key: menuKey,
-    state: {
-      init: () => null,
-      apply: (tr, current) => {
-        const meta = tr.getMeta(menuKey);
-        if (meta === CLOSE) return null;
-        const anchor = toAnchor(meta);
-        if (anchor) return anchor;
-        return tr.docChanged ? null : current;
-      }
-    },
-    props: {
-      handleDOMEvents: {
-        contextmenu(view, event) {
-          if (editingProtection(view.state) === "readOnly") return false;
-          if (!isInEditor(view, event.target)) return false;
-          const spot = clickedSpot(view, event);
-          if (editsShut(view.state) && !isInSelection(view.state, spot)) {
-            return false;
-          }
-          if (forTableMenu(view, event.target, spot)) return false;
-          event.preventDefault();
-          view.dispatch(openMenu(view.state, event, spot));
-          return true;
+var menu = panelPlugin({
+  name: "docxEditorTextMenu",
+  isAnchor: isTextMenuAnchor,
+  // Once the document changes, what the menu was aimed at may no longer be there
+  onDocChange: "close",
+  props: {
+    handleDOMEvents: {
+      contextmenu(view, event) {
+        if (editingProtection(view.state) === "readOnly") return false;
+        if (!isInEditor(view, event.target)) return false;
+        const spot = clickedSpot(view, event);
+        if (editsShut(view.state) && !isInSelection(view.state, spot)) {
+          return false;
         }
+        if (forTableMenu(view, event.target, spot)) return false;
+        event.preventDefault();
+        view.dispatch(openMenu(view.state, event, spot));
+        return true;
       }
     }
-  });
+  }
+});
+function textMenuAnchor(state) {
+  return menu.anchor(state);
+}
+var closeTextMenu = menu.close;
+function textContextMenu() {
+  return menu.plugin;
 }
 export {
   closeTextMenu,

package/dist/ooxml/fragment.d.ts

@@ -16,6 +16,7 @@
  * What a raw XML string has to look like to be let into the attr that carries it.
  *
  * `element` is a whole element: a properties fragment, a drawing, an annotation reference.
+ * `elements` is a run of them standing side by side, as a table carries between its rows.
  * `attributes` is what stood inside an opening tag, as `attrString` writes it.
  * `openTag` is an opening tag with everything it wrapped cut away, which the writer puts back by
  * appending the closing text `closedBy` names. `head` is what may still stand between the two:
@@ -24,6 +25,8 @@
 export type RawXmlShape = {
     kind: "element";
     names: readonly string[] | "any";
+} | {
+    kind: "elements";
 } | {
     kind: "attributes";
 } | {
@@ -42,6 +45,14 @@ export declare function ELEMENT(...names: string[]): RawXmlShape;
  * turn a document the editor reads today into a demoted one.
  */
 export declare const ANY_ELEMENT: RawXmlShape;
+/**
+ * A run of one or more elements standing side by side, of any name, in any namespace.
+ *
+ * A table carries the markers that stood between its rows, and a row those between its cells
+ * (`docx/importTable`), and there may be several of them in a row: the end of one bookmark and the
+ * start of the next stand together with nothing between them.
+ */
+export declare const ANY_ELEMENTS: RawXmlShape;
 /** The attributes of an opening tag, with neither the tag nor anything it held */
 export declare const ATTRIBUTES: RawXmlShape;
 /**

package/dist/ooxml/fragment.js

@@ -10,17 +10,22 @@ function ELEMENT(...names) {
   return { kind: "element", names };
 }
 var ANY_ELEMENT = { kind: "element", names: "any" };
+var ANY_ELEMENTS = { kind: "elements" };
 var ATTRIBUTES = { kind: "attributes" };
-function loneElement(xml) {
+function wrappedElements(xml) {
   let root;
   try {
     root = parseXml(`<x ${namespaceDecls(xml)}>${xml}</x>`).documentElement;
   } catch {
     return null;
   }
-  if (root.childNodes.length !== 1) return null;
-  const el = elementChildren(root)[0];
-  return el === void 0 || rebindsReservedPrefix(el) ? null : el;
+  const elements = elementChildren(root);
+  if (root.childNodes.length !== elements.length) return null;
+  return elements.some(rebindsReservedPrefix) ? null : elements;
+}
+function loneElement(xml) {
+  const elements = wrappedElements(xml);
+  return elements?.length === 1 ? elements[0] : null;
 }
 function isNamed(el, names) {
   if (!names.includes(el.localName)) return false;
@@ -54,6 +59,10 @@ function holdsShape(shape, value) {
       if (el === null) return false;
       return shape.names === "any" || isNamed(el, shape.names);
     }
+    case "elements": {
+      const elements = wrappedElements(value);
+      return elements !== null && elements.length > 0;
+    }
     case "attributes": {
       const el = loneElement(`<y ${value}></y>`);
       return el !== null && el.childNodes.length === 0;
@@ -70,6 +79,7 @@ function acceptRawXml(shape, value) {
 }
 export {
   ANY_ELEMENT,
+  ANY_ELEMENTS,
   ATTRIBUTES,
   ELEMENT,
   acceptRawXml

package/dist/ooxml/image.d.ts

@@ -67,11 +67,10 @@ export interface DrawingPicture {
  */
 export declare function readDrawingPicture(drawing: Element): DrawingPicture | null;
 /**
- * The same drawing XML with both extents set to this size.
+ * The same drawing XML with its inline extent and its picture transform's extent set to this size.
  *
- * Only those two elements are touched; every other byte of the original stays where it
- * was. Handed the size it was imported with, this gives back the original string
- * unchanged, so nothing has to keep track of whether a resize happened.
+ * Only those two elements' size attributes are touched; every other byte stays where it was.
+ * Values already equal to the requested size keep their original spelling as well.
  */
 export declare function withExtent(xml: string, extent: ImageExtent): string;
 /** A picture that was inserted during editing and has no original XML to go back to */