@beyondwork/docx-react-component 1.0.101 → 1.0.102

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.101",
+  "version": "1.0.102",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/io/export/build-app-properties-xml.ts

@@ -40,10 +40,22 @@ export interface AppPropertiesStats {
   words?: number;
   /** Character count. */
   characters?: number;
+  /** Character count including spaces. */
+  charactersWithSpaces?: number;
   /** Line count. */
   lines?: number;
   /** Paragraph count. */
   paragraphs?: number;
+  /** Editing time in minutes. */
+  totalTime?: number;
+  /** Source template name. */
+  template?: string;
+  /** Source company property. */
+  company?: string;
+  /** Source manager property. */
+  manager?: string;
+  /** Document security flag. */
+  docSecurity?: number;
   /** App-version string override; defaults to the package version. */
   appVersion?: string;
   /** Application identifier override; defaults to package.json name@version. */
@@ -58,19 +70,31 @@ export function buildAppPropertiesXml(
   const pages = stats.pages ?? 0;
   const words = stats.words ?? 0;
   const characters = stats.characters ?? 0;
+  const charactersWithSpaces = stats.charactersWithSpaces;
   const lines = stats.lines ?? 0;
   const paragraphs = stats.paragraphs ?? 0;
+  const totalTime = stats.totalTime;
 
   return [
     `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
     `<Properties xmlns="${APP_PROPERTIES_NAMESPACE}" xmlns:vt="${APP_PROPERTIES_VT_NAMESPACE}">`,
     `  <Application>${escapeXml(application)}</Application>`,
     `  <AppVersion>${escapeXml(appVersion)}</AppVersion>`,
+    ...(stats.template ? [`  <Template>${escapeXml(stats.template)}</Template>`] : []),
     `  <Pages>${Math.max(0, Math.round(pages))}</Pages>`,
     `  <Words>${Math.max(0, Math.round(words))}</Words>`,
     `  <Characters>${Math.max(0, Math.round(characters))}</Characters>`,
+    ...(charactersWithSpaces !== undefined
+      ? [`  <CharactersWithSpaces>${Math.max(0, Math.round(charactersWithSpaces))}</CharactersWithSpaces>`]
+      : []),
     `  <Lines>${Math.max(0, Math.round(lines))}</Lines>`,
     `  <Paragraphs>${Math.max(0, Math.round(paragraphs))}</Paragraphs>`,
+    ...(totalTime !== undefined ? [`  <TotalTime>${Math.max(0, Math.round(totalTime))}</TotalTime>`] : []),
+    ...(stats.company ? [`  <Company>${escapeXml(stats.company)}</Company>`] : []),
+    ...(stats.manager ? [`  <Manager>${escapeXml(stats.manager)}</Manager>`] : []),
+    ...(stats.docSecurity !== undefined
+      ? [`  <DocSecurity>${Math.max(0, Math.round(stats.docSecurity))}</DocSecurity>`]
+      : []),
     `</Properties>`,
   ].join("\n");
 }

package/src/io/ooxml/docprops.ts

@@ -0,0 +1,298 @@
+import type { DocumentMetadata } from "../../model/canonical-document.ts";
+import {
+  findFirstChild,
+  localName,
+  parseXml,
+  type XmlElementNode,
+  type XmlNode,
+} from "./_mini-xml.ts";
+
+export interface CorePropertiesView {
+  readonly title?: string;
+  readonly subject?: string;
+  readonly description?: string;
+  readonly creator?: string;
+  readonly language?: string;
+  readonly keywords?: string;
+  readonly category?: string;
+  readonly lastModifiedBy?: string;
+  readonly contentStatus?: string;
+  readonly revision?: string;
+  readonly version?: string;
+  readonly createdUtc?: string;
+  readonly modifiedUtc?: string;
+}
+
+export interface AppPropertiesView {
+  readonly application?: string;
+  readonly appVersion?: string;
+  readonly template?: string;
+  readonly pages?: number;
+  readonly words?: number;
+  readonly characters?: number;
+  readonly charactersWithSpaces?: number;
+  readonly totalTime?: number;
+  readonly company?: string;
+  readonly manager?: string;
+  readonly docSecurity?: number;
+}
+
+export interface CustomPropertyValue {
+  readonly name: string;
+  readonly value: string;
+  readonly valueKind: string;
+}
+
+export interface DocpropsView {
+  readonly coreProperties: CorePropertiesView | null;
+  readonly appProperties: AppPropertiesView | null;
+  readonly customProperties: ReadonlyArray<CustomPropertyValue>;
+  readonly sourcePresence: {
+    readonly core: boolean;
+    readonly app: boolean;
+    readonly custom: boolean;
+  };
+  readonly parseErrors: ReadonlyArray<{
+    readonly part: "core" | "app" | "custom";
+    readonly message: string;
+  }>;
+}
+
+export interface DocpropsParts {
+  readonly core?: Uint8Array;
+  readonly app?: Uint8Array;
+  readonly custom?: Uint8Array;
+}
+
+export interface OpcPartMap {
+  get(path: string): { bytes: Uint8Array } | undefined;
+}
+
+const CORE_PART = "/docProps/core.xml";
+const APP_PART = "/docProps/app.xml";
+const CUSTOM_PART = "/docProps/custom.xml";
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: false });
+
+export function parseDocprops(parts: DocpropsParts): DocpropsView {
+  const parseErrors: { part: "core" | "app" | "custom"; message: string }[] = [];
+
+  let coreProperties: CorePropertiesView | null = null;
+  if (parts.core) {
+    try {
+      coreProperties = parseCoreXml(decodeXmlBytes(parts.core));
+    } catch (err) {
+      parseErrors.push({
+        part: "core",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  let appProperties: AppPropertiesView | null = null;
+  if (parts.app) {
+    try {
+      appProperties = parseAppXml(decodeXmlBytes(parts.app));
+    } catch (err) {
+      parseErrors.push({
+        part: "app",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  let customProperties: ReadonlyArray<CustomPropertyValue> = [];
+  if (parts.custom) {
+    try {
+      customProperties = parseCustomXml(decodeXmlBytes(parts.custom));
+    } catch (err) {
+      parseErrors.push({
+        part: "custom",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return {
+    coreProperties,
+    appProperties,
+    customProperties,
+    sourcePresence: {
+      core: Boolean(parts.core),
+      app: Boolean(parts.app),
+      custom: Boolean(parts.custom),
+    },
+    parseErrors,
+  };
+}
+
+export function parseDocpropsFromOpcParts(parts: OpcPartMap): DocpropsView {
+  const core = parts.get(CORE_PART);
+  const app = parts.get(APP_PART);
+  const custom = parts.get(CUSTOM_PART);
+  return parseDocprops({
+    ...(core ? { core: core.bytes } : {}),
+    ...(app ? { app: app.bytes } : {}),
+    ...(custom ? { custom: custom.bytes } : {}),
+  });
+}
+
+export function parseDocumentMetadataFromOpcParts(parts: OpcPartMap): DocumentMetadata {
+  return docpropsToDocumentMetadata(parseDocpropsFromOpcParts(parts));
+}
+
+export function docpropsToDocumentMetadata(view: DocpropsView): DocumentMetadata {
+  const core = view.coreProperties;
+  const app = view.appProperties;
+  const appProperties = app ? compactObject({
+    application: app.application,
+    appVersion: app.appVersion,
+    template: app.template,
+    pages: app.pages,
+    words: app.words,
+    characters: app.characters,
+    charactersWithSpaces: app.charactersWithSpaces,
+    totalTime: app.totalTime,
+    company: app.company,
+    manager: app.manager,
+    docSecurity: app.docSecurity,
+  }) : undefined;
+  return {
+    ...(core?.title ? { title: core.title } : {}),
+    ...(core?.subject ? { subject: core.subject } : {}),
+    ...(core?.description ? { description: core.description } : {}),
+    ...(core?.creator ? { creator: core.creator } : {}),
+    ...(core?.language ? { language: core.language } : {}),
+    ...(parseKeywords(core?.keywords) ? { keywords: parseKeywords(core?.keywords) } : {}),
+    ...(core?.category ? { category: core.category } : {}),
+    ...(core?.lastModifiedBy ? { lastModifiedBy: core.lastModifiedBy } : {}),
+    ...(core?.contentStatus ? { contentStatus: core.contentStatus } : {}),
+    ...(core?.revision ? { revision: core.revision } : {}),
+    ...(core?.version ? { version: core.version } : {}),
+    ...(core?.createdUtc ? { createdUtc: core.createdUtc } : {}),
+    ...(core?.modifiedUtc ? { modifiedUtc: core.modifiedUtc } : {}),
+    ...(appProperties && Object.keys(appProperties).length > 0 ? { appProperties } : {}),
+    customProperties: Object.fromEntries(
+      view.customProperties.map((property) => [property.name, property.value]),
+    ),
+  };
+}
+
+function parseCoreXml(xml: string): CorePropertiesView {
+  const parsed = parseXml(xml);
+  const root = documentElement(parsed) ?? parsed;
+  return {
+    title: textOfFirstChild(root, "title"),
+    subject: textOfFirstChild(root, "subject"),
+    description: textOfFirstChild(root, "description"),
+    creator: textOfFirstChild(root, "creator"),
+    language: textOfFirstChild(root, "language"),
+    keywords: textOfFirstChild(root, "keywords"),
+    category: textOfFirstChild(root, "category"),
+    lastModifiedBy: textOfFirstChild(root, "lastModifiedBy"),
+    contentStatus: textOfFirstChild(root, "contentStatus"),
+    revision: textOfFirstChild(root, "revision"),
+    version: textOfFirstChild(root, "version"),
+    createdUtc: textOfFirstChild(root, "created"),
+    modifiedUtc: textOfFirstChild(root, "modified"),
+  };
+}
+
+function parseAppXml(xml: string): AppPropertiesView {
+  const parsed = parseXml(xml);
+  const root = documentElement(parsed) ?? parsed;
+  return {
+    application: textOfFirstChild(root, "Application"),
+    appVersion: textOfFirstChild(root, "AppVersion"),
+    template: textOfFirstChild(root, "Template"),
+    pages: parseNonNegativeInt(textOfFirstChild(root, "Pages")),
+    words: parseNonNegativeInt(textOfFirstChild(root, "Words")),
+    characters: parseNonNegativeInt(textOfFirstChild(root, "Characters")),
+    charactersWithSpaces: parseNonNegativeInt(textOfFirstChild(root, "CharactersWithSpaces")),
+    totalTime: parseNonNegativeInt(textOfFirstChild(root, "TotalTime")),
+    company: textOfFirstChild(root, "Company"),
+    manager: textOfFirstChild(root, "Manager"),
+    docSecurity: parseNonNegativeInt(textOfFirstChild(root, "DocSecurity")),
+  };
+}
+
+function parseCustomXml(xml: string): CustomPropertyValue[] {
+  const parsed = parseXml(xml);
+  const root = documentElement(parsed) ?? parsed;
+  const out: CustomPropertyValue[] = [];
+  for (const child of root.children as XmlNode[]) {
+    if (child.type !== "element" || localName(child.name) !== "property") {
+      continue;
+    }
+    const name = child.attributes.name;
+    if (typeof name !== "string" || name.length === 0) {
+      continue;
+    }
+    const valueNode = firstElementChild(child);
+    if (!valueNode) {
+      continue;
+    }
+    out.push({
+      name,
+      value: extractChildText(valueNode).trim(),
+      valueKind: localName(valueNode.name),
+    });
+  }
+  return out;
+}
+
+function decodeXmlBytes(bytes: Uint8Array): string {
+  return UTF8_DECODER.decode(bytes);
+}
+
+function documentElement(root: XmlElementNode): XmlElementNode | undefined {
+  for (const child of root.children) {
+    if (child.type === "element") return child;
+  }
+  return undefined;
+}
+
+function textOfFirstChild(node: XmlElementNode, name: string): string | undefined {
+  const child = findFirstChild(node, name);
+  if (!child) return undefined;
+  const raw = extractChildText(child).trim();
+  return raw.length === 0 ? undefined : raw;
+}
+
+function extractChildText(node: XmlElementNode): string {
+  let out = "";
+  for (const child of node.children) {
+    if (child.type === "text") {
+      out += child.text;
+    } else {
+      out += extractChildText(child);
+    }
+  }
+  return out;
+}
+
+function firstElementChild(node: XmlElementNode): XmlElementNode | undefined {
+  for (const child of node.children) {
+    if (child.type === "element") return child;
+  }
+  return undefined;
+}
+
+function parseNonNegativeInt(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+
+function parseKeywords(raw: string | undefined): string[] | undefined {
+  if (!raw) return undefined;
+  const keywords = raw.split(",").map((entry) => entry.trim()).filter(Boolean);
+  return keywords.length > 0 ? keywords : undefined;
+}
+
+function compactObject<T extends Record<string, string | number | undefined>>(
+  value: T,
+): { [K in keyof T]?: Exclude<T[K], undefined> } {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined),
+  ) as { [K in keyof T]?: Exclude<T[K], undefined> };
+}

package/src/model/canonical-document.ts

@@ -189,13 +189,35 @@ export interface DocumentMetadata {
   title?: string;
   subject?: string;
   description?: string;
+  creator?: string;
   language?: string;
   keywords?: string[];
   category?: string;
+  lastModifiedBy?: string;
+  contentStatus?: string;
+  revision?: string;
+  version?: string;
+  createdUtc?: string;
+  modifiedUtc?: string;
   importMode?: string;
+  appProperties?: DocumentAppProperties;
   customProperties: Record<string, string>;
 }
 
+export interface DocumentAppProperties {
+  application?: string;
+  appVersion?: string;
+  template?: string;
+  pages?: number;
+  words?: number;
+  characters?: number;
+  charactersWithSpaces?: number;
+  totalTime?: number;
+  company?: string;
+  manager?: string;
+  docSecurity?: number;
+}
+
 export interface StylesCatalog {
   paragraphs: Record<string, ParagraphStyleDefinition>;
   characters: Record<string, CharacterStyleDefinition>;
@@ -2408,6 +2430,9 @@ export function repairCanonicalDocumentEnvelope(
   });
   const record = isPlainRecord(value) ? value : {};
   const metadata = isPlainRecord(record.metadata) ? record.metadata : {};
+  const metadataRest = { ...metadata };
+  delete metadataRest.customProperties;
+  delete metadataRest.appProperties;
   const customProperties = isPlainRecord(metadata.customProperties)
     ? (Object.fromEntries(
         Object.entries(metadata.customProperties).filter(
@@ -2415,6 +2440,15 @@ export function repairCanonicalDocumentEnvelope(
         ),
       ) as Record<string, string>)
     : {};
+  const appProperties = isPlainRecord(metadata.appProperties)
+    ? (Object.fromEntries(
+        Object.entries(metadata.appProperties).filter(
+          ([, entry]) =>
+            typeof entry === "string" ||
+            (typeof entry === "number" && Number.isFinite(entry) && entry >= 0),
+        ),
+      ) as DocumentAppProperties)
+    : undefined;
 
   const envelope: Mutable<CanonicalDocument> = {
     ...base,
@@ -2430,7 +2464,8 @@ export function repairCanonicalDocumentEnvelope(
         : base.updatedAt,
     metadata: {
       ...base.metadata,
-      ...metadata,
+      ...metadataRest,
+      ...(appProperties !== undefined ? { appProperties } : {}),
       customProperties,
     } as CanonicalDocument["metadata"],
     styles:
@@ -2614,6 +2649,74 @@ function validateMetadata(
     return;
   }
 
+  for (const field of [
+    "title",
+    "subject",
+    "description",
+    "creator",
+    "language",
+    "category",
+    "lastModifiedBy",
+    "contentStatus",
+    "revision",
+    "version",
+    "createdUtc",
+    "modifiedUtc",
+    "importMode",
+  ]) {
+    if (record[field] !== undefined && typeof record[field] !== "string") {
+      issues.push({
+        path: `${path}.${field}`,
+        message: "metadata string fields must be strings when present.",
+      });
+    }
+  }
+
+  if (
+    record.keywords !== undefined &&
+    (!Array.isArray(record.keywords) ||
+      record.keywords.some((entry) => typeof entry !== "string"))
+  ) {
+    issues.push({
+      path: `${path}.keywords`,
+      message: "metadata keywords must be an array of strings when present.",
+    });
+  }
+
+  if (record.appProperties !== undefined) {
+    const appProperties = asPlainObject(record.appProperties, `${path}.appProperties`, issues);
+    if (appProperties) {
+      for (const field of ["application", "appVersion", "template", "company", "manager"]) {
+        if (appProperties[field] !== undefined && typeof appProperties[field] !== "string") {
+          issues.push({
+            path: `${path}.appProperties.${field}`,
+            message: "appProperties string fields must be strings when present.",
+          });
+        }
+      }
+      for (const field of [
+        "pages",
+        "words",
+        "characters",
+        "charactersWithSpaces",
+        "totalTime",
+        "docSecurity",
+      ]) {
+        if (
+          appProperties[field] !== undefined &&
+          (typeof appProperties[field] !== "number" ||
+            !Number.isFinite(appProperties[field]) ||
+            appProperties[field] < 0)
+        ) {
+          issues.push({
+            path: `${path}.appProperties.${field}`,
+            message: "appProperties numeric fields must be finite non-negative numbers when present.",
+          });
+        }
+      }
+    }
+  }
+
   const customProperties = asPlainObject(record.customProperties, `${path}.customProperties`, issues);
   if (!customProperties) {
     return;

package/src/session/export/stateful-export-pipeline.ts

@@ -136,7 +136,7 @@ export function ensureHostMetadataParts(
   if (!corePropertiesPart || corePropertiesPart.contentType !== CORE_PROPERTIES_CONTENT_TYPE) {
     exportSession.replaceOwnedPart({
       path: CORE_PROPERTIES_PART_PATH,
-      bytes: corePropertiesPart?.bytes ?? new TextEncoder().encode(buildCorePropertiesXml(document)),
+      bytes: new TextEncoder().encode(buildCorePropertiesXml(document)),
       contentType: CORE_PROPERTIES_CONTENT_TYPE,
       compression: corePropertiesPart?.compression,
     });
@@ -146,7 +146,7 @@ export function ensureHostMetadataParts(
   if (!appPropertiesPart || appPropertiesPart.contentType !== APP_PROPERTIES_CONTENT_TYPE) {
     exportSession.replaceOwnedPart({
       path: APP_PROPERTIES_PART_PATH,
-      bytes: appPropertiesPart?.bytes ?? new TextEncoder().encode(buildAppPropertiesXml()),
+      bytes: new TextEncoder().encode(buildAppPropertiesXml(document.metadata.appProperties)),
       contentType: APP_PROPERTIES_CONTENT_TYPE,
       compression: appPropertiesPart?.compression,
     });
@@ -305,11 +305,16 @@ export function buildCorePropertiesXml(document: CanonicalDocumentEnvelope): str
     xmlNode("dc:title", metadata.title),
     xmlNode("dc:subject", metadata.subject),
     xmlNode("dc:description", metadata.description),
+    xmlNode("dc:creator", metadata.creator),
     xmlNode("dc:language", metadata.language),
     xmlNode("cp:keywords", keywords),
     xmlNode("cp:category", metadata.category),
-    xmlNode('dcterms:created xsi:type="dcterms:W3CDTF"', document.createdAt),
-    xmlNode('dcterms:modified xsi:type="dcterms:W3CDTF"', document.updatedAt),
+    xmlNode("cp:lastModifiedBy", metadata.lastModifiedBy),
+    xmlNode("cp:contentStatus", metadata.contentStatus),
+    xmlNode("cp:revision", metadata.revision),
+    xmlNode("cp:version", metadata.version),
+    xmlNode('dcterms:created xsi:type="dcterms:W3CDTF"', metadata.createdUtc ?? document.createdAt),
+    xmlNode('dcterms:modified xsi:type="dcterms:W3CDTF"', metadata.modifiedUtc ?? document.updatedAt),
   ].filter((line): line is string => Boolean(line));
 
   return [

package/src/session/export/stateful-export.ts

@@ -83,6 +83,7 @@ import {
 import { toEditorSessionState } from "../import/canonical-assembly.ts";
 import {
   serializeCanonicalDocumentForExport,
+  serializeNumberingCatalogForExport,
 } from "../shared/session-utils.ts";
 import { withDocumentRelatedParts } from "../import/package-parts.ts";
 import {
@@ -290,6 +291,14 @@ export async function runStatefulExport(
     state.sourcePeoplePartPath ?? PEOPLE_PART_PATH;
   const numberingPartPath =
     state.sourceNumberingPartPath ?? NUMBERING_PART_PATH;
+  const sourceNumberingPart = state.sourceNumberingPartPath
+    ? state.sourcePackage.parts.get(numberingPartPath)
+    : undefined;
+  const numberingSignatureMatch =
+    serializeNumberingCatalogForExport(currentDocument.numbering as NumberingCatalog) ===
+    state.initialNumberingSignature;
+  const canReuseSourceNumberingPart =
+    numberingSignatureMatch && sourceNumberingPart !== undefined;
   const serializedNumberingXml = hasSerializableNumberingEntries(
     currentDocument.numbering as NumberingCatalog,
   )
@@ -303,6 +312,7 @@ export async function runStatefulExport(
         partPath: numberingPartPath,
         existingRelationshipId: state.sourceNumberingRelationshipId,
         include:
+          canReuseSourceNumberingPart ||
           Boolean(serializedNumberingXml) ||
           Boolean(state.sourceNumberingPartPath),
       },
@@ -423,16 +433,22 @@ export async function runStatefulExport(
     relationships: nextRelationships,
   });
 
-  if (serializedNumberingXml || state.sourceNumberingPartPath) {
+  if (canReuseSourceNumberingPart || serializedNumberingXml || state.sourceNumberingPartPath) {
+    const numberingBytes =
+      canReuseSourceNumberingPart && sourceNumberingPart
+        ? sourceNumberingPart.bytes
+        : new TextEncoder().encode(
+          serializedNumberingXml ??
+            `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w:numbering xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"></w:numbering>`,
+        );
+
     exportSession.replaceOwnedPart({
       path: numberingPartPath,
-      bytes: new TextEncoder().encode(
-        serializedNumberingXml ??
-          `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w:numbering xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"></w:numbering>`,
-      ),
+      bytes: numberingBytes,
       contentType:
-        state.sourcePackage.parts.get(numberingPartPath)?.contentType ??
+        sourceNumberingPart?.contentType ??
         WORD_NUMBERING_CONTENT_TYPE,
+      compression: sourceNumberingPart?.compression,
     });
   }
 

package/src/session/import/canonical-assembly.ts

@@ -133,6 +133,7 @@ export function createImportedCanonicalDocument(input: {
   subParts?: SubPartsCatalog;
   parsedStyles?: ParseStylesResult;
   fontTable?: CanonicalDocument["fontTable"];
+  metadata?: CanonicalDocument["metadata"];
   preservation: CanonicalDocument["preservation"];
   diagnostics: CanonicalDocument["diagnostics"];
   review: CanonicalDocument["review"];
@@ -166,9 +167,7 @@ export function createImportedCanonicalDocument(input: {
     docId: createCanonicalDocumentId(input.documentId),
     createdAt: input.timestamp,
     updatedAt: input.timestamp,
-    metadata: {
-      customProperties: {},
-    },
+    metadata: input.metadata ?? { customProperties: {} },
     styles,
     numbering,
     media: input.media,

package/src/session/import/loader-types.ts

@@ -252,7 +252,8 @@ export interface LoadedDocxEditorSession {
  * State captured at import time that the export pipeline consumes to
  * round-trip the package. Carries source bytes, the OPC package
  * snapshot, per-part relationships, preserved-part manifest, and the
- * initial canonical signature used for fast-path byte reuse.
+ * initial canonical signatures used for fast-path byte reuse and
+ * preserve-first per-part export decisions.
  *
  * Load path builds this; `exportDocxEditorSession` consumes it via
  * the closure captured at open time.
@@ -299,6 +300,7 @@ export interface ImportedDocxState {
   preservedCommentDefinitions: readonly ImportedCommentDefinition[];
   blockingCommentDiagnostics: readonly CommentImportDiagnostic[];
   initialCanonicalSignature: string;
+  initialNumberingSignature: string;
   sourceSubPartPaths: {
     headers: Array<{ partPath: string; relationshipId: string }>;
     footers: Array<{ partPath: string; relationshipId: string }>;

package/src/session/import/loader.ts

@@ -97,6 +97,7 @@ import {
 } from "../../io/ooxml/parse-revisions.ts";
 import { parseCommentsFromOoxml } from "../../io/ooxml/parse-comments.ts";
 import { parseNumberingXml } from "../../io/ooxml/parse-numbering.ts";
+import { parseDocumentMetadataFromOpcParts } from "../../io/ooxml/docprops.ts";
 import {
   parseHeaderFooterReferences,
   parseHeaderXml,
@@ -131,6 +132,7 @@ import {
   decodeUtf8,
   extractDocumentRootAttributes,
   serializeCanonicalDocumentForExport,
+  serializeNumberingCatalogForExport,
   toUint8Array,
 } from "../shared/session-utils.ts";
 import {
@@ -285,6 +287,7 @@ export async function loadDocxSessionAsync(
       }),
     );
   }
+  const packageMetadata = parseDocumentMetadataFromOpcParts(sourcePackage.parts);
   stages.emit("opc");
   await scheduler.yield();
   const embeddedWorkflowPayload = parseWorkflowPayloadEnvelopeFromPackage(sourcePackage);
@@ -1018,6 +1021,7 @@ export async function loadDocxSessionAsync(
       subParts,
       parsedStyles,
       fontTable: parsedFontTable,
+      metadata: packageMetadata,
       preservation: buildImportPreservation(normalizedDocument.preservation, sourcePackage, [
         mainDocumentPath,
         numberingPartPath,
@@ -1152,6 +1156,9 @@ export async function loadDocxSessionAsync(
         BLOCKING_COMMENT_DIAGNOSTIC_CODES.has(diagnostic.code),
       ),
       initialCanonicalSignature: serializeCanonicalDocumentForExport(document),
+      initialNumberingSignature: serializeNumberingCatalogForExport(
+        document.numbering as _NumberingCatalog,
+      ),
       sourceSubPartPaths: {
         headers: sourceHeaderPaths,
         footers: sourceFooterPaths,
@@ -1229,6 +1236,7 @@ export function loadDocxSessionSync(
       }),
     );
   }
+  const packageMetadata = parseDocumentMetadataFromOpcParts(sourcePackage.parts);
   stages.emit("opc");
   const embeddedWorkflowPayload = parseWorkflowPayloadEnvelopeFromPackage(sourcePackage);
   const embeddedWorkflowMetadata = embeddedWorkflowPayload?.workflowMetadata;
@@ -1697,6 +1705,7 @@ export function loadDocxSessionSync(
       subParts,
       parsedStyles,
       fontTable: parsedFontTable,
+      metadata: packageMetadata,
       preservation: buildImportPreservation(normalizedDocument.preservation, sourcePackage, [
         mainDocumentPath,
         numberingPartPath,
@@ -1808,6 +1817,9 @@ export function loadDocxSessionSync(
         BLOCKING_COMMENT_DIAGNOSTIC_CODES.has(diagnostic.code),
       ),
       initialCanonicalSignature: serializeCanonicalDocumentForExport(document),
+      initialNumberingSignature: serializeNumberingCatalogForExport(
+        document.numbering as _NumberingCatalog,
+      ),
       sourceSubPartPaths: {
         headers: sourceHeaderPaths,
         footers: sourceFooterPaths,

package/src/session/import/source-package-evidence.ts

@@ -0,0 +1,405 @@
+import type { OpcPackage } from "../../io/opc/package-reader.ts";
+import { readOpcPackage } from "../../io/opc/package-reader.ts";
+import { sha256Hex } from "../../io/source-package-provenance.ts";
+import {
+  normalizePartPath,
+  resolveRelationshipTarget,
+  type OpcPackagePart,
+  type OpcRelationship,
+} from "../../io/ooxml/part-manifest.ts";
+import { parseXml } from "../../io/ooxml/xml-parser.ts";
+import type { XmlElementNode } from "../../io/ooxml/xml-element.ts";
+import { localName } from "../../io/ooxml/xml-attr-helpers.ts";
+import {
+  resolveMainDocumentPartPath,
+} from "./part-discovery.ts";
+
+export interface SourcePackageElementCounts {
+  tables: number;
+  tableRows: number;
+  tableCells: number;
+  anchors: number;
+  inlineDrawings: number;
+  drawings: number;
+  vmlShapes: number;
+  contentControls: number;
+  fieldMarkers: number;
+  fieldInstructions: number;
+  simpleFields: number;
+  bookmarks: number;
+  footnotes: number;
+  endnotes: number;
+}
+
+export interface SourcePackagePartEvidence {
+  path: string;
+  storyKind: SourcePackageStoryKind;
+  contentType: string | null;
+  byteLength: number;
+  relationshipCount: number;
+  counts: SourcePackageElementCounts;
+}
+
+export interface SourcePackageRelationshipEvidence {
+  sourcePartPath: string | null;
+  relationshipId: string;
+  relationshipType: string;
+  targetMode: OpcRelationship["targetMode"];
+  target: string;
+  resolvedTarget: string;
+  targetExists: boolean;
+}
+
+export interface SourcePackageEvidence {
+  schemaVersion: 1;
+  docId: string;
+  sourceLabel?: string;
+  sha256Hex: string;
+  sourceByteLength: number;
+  mainDocumentPartPath?: string;
+  partCount: number;
+  contentPartCount: number;
+  relationshipCount: number;
+  internalRelationshipCount: number;
+  externalRelationshipCount: number;
+  brokenInternalRelationshipCount: number;
+  counts: SourcePackageElementCounts & {
+    headers: number;
+    footers: number;
+    mediaParts: number;
+    imageParts: number;
+    chartParts: number;
+    embeddedParts: number;
+    customXmlParts: number;
+    commentsParts: number;
+    numberingParts: number;
+    settingsParts: number;
+    themeParts: number;
+  };
+  parts: SourcePackagePartEvidence[];
+  relationships: SourcePackageRelationshipEvidence[];
+  parseErrors: Array<{ partPath: string; message: string }>;
+}
+
+export type SourcePackageStoryKind =
+  | "main-document"
+  | "header"
+  | "footer"
+  | "footnotes"
+  | "endnotes"
+  | "comments"
+  | "numbering"
+  | "settings"
+  | "styles"
+  | "font-table"
+  | "theme"
+  | "chart"
+  | "media"
+  | "embedded"
+  | "custom-xml"
+  | "relationships"
+  | "content-types"
+  | "other";
+
+const ZERO_COUNTS: SourcePackageElementCounts = {
+  tables: 0,
+  tableRows: 0,
+  tableCells: 0,
+  anchors: 0,
+  inlineDrawings: 0,
+  drawings: 0,
+  vmlShapes: 0,
+  contentControls: 0,
+  fieldMarkers: 0,
+  fieldInstructions: 0,
+  simpleFields: 0,
+  bookmarks: 0,
+  footnotes: 0,
+  endnotes: 0,
+};
+
+export function createSourcePackageEvidenceFromBytes(
+  input: {
+    bytes: Uint8Array | ArrayBuffer;
+    docId: string;
+    sourceLabel?: string;
+  },
+): SourcePackageEvidence {
+  const bytes = input.bytes instanceof Uint8Array
+    ? input.bytes
+    : new Uint8Array(input.bytes);
+  return createSourcePackageEvidence(readOpcPackage(bytes), {
+    docId: input.docId,
+    sourceLabel: input.sourceLabel,
+    sha256Hex: sha256Hex(bytes),
+  });
+}
+
+export function createSourcePackageEvidence(
+  sourcePackage: OpcPackage,
+  input: {
+    docId: string;
+    sourceLabel?: string;
+    sha256Hex?: string;
+  },
+): SourcePackageEvidence {
+  const mainDocumentPartPath = resolveMainDocumentPartPath(sourcePackage);
+  const parseErrors: SourcePackageEvidence["parseErrors"] = [];
+  const parts = [...sourcePackage.parts.values()]
+    .sort((left, right) => left.path.localeCompare(right.path))
+    .map((part) => summarizePart(part, mainDocumentPartPath, parseErrors));
+  const relationships = collectRelationships(sourcePackage);
+  const relationshipCount = relationships.length;
+  const internalRelationshipCount = relationships.filter(
+    (relationship) => relationship.targetMode === "internal",
+  ).length;
+  const externalRelationshipCount = relationshipCount - internalRelationshipCount;
+  const brokenInternalRelationshipCount = relationships.filter(
+    (relationship) =>
+      relationship.targetMode === "internal" && !relationship.targetExists,
+  ).length;
+  const contentParts = parts.filter(
+    (part) => part.storyKind !== "relationships" && part.storyKind !== "content-types",
+  );
+  const aggregateCounts = aggregateElementCounts(parts.map((part) => part.counts));
+
+  return {
+    schemaVersion: 1,
+    docId: input.docId,
+    ...(input.sourceLabel !== undefined ? { sourceLabel: input.sourceLabel } : {}),
+    sha256Hex: input.sha256Hex ?? "",
+    sourceByteLength: sourcePackage.sourceByteLength,
+    ...(mainDocumentPartPath !== undefined ? { mainDocumentPartPath } : {}),
+    partCount: sourcePackage.parts.size,
+    contentPartCount: contentParts.length,
+    relationshipCount,
+    internalRelationshipCount,
+    externalRelationshipCount,
+    brokenInternalRelationshipCount,
+    counts: {
+      ...aggregateCounts,
+      headers: countParts(parts, "header"),
+      footers: countParts(parts, "footer"),
+      mediaParts: countParts(parts, "media"),
+      imageParts: parts.filter((part) => part.contentType?.startsWith("image/")).length,
+      chartParts: countParts(parts, "chart"),
+      embeddedParts: countParts(parts, "embedded"),
+      customXmlParts: countParts(parts, "custom-xml"),
+      commentsParts: countParts(parts, "comments"),
+      numberingParts: countParts(parts, "numbering"),
+      settingsParts: countParts(parts, "settings"),
+      themeParts: countParts(parts, "theme"),
+    },
+    parts,
+    relationships,
+    parseErrors,
+  };
+}
+
+function summarizePart(
+  part: OpcPackagePart,
+  mainDocumentPartPath: string | undefined,
+  parseErrors: SourcePackageEvidence["parseErrors"],
+): SourcePackagePartEvidence {
+  const storyKind = classifyPart(part, mainDocumentPartPath);
+  return {
+    path: part.path,
+    storyKind,
+    contentType: part.contentType,
+    byteLength: part.bytes.byteLength,
+    relationshipCount: part.relationships.length,
+    counts: countPartElements(part, storyKind, parseErrors),
+  };
+}
+
+function countPartElements(
+  part: OpcPackagePart,
+  storyKind: SourcePackageStoryKind,
+  parseErrors: SourcePackageEvidence["parseErrors"],
+): SourcePackageElementCounts {
+  if (!shouldParseXmlPart(part, storyKind)) {
+    return { ...ZERO_COUNTS };
+  }
+
+  try {
+    return countElements(parseXml(new TextDecoder("utf-8").decode(part.bytes)));
+  } catch (error) {
+    parseErrors.push({
+      partPath: part.path,
+      message: error instanceof Error ? error.message : String(error),
+    });
+    return { ...ZERO_COUNTS };
+  }
+}
+
+function shouldParseXmlPart(
+  part: OpcPackagePart,
+  storyKind: SourcePackageStoryKind,
+): boolean {
+  if (part.surfaceKind !== "content") {
+    return false;
+  }
+  if (storyKind === "media" || storyKind === "embedded") {
+    return false;
+  }
+  return (
+    part.contentType?.includes("xml") === true ||
+    part.path.endsWith(".xml")
+  );
+}
+
+function countElements(root: XmlElementNode): SourcePackageElementCounts {
+  const counts = { ...ZERO_COUNTS };
+  const visit = (node: XmlElementNode): void => {
+    const name = localName(node.name);
+    switch (name) {
+      case "tbl":
+        counts.tables += 1;
+        break;
+      case "tr":
+        counts.tableRows += 1;
+        break;
+      case "tc":
+        counts.tableCells += 1;
+        break;
+      case "anchor":
+        counts.anchors += 1;
+        break;
+      case "inline":
+        counts.inlineDrawings += 1;
+        break;
+      case "drawing":
+        counts.drawings += 1;
+        break;
+      case "shape":
+        counts.vmlShapes += 1;
+        break;
+      case "sdt":
+        counts.contentControls += 1;
+        break;
+      case "fldChar":
+        counts.fieldMarkers += 1;
+        break;
+      case "instrText":
+        counts.fieldInstructions += 1;
+        break;
+      case "fldSimple":
+        counts.simpleFields += 1;
+        break;
+      case "bookmarkStart":
+        counts.bookmarks += 1;
+        break;
+      case "footnote":
+        counts.footnotes += 1;
+        break;
+      case "endnote":
+        counts.endnotes += 1;
+        break;
+    }
+
+    for (const child of node.children) {
+      if (child.type === "element") {
+        visit(child);
+      }
+    }
+  };
+
+  visit(root);
+  return counts;
+}
+
+function collectRelationships(
+  sourcePackage: OpcPackage,
+): SourcePackageRelationshipEvidence[] {
+  const relationships: SourcePackageRelationshipEvidence[] = [];
+  const pushRelationship = (
+    sourcePartPath: string | null,
+    relationship: OpcRelationship,
+  ): void => {
+    const resolvedTarget =
+      relationship.targetMode === "internal"
+        ? resolveRelationshipTarget(sourcePartPath, relationship)
+        : relationship.target;
+    relationships.push({
+      sourcePartPath,
+      relationshipId: relationship.id,
+      relationshipType: relationship.type,
+      targetMode: relationship.targetMode,
+      target: relationship.target,
+      resolvedTarget,
+      targetExists:
+        relationship.targetMode === "external" ||
+        sourcePackage.parts.has(normalizePartPath(resolvedTarget)),
+    });
+  };
+
+  for (const relationship of sourcePackage.manifest.packageRelationships) {
+    pushRelationship(null, relationship);
+  }
+  for (const part of sourcePackage.parts.values()) {
+    for (const relationship of part.relationships) {
+      pushRelationship(part.path, relationship);
+    }
+  }
+
+  return relationships.sort((left, right) => {
+    const leftKey = `${left.sourcePartPath ?? ""}:${left.relationshipId}`;
+    const rightKey = `${right.sourcePartPath ?? ""}:${right.relationshipId}`;
+    return leftKey.localeCompare(rightKey);
+  });
+}
+
+function classifyPart(
+  part: OpcPackagePart,
+  mainDocumentPartPath: string | undefined,
+): SourcePackageStoryKind {
+  const path = part.path;
+  if (part.surfaceKind === "relationships") return "relationships";
+  if (part.surfaceKind === "content-types") return "content-types";
+  if (mainDocumentPartPath && path === mainDocumentPartPath) return "main-document";
+  if (/^\/word\/header\d*\.xml$/u.test(path)) return "header";
+  if (/^\/word\/footer\d*\.xml$/u.test(path)) return "footer";
+  if (path === "/word/footnotes.xml") return "footnotes";
+  if (path === "/word/endnotes.xml") return "endnotes";
+  if (path.startsWith("/word/comments")) return "comments";
+  if (path === "/word/numbering.xml") return "numbering";
+  if (path === "/word/settings.xml") return "settings";
+  if (path === "/word/styles.xml") return "styles";
+  if (path === "/word/fontTable.xml") return "font-table";
+  if (path.startsWith("/word/theme/")) return "theme";
+  if (path.startsWith("/word/charts/")) return "chart";
+  if (path.startsWith("/word/media/")) return "media";
+  if (path.startsWith("/word/embeddings/")) return "embedded";
+  if (path.startsWith("/customXml/") && path.endsWith(".xml")) return "custom-xml";
+  return "other";
+}
+
+function aggregateElementCounts(
+  countsList: SourcePackageElementCounts[],
+): SourcePackageElementCounts {
+  const aggregate = { ...ZERO_COUNTS };
+  for (const counts of countsList) {
+    aggregate.tables += counts.tables;
+    aggregate.tableRows += counts.tableRows;
+    aggregate.tableCells += counts.tableCells;
+    aggregate.anchors += counts.anchors;
+    aggregate.inlineDrawings += counts.inlineDrawings;
+    aggregate.drawings += counts.drawings;
+    aggregate.vmlShapes += counts.vmlShapes;
+    aggregate.contentControls += counts.contentControls;
+    aggregate.fieldMarkers += counts.fieldMarkers;
+    aggregate.fieldInstructions += counts.fieldInstructions;
+    aggregate.simpleFields += counts.simpleFields;
+    aggregate.bookmarks += counts.bookmarks;
+    aggregate.footnotes += counts.footnotes;
+    aggregate.endnotes += counts.endnotes;
+  }
+  return aggregate;
+}
+
+function countParts(
+  parts: SourcePackagePartEvidence[],
+  storyKind: SourcePackageStoryKind,
+): number {
+  return parts.filter((part) => part.storyKind === storyKind).length;
+}

package/src/session/shared/session-utils.ts

@@ -16,6 +16,9 @@
  *     signature wrapper that zeroes out `docId` / `createdAt` /
  *     `updatedAt` so structural comparison doesn't falsely register
  *     semantic drift.
+ *   - `serializeNumberingCatalogForExport` — numbering-only signature
+ *     used by export to preserve source numbering bytes when unrelated
+ *     document edits force a package rewrite.
  *
  * P6-clean: imports only from `src/model/**` + `src/api/**`.
  */
@@ -80,3 +83,9 @@ export function serializeCanonicalDocumentForExport(
     updatedAt: "__export__",
   });
 }
+
+export function serializeNumberingCatalogForExport(
+  numbering: NumberingCatalog,
+): string {
+  return createCanonicalDocumentSignature(numbering);
+}