@stll/folio-core 0.54.2 → 0.56.0

package/dist/docx/reviewHistoryNamespace.js

@@ -0,0 +1,4 @@
+//#region src/docx/reviewHistoryNamespace.ts
+const FOLIO_REVIEW_HISTORY_NAMESPACE = "urn:stella:folio:review-history:1";
+//#endregion
+export { FOLIO_REVIEW_HISTORY_NAMESPACE };

package/dist/docx/reviewResolutionProvenance.d.ts

@@ -0,0 +1,25 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/reviewResolutionProvenance.d.ts
+type ResolutionJoins = NonNullable<document_d_exports.Insertion["resolutionJoins"]>;
+type BoundaryJoins = NonNullable<document_d_exports.RunPropertyChange["boundaryJoins"]>;
+declare const isResolutionJoins: (value: unknown) => value is ResolutionJoins;
+declare const isParagraphMarkResolutionJoin: (value: unknown) => value is NonNullable<document_d_exports.ParagraphMarkChange["resolutionJoin"]>;
+declare const isBoundaryJoins: (value: unknown) => value is BoundaryJoins;
+declare const ReviewResolutionProvenanceError_base: import("better-result").TaggedErrorClass<"ReviewResolutionProvenanceError">;
+declare class ReviewResolutionProvenanceError extends ReviewResolutionProvenanceError_base<{
+  message: string;
+  attribute: string;
+  reason: "invalid" | "unsupportedVersion" | "unrepresentable";
+}> {}
+declare const parseResolutionJoins: (node: XmlElement) => ResolutionJoins | undefined;
+declare const parseBoundaryJoins: (node: XmlElement) => BoundaryJoins | undefined;
+declare const serializeResolutionJoins: (value: document_d_exports.Insertion["resolutionJoins"]) => string;
+declare const serializeBoundaryJoins: (value: document_d_exports.RunPropertyChange["boundaryJoins"]) => string;
+/** Null carries an owned undefined depth; a missing attribute carries no field. */
+declare const parseParagraphMarkResolutionJoin: (node: XmlElement) => Pick<document_d_exports.ParagraphMarkChange, "resolutionJoin">;
+declare const serializeParagraphMarkResolutionJoin: (mark: document_d_exports.ParagraphMarkChange) => string;
+/** Captured paragraph properties compose the same envelope into a parsed XML element. */
+declare const paragraphMarkResolutionJoinAttributes: (mark: document_d_exports.ParagraphMarkChange) => Record<string, string>;
+//#endregion
+export { ReviewResolutionProvenanceError, isBoundaryJoins, isParagraphMarkResolutionJoin, isResolutionJoins, paragraphMarkResolutionJoinAttributes, parseBoundaryJoins, parseParagraphMarkResolutionJoin, parseResolutionJoins, serializeBoundaryJoins, serializeParagraphMarkResolutionJoin, serializeResolutionJoins };

package/dist/docx/reviewResolutionProvenance.js

@@ -0,0 +1,153 @@
+import { FOLIO_REVIEW_HISTORY_NAMESPACE } from "./reviewHistoryNamespace.js";
+import { getAttributeByNamespaceUri } from "./xmlParser.js";
+import { Result, TaggedError } from "better-result";
+import { escapeXmlAttribute } from "@stll/docx-core";
+import { MAX_REVISION_ID } from "@stll/docx-core/model";
+//#region src/docx/reviewResolutionProvenance.ts
+const NAMESPACES = /* @__PURE__ */ new Set([FOLIO_REVIEW_HISTORY_NAMESPACE]);
+const VERSION = 1;
+const MAX_ATTRIBUTE_LENGTH = 32768;
+const SLOT_FIELDS = {
+	space: true,
+	id: true
+};
+const RETAINED_FIELDS = {
+	depth: true,
+	source: true,
+	target: true
+};
+const JOIN_FIELDS = {
+	before: true,
+	after: true,
+	remove: true,
+	retainedAfter: true,
+	deferredRemove: true,
+	acceptance: true
+};
+const ACCEPTANCE_POLICIES = { "merge-plain-runs": true };
+const PARAGRAPH_MARK_FIELDS = {
+	kind: { type: "ooxml" },
+	info: { type: "ooxml" },
+	resolutionJoin: {
+		type: "private",
+		attribute: "resolutionJoin"
+	}
+};
+const DEFERRED_REMOVAL_FIELDS = {
+	depth: true,
+	blockers: true
+};
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const natural = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const slots = (value) => Array.isArray(value) && value.every((slot) => record(slot) && Object.keys(slot).every((key) => Object.hasOwn(SLOT_FIELDS, key)) && (slot["space"] === "revision" || slot["space"] === "control") && natural(slot["id"]) && slot["id"] <= MAX_REVISION_ID);
+const retained = (value) => Array.isArray(value) && value.every((item) => {
+	if (!record(item)) return false;
+	const source = item["source"];
+	const target = item["target"];
+	return Object.keys(item).every((key) => Object.hasOwn(RETAINED_FIELDS, key)) && natural(item["depth"]) && slots(source) && slots(target) && source.length === target.length && source.every((slot, index) => slot.space === target.at(index)?.space);
+});
+const deferredRemoval = (value) => {
+	if (!record(value) || Object.keys(value).some((key) => !Object.hasOwn(DEFERRED_REMOVAL_FIELDS, key))) return false;
+	const depth = value["depth"];
+	const blockers = value["blockers"];
+	return natural(depth) && depth <= MAX_REVISION_ID && Array.isArray(blockers) && blockers.length > 0 && !blockers.includes(void 0) && new Set(blockers).size === blockers.length && blockers.every((blocker) => natural(blocker) && blocker <= MAX_REVISION_ID);
+};
+const deferredRemovals = (value) => {
+	if (!Array.isArray(value) || value.length === 0 || value.includes(void 0) || !value.every(deferredRemoval)) return false;
+	const groups = value.map(({ depth, blockers }) => JSON.stringify({
+		depth,
+		blockers
+	}));
+	return new Set(groups).size === groups.length;
+};
+const isResolutionJoins = (value) => record(value) && Object.keys(value).every((key) => Object.hasOwn(JOIN_FIELDS, key)) && natural(value["before"]) && natural(value["after"]) && natural(value["remove"]) && (!Object.hasOwn(value, "acceptance") || typeof value["acceptance"] === "string" && Object.hasOwn(ACCEPTANCE_POLICIES, value["acceptance"])) && (value["retainedAfter"] === void 0 || retained(value["retainedAfter"])) && (!Object.hasOwn(value, "deferredRemove") || deferredRemovals(value["deferredRemove"]));
+const isParagraphMarkResolutionJoin = (value) => natural(value) && value <= MAX_REVISION_ID;
+const isEncodedParagraphMarkResolutionJoin = (value) => value === null || isParagraphMarkResolutionJoin(value);
+const isBoundaryJoins = (value) => Array.isArray(value) && value.length <= 2 && new Set(value).size === value.length && value.every((side) => side === "before" || side === "after");
+var ReviewResolutionProvenanceError = class extends TaggedError("ReviewResolutionProvenanceError") {};
+const parseAttribute = ({ node, attribute, valid }) => {
+	const encoded = getAttributeByNamespaceUri(node, NAMESPACES, attribute);
+	if (encoded === null) return void 0;
+	const failed = (reason = "invalid") => new ReviewResolutionProvenanceError({
+		attribute,
+		message: `Invalid or unsupported ${attribute} review provenance.`,
+		reason
+	});
+	if (encoded.length > MAX_ATTRIBUTE_LENGTH) throw failed();
+	const parsed = Result.try({
+		try: () => JSON.parse(encoded),
+		catch: () => failed()
+	});
+	if (parsed.isErr()) throw parsed.error;
+	const decoded = parsed.value;
+	if (!record(decoded) || Object.keys(decoded).some((key) => key !== "version" && key !== "value")) throw failed();
+	const value = decoded["value"];
+	if (!valid(value)) throw failed();
+	if (decoded["version"] !== VERSION) throw failed("unsupportedVersion");
+	return value;
+};
+const encodeAttribute = ({ attribute, value, valid }) => {
+	if (value === void 0) return void 0;
+	if (!valid(value)) throw new ReviewResolutionProvenanceError({
+		attribute,
+		reason: "invalid",
+		message: `Invalid or oversized ${attribute} review provenance.`
+	});
+	const encoded = JSON.stringify({
+		version: VERSION,
+		value
+	});
+	if (encoded.length > MAX_ATTRIBUTE_LENGTH) throw new ReviewResolutionProvenanceError({
+		attribute,
+		reason: "invalid",
+		message: `Oversized ${attribute} review provenance.`
+	});
+	return encoded;
+};
+const serializeAttribute = (options) => {
+	const encoded = encodeAttribute(options);
+	return encoded === void 0 ? "" : ` folio:${options.attribute}="${escapeXmlAttribute(encoded)}"`;
+};
+const parseResolutionJoins = (node) => parseAttribute({
+	node,
+	attribute: "resolutionJoins",
+	valid: isResolutionJoins
+});
+const parseBoundaryJoins = (node) => parseAttribute({
+	node,
+	attribute: "boundaryJoins",
+	valid: isBoundaryJoins
+});
+const serializeResolutionJoins = (value) => serializeAttribute({
+	attribute: "resolutionJoins",
+	value,
+	valid: isResolutionJoins
+});
+const serializeBoundaryJoins = (value) => serializeAttribute({
+	attribute: "boundaryJoins",
+	value,
+	valid: isBoundaryJoins
+});
+/** Null carries an owned undefined depth; a missing attribute carries no field. */
+const parseParagraphMarkResolutionJoin = (node) => {
+	const value = parseAttribute({
+		node,
+		attribute: PARAGRAPH_MARK_FIELDS.resolutionJoin.attribute,
+		valid: isEncodedParagraphMarkResolutionJoin
+	});
+	return value === void 0 ? {} : { resolutionJoin: value === null ? void 0 : value };
+};
+const paragraphMarkResolutionJoinOptions = (mark) => ({
+	attribute: PARAGRAPH_MARK_FIELDS.resolutionJoin.attribute,
+	value: Object.hasOwn(mark, "resolutionJoin") ? mark.resolutionJoin ?? null : void 0,
+	valid: isEncodedParagraphMarkResolutionJoin
+});
+const serializeParagraphMarkResolutionJoin = (mark) => serializeAttribute(paragraphMarkResolutionJoinOptions(mark));
+/** Captured paragraph properties compose the same envelope into a parsed XML element. */
+const paragraphMarkResolutionJoinAttributes = (mark) => {
+	const options = paragraphMarkResolutionJoinOptions(mark);
+	const encoded = encodeAttribute(options);
+	return encoded === void 0 ? {} : { [`folio:${options.attribute}`]: encoded };
+};
+//#endregion
+export { ReviewResolutionProvenanceError, isBoundaryJoins, isParagraphMarkResolutionJoin, isResolutionJoins, paragraphMarkResolutionJoinAttributes, parseBoundaryJoins, parseParagraphMarkResolutionJoin, parseResolutionJoins, serializeBoundaryJoins, serializeParagraphMarkResolutionJoin, serializeResolutionJoins };

package/dist/docx/rezip.d.ts

@@ -1,5 +1,8 @@
 import { document_d_exports } from "../types/document.js";
+import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
+import { SaveDiagnosticOptions } from "./saveDiagnostics.js";
 import { BlockContent, Hyperlink } from "../types/content.js";
+import { DocumentBodyAuthorityOptions } from "./serializer/documentSerializer.js";
 import { RawDocxContent } from "./unzip.js";
 import JSZip from "jszip";
 //#region src/docx/rezip.d.ts
@@ -37,16 +40,46 @@ declare class DocxDuplicateSectionCarrierError extends DocxPackageFidelityError
  */
 declare function findMaxRId(relsXml: string): number;
 /**
- * Collect all hyperlinks that have an href but no rId from block content.
- * These are newly created hyperlinks that need relationship entries.
+ * Every serialized section has exactly one model record, and vice versa.
+ *
+ * A split paragraph's duplicated `w:sectPr` is a section nobody added,
+ * repeating the real one's `w:rsidSect` and claiming its revision history too.
+ * Two carriers over one record are therefore invalid regardless of whether a
+ * separate deletion makes the total section count rise, fall, or stay equal.
+ *
+ * The count is a separate invariant: `serializeSectionProperties` fails closed
+ * to `""` for a record holding settings it cannot write, so carrier uniqueness
+ * alone does not prove the package states the sections the model holds.
  */
+declare const assertSectionCarriersMatchModel: ({ doc, serializedSectionCount }: {
+  doc: document_d_exports.Document;
+  serializedSectionCount: number;
+}) => void;
+declare const CanonicalImageRelationshipRefusalError_base: import("better-result").TaggedErrorClass<"CanonicalImageRelationshipRefusalError">;
+declare class CanonicalImageRelationshipRefusalError extends CanonicalImageRelationshipRefusalError_base<{
+  message: string;
+  gap: typeof CANONICAL_GAP.save;
+  part: string;
+  relationshipId: string;
+  reason: "conflict" | "unresolved" | "missingMedia" | "unsafeTarget";
+}> {}
+type PublishCanonicalImageResourcesOptions = {
+  document: document_d_exports.Document;
+  zip: JSZip;
+  compressionLevel: number;
+};
+/** Publish allocated pictures into each owning story without rebinding canonical ids. */
+declare const publishCanonicalImageResources: ({ document, zip, compressionLevel }: PublishCanonicalImageResourcesOptions) => Promise<void>;
+/** Newly authored text links; the census shares the complete owning-part traversal. */
 declare function collectHyperlinksWithoutRId(blocks: BlockContent[]): Hyperlink[];
 /** The selective save boundary must use the same resource census as full repack. */
 declare const hasUnmaterializedInlineResources: (blocks: BlockContent[]) => boolean;
+/** Compare against the already loaded source ZIP, without mutating model or package. */
+declare const hasUnmaterializedHyperlinkBindings: (document: document_d_exports.Document, zip: JSZip) => Promise<boolean>;
 /**
  * Options for repacking DOCX
  */
-type RepackOptions = {
+type RepackOptions = SaveDiagnosticOptions & DocumentBodyAuthorityOptions & {
   /** Compression level (0-9, default: 6) */
   compressionLevel?: number;
   /** Whether to update modification date in docProps/core.xml */
@@ -185,7 +218,22 @@ declare function hasModelDrivenPictureWatermark(doc: document_d_exports.Document
  * `sourceZip` supplies each part as it stands before the save so the rebuilt
  * root can keep any prefix binding only the source document declared.
  */
-declare function collectHeaderFooterUpdates(doc: document_d_exports.Document, sourceZip: JSZip): Promise<Map<string, string>>;
+type CollectHeaderFooterUpdatesOptions = SaveDiagnosticOptions & {
+  sourceZip: JSZip;
+};
+declare function collectHeaderFooterUpdates(doc: document_d_exports.Document, { sourceZip, onDiagnostic }: CollectHeaderFooterUpdatesOptions): Promise<Map<string, string>>;
+type AddedStylesPlan = {
+  type: "unchanged";
+} | {
+  type: "materialize";
+  styles: document_d_exports.StyleDefinitions;
+} | {
+  type: "patch";
+  path: string;
+  xml: string;
+};
+/** One append-only style owner for full repack and selective overlays. */
+declare function planAddedStyles(doc: document_d_exports.Document, originalZip: JSZip): Promise<AddedStylesPlan>;
 /** `word/Footnotes.xml` -> `word/_rels/Footnotes.xml.rels` (casing preserved). */
 declare function notePartRelsPath(partPath: string): string;
 /** Update existing core-property values without synthesizing absent metadata. */
@@ -219,7 +267,7 @@ declare function isDocxBuffer(buffer: ArrayBuffer): boolean;
  * ignored for a document that carries a source package, which keeps the
  * properties that package already states.
  */
-type DocumentPropertiesOptions = {
+type DocumentPropertiesOptions = SaveDiagnosticOptions & DocumentBodyAuthorityOptions & {
   /** `dc:creator` in `docProps/core.xml`. Omitted when absent. */
   creator?: string;
   /** `Application` in `docProps/app.xml`. Omitted, with `AppVersion`, when absent. */
@@ -242,4 +290,4 @@ declare function createEmptyDocx(properties?: DocumentPropertiesOptions): Promis
  */
 declare function createDocx(doc: document_d_exports.Document, properties?: DocumentPropertiesOptions): Promise<ArrayBuffer>;
 //#endregion
-export { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_CONTENT_TYPE, COMMENTS_EXTENDED_PART, COMMENTS_EXTENDED_PART_LOWER, DocumentPropertiesOptions, DocxDuplicateSectionCarrierError, DocxPackageFidelityError, RepackOptions, addCommentsExtendedOverride, addCommentsExtendedRelationship, addMedia, addRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, collectHyperlinksWithoutRId, createDocx, createEmptyDocx, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, isDocxBuffer, notePartRelsPath, removeCommentsExtendedOverride, removeCommentsExtendedRelationship, repackDocx, repackDocxFromRaw, updateCoreProperties, updateDocumentXml, updateMultipleFiles, updateXmlFile, validateDocx, withoutAttachedTemplate };
+export { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_CONTENT_TYPE, COMMENTS_EXTENDED_PART, COMMENTS_EXTENDED_PART_LOWER, CanonicalImageRelationshipRefusalError, DocumentPropertiesOptions, DocxDuplicateSectionCarrierError, DocxPackageFidelityError, RepackOptions, addCommentsExtendedOverride, addCommentsExtendedRelationship, addMedia, addRelationship, applyUpdatesToZip, assertSectionCarriersMatchModel, collectHeaderFooterUpdates, collectHyperlinksWithoutRId, createDocx, createEmptyDocx, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedHyperlinkBindings, hasUnmaterializedInlineResources, isDocxBuffer, notePartRelsPath, planAddedStyles, publishCanonicalImageResources, removeCommentsExtendedOverride, removeCommentsExtendedRelationship, repackDocx, repackDocxFromRaw, updateCoreProperties, updateDocumentXml, updateMultipleFiles, updateXmlFile, validateDocx, withoutAttachedTemplate };