@portone/docx-editor 0.5.1 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @portone/docx-editor
 
+## 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
+
+- [#131](https://github.com/portone-io/docx-editor/pull/131) [`5dd468a`](https://github.com/portone-io/docx-editor/commit/5dd468ae14d6210070ab6c8275d16e03b20cf64c) Thanks [@Deea222](https://github.com/Deea222)! - A comment now outlives the text it was written for, and a resolved one stops marking the page.
+  
+  Deleting commented text used to delete the comment and everything said under it. The thread now
+  stays. Trim the highlighted text - type over part of it, backspace through its edge - and the
+  comment follows what is left. Delete all of it and the comment comes back detached: no longer drawn
+  beside the page, since there is nothing to draw it next to, and listed under All comments marked
+  "Original content deleted". Cutting commented text leaves it behind the same way instead of dropping
+  it. Word has no detached state, so such a comment reaches the saved file as an ordinary comment
+  sitting where the deleted text was. Deleting a comment from its own Delete button still deletes it,
+  and undo and redo still take a deletion back and make it again.
+  
+  Resolving a thread now takes its highlight off the text, and reopening puts it back. Clicking a
+  resolved comment's card in All comments selects the text it was written about and scrolls it into
+  view, which `selectComment` now does for every caller.
+  
+  `documentComments` reports a new `anchored` field on every comment, `false` for one that no longer
+  marks a stretch of the document. Its existing fields are unchanged, so a panel of your own keeps
+  working and can read the new field to decide what a click on a card should do.
+
 ## 0.5.1
 
 ### Patch Changes

package/CONTRIBUTING.md

@@ -44,22 +44,28 @@ Run a specialized check when your change affects its area:
 pnpm test:package
 pnpm verify:package
 pnpm test:e2e
+pnpm bench
 ```
 
+A pull request that changes performance-sensitive code attaches its `pnpm bench` output to the description.
+
 [Testing](https://github.com/portone-io/docx-editor/blob/main/docs/testing.md) explains the scope and prerequisites of every check.
+CI runs `pnpm test:package` on every pull request in a separate job; it is not part of the local `pnpm check` command.
 
 A command added to `./commands` or `./table` needs a writer probe in `src/docx/__testing__/writerProbes.ts` with a `check` of its immediate effect, so its export is validated before another command can overwrite it, or an entry in `NOT_A_WRITER` giving the reason it reaches no writer.
 
 ## Changesets
 
-If you changed anything under `src/`, run `pnpm changeset` and commit the file it writes.
+If you changed production code under `src/`, run `pnpm changeset` and commit the file it writes.
 It becomes the CHANGELOG entry, so write it for someone reading release notes rather than the diff.
+Changes limited to tests, fixtures, scripts, or documentation do not need a changeset.
 
-The public API is the exported names and types of the four entry points - `.`, `./core`, `./commands`, and `./table` - together with the parts of the document model that [What a plugin may rely on](https://docx-editor.portone.io/docs/custom-controls#what-a-plugin-may-rely-on) calls stable.
+The public API is the exported names and types of the four entry points - `.`, `./core`, `./commands`, and `./table` - together with the parts of the document model that [What a plugin may rely on](https://docx-editor.portone.io/docs/editor-api/plugins-and-presets#what-a-plugin-may-rely-on) calls stable.
 An attr that page calls internal is not part of it, and neither is anything under `src/` that no entry point reaches.
 
 Choose `patch` unless the change adds to that surface, takes something out of it, or changes what a part of it means.
 Those are `minor` while the package is below 1.0.
+A diff to `src/schema/attrRoles.ts` is where to check this: a change to a stable document-model attr is `minor` even when the declaration reports do not change.
 A declaration added, removed, or rewritten in `etc/*.api.md` after running `pnpm api:update` is what that looks like; a line that only gains or loses an `(undocumented)` marker is not.
 Commit the regenerated report in the same commit as the changeset.
 

package/README.md

@@ -47,7 +47,7 @@ export function Editor({
 - Preserves document structures and package parts across edits, and records who wrote each comment.
 - Reads document styles, theme fonts, page layout, and CJK font information for display.
 
-See [Feature support](https://docx-editor.portone.io/docs/features) for the support matrix. Build [custom controls](https://docx-editor.portone.io/docs/custom-controls) or use [programmatic DOCX import and export](https://docx-editor.portone.io/docs/core).
+See [Feature support](https://docx-editor.portone.io/docs/features) for the support matrix. Build controls of your own with the [Editor API](https://docx-editor.portone.io/docs/editor-api) or use [programmatic DOCX import and export](https://docx-editor.portone.io/docs/core).
 
 The full [documentation](https://docx-editor.portone.io/docs) lives on the documentation site.
 

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";
@@ -31,19 +43,35 @@ import { usePageLayout } from "./page/usePageLayout.js";
 import { editingProtection, protectionOf } from "./schema/protectionState.js";
 import { storyNodeOf } from "./schema/stories.js";
 import { editorClassNames } from "./styles/classNames.js";
-import { CommentsPanel } from "./ui/CommentsPanel.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;
@@ -280,9 +330,9 @@ function DocxEditorSurface({
   const tableAnchor = live && !textAnchor ? tableMenuAnchor(live.state) : null;
   const linkAtCursor = live && !live.view.composing && !isLinkPanelOpen(live.state) ? activeLinkSpan(live.state) : null;
   const comments = live?.state === void 0 ? [] : commentProjection.read(live.state).comments;
-  const hasUnresolvedComments = comments.some((comment) => !comment.resolved);
+  const hasRailComments = comments.some(shownBesideThePage);
   const composerOpen = live !== null && isCommentComposerOpen(live.state);
-  const showComments = live !== null && (commentsOpen || composerOpen || hasUnresolvedComments);
+  const showComments = live !== null && (commentsOpen || composerOpen || hasRailComments);
   const commentsPanel = live && showComments && /* @__PURE__ */ jsx(
     CommentsPanel,
     {
@@ -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/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

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;
 }
@@ -141,7 +134,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";
@@ -65,3 +71,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

@@ -130,12 +130,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 +140,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
 };