@portone/docx-editor 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @portone/docx-editor
 
+## 0.6.2
+
+### Patch Changes
+
+- [#143](https://github.com/portone-io/docx-editor/pull/143) [`2238131`](https://github.com/portone-io/docx-editor/commit/2238131792ecab86ad544545bc28eae24841cbca) Thanks [@Deea222](https://github.com/Deea222)! - Say which content blocks an export, and where it stands.
+  
+  Every entry `exportProblems`, `documentExportProblems` and a `blocked` `downloadDocx` report now carries a `reason`: a discriminated union naming the situation met and the content it is about, such as `unwritten-story-change` with the story and what was done to it, or `missing-content-types` with the part. It tells apart the situations one code covers, so a host can write the sentence its own user reads instead of matching an English message. The codes and messages are unchanged, so a `switch` over `code` keeps working.
+  
+  A problem about a footnote or an endnote now carries `pos` as well, the first reference to that note in the body, since the note's own text stands nowhere there. A note nothing refers to still has no position.
+  
+  `DocxExportError` carries the entry it was raised for as `problem`, so a `catch` reads the same `reason` and `pos` without asking again. A refusal met while writing that the invariants did not predict leaves it absent.
+  
+  The checks are now asked of every side story an edit reached - a footnote, an endnote, a header, a footer, a comment body - as well as of the body, so an unmatched bookmark, a vertical merge past its table, a placeholder that lost its XML or a paragraph in an undefined list is refused wherever it stands instead of going into the file unchecked. Each such reason carries a `story` saying where, `null` for the body. A story nobody touched goes out as it arrived and is not asked about.
+  
+  Since 0.6.1, `exportBytes` and `exportDocx` refuse a document holding a change nothing writes back - a header or footer story added or removed, an edited footnote or endnote separator - instead of saving the file without it. Check `exportProblems` before writing, or catch `DocxExportError`.
+
+## 0.6.1
+
+### Patch Changes
+
+- [#137](https://github.com/portone-io/docx-editor/pull/137) [`a2f1a96`](https://github.com/portone-io/docx-editor/commit/a2f1a96a97c9dd45e07c962ae4a85e8d6954f657) Thanks [@Deea222](https://github.com/Deea222)! - Typing with an IME over a selection that begins at a footnote's number now replaces the selection. Selecting the whole of a footnote and typing over it left its words standing behind the composed text.
+
+- [#138](https://github.com/portone-io/docx-editor/pull/138) [`16467c2`](https://github.com/portone-io/docx-editor/commit/16467c21934d9659f6e0b85d2094277cfcaa7366) Thanks [@Deea222](https://github.com/Deea222)! - Edit, insert, delete, and copy endnotes the way footnotes are, and draw them after the last paragraph of the document.
+
+- [#137](https://github.com/portone-io/docx-editor/pull/137) [`a2f1a96`](https://github.com/portone-io/docx-editor/commit/a2f1a96a97c9dd45e07c962ae4a85e8d6954f657) Thanks [@Deea222](https://github.com/Deea222)! - Paste a copied footnote reference with a copy of its footnote.
+
+- [#137](https://github.com/portone-io/docx-editor/pull/137) [`a2f1a96`](https://github.com/portone-io/docx-editor/commit/a2f1a96a97c9dd45e07c962ae4a85e8d6954f657) Thanks [@Deea222](https://github.com/Deea222)! - Edit footnotes in place: insert one from the right-click menu or with Mod+Alt+F, open it by clicking its number, and leave it with Escape.
+
+- [#136](https://github.com/portone-io/docx-editor/pull/136) [`3c74b87`](https://github.com/portone-io/docx-editor/commit/3c74b87e52233b990e820752d50383411032e81d) Thanks [@Deea222](https://github.com/Deea222)! - Add the `insertFootnote`, `canInsertFootnote`, and `setFootnoteBody` commands, and delete a footnote together with its last reference, so one undo brings both back.
+
+- [#136](https://github.com/portone-io/docx-editor/pull/136) [`3c74b87`](https://github.com/portone-io/docx-editor/commit/3c74b87e52233b990e820752d50383411032e81d) Thanks [@Deea222](https://github.com/Deea222)! - Draw footnotes at the foot of the page that refers to them, with the page ending above them, and list endnotes with their formatting after the last page, in place of the plain-text notes list.
+
+- [#135](https://github.com/portone-io/docx-editor/pull/135) [`d6c701e`](https://github.com/portone-io/docx-editor/commit/d6c701ee3ce60b52772c7413e9f003fc717dbd77) Thanks [@Deea222](https://github.com/Deea222)! - Number footnotes and endnotes in the document's own format, starting number, and section restarts, and renumber them after every edit. A reference that carries its own mark, such as a dagger, is announced by its kind alone rather than by a number it does not have.
+
+- [#135](https://github.com/portone-io/docx-editor/pull/135) [`d6c701e`](https://github.com/portone-io/docx-editor/commit/d6c701ee3ce60b52772c7413e9f003fc717dbd77) Thanks [@Deea222](https://github.com/Deea222)! - Save an edited, added, or deleted footnote or endnote into the file, creating the notes part where the document had none. An export that changed something nothing writes back yet, such as a note separator, is refused rather than saved without the change.
+
+- [#140](https://github.com/portone-io/docx-editor/pull/140) [`a35b24c`](https://github.com/portone-io/docx-editor/commit/a35b24ccbac8cbc9d851381290e0e469a4abc6f1) Thanks [@Deea222](https://github.com/Deea222)! - Fix arrow navigation entering page-break spacing near footnotes, where typed text could appear without being saved in the document.
+
+- [#139](https://github.com/portone-io/docx-editor/pull/139) [`0e8c474`](https://github.com/portone-io/docx-editor/commit/0e8c474a913c5dba8f40cdc539c401782fba5c64) Thanks [@Deea222](https://github.com/Deea222)! - A document breaks into the same pages at every zoom and window width. Below a zoom of about 0.8, a document sitting close to a page boundary could gain a page and its pages could move as the window narrowed; a scale an application puts around the editor, such as a dialog that opens on a scale, no longer moves them either.
+
 ## 0.6.0
 
 ### Minor Changes

package/dist/DocxEditor.js

@@ -1,6 +1,7 @@
 // src/DocxEditor.tsx
 import {
   forwardRef,
+  useCallback,
   useEffect,
   useImperativeHandle,
   useLayoutEffect,
@@ -15,6 +16,13 @@ import { exportProblems } from "./docx/invariants.js";
 import { sectionIn, sectionsOf } from "./docx/sections.js";
 import { activeLinkSpan } from "./editor/commands/linkCommands.js";
 import { createEditorView, editorStateForSession } from "./editor/createEditor.js";
+import { sectionGeometryAt } from "./editor/documentStyles.js";
+import { storyDocument } from "./editor/editorDocument.js";
+import {
+  noteExtensions,
+  noteHost,
+  returnToReference
+} from "./editor/notes/noteSurface.js";
 import {
   closeCommentComposer,
   isCommentComposerOpen
@@ -22,6 +30,10 @@ import {
 import { commentProjection } from "./editor/plugins/commentDecorations.js";
 import { setProtection } from "./editor/plugins/documentProtection.js";
 import { isLinkPanelOpen } from "./editor/plugins/linkPanel.js";
+import {
+  openNoteCommand,
+  requestedNote
+} from "./editor/plugins/noteNavigation.js";
 import { tableMenuAnchor } from "./editor/plugins/tableContextMenu.js";
 import { textMenuAnchor } from "./editor/plugins/textContextMenu.js";
 import { DocxImportError } from "./ooxml/errors.js";
@@ -34,16 +46,32 @@ import { editorClassNames } from "./styles/classNames.js";
 import { CommentsPanel, shownBesideThePage } from "./ui/CommentsPanel.js";
 import { LinkCard } from "./ui/LinkCard.js";
 import { LinkPanel } from "./ui/LinkPanel.js";
-import { NotesPanel } from "./ui/NotesPanel.js";
+import { NotesAroundPage, useNoteBands } from "./ui/notes/noteBands.js";
+import {
+  useStorySurface
+} from "./ui/notes/useStorySurface.js";
 import { TableMenu } from "./ui/TableMenu.js";
 import { TextMenu } from "./ui/TextMenu.js";
 import { Toolbar } from "./ui/Toolbar.js";
 import { useFitWidthZoom } from "./ui/useFitWidthZoom.js";
+import { usePageRoom } from "./ui/usePageRoom.js";
 import { normalizeZoom } from "./ui/zoom.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 function runOn(view, command) {
   command(view.state, (transaction) => view.dispatch(transaction));
 }
+var NOTE_SURFACE = {
+  hostOf: noteHost,
+  extensionsOf: (main, row) => noteExtensions(main, row.key, () => row.label),
+  // The paper a note wraps at is the paper of the section its reference stands in, which a story
+  // holds no section of its own to say (`editor/documentStyles`)
+  documentFor: (main, snapshot, row) => storyDocument(snapshot, sectionGeometryAt(main, row.referencePos)),
+  requestedIn: requestedNote,
+  // The kind's own public command is what a consumer calls; here the kind is a value the row
+  // carries, so the factory behind the two takes it
+  openIn: (main, row) => runOn(main, openNoteCommand(row.kind, row.id)),
+  returnFrom: (main, row) => returnToReference(main, row.key)
+};
 function affordancesOf(mode) {
   switch (mode.kind) {
     case "readOnly":
@@ -169,6 +197,12 @@ function DocxEditorSurface({
   );
   const viewRef = useRef(null);
   const [live, setLive] = useState(null);
+  const [pageBox, setPageBox] = useState(null);
+  const [pageLayer, setPageLayer] = useState(null);
+  const holdPageLayer = useCallback((node) => {
+    layerRef.current = node;
+    setPageLayer(node);
+  }, []);
   const [commentsOpen, setCommentsOpen] = useState(false);
   const [uncontrolledZoom, setUncontrolledZoom] = useState(
     () => normalizeZoom(defaultZoom)
@@ -179,6 +213,7 @@ function DocxEditorSurface({
   const page = opened?.status === "opened" ? pagePixels(opened.session.geometry) : A4_PAGE_PIXELS;
   const fitWidth = useFitWidthZoom(rootRef, page.pageWidth);
   const effectiveZoom = selectedZoom === "fit-width" ? fitWidth : selectedZoom;
+  usePageRoom(pageBox, pageLayer, effectiveZoom);
   const changeZoom = (next) => {
     const normalized = normalizeZoom(next);
     if (zoom === void 0) setUncontrolledZoom(normalized);
@@ -254,12 +289,27 @@ function DocxEditorSurface({
     () => sections === null ? void 0 : sectionPixels(sections),
     [sections]
   );
+  const notes = useNoteBands({
+    state: live?.state ?? null,
+    of: opened,
+    fontFallbacks: mountedFontFallbacks
+  });
+  const surface = useStorySurface({
+    main: live,
+    rows: notes.rows,
+    binding: NOTE_SURFACE
+  });
   const overlay = usePageLayout({
     view: live?.view ?? null,
     layer: layerRef,
     enabled: showPageGuides,
     revision: live?.state.doc,
-    sections: sectionPapers
+    sections: sectionPapers,
+    bands: notes.bands,
+    trailing: notes.trailing,
+    // A page laid out again draws the row the open note stands in wherever it now lands, which
+    // would take its composition down with it
+    composing: surface.composing
   });
   const headersFootersFor = useMemo(() => {
     if (doc === null || session === null || sections === null) return void 0;
@@ -299,11 +349,11 @@ function DocxEditorSurface({
       className: [editorClassNames.frame, className].filter(Boolean).join(" "),
       style,
       children: [
-        live && toolbar && /* @__PURE__ */ jsx(
+        live && toolbar && surface.active && /* @__PURE__ */ jsx(
           Toolbar,
           {
-            view: live.view,
-            state: live.state,
+            main: live,
+            active: surface.active,
             fontFallbacks: mountedFontFallbacks,
             presets,
             commentsOpen,
@@ -333,25 +383,31 @@ function DocxEditorSurface({
                 }
               ),
               /* @__PURE__ */ jsxs("div", { ref: rootRef, className: editorClassNames.root, children: [
-                /* @__PURE__ */ jsxs(
-                  "div",
-                  {
-                    ref: layerRef,
-                    className: editorClassNames.pageLayer,
-                    style: { zoom: effectiveZoom },
-                    children: [
-                      /* @__PURE__ */ jsx("div", { ref: mountRef }),
-                      overlay && /* @__PURE__ */ jsx(
-                        PageGuides,
-                        {
-                          overlay,
-                          headersFootersFor
-                        }
-                      ),
-                      live && opened?.status === "opened" && /* @__PURE__ */ jsx(NotesPanel, { state: live.state, pageWidth: page.pageWidth })
-                    ]
-                  }
-                ),
+                /* @__PURE__ */ jsx("div", { ref: setPageBox, className: editorClassNames.pageBox, children: /* @__PURE__ */ jsxs("div", { ref: holdPageLayer, className: editorClassNames.pageLayer, children: [
+                  /* @__PURE__ */ jsx("div", { ref: mountRef }),
+                  overlay && /* @__PURE__ */ jsx(
+                    PageGuides,
+                    {
+                      overlay,
+                      headersFootersFor
+                    }
+                  ),
+                  /* @__PURE__ */ jsx(
+                    NotesAroundPage,
+                    {
+                      notes,
+                      overlay,
+                      page,
+                      zoom: effectiveZoom,
+                      open: surface.open,
+                      editing: surface.editing,
+                      readOnly: surface.readOnly,
+                      revision: live?.state,
+                      onOpen: surface.onOpen,
+                      onReturn: surface.onReturn
+                    }
+                  )
+                ] }) }),
                 !commentsOpen && commentsPanel
               ] }),
               commentsOpen && commentsPanel
@@ -368,21 +424,23 @@ function DocxEditorSurface({
           },
           linkAtCursor.from
         ),
-        live && textAnchor && /* @__PURE__ */ jsx(
+        live && textAnchor && surface.active && /* @__PURE__ */ jsx(
           TextMenu,
           {
             view: live.view,
             state: live.state,
             anchor: textAnchor,
+            takes: surface.active.takes,
             allowLocking: locking
           }
         ),
-        live && tableAnchor && /* @__PURE__ */ jsx(
+        live && tableAnchor && surface.active && /* @__PURE__ */ jsx(
           TableMenu,
           {
             view: live.view,
             state: live.state,
             anchor: tableAnchor,
+            takes: surface.active.takes,
             allowLocking: locking
           }
         )

package/dist/core.d.ts

@@ -19,9 +19,10 @@ export type { ParagraphStyleOption } from "./docx/formatting";
 export type { DocxBytes, ImportOptions } from "./docx/importDocx";
 /**
  * What the writer would refuse the document over, asked ahead of the write. The first entry is
- * what `exportDocx` throws, so the two cannot disagree.
+ * what `exportDocx` throws, so the two cannot disagree. `reason` tells the situations one code
+ * covers apart and names the content each is about.
  */
-export type { ExportProblem } from "./docx/invariants";
+export type { ExportPartName, ExportProblem, ExportProblemReason, ExportProblemStory, ExportStoryKind, } from "./docx/invariants";
 export { exportProblems } from "./docx/invariants";
 export type { DocxSession } from "./docx/session";
 export { documentNumbering, documentPartPath } from "./docx/session";
@@ -29,7 +30,7 @@ export type { CellFormat, CellVerticalAlign, DocumentDefaults, HighlightName, Li
 export { toCellFormat, toParagraphFormat, toRowFormat, toRunFormat, toTableFormat, toTableWidth, } from "./model/format";
 export type { LevelAlign, LevelIndent, LevelSuffix, NewList, NewListLevel, NumberFormat, Numbering, NumberingLevel, NumberingList, NumberingOptions, NumberingStyleLinks, ReadLevelRun, } from "./numbering/parseNumbering";
 export { parseNumbering } from "./numbering/parseNumbering";
-export type { DocxExportErrorCode, DocxImportErrorCode, } from "./ooxml/errors";
+export type { DocxExportErrorCode, DocxExportErrorOptions, DocxImportErrorCode, } from "./ooxml/errors";
 export { DocxExportError, DocxImportError } from "./ooxml/errors";
 /**
  * An image node's size is written in EMU, the unit the document itself uses. A builder

package/dist/docx/exportDocx.d.ts

@@ -4,7 +4,8 @@
  * The body (document.xml) is always rebuilt from preserved and edited blocks. Every other part is
  * written by a planner (`./partPlan`) that answers only when the document gives it something to
  * write: numbering.xml when a list was newly started, the comment parts when comments changed,
- * media parts when an image was inserted. Content types and relationships change only when one
+ * a header, a footer, or the Footnotes part when a story it holds changed, media parts when an
+ * image was inserted. Content types and relationships change only when one
  * of those additions declares itself through the context every planner shares.
  *
  * The body is written before that relationships part, because a link asks for its relationship as
@@ -35,7 +36,7 @@ export declare function exportDocx(doc: PMNode, session: DocxSession, options?:
  *
  * The first problem `exportProblems` reports is thrown before anything is written, so a refusal a
  * caller could have asked about ahead of time arrives with the same code and message it would
- * have read there.
+ * have read there, and carries that entry as the error's `problem`.
  */
 export declare function exportDocxReport(doc: PMNode, session: DocxSession, options?: ExportOptions): {
     bytes: Uint8Array;

package/dist/docx/exportDocx.js

@@ -10,22 +10,20 @@ import {
   W_NS,
   withXmlParser
 } from "../ooxml/xml.js";
-import { commentsPlanner } from "./comments.js";
 import { repackParts } from "./container.js";
 import {
   fidelityNotesOf
 } from "./fidelity.js";
-import { headerFooterPlanner } from "./headersFooters.js";
 import { hyperlinkRefs } from "./hyperlink.js";
 import { withUniqueIdentities } from "./identities.js";
 import { problemsOf } from "./invariants.js";
 import { NO_IMAGE_REFS, planImageMedia } from "./media.js";
-import { numberingPlanner } from "./numberingPlanner.js";
 import { CONTENT_TYPES_PATH, contentTypeWriter } from "./packageParts.js";
 import {
   assertPartsParse,
   runPartPlanners
 } from "./partPlan.js";
+import { PART_PLANNERS } from "./partPlanners.js";
 import {
   readRelationships,
   relationshipWriter,
@@ -105,11 +103,6 @@ function assertMainPart(documentXml, wroteLinks) {
   }
 }
 var LINK_MARKUP = { namespaces: { r: R_NS } };
-var PART_PLANNERS = [
-  numberingPlanner,
-  commentsPlanner,
-  headerFooterPlanner
-];
 function exportDocx(doc, session, options) {
   return exportDocxReport(doc, session, options).bytes;
 }
@@ -123,7 +116,9 @@ function reportThrough(planners, doc, session, options) {
   return withXmlParser(options?.xmlParser, () => {
     const store = sessionOf(session);
     const problem = problemsOf(doc, store)[0];
-    if (problem) throw new DocxExportError(problem.code, problem.message);
+    if (problem) {
+      throw new DocxExportError(problem.code, problem.message, { problem });
+    }
     const approximated = [];
     const bytes = writeDocx(
       doc,
@@ -141,7 +136,8 @@ function writeDocx(doc, store, notes, planners) {
   const relsPath = relsPathOf(store.mainPartPath);
   const context = {
     relationships: relationshipWriter(readRelationships(store.parts, relsPath)),
-    contentTypes: contentTypeWriter(store.parts)
+    contentTypes: contentTypeWriter(store.parts),
+    notes
   };
   const media = planImageMedia(doc, store, context);
   const links = hyperlinkRefs(context.relationships);

package/dist/docx/headersFooters.js

@@ -7,10 +7,13 @@ import {
 import { isOnElement } from "../ooxml/units.js";
 import { decodeUtf8, encodeUtf8, parseXml, R_NS, W_NS } from "../ooxml/xml.js";
 import { docxSchema } from "../schema/index.js";
-import { sameSource } from "../schema/sourceEquality.js";
-import { storyKey, storyNodeOf } from "../schema/stories.js";
+import {
+  HEADER_FOOTER_KINDS,
+  storyKey
+} from "../schema/stories.js";
 import { NO_EXPORT_REFS } from "./exportRefs.js";
 import { fieldSpans, isFieldCharacter } from "./fields.js";
+import { withUniqueStoryIdentities } from "./identities.js";
 import { relatedPartPath } from "./packageParts.js";
 import { readRelationships, relsPathOf, resolveTarget } from "./relationships.js";
 import {
@@ -21,12 +24,16 @@ import {
   readStory,
   storyLeafText
 } from "./story.js";
+import { storyChangesOf } from "./storyParts.js";
 var EMPTY_VARIANTS = {
   default: null,
   first: null,
   even: null
 };
-var PART_ROOT = { header: "hdr", footer: "ftr" };
+var PART_ROOT = {
+  header: "hdr",
+  footer: "ftr"
+};
 function settingsEvenAndOdd(parts, mainPartPath) {
   const path = relatedPartPath(parts, mainPartPath, `${R_NS}/settings`);
   const bytes = path === null ? void 0 : parts.get(path);
@@ -36,9 +43,9 @@ function settingsEvenAndOdd(parts, mainPartPath) {
   return isOnElement(setting);
 }
 function kindOf(relationshipType) {
-  if (relationshipType === `${R_NS}/header`) return "header";
-  if (relationshipType === `${R_NS}/footer`) return "footer";
-  return null;
+  return HEADER_FOOTER_KINDS.find(
+    (kind) => relationshipType === `${R_NS}/${kind}`
+  ) ?? null;
 }
 function readHeaderFooterStories(parts, mainPartPath, referenced, depsFor) {
   const keyByRelId = /* @__PURE__ */ new Map();
@@ -166,29 +173,34 @@ function headerFooterText(story, page, totalPages) {
   return lines.join("\n");
 }
 var HEADER_MARKUP = { namespaces: { w: NAMESPACES.w } };
-function rewrittenParts(doc, session) {
-  const parts = /* @__PURE__ */ new Map();
-  for (const [key, imported] of session.stories) {
-    if (imported.kind !== "header" && imported.kind !== "footer") continue;
-    const current = storyNodeOf(doc, key);
-    if (current === null || sameSource(current, imported.doc)) continue;
-    const written = serializeStory(current, imported, imported, {
+function writtenPart(imported, current, session, notes) {
+  const written = withUniqueStoryIdentities([{ story: current, frozen: false }]).map(
+    (story) => serializeStory(story, imported, imported, {
       ...NO_EXPORT_REFS,
+      notes,
       session
-    });
-    const hadBom = decodeUtf8(
-      session.parts.get(imported.partPath) ?? new Uint8Array()
-    ).hadBom;
-    parts.set(
+    })
+  ).join("");
+  const hadBom = decodeUtf8(
+    session.parts.get(imported.partPath) ?? new Uint8Array()
+  ).hadBom;
+  return encodeUtf8(ensureRootDeclarations(written, HEADER_MARKUP), hadBom);
+}
+function rewrittenParts(doc, session, notes) {
+  const edited = HEADER_FOOTER_KINDS.flatMap(
+    (kind) => storyChangesOf(doc, session, kind)
+  ).flatMap((change) => change.change === "edited" ? [change] : []);
+  if (edited.length === 0) return null;
+  return new Map(
+    edited.map(({ imported, current }) => [
       imported.partPath,
-      encodeUtf8(ensureRootDeclarations(written, HEADER_MARKUP), hadBom)
-    );
-  }
-  return parts.size === 0 ? null : parts;
+      writtenPart(imported, current, session, notes)
+    ])
+  );
 }
 var headerFooterPlanner = {
   name: "headers and footers",
-  plan: (doc, session) => rewrittenParts(doc, session)
+  plan: (doc, session, context) => rewrittenParts(doc, session, context.notes)
 };
 export {
   displayPageNumber,

package/dist/docx/identities.d.ts

@@ -14,6 +14,12 @@
  * and throws over a block that cannot yield, and `identityProblems` runs the same walk for
  * `docx/invariants` and lists those blocks instead, so what the query reports and what the write
  * refuses cannot come apart.
+ *
+ * A side story is settled by its part rather than by the document: `w14:paraId` is unique within a
+ * part (Part 1 §11.3), so `withUniqueStoryIdentities` walks the stories one part holds as one run
+ * of blocks, and a name the body or another part holds is not compared. A story the part writes as
+ * the bytes it arrived as keeps every name it holds, since no later claimant of one could give it
+ * up in bytes nothing rewrites.
  */
 import { type Node as PMNode } from "prosemirror-model";
 import { type DocxExportErrorCode } from "../ooxml/errors";
@@ -55,6 +61,8 @@ export declare const IDENTITY_RULES: readonly IdentityRule[];
 export interface IdentityProblem {
     readonly code: DocxExportErrorCode;
     readonly message: string;
+    /** The node type standing twice, which `docx/invariants` names in the problem's reason */
+    readonly node: string;
     readonly pos: number;
 }
 /** The document with every later claimant of a name released, in document order */
@@ -65,3 +73,25 @@ export declare function withUniqueIdentities(doc: PMNode, rules?: readonly Ident
  * document is dropped, so a caller asking ahead of the write reads the same refusal it would throw.
  */
 export declare function identityProblems(doc: PMNode, rules?: readonly IdentityRule[]): readonly IdentityProblem[];
+/** A block of a side story that cannot yield */
+export interface StoryIdentityProblem extends IdentityProblem {
+    /** The story's place in the list the part was handed over as; `pos` stands inside that story */
+    readonly story: number;
+}
+/** One story as its part hands it over to the pass */
+export interface StoryToSettle {
+    readonly story: PMNode;
+    /**
+     * Whether the part writes this story as the bytes it arrived as. A frozen story cannot give a
+     * name up, since nothing rewrites what it goes out as, so it claims its names ahead of every
+     * story that can.
+     */
+    readonly frozen: boolean;
+}
+/**
+ * The stories one part holds, in the order the part writes them, with every later claimant of a
+ * name released. A story holding no such claimant is handed back as the very same node.
+ */
+export declare function withUniqueStoryIdentities(entries: readonly StoryToSettle[], rules?: readonly IdentityRule[]): readonly PMNode[];
+/** Every block `withUniqueStoryIdentities` would refuse over, in the order the part writes them */
+export declare function identityProblemsInStories(entries: readonly StoryToSettle[], rules?: readonly IdentityRule[]): readonly StoryIdentityProblem[];

package/dist/docx/identities.js

@@ -103,6 +103,7 @@ function refusalOf(block, pos) {
   return {
     code: "unsupported-content",
     message: `a preserved block stands in two places (${block.type.name})`,
+    node: block.type.name,
     pos
   };
 }
@@ -130,12 +131,7 @@ function rewriteBlock(block, pos, walk) {
   });
   return changed ? visited.copy(Fragment.fromArray(children)) : visited;
 }
-function walkBlocks(doc, rules, refuse) {
-  const walk = {
-    rules,
-    written: rules.map(() => /* @__PURE__ */ new Set()),
-    refuse
-  };
+function settle(doc, walk) {
   const blocks = [];
   let changed = false;
   doc.forEach((block, offset) => {
@@ -145,21 +141,58 @@ function walkBlocks(doc, rules, refuse) {
   });
   return changed ? doc.copy(Fragment.fromArray(blocks)) : doc;
 }
+function unwritten(rules) {
+  return rules.map(() => /* @__PURE__ */ new Set());
+}
+function refuseExport(problem) {
+  throw new DocxExportError(problem.code, problem.message);
+}
 function withUniqueIdentities(doc, rules = IDENTITY_RULES) {
-  return walkBlocks(doc, rules, (problem) => {
-    throw new DocxExportError(problem.code, problem.message);
+  return settle(doc, {
+    rules,
+    written: unwritten(rules),
+    refuse: refuseExport
   });
 }
 function identityProblems(doc, rules = IDENTITY_RULES) {
   const problems = [];
-  walkBlocks(doc, rules, (problem) => problems.push(problem));
+  settle(doc, {
+    rules,
+    written: unwritten(rules),
+    refuse: (problem) => problems.push(problem)
+  });
+  return problems;
+}
+var CLAIMS_ONLY = () => {
+};
+function settleStories(entries, rules, refuse) {
+  const written = unwritten(rules);
+  for (const { story, frozen } of entries) {
+    if (frozen) settle(story, { rules, written, refuse: CLAIMS_ONLY });
+  }
+  return entries.map(
+    ({ story, frozen }, index) => frozen ? story : settle(story, {
+      rules,
+      written,
+      refuse: (problem) => refuse({ ...problem, story: index })
+    })
+  );
+}
+function withUniqueStoryIdentities(entries, rules = IDENTITY_RULES) {
+  return settleStories(entries, rules, refuseExport);
+}
+function identityProblemsInStories(entries, rules = IDENTITY_RULES) {
+  const problems = [];
+  settleStories(entries, rules, (problem) => problems.push(problem));
   return problems;
 }
 export {
   IDENTITY_RULES,
   controlRule,
   identityProblems,
+  identityProblemsInStories,
   paragraphIdRule,
   sourceBlockRule,
-  withUniqueIdentities
+  withUniqueIdentities,
+  withUniqueStoryIdentities
 };