@portone/docx-editor 0.4.0 → 0.5.0

package/dist/docx/protectionPolicy.d.ts

@@ -11,7 +11,7 @@
  * undefined, and a caller holding the level alone has nothing to run.
  */
 import { type XmlParser } from "../ooxml/xml";
-import type { EditableComments, EditingProtection } from "../schema/protection";
+import { type EditableComments, type EditingProtection } from "../schema/protection";
 import { type DocxBytes } from "./importDocx";
 import type { SessionStore } from "./session";
 import { type Story } from "./storyProjection";
@@ -59,8 +59,14 @@ export interface StoryPartKind {
     rootKept(before: SessionStore, after: SessionStore): boolean;
     /** The keys this file still stands behind, which is what an entry has to be keyed by */
     referents(story: Story): ReadonlySet<string>;
-    /** Grammar alone: whether the entry is one this editor's writer could have put out, whoever it belongs to */
-    wellFormed(entry: Element): boolean;
+    /**
+     * Grammar alone: whether the entry is one this editor's writer could have put out, whoever it
+     * belongs to. `original` is the entry the file that arrived held under the same key, and null
+     * for one that appeared, because what the writer can put out depends on what it had to work
+     * with: it writes a comment's body out of the blocks it models and passes the rest through from
+     * the entry it read.
+     */
+    wellFormed(entry: Element, original: Element | null): boolean;
     /**
      * Whether the entry came back differing from the one that arrived in nothing but a change this
      * protection leaves to everyone. Such an entry is nobody's rewrite, so it is held neither to
@@ -70,9 +76,11 @@ export interface StoryPartKind {
     /**
      * Permission alone: whether `authorId` may have written (`original === null`) or rewritten this
      * entry under `options`. `session` is the submission's, so a kind can look across at a sibling
-     * part, the way a comment's author resolves through the people part.
+     * part, the way a comment's author resolves through the people part. `unattributed` is the
+     * display names the file that arrived writes comments under while recording nobody for them,
+     * which is what an entry claiming no identity is held against.
      */
-    allowed(entry: Element, original: Element | null, authorId: string, options: PolicyOptions, session: SessionStore): boolean;
+    allowed(entry: Element, original: Element | null, authorId: string, options: PolicyOptions, session: SessionStore, unattributed: ReadonlySet<string>): boolean;
 }
 /** The two reasons the package comparison answers with, whatever the policy */
 export type PackageReason = "part-changed" | "relationship-changed";

package/dist/docx/protectionPolicy.js

@@ -5,6 +5,9 @@ import {
   parseXml,
   withXmlParser
 } from "../ooxml/xml.js";
+import {
+  unattributedCommentAuthors
+} from "../schema/protection.js";
 import { importDocx } from "./importDocx.js";
 import { CONTENT_TYPES_PATH } from "./packageParts.js";
 import {
@@ -31,9 +34,10 @@ function excusedPaths(policy, session) {
     (path) => path !== null
   );
 }
-function aroundTheStory(session) {
-  const preserved = session.blocks.filter((block) => !isModelledBlock(block.node)).map((block) => block.xml).join("");
-  return session.documentPrefix + preserved + session.documentSuffix;
+function aroundTheStory(story) {
+  const preserved = story.session.blocks.filter((block) => !isModelledBlock(block.node)).map((block) => block.xml).join("");
+  const sectPr = story.doc.attrs.sectPr;
+  return story.session.documentPrefix + preserved + (typeof sectPr === "string" ? sectPr : "") + story.session.documentSuffix;
 }
 function relationshipsKept(before, after, relTypes) {
   if (new Set(before.map((entry) => entry.id)).size !== before.length || new Set(after.map((entry) => entry.id)).size !== after.length) {
@@ -77,41 +81,43 @@ function gainedPartsAreNew(policy, before, after) {
   );
 }
 function packageKept(policy, before, after) {
-  if (before.mainPartPath !== after.mainPartPath) {
-    return { ok: false, reason: "part-changed", part: before.mainPartPath };
+  const was = before.session;
+  const now = after.session;
+  if (was.mainPartPath !== now.mainPartPath) {
+    return { ok: false, reason: "part-changed", part: was.mainPartPath };
   }
-  const relsPath = relsPathOf(before.mainPartPath);
+  const relsPath = relsPathOf(was.mainPartPath);
   const untouched = /* @__PURE__ */ new Set([
-    before.mainPartPath,
+    was.mainPartPath,
     relsPath,
     CONTENT_TYPES_PATH,
-    ...excusedPaths(policy, before),
-    ...excusedPaths(policy, after)
+    ...excusedPaths(policy, was),
+    ...excusedPaths(policy, now)
   ]);
-  for (const path of /* @__PURE__ */ new Set([...before.parts.keys(), ...after.parts.keys()])) {
+  for (const path of /* @__PURE__ */ new Set([...was.parts.keys(), ...now.parts.keys()])) {
     if (untouched.has(path)) continue;
-    const was = before.parts.get(path);
-    const now = after.parts.get(path);
-    if (was === void 0 || now === void 0 || !sameBytes(was, now)) {
+    const arrived = was.parts.get(path);
+    const submitted = now.parts.get(path);
+    if (arrived === void 0 || submitted === void 0 || !sameBytes(arrived, submitted)) {
       return { ok: false, reason: "part-changed", part: path };
     }
   }
   if (!relationshipsKept(
-    readRelationships(before.parts, relsPath),
-    readRelationships(after.parts, relsPath),
+    readRelationships(was.parts, relsPath),
+    readRelationships(now.parts, relsPath),
     policy.parts.map((kind) => kind.relType)
-  ) || !gainedPartsAreNew(policy, before, after)) {
+  ) || !gainedPartsAreNew(policy, was, now)) {
     return { ok: false, reason: "relationship-changed", part: relsPath };
   }
   if (!contentTypesKept(
-    contentTypes(before.parts.get(CONTENT_TYPES_PATH)),
-    contentTypes(after.parts.get(CONTENT_TYPES_PATH)),
+    contentTypes(was.parts.get(CONTENT_TYPES_PATH)),
+    contentTypes(now.parts.get(CONTENT_TYPES_PATH)),
     policy.parts.map((kind) => kind.contentType)
   )) {
     return { ok: false, reason: "part-changed", part: CONTENT_TYPES_PATH };
   }
   if (aroundTheStory(before) !== aroundTheStory(after)) {
-    return { ok: false, reason: "part-changed", part: before.mainPartPath };
+    return { ok: false, reason: "part-changed", part: was.mainPartPath };
   }
   return { ok: true };
 }
@@ -120,18 +126,22 @@ function partKept(kind, before, after, authorId, options) {
   const submitted = kind.entriesIn(after.session, "submitted");
   if (submitted === null) return false;
   if (!kind.rootKept(before.session, after.session)) return false;
+  const unattributed = unattributedCommentAuthors(
+    before.session.comments.ordered
+  );
   const stoodBehindNow = kind.referents(after);
   for (const [id, entry] of submitted) {
     const original = arrived.get(id);
     if (original && original.xml === entry.xml) continue;
     if (!stoodBehindNow.has(id)) return false;
     if (original && kind.anyonesChange(entry.el, original.el)) continue;
-    if (!kind.wellFormed(entry.el) || !kind.allowed(
+    if (!kind.wellFormed(entry.el, original?.el ?? null) || !kind.allowed(
       entry.el,
       original?.el ?? null,
       authorId,
       options,
-      after.session
+      after.session,
+      unattributed
     )) {
       return false;
     }
@@ -155,7 +165,7 @@ function verifyChange(policy, original, submitted, authorId, { xmlParser, ...opt
   return withXmlParser(xmlParser, () => {
     const before = importDocx(original);
     const after = importDocx(submitted);
-    const packaged = packageKept(policy, before.session, after.session);
+    const packaged = packageKept(policy, before, after);
     if (!packaged.ok) return packaged;
     const story = policy.storyKept(before, after, authorId, options);
     return story.ok ? partsKept(policy, before, after, authorId, options) : story;

package/dist/docx/scan.d.ts

@@ -1,20 +1,30 @@
 /**
- * Finds the span each individual body block occupies in the raw document.xml text and slices it out.
+ * Finds the span each individual block occupies in the raw text of a part and slices it out.
  *
  * A block that was not edited is exported by writing this fragment back out untouched,
- * which keeps its original bytes intact.
+ * which keeps its original bytes intact. The body of the main part is one such run of blocks;
+ * a comment and a footnote hold another (`docx/story`), and all of them are sliced here so that
+ * one story cannot end up compared or written by rules another does not follow.
  */
-export interface BodyBlockSlice {
+import { type Tag } from "../ooxml/tagScan";
+export interface BlockSlice {
     /** The tag name exactly as written (e.g. "w:p", "w:tbl", "w:sectPr") */
     name: string;
     /** The original XML fragment. It also carries the whitespace that sat between this block and the one before it */
     xml: string;
 }
-export interface BodyScan {
-    /** Everything in the raw text before the first block */
+export interface BlockScan {
+    /** Everything in the raw text before the first block, the container's own opening tag included */
     prefix: string;
-    blocks: BodyBlockSlice[];
-    /** Everything in the raw text after the last block */
+    blocks: BlockSlice[];
+    /** Everything in the raw text after the last block, the container's closing tag included */
     suffix: string;
 }
-export declare function scanBody(source: string): BodyScan;
+/** The tag whose children are the blocks, asked of every opening tag with the depth it stands at */
+export type ContainerTest = (tag: Tag, depth: number) => boolean;
+/**
+ * The blocks the first container this test names holds, and the text on either side of them.
+ * null for a source holding no such container; a caller says in its own words what that means.
+ */
+export declare function scanBlocksIn(source: string, isContainer: ContainerTest): BlockScan | null;
+export declare function scanBody(source: string): BlockScan;

package/dist/docx/scan.js

@@ -13,15 +13,15 @@ function tagAt(source, lt) {
   return tag;
 }
 function isBodyTag(tag, depth) {
-  return localPart(tag.name) === "body" && depth === 1 && tag.kind === "open";
+  return localPart(tag.name) === "body" && depth === 1;
 }
-function scanBody(source) {
+function scanBlocksIn(source, isContainer) {
   const stack = [];
   const blocks = [];
-  let bodyDepth = null;
+  let containerDepth = null;
   let contentStart = -1;
   let sliceStart = -1;
-  const atBodyLevel = () => bodyDepth !== null && stack.length === bodyDepth;
+  const atBlockLevel = () => containerDepth !== null && stack.length === containerDepth;
   const takeBlock = (name, end) => {
     blocks.push({ name, xml: source.slice(sliceStart, end) });
     sliceStart = end;
@@ -43,24 +43,22 @@ function scanBody(source) {
           `mismatched tags: ${opened} vs ${tag.name}`
         );
       }
-      if (atBodyLevel()) takeBlock(tag.name, tag.end);
+      if (atBlockLevel()) takeBlock(tag.name, tag.end);
       i = tag.end;
       continue;
     }
-    if (bodyDepth === null && isBodyTag(tag, stack.length)) {
+    if (containerDepth === null && tag.kind === "open" && isContainer(tag, stack.length)) {
       stack.push(tag.name);
-      bodyDepth = stack.length;
+      containerDepth = stack.length;
       contentStart = tag.end;
       sliceStart = tag.end;
     } else {
-      if (atBodyLevel() && tag.kind === "empty") takeBlock(tag.name, tag.end);
+      if (atBlockLevel() && tag.kind === "empty") takeBlock(tag.name, tag.end);
       if (tag.kind === "open") stack.push(tag.name);
     }
     i = tag.end;
   }
-  if (bodyDepth === null) {
-    throw new DocxImportError("missing-body", "document has no w:body");
-  }
+  if (containerDepth === null) return null;
   if (stack.length > 0) {
     throw new DocxImportError(
       "malformed-xml",
@@ -73,6 +71,14 @@ function scanBody(source) {
     suffix: source.slice(sliceStart)
   };
 }
+function scanBody(source) {
+  const scan = scanBlocksIn(source, isBodyTag);
+  if (scan === null) {
+    throw new DocxImportError("missing-body", "document has no w:body");
+  }
+  return scan;
+}
 export {
+  scanBlocksIn,
   scanBody
 };

package/dist/docx/sections.d.ts

@@ -0,0 +1,126 @@
+/**
+ * What each section of a document lays down, read once out of the one `w:sectPr` that says it.
+ *
+ * A document is a sequence of sections. Every section but the last is closed by the paragraph that
+ * ends it, which carries that section's `w:sectPr` inside its own `w:pPr` (§17.6.17); the last one
+ * is closed by the body, whose `w:sectPr` stands after the final block (§17.6.18). The body's is
+ * the one the document node carries as `sectPr`, so an edit to it goes through a transaction and
+ * select-all + delete cannot take it away along with the blocks.
+ *
+ * A fragment is only ever sliced, never rebuilt: an untouched section goes back out as the bytes it
+ * arrived as, and a rewritten child is swapped into the spot `CT_SectPr` lays down.
+ */
+import type { Node as PMNode } from "prosemirror-model";
+import { type PageGeometry } from "./pageGeometry";
+export type HeaderFooterVariant = "default" | "first" | "even";
+/** The variants a `w:headerReference` or a `w:footerReference` may name. §17.6.12, §17.6.5 */
+export declare const HEADER_FOOTER_VARIANTS: readonly HeaderFooterVariant[];
+/** The part each variant of one story kind is drawn from, as the relationship id naming it */
+export type HeaderFooterRefs = Readonly<Record<HeaderFooterVariant, string | null>>;
+/** What one `w:sectPr` says, read once and shared by pagination, headers and editing */
+export interface SectionProperties {
+    /**
+     * The `<w:sectPr>...</w:sectPr>` fragment exactly as written.
+     *
+     * "" for a section read out of a parsed document rather than out of text: the only fragments this
+     * package writes back are the slices it took (a paragraph's `w:pPr` child, the document node's
+     * own attr), so a section read off a DOM has no text of its own to hand back.
+     */
+    xml: string;
+    geometry: PageGeometry;
+    headerRefs: HeaderFooterRefs;
+    footerRefs: HeaderFooterRefs;
+    titlePg: boolean;
+    /** §17.6.19 `w:pgNumType/@w:start`; null where the section carries the numbering on */
+    pageNumberStart: number | null;
+    /** §17.6.22 `w:type/@w:val`; null when omitted (nextPage) */
+    type: "continuous" | "evenPage" | "nextPage" | "oddPage" | "nextColumn" | null;
+}
+/** What a section the document does not spell out lays down: the paper every document used to be drawn on */
+export declare const DEFAULT_SECTION: SectionProperties;
+/** Which `w:sectPr` closes a section: the paragraph carrying it, or the body itself */
+export type SectionAnchor = {
+    kind: "paragraph";
+    pos: number;
+} | {
+    kind: "body";
+};
+export interface DocumentSection {
+    index: number;
+    /** Top-level block indexes this section covers, inclusive */
+    firstBlock: number;
+    lastBlock: number;
+    anchor: SectionAnchor;
+    props: SectionProperties;
+}
+/**
+ * Every relationship the sections of this body name as a header or a footer story.
+ *
+ * A `w:headerReference` and a `w:footerReference` stand only inside a `w:sectPr` (§17.6.12,
+ * §17.6.5), so the body holds all of them however many sections it is written in. A part no
+ * section names is one a producer left behind rather than content this document shows.
+ */
+export declare function storyReferenceIds(body: Element): ReadonlySet<string>;
+/**
+ * Everything one `w:sectPr` lays down.
+ *
+ * The reading is deliberately forgiving: it runs against a document already opened, and a value
+ * that cannot be read is a reason to fall back on what a section saying nothing lays down, never a
+ * reason to refuse the file.
+ */
+export declare function readSectionProperties(sectPr: Element): SectionProperties;
+/**
+ * The same, off a fragment held as text, which keeps the text as `xml`.
+ *
+ * null for anything that is not a readable `w:sectPr`, which leaves the caller holding the
+ * fragment it already has rather than a section read out of a guess.
+ */
+export declare function parseSectionProperties(xml: string): SectionProperties | null;
+/**
+ * The first `w:sectPr` of an already parsed body: the one closing the first section, wherever it
+ * stands, and the body's own where the document holds a single section.
+ */
+export declare function firstSectPrElement(body: Element): Element | null;
+/** The `w:sectPr` this paragraph's properties carry, and null for a paragraph that ends no section */
+export declare function sectionBreakOf(pPr: string | null): string | null;
+/**
+ * The paragraph properties without the section break, and null for properties left holding nothing
+ * at all. Properties carrying no break, and properties whose shape cannot be made out, are handed
+ * back as they stand.
+ *
+ * `parseProps` lists direct children alone, so the `w:sectPr` inside a `w:pPrChange` - the
+ * properties this paragraph wore before a tracked change - is not this paragraph's own break and
+ * stays where it stands.
+ */
+export declare function withoutSectionBreak(pPr: string | null): string | null;
+/** The paragraph properties with this section break in the spot `CT_PPr` gives it */
+export declare function withSectionBreak(pPr: string | null, sectPr: string): string;
+/**
+ * One child of a section swapped for new XML, or taken away with a null.
+ *
+ * A child that was not there goes into the spot `CT_SectPr` lays down, and every other child of
+ * the section keeps the text it was written as, whitespace between them included. A header or
+ * footer reference names one variant of one story, so writing one leaves the section's references
+ * to the other variants where they stand.
+ *
+ * A fragment whose shape cannot be made out is handed back untouched, which leaves the caller with
+ * the section the document wrote rather than one written over a guess.
+ */
+export declare function setSectionChild(sectPrXml: string, name: string, childXml: string | null): string;
+/**
+ * Every section of the document in order, the last of them the one the document node carries.
+ *
+ * A document naming no section at all still has one, drawn on the paper `DEFAULT_SECTION` lays
+ * down. The last section covers no block where the final paragraph itself ends a section, which
+ * leaves `firstBlock` past `lastBlock`.
+ */
+export declare function sectionsOf(doc: PMNode): readonly DocumentSection[];
+/**
+ * The same, against a table already read.
+ *
+ * Reading the table walks every block of the document, so anything asking about more than one
+ * position - the pages of a preview, one per section - reads it once and asks here.
+ */
+export declare function sectionIn(sections: readonly DocumentSection[], doc: PMNode, pos: number): DocumentSection;
+/** The section the block at this position belongs to */
+export declare function sectionAt(doc: PMNode, pos: number): DocumentSection;

package/dist/docx/sections.js

@@ -0,0 +1,207 @@
+// src/docx/sections.ts
+import {
+  parseProps,
+  parsePropsXml,
+  renderElement,
+  renderProps,
+  setChild
+} from "../ooxml/props.js";
+import { rootTagAt } from "../ooxml/tagScan.js";
+import { isOnElement } from "../ooxml/units.js";
+import {
+  attributeByLocalName,
+  childByLocalName,
+  elementChildren,
+  R_NS,
+  W_NS
+} from "../ooxml/xml.js";
+import {
+  A4_PORTRAIT,
+  readPageGeometry
+} from "./pageGeometry.js";
+var HEADER_FOOTER_VARIANTS = [
+  "default",
+  "first",
+  "even"
+];
+var NO_REFS = { default: null, first: null, even: null };
+var DEFAULT_SECTION = {
+  xml: "",
+  geometry: A4_PORTRAIT,
+  headerRefs: NO_REFS,
+  footerRefs: NO_REFS,
+  titlePg: false,
+  pageNumberStart: null,
+  type: null
+};
+var SECTION_TYPES = [
+  "continuous",
+  "evenPage",
+  "nextPage",
+  "oddPage",
+  "nextColumn"
+];
+function sectionType(sectPr) {
+  const declared = childByLocalName(sectPr, "type");
+  const value = declared ? attributeByLocalName(declared, "val") : null;
+  return SECTION_TYPES.find((known) => known === value) ?? null;
+}
+function pageNumberStart(sectPr) {
+  const pgNumType = childByLocalName(sectPr, "pgNumType");
+  const declared = pgNumType ? attributeByLocalName(pgNumType, "start") : null;
+  if (declared === null || declared.trim() === "") return null;
+  const start = Number(declared);
+  return Number.isSafeInteger(start) && start >= 0 ? start : null;
+}
+function storyRefs(sectPr, kind) {
+  const refs = { ...NO_REFS };
+  for (const reference of elementChildren(sectPr)) {
+    if (reference.localName !== `${kind}Reference`) continue;
+    const declared = attributeByLocalName(reference, "type") ?? "default";
+    const variant = HEADER_FOOTER_VARIANTS.find((known) => known === declared);
+    if (variant === void 0 || refs[variant] !== null) continue;
+    const id = referenceId(reference);
+    if (id) refs[variant] = id;
+  }
+  return refs;
+}
+function referenceId(reference) {
+  return reference.getAttributeNS(R_NS, "id") ?? attributeByLocalName(reference, "id");
+}
+function storyReferenceIds(body) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const name of ["headerReference", "footerReference"]) {
+    for (const reference of body.getElementsByTagNameNS(W_NS, name)) {
+      const id = referenceId(reference);
+      if (id) ids.add(id);
+    }
+  }
+  return ids;
+}
+function readSectionProperties(sectPr) {
+  return {
+    xml: "",
+    geometry: readPageGeometry(sectPr),
+    headerRefs: storyRefs(sectPr, "header"),
+    footerRefs: storyRefs(sectPr, "footer"),
+    titlePg: isOnElement(childByLocalName(sectPr, "titlePg")),
+    pageNumberStart: pageNumberStart(sectPr),
+    type: sectionType(sectPr)
+  };
+}
+function parseSectionProperties(xml) {
+  const el = parsePropsXml(xml);
+  if (el?.localName !== "sectPr") return null;
+  return { ...readSectionProperties(el), xml };
+}
+function firstSectPrElement(body) {
+  const wordSection = body.getElementsByTagNameNS(W_NS, "sectPr")[0];
+  if (wordSection) return wordSection;
+  for (const el of body.getElementsByTagName("*")) {
+    if (el.localName === "sectPr") return el;
+  }
+  return null;
+}
+function pPrText(node) {
+  const pPr = node.attrs.pPr;
+  return typeof pPr === "string" ? pPr : null;
+}
+function sectionBreakOf(pPr) {
+  if (pPr === null) return null;
+  const props = parseProps(pPr);
+  return props?.children.find((child) => child.name === "sectPr")?.xml ?? null;
+}
+function withoutSectionBreak(pPr) {
+  if (pPr === null) return null;
+  const props = parseProps(pPr);
+  if (props === null) return pPr;
+  const without = setChild(props, "sectPr", null);
+  if (without.children.length === props.children.length) return pPr;
+  return renderProps(without) || null;
+}
+function withSectionBreak(pPr, sectPr) {
+  const props = (pPr === null ? null : parseProps(pPr)) ?? EMPTY_P_PR;
+  return renderElement(setChild(props, "sectPr", sectPr));
+}
+var EMPTY_P_PR = { tag: "w:pPr", attrs: null, children: [] };
+var REFERENCE_CHILDREN = [
+  "headerReference",
+  "footerReference"
+];
+function referenceVariant(xml) {
+  const el = parsePropsXml(xml);
+  return (el && attributeByLocalName(el, "type")) ?? "default";
+}
+function withReference(props, name, childXml) {
+  const variant = referenceVariant(childXml);
+  let last = -1;
+  let replaced = false;
+  const children = props.children.map((child, index) => {
+    if (child.name !== name) return child;
+    last = index;
+    if (referenceVariant(child.xml) !== variant) return child;
+    replaced = true;
+    return { ...child, xml: childXml };
+  });
+  if (replaced) return { ...props, children };
+  if (last === -1) return setChild(props, name, childXml);
+  children.splice(last + 1, 0, { name, xml: childXml });
+  return { ...props, children };
+}
+function setSectionChild(sectPrXml, name, childXml) {
+  const start = rootTagAt(sectPrXml);
+  if (start === -1) return sectPrXml;
+  const gap = sectPrXml.slice(0, start);
+  const props = parseProps(sectPrXml.slice(start));
+  if (props === null) return sectPrXml;
+  const written = childXml !== null && REFERENCE_CHILDREN.includes(name) ? withReference(props, name, childXml) : setChild(props, name, childXml);
+  return gap + renderElement(written);
+}
+function sectionsOf(doc) {
+  const sections = [];
+  let firstBlock = 0;
+  doc.forEach((child, offset, index) => {
+    const brk = sectionBreakOf(pPrText(child));
+    if (brk === null) return;
+    sections.push({
+      index: sections.length,
+      firstBlock,
+      lastBlock: index,
+      anchor: { kind: "paragraph", pos: offset },
+      props: parseSectionProperties(brk) ?? { ...DEFAULT_SECTION, xml: brk }
+    });
+    firstBlock = index + 1;
+  });
+  const body = doc.attrs.sectPr;
+  const xml = typeof body === "string" ? body : null;
+  sections.push({
+    index: sections.length,
+    firstBlock,
+    lastBlock: doc.childCount - 1,
+    anchor: { kind: "body" },
+    props: xml === null ? DEFAULT_SECTION : parseSectionProperties(xml) ?? { ...DEFAULT_SECTION, xml }
+  });
+  return sections;
+}
+function sectionIn(sections, doc, pos) {
+  const index = doc.resolve(Math.min(Math.max(pos, 0), doc.content.size)).index(0);
+  return sections.find((section) => index <= section.lastBlock) ?? sections[sections.length - 1];
+}
+function sectionAt(doc, pos) {
+  return sectionIn(sectionsOf(doc), doc, pos);
+}
+export {
+  DEFAULT_SECTION,
+  HEADER_FOOTER_VARIANTS,
+  firstSectPrElement,
+  parseSectionProperties,
+  readSectionProperties,
+  sectionAt,
+  sectionBreakOf,
+  sectionIn,
+  sectionsOf,
+  setSectionChild,
+  storyReferenceIds,
+  withSectionBreak,
+  withoutSectionBreak
+};

package/dist/docx/serializeBlock.d.ts

@@ -1,6 +1,15 @@
 import type { Node as PMNode } from "prosemirror-model";
 import { type ExportRefs } from "./exportRefs";
-import { type SessionStore } from "./session";
-/** Why there is no original to write, which a block that came in from another document answers differently */
-export declare function lostOriginal(node: PMNode, session: SessionStore): string;
-export declare function serializeBlock(node: PMNode, session: SessionStore, refs?: ExportRefs): string;
+export declare function serializeBlock(node: PMNode, refs?: ExportRefs): string;
+/**
+ * An unchanged block is written back as its original XML; only a changed block is rebuilt.
+ *
+ * Unchanged is judged by `sameSource` rather than by `Node.eq`, because opening a file works the
+ * display attrs out again (`schema/attrRoles`) and a block rebuilt over that would lose the markup
+ * the writer does not model, the properties of a cell continuing a vertical merge among it.
+ *
+ * `onlyBlock` says the block stands alone in its story. An original of empty XML belongs to the
+ * editable placeholder a story with no block of its own opens with; once another block joins it,
+ * that paragraph stands for a real blank line and has to be written.
+ */
+export declare function blockXml(node: PMNode, refs: ExportRefs, onlyBlock: boolean): string;

package/dist/docx/serializeBlock.js

@@ -1,32 +1,30 @@
 // src/docx/serializeBlock.ts
 import { DocxExportError } from "../ooxml/errors.js";
+import { sameSource } from "../schema/sourceEquality.js";
 import { NO_EXPORT_REFS } from "./exportRefs.js";
-import { preservedXml, serializeParagraph } from "./serializeParagraph.js";
+import { serializeParagraph } from "./serializeParagraph.js";
+import { serializePreservedBlock } from "./serializePreserved.js";
 import { serializeTable } from "./serializeTable.js";
-import { originalBlock, splitBlockKey } from "./session.js";
-function lostOriginal(node, session) {
-  const srcId = node.attrs.srcId;
-  const key = typeof srcId === "string" ? splitBlockKey(srcId) : null;
-  return key === null || key.sessionId === session.sessionId ? "a preserved block has lost its original XML" : `a preserved block comes from another document (${key.sessionId})`;
-}
-function serializeRaw(node, session) {
-  const imported = originalBlock(node, session);
-  if (!imported) {
-    throw new DocxExportError("lost-original", lostOriginal(node, session));
-  }
-  return imported.xml;
-}
-function serializeBlock(node, session, refs = NO_EXPORT_REFS) {
+import { originalBlock } from "./session.js";
+function serializeBlock(node, refs = NO_EXPORT_REFS) {
   if (node.type.name === "paragraph") return serializeParagraph(node, refs);
   if (node.type.name === "table") return serializeTable(node, refs);
-  if (node.type.name === "rawBlock") return preservedXml(node);
-  if (node.type.isInGroup("preserved")) return serializeRaw(node, session);
+  if (node.type.isInGroup("preserved")) {
+    return serializePreservedBlock(node, refs);
+  }
   throw new DocxExportError(
     "unsupported-content",
     `block we cannot serialize: ${node.type.name}`
   );
 }
+function blockXml(node, refs, onlyBlock) {
+  const imported = refs.session === null ? void 0 : originalBlock(node, refs.session);
+  if (imported && (imported.xml !== "" || onlyBlock) && sameSource(node, imported.node)) {
+    return imported.xml;
+  }
+  return serializeBlock(node, refs);
+}
 export {
-  lostOriginal,
+  blockXml,
   serializeBlock
 };