@beyondwork/docx-react-component 1.0.0

package/src/preservation/opaque-fragment-store.ts

@@ -0,0 +1,89 @@
+import type {
+  DocRange,
+  OpaqueFragmentRecord,
+  PreservationStore,
+} from "../model/canonical-document.ts";
+import {
+  describeOpaqueFragment,
+  findOpaqueFragmentsIntersectingRange,
+  getOpaqueFragment,
+  listOpaqueFragments,
+} from "./store.ts";
+
+export interface LockedOpaqueFragment {
+  fragmentId: string;
+  warningId: string;
+  featureClass: "preserve-only";
+  range: DocRange;
+  label: string;
+  detail: string;
+}
+
+export interface OpaqueFragmentDeletionIntent {
+  fragmentId: string;
+  warningId: string;
+  featureClass: "preserve-only";
+  destructive: true;
+  confirmationLabel: "Delete preserved content";
+  confirmationDetail: string;
+  range: DocRange;
+}
+
+export function getLockedOpaqueFragment(
+  store: PreservationStore,
+  fragmentId: string,
+): LockedOpaqueFragment | undefined {
+  const fragment = getOpaqueFragment(store, fragmentId);
+  return fragment ? toLockedOpaqueFragment(fragment) : undefined;
+}
+
+export function listLockedOpaqueFragments(
+  store: PreservationStore,
+): LockedOpaqueFragment[] {
+  return listOpaqueFragments(store).map(toLockedOpaqueFragment);
+}
+
+export function listLockedOpaqueFragmentsIntersectingRange(
+  store: PreservationStore,
+  range: DocRange,
+): LockedOpaqueFragment[] {
+  return findOpaqueFragmentsIntersectingRange(store, range).map(
+    toLockedOpaqueFragment,
+  );
+}
+
+export function createOpaqueFragmentDeletionIntent(
+  store: PreservationStore,
+  fragmentId: string,
+): OpaqueFragmentDeletionIntent | undefined {
+  const lockedFragment = getLockedOpaqueFragment(store, fragmentId);
+  if (!lockedFragment) {
+    return undefined;
+  }
+
+  return {
+    fragmentId: lockedFragment.fragmentId,
+    warningId: lockedFragment.warningId,
+    featureClass: lockedFragment.featureClass,
+    destructive: true,
+    confirmationLabel: "Delete preserved content",
+    confirmationDetail:
+      `${lockedFragment.label} is preserved as an atomic region. ` +
+      "Deleting it removes the preserved payload and may prevent exact OOXML reattachment.",
+    range: lockedFragment.range,
+  };
+}
+
+function toLockedOpaqueFragment(
+  fragment: OpaqueFragmentRecord,
+): LockedOpaqueFragment {
+  const descriptor = describeOpaqueFragment(fragment);
+  return {
+    fragmentId: fragment.fragmentId,
+    warningId: fragment.warningId,
+    featureClass: fragment.featureClass,
+    range: fragment.lastKnownRange,
+    label: descriptor.label,
+    detail: descriptor.detail,
+  };
+}

package/src/preservation/opaque-region.ts

@@ -0,0 +1,233 @@
+import type { CompatibilityFeatureEntry } from "../api/public-types";
+import type { SurfaceBlockSnapshot } from "../api/public-types";
+import type {
+  DocRange,
+  OpaqueFragmentRecord,
+  PreservationStore,
+} from "../model/canonical-document.ts";
+import {
+  createOpaqueFragmentDeletionIntent,
+  getLockedOpaqueFragment,
+  listLockedOpaqueFragments,
+  listLockedOpaqueFragmentsIntersectingRange,
+  type LockedOpaqueFragment,
+  type OpaqueFragmentDeletionIntent,
+} from "./opaque-fragment-store.ts";
+import { describeOpaqueFragment, getOpaqueFragment } from "./store.ts";
+
+export interface OpaqueRegionSurfaceModel {
+  fragmentId: string;
+  warningId: string;
+  featureKey: string;
+  state: "locked-preserve-only";
+  label: string;
+  detail: string;
+  range: DocRange;
+  wholeUnitLabel: string;
+  selectionLabel: string;
+  destructiveAction: OpaqueFragmentDeletionIntent;
+}
+
+export interface OpaqueRegionTrustMessage {
+  eyebrow: string;
+  title: string;
+  body: string;
+  exportState: "ready" | "blocked";
+  exportLabel: string;
+}
+
+export interface OpaqueRegionTrustMessageOptions {
+  blockExport?: boolean;
+  blockExportReason?: string;
+  blockingFeature?: Pick<CompatibilityFeatureEntry, "featureKey" | "featureClass" | "message">;
+}
+
+export function getOpaqueRegionSurfaceModel(
+  store: PreservationStore,
+  fragmentId: string,
+): OpaqueRegionSurfaceModel | undefined {
+  const locked = getLockedOpaqueFragment(store, fragmentId);
+  if (!locked) {
+    return undefined;
+  }
+  const fragment = getOpaqueFragment(store, fragmentId);
+  if (!fragment) {
+    return undefined;
+  }
+
+  return toOpaqueRegionSurfaceModel(
+    fragment,
+    locked,
+    createOpaqueFragmentDeletionIntent(store, fragmentId),
+  );
+}
+
+export function listOpaqueRegionSurfaceModels(
+  store: PreservationStore,
+): OpaqueRegionSurfaceModel[] {
+  return listLockedOpaqueFragments(store).flatMap((locked) => {
+    const fragment = getOpaqueFragment(store, locked.fragmentId);
+    if (!fragment) {
+      return [];
+    }
+
+    return [
+      toOpaqueRegionSurfaceModel(
+        fragment,
+        locked,
+        createOpaqueFragmentDeletionIntent(store, locked.fragmentId),
+      ),
+    ];
+  });
+}
+
+export function listOpaqueRegionSurfaceModelsIntersectingRange(
+  store: PreservationStore,
+  range: DocRange,
+): OpaqueRegionSurfaceModel[] {
+  return listLockedOpaqueFragmentsIntersectingRange(store, range).flatMap((locked) => {
+    const fragment = getOpaqueFragment(store, locked.fragmentId);
+    if (!fragment) {
+      return [];
+    }
+
+    return [
+      toOpaqueRegionSurfaceModel(
+        fragment,
+        locked,
+        createOpaqueFragmentDeletionIntent(store, locked.fragmentId),
+      ),
+    ];
+  });
+}
+
+export function createOpaqueRegionSurfaceModel(
+  fragment: OpaqueFragmentRecord,
+): OpaqueRegionSurfaceModel {
+  const store: PreservationStore = {
+    opaqueFragments: {
+      [fragment.fragmentId]: fragment,
+    },
+    packageParts: {},
+  };
+  const region = getOpaqueRegionSurfaceModel(store, fragment.fragmentId);
+  if (!region) {
+    throw new Error(`Opaque region ${fragment.fragmentId} could not be projected.`);
+  }
+
+  return region;
+}
+
+export function createOpaqueRegionSurfaceModelFromSurfaceBlock(
+  block: Extract<SurfaceBlockSnapshot, { kind: "opaque_block" }>,
+): OpaqueRegionSurfaceModel {
+  return {
+    fragmentId: block.fragmentId,
+    warningId: block.warningId,
+    featureKey: "preserve-only-region",
+    state: "locked-preserve-only",
+    label: block.label,
+    detail: block.detail,
+    range: {
+      from: block.from,
+      to: block.to,
+    },
+    wholeUnitLabel: "Whole-unit only",
+    selectionLabel: `Select preserved region ${block.from}-${block.to}`,
+    destructiveAction: {
+      fragmentId: block.fragmentId,
+      warningId: block.warningId,
+      featureClass: "preserve-only",
+      destructive: true,
+      confirmationLabel: "Delete preserved content",
+      confirmationDetail:
+        `${block.label} is preserved as an atomic region. ` +
+        "Deleting it removes the preserved payload and may prevent exact OOXML reattachment.",
+      range: {
+        from: block.from,
+        to: block.to,
+      },
+    },
+  };
+}
+
+export function createOpaqueRegionTrustMessage(
+  region: OpaqueRegionSurfaceModel,
+  options: OpaqueRegionTrustMessageOptions = {},
+): OpaqueRegionTrustMessage {
+  const blockingFeature = normalizeBlockingFeature(
+    region,
+    options.blockExportReason,
+    options.blockingFeature,
+  );
+  const exportState = options.blockExport ? "blocked" : "ready";
+  const title = options.blockExport
+    ? "Export needs another fix before this snapshot can leave the editor"
+    : "Export remains available while this preserved region stays intact";
+  const baseSentence =
+    `${region.label} stays visible but locked as one preserved unit so Word-specific OOXML can round-trip safely.`;
+  const body = options.blockExport
+    ? blockingFeature
+      ? `${baseSentence} Export is blocked by ${blockingFeature}, not by this preserve-only region alone.`
+      : `${baseSentence} Export is blocked because this snapshot also contains unsupported issues that cannot be preserved as-is.`
+    : `${baseSentence} Internal editing is disabled here, but the document can still export if no unsupported-fatal issues are present.`;
+
+  return {
+    eyebrow: "Preserve-only region",
+    title,
+    body,
+    exportState,
+    exportLabel: exportState === "blocked" ? "export blocked elsewhere" : "export remains available",
+  };
+}
+
+function toOpaqueRegionSurfaceModel(
+  fragment: OpaqueFragmentRecord,
+  locked: LockedOpaqueFragment,
+  deletionIntent: OpaqueFragmentDeletionIntent | undefined,
+): OpaqueRegionSurfaceModel {
+  if (!deletionIntent) {
+    throw new Error(`Missing deletion intent for preserved region ${locked.fragmentId}.`);
+  }
+  const descriptor = describeOpaqueFragment(fragment);
+
+  return {
+    fragmentId: locked.fragmentId,
+    warningId: locked.warningId,
+    featureKey: descriptor.featureKey,
+    state: "locked-preserve-only",
+    label: locked.label,
+    detail: locked.detail,
+    range: locked.range,
+    wholeUnitLabel: "Whole-unit only",
+    selectionLabel: `Select preserved region ${locked.range.from}-${locked.range.to}`,
+    destructiveAction: deletionIntent,
+  };
+}
+
+function normalizeBlockingFeature(
+  region: OpaqueRegionSurfaceModel,
+  blockExportReason?: string,
+  blockingFeature?: Pick<CompatibilityFeatureEntry, "featureKey" | "featureClass" | "message">,
+): string | undefined {
+  if (typeof blockExportReason === "string" && blockExportReason.trim().length > 0) {
+    const trimmedReason = blockExportReason.trim();
+    return trimmedReason.charAt(0).toLowerCase() + trimmedReason.slice(1);
+  }
+  if (!blockingFeature) {
+    return undefined;
+  }
+  if (
+    blockingFeature.featureClass === "preserve-only" &&
+    blockingFeature.featureKey === region.featureKey
+  ) {
+    return undefined;
+  }
+
+  const trimmedMessage = blockingFeature.message.trim();
+  if (trimmedMessage.length > 0) {
+    return trimmedMessage.charAt(0).toLowerCase() + trimmedMessage.slice(1);
+  }
+
+  return blockingFeature.featureKey.replace(/[-_]+/gu, " ");
+}

package/src/preservation/package-preservation.ts

@@ -0,0 +1,120 @@
+import type { PreservedPackagePart } from "../model/canonical-document.ts";
+import { resolveRelationshipTarget } from "../io/ooxml/part-manifest.ts";
+import type { OpcPackage } from "../io/opc/package-reader.ts";
+
+const CORE_NON_PRESERVED_PART_PATHS = new Set([
+  "/docProps/app.xml",
+  "/docProps/core.xml",
+  "/docProps/custom.xml",
+  "/word/fontTable.xml",
+  "/word/numbering.xml",
+  "/word/settings.xml",
+  "/word/styles.xml",
+  "/word/stylesWithEffects.xml",
+  "/word/theme/theme1.xml",
+  "/word/webSettings.xml",
+]);
+
+export function collectPreservedPackageParts(
+  sourcePackage: OpcPackage,
+  commentsPartPath?: string,
+): Record<string, PreservedPackagePart> {
+  return Object.fromEntries(
+    [...sourcePackage.parts.values()]
+      .filter((part) => shouldPreservePackagePart(part.path, part.surfaceKind, commentsPartPath))
+      .map((part) => [
+        part.path,
+        {
+          packagePartName: part.path,
+          contentType: part.contentType ?? "application/octet-stream",
+          relationshipIds: findRelationshipIdsTargetingPart(sourcePackage, part.path),
+        } satisfies PreservedPackagePart,
+      ]),
+  );
+}
+
+export function collectBrokenInternalRelationshipTargets(
+  sourcePackage: OpcPackage,
+): string[] {
+  const brokenTargets: string[] = [];
+
+  for (const relationship of sourcePackage.manifest.packageRelationships) {
+    if (relationship.targetMode !== "internal") {
+      continue;
+    }
+
+    const target = resolveRelationshipTarget(null, relationship);
+    if (!sourcePackage.parts.has(target)) {
+      brokenTargets.push(target);
+    }
+  }
+
+  for (const part of sourcePackage.parts.values()) {
+    for (const relationship of part.relationships) {
+      if (relationship.targetMode !== "internal") {
+        continue;
+      }
+
+      const target = resolveRelationshipTarget(part.path, relationship);
+      if (!sourcePackage.parts.has(target)) {
+        brokenTargets.push(target);
+      }
+    }
+  }
+
+  return [...new Set(brokenTargets)].sort();
+}
+
+export function shouldPreservePackagePart(
+  partPath: string,
+  surfaceKind: OpcPackage["parts"] extends Map<string, infer T>
+    ? T extends { surfaceKind: infer U }
+      ? U
+      : never
+    : never,
+  commentsPartPath?: string,
+): boolean {
+  if (surfaceKind !== "content") {
+    return false;
+  }
+
+  if (
+    partPath === "/word/document.xml" ||
+    partPath === commentsPartPath ||
+    partPath.startsWith("/word/media/") ||
+    CORE_NON_PRESERVED_PART_PATHS.has(partPath)
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+export function findRelationshipIdsTargetingPart(
+  sourcePackage: OpcPackage,
+  targetPartPath: string,
+): string[] {
+  const ids = new Set<string>();
+
+  for (const relationship of sourcePackage.manifest.packageRelationships) {
+    if (
+      relationship.targetMode === "internal" &&
+      resolveRelationshipTarget(null, relationship) === targetPartPath
+    ) {
+      ids.add(relationship.id);
+    }
+  }
+
+  for (const part of sourcePackage.parts.values()) {
+    for (const relationship of part.relationships) {
+      if (
+        relationship.targetMode === "internal" &&
+        resolveRelationshipTarget(part.path, relationship) === targetPartPath
+      ) {
+        ids.add(relationship.id);
+      }
+    }
+  }
+
+  return [...ids].sort();
+}

package/src/preservation/preserved-part-manifest.ts

@@ -0,0 +1,56 @@
+import type {
+  PreservationStore,
+  PreservedPackagePart,
+} from "../model/canonical-document.ts";
+import { listPreservedPackageParts } from "./store.ts";
+
+export interface PreservedPartManifestEntry {
+  packagePartName: string;
+  contentType: string;
+  relationshipIds: string[];
+  label: string;
+  detail: string;
+}
+
+export function listPreservedPartManifestEntries(
+  store: PreservationStore,
+): PreservedPartManifestEntry[] {
+  return listPreservedPackageParts(store).map(toManifestEntry);
+}
+
+export function getPreservedPartManifestEntry(
+  store: PreservationStore,
+  packagePartName: string,
+): PreservedPartManifestEntry | undefined {
+  const part = store.packageParts[packagePartName];
+  return part ? toManifestEntry(part) : undefined;
+}
+
+export function findPreservedPartsReferencingRelationship(
+  store: PreservationStore,
+  relationshipId: string,
+): PreservedPartManifestEntry[] {
+  return listPreservedPackageParts(store)
+    .filter((part) => part.relationshipIds.includes(relationshipId))
+    .map(toManifestEntry);
+}
+
+function toManifestEntry(
+  part: PreservedPackagePart,
+): PreservedPartManifestEntry {
+  const relationshipCount = part.relationshipIds.length;
+  const relationshipDetail =
+    relationshipCount === 0
+      ? "No explicit preserved relationships recorded."
+      : relationshipCount === 1
+        ? `Tracks relationship ${part.relationshipIds[0]}.`
+        : `Tracks ${relationshipCount} preserved relationships.`;
+
+  return {
+    packagePartName: part.packagePartName,
+    contentType: part.contentType,
+    relationshipIds: [...part.relationshipIds],
+    label: `Preserved package part ${part.packagePartName}`,
+    detail: `${part.contentType}. ${relationshipDetail}`,
+  };
+}

package/src/preservation/relationship-retention.ts

@@ -0,0 +1,57 @@
+import type { OpaqueFragmentRecord, PreservationStore } from "../model/canonical-document.ts";
+import type { OpcRelationship } from "../io/ooxml/part-manifest.ts";
+
+export function retainRelationshipsForFragment(
+  fragment: OpaqueFragmentRecord | undefined,
+  relationships: OpcRelationship[],
+  existingRelationshipMap: Map<string, OpcRelationship>,
+  retainedRelationshipIds: Set<string>,
+): void {
+  if (!fragment || fragment.payloadKind !== "xml-subtree") {
+    return;
+  }
+
+  for (const relationshipId of extractReferencedRelationshipIds(fragment.payloadReference)) {
+    if (retainedRelationshipIds.has(relationshipId)) {
+      continue;
+    }
+
+    const relationship = existingRelationshipMap.get(relationshipId);
+    if (!relationship) {
+      continue;
+    }
+
+    relationships.push({ ...relationship });
+    retainedRelationshipIds.add(relationshipId);
+  }
+}
+
+export function retainRelationshipsForStore(
+  store: PreservationStore,
+  relationships: OpcRelationship[],
+  existingRelationshipMap: Map<string, OpcRelationship>,
+  retainedRelationshipIds: Set<string>,
+): void {
+  for (const fragment of Object.values(store.opaqueFragments)) {
+    retainRelationshipsForFragment(
+      fragment,
+      relationships,
+      existingRelationshipMap,
+      retainedRelationshipIds,
+    );
+  }
+}
+
+export function extractReferencedRelationshipIds(xml: string): Set<string> {
+  const relationshipIds = new Set<string>();
+  const relationshipPattern = /\br:id=(["'])([^"']+)\1/gu;
+
+  for (const match of xml.matchAll(relationshipPattern)) {
+    const relationshipId = match[2];
+    if (relationshipId) {
+      relationshipIds.add(relationshipId);
+    }
+  }
+
+  return relationshipIds;
+}