@beyondwork/docx-react-component 1.0.29 → 1.0.31

package/src/compare/export-redlines.ts

@@ -0,0 +1,280 @@
+import type { OpcRelationship } from "../io/ooxml/part-manifest.ts";
+import { serializeMainDocument } from "../io/export/serialize-main-document.ts";
+import {
+  WORD_NUMBERING_CONTENT_TYPE,
+  serializeNumberingXml,
+} from "../io/export/serialize-numbering.ts";
+import { serializeRuntimeRevisionsIntoDocumentXml } from "../io/export/serialize-runtime-revisions.ts";
+import { splitDocumentAtReviewBoundaries } from "../io/export/split-review-boundaries.ts";
+import {
+  createCommentExportIdMap,
+  serializeCommentAnchorsIntoDocumentXml,
+  serializeMergedCommentsXml,
+} from "../io/export/serialize-comments.ts";
+import { createExportSession } from "../io/export/export-session.ts";
+import {
+  DOCX_DOCUMENT_CONTENT_TYPE,
+  DOCX_MIME_TYPE,
+  writeDocxPackage,
+} from "../io/opc/docx-package.ts";
+import type { OpcPackage } from "../io/opc/package-reader.ts";
+import { readOpcPackage } from "../io/opc/package-reader.ts";
+import { createCommentStoreFromRuntimeComments } from "../review/store/runtime-comment-store.ts";
+import type { RevisionRecord as ReviewRevisionRecord } from "../review/store/revision-types.ts";
+import type { VersionCompareResult } from "./diff-engine.ts";
+
+const MAIN_DOCUMENT_PATH = "/word/document.xml";
+const NUMBERING_PART_PATH = "/word/numbering.xml";
+const COMMENTS_PART_PATH = "/word/comments.xml";
+const COMMENTS_EXTENDED_PART_PATH = "/word/commentsExtended.xml";
+const COMMENTS_IDS_PART_PATH = "/word/commentsIds.xml";
+const PEOPLE_PART_PATH = "/word/people.xml";
+const NUMBERING_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering";
+const COMMENTS_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
+const COMMENTS_EXTENDED_RELATIONSHIP_TYPE =
+  "http://schemas.microsoft.com/office/2011/relationships/commentsExtended";
+const COMMENTS_IDS_RELATIONSHIP_TYPE =
+  "http://schemas.microsoft.com/office/2016/09/relationships/commentsIds";
+const PEOPLE_RELATIONSHIP_TYPE =
+  "http://schemas.microsoft.com/office/2011/relationships/people";
+const COMMENTS_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml";
+const COMMENTS_EXTENDED_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml";
+const COMMENTS_IDS_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml";
+const PEOPLE_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.people+xml";
+
+export interface ExportComparedDocumentOptions {
+  fileName?: string;
+  sourcePackage?: OpcPackage;
+}
+
+export interface ExportComparedDocumentResult {
+  bytes: Uint8Array;
+  mimeType: string;
+  fileName: string;
+}
+
+export function exportComparedDocumentRedlines(
+  result: VersionCompareResult,
+  options: ExportComparedDocumentOptions = {},
+): ExportComparedDocumentResult {
+  const sourcePackage =
+    options.sourcePackage ??
+    readOpcPackage(
+      writeDocxPackage({
+        documentXml: `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body><w:p/><w:sectPr/></w:body></w:document>`,
+      }),
+    );
+  const existingRelationships =
+    sourcePackage.parts.get(MAIN_DOCUMENT_PATH)?.relationships ?? [];
+
+  const commentThreads = Object.values(
+    createCommentStoreFromRuntimeComments(result.comparedDocument.review.comments).threads,
+  );
+  const actionableRevisions = toReviewRevisionRecords(result.comparedDocument.review.revisions);
+  const serialized = serializeMainDocument(
+    splitDocumentAtReviewBoundaries(
+      result.comparedDocument.content as never,
+      commentThreads,
+      actionableRevisions,
+    ) as never,
+    result.comparedDocument.preservation,
+    existingRelationships,
+    {
+      media: result.comparedDocument.media,
+    },
+  );
+  const revisionDocument = serializeRuntimeRevisionsIntoDocumentXml(
+    serialized.documentXml,
+    actionableRevisions,
+    serialized.paragraphBoundaries,
+  );
+  if (revisionDocument.skippedRevisionIds.length > 0) {
+    throw new Error(
+      `Compare export skipped ${revisionDocument.skippedRevisionIds.length} revision markers.`,
+    );
+  }
+  const exportCommentIds = createCommentExportIdMap(commentThreads);
+  const serializedComments = serializeMergedCommentsXml(commentThreads, {
+    exportCommentIds,
+  });
+  const annotatedDocument = serializeCommentAnchorsIntoDocumentXml(
+    revisionDocument.documentXml,
+    commentThreads,
+    undefined,
+    {
+      exportCommentIds,
+    },
+  );
+  if (annotatedDocument.skippedCommentIds.length > 0) {
+    throw new Error(
+      `Compare export skipped ${annotatedDocument.skippedCommentIds.length} comment anchors.`,
+    );
+  }
+
+  const numberingXml = hasNumberingEntries(result.comparedDocument.numbering)
+    ? serializeNumberingXml(result.comparedDocument.numbering)
+    : undefined;
+  const relationships = withOptionalRelatedPart(
+    withOptionalRelatedPart(
+      withOptionalRelatedPart(
+        withOptionalRelatedPart(
+          withOptionalRelatedPart(
+            serialized.relationships,
+            existingRelationships,
+            NUMBERING_RELATIONSHIP_TYPE,
+            "numbering.xml",
+            Boolean(numberingXml),
+          ),
+          existingRelationships,
+          COMMENTS_RELATIONSHIP_TYPE,
+          "comments.xml",
+          serializedComments.serializedCommentIds.length > 0,
+        ),
+        existingRelationships,
+        COMMENTS_EXTENDED_RELATIONSHIP_TYPE,
+        "commentsExtended.xml",
+        Boolean(serializedComments.commentsExtendedXml),
+      ),
+      existingRelationships,
+      COMMENTS_IDS_RELATIONSHIP_TYPE,
+      "commentsIds.xml",
+      Boolean(serializedComments.commentsIdsXml),
+    ),
+    existingRelationships,
+    PEOPLE_RELATIONSHIP_TYPE,
+    "people.xml",
+    Boolean(serializedComments.peopleXml),
+  );
+  const exportSession = createExportSession(sourcePackage, [
+    MAIN_DOCUMENT_PATH,
+    ...(numberingXml ? [NUMBERING_PART_PATH] : []),
+    ...(serializedComments.serializedCommentIds.length > 0 ? [COMMENTS_PART_PATH] : []),
+    ...(serializedComments.commentsExtendedXml ? [COMMENTS_EXTENDED_PART_PATH] : []),
+    ...(serializedComments.commentsIdsXml ? [COMMENTS_IDS_PART_PATH] : []),
+    ...(serializedComments.peopleXml ? [PEOPLE_PART_PATH] : []),
+  ]);
+
+  exportSession.replaceOwnedPart({
+    path: MAIN_DOCUMENT_PATH,
+    bytes: new TextEncoder().encode(annotatedDocument.documentXml),
+    contentType: DOCX_DOCUMENT_CONTENT_TYPE,
+    relationships,
+  });
+
+  if (numberingXml) {
+    exportSession.replaceOwnedPart({
+      path: NUMBERING_PART_PATH,
+      bytes: new TextEncoder().encode(numberingXml),
+      contentType:
+        sourcePackage.parts.get(NUMBERING_PART_PATH)?.contentType ?? WORD_NUMBERING_CONTENT_TYPE,
+    });
+  }
+
+  if (serializedComments.serializedCommentIds.length > 0) {
+    exportSession.replaceOwnedPart({
+      path: COMMENTS_PART_PATH,
+      bytes: new TextEncoder().encode(serializedComments.commentsXml),
+      contentType:
+        sourcePackage.parts.get(COMMENTS_PART_PATH)?.contentType ?? COMMENTS_CONTENT_TYPE,
+    });
+  }
+
+  if (serializedComments.commentsExtendedXml) {
+    exportSession.replaceOwnedPart({
+      path: COMMENTS_EXTENDED_PART_PATH,
+      bytes: new TextEncoder().encode(serializedComments.commentsExtendedXml),
+      contentType:
+        sourcePackage.parts.get(COMMENTS_EXTENDED_PART_PATH)?.contentType ??
+        COMMENTS_EXTENDED_CONTENT_TYPE,
+    });
+  }
+
+  if (serializedComments.commentsIdsXml) {
+    exportSession.replaceOwnedPart({
+      path: COMMENTS_IDS_PART_PATH,
+      bytes: new TextEncoder().encode(serializedComments.commentsIdsXml),
+      contentType:
+        sourcePackage.parts.get(COMMENTS_IDS_PART_PATH)?.contentType ?? COMMENTS_IDS_CONTENT_TYPE,
+    });
+  }
+
+  if (serializedComments.peopleXml) {
+    exportSession.replaceOwnedPart({
+      path: PEOPLE_PART_PATH,
+      bytes: new TextEncoder().encode(serializedComments.peopleXml),
+      contentType:
+        sourcePackage.parts.get(PEOPLE_PART_PATH)?.contentType ?? PEOPLE_CONTENT_TYPE,
+    });
+  }
+
+  return {
+    bytes: exportSession.serialize(),
+    mimeType: DOCX_MIME_TYPE,
+    fileName: options.fileName ?? `${result.target.name}-compared.docx`,
+  };
+}
+
+function toReviewRevisionRecords(
+  revisions: VersionCompareResult["comparedDocument"]["review"]["revisions"],
+): ReviewRevisionRecord[] {
+  return Object.values(revisions).map((revision) => ({
+    revisionId: revision.changeId,
+    kind: revision.kind,
+    anchor: revision.anchor,
+    authorId: revision.authorId ?? "Version Compare",
+    createdAt: revision.createdAt,
+    warningIds: [...(revision.warningIds ?? [])],
+    metadata: {
+      source: revision.metadata?.source ?? "runtime",
+      preserveOnlyReason: revision.metadata?.preserveOnlyReason,
+      importedRevisionForm: revision.metadata?.importedRevisionForm,
+      originalRevisionType: revision.metadata?.originalRevisionType,
+      ooxmlRevisionId: revision.metadata?.ooxmlRevisionId,
+    },
+    status: revision.status === "open" ? "active" : revision.status,
+  }));
+}
+
+function hasNumberingEntries(
+  numbering: VersionCompareResult["comparedDocument"]["numbering"],
+): boolean {
+  return (
+    Object.keys(numbering.abstractDefinitions).length > 0 ||
+    Object.keys(numbering.instances).length > 0
+  );
+}
+
+function withOptionalRelatedPart(
+  relationships: readonly OpcRelationship[],
+  existingRelationships: readonly OpcRelationship[],
+  relationshipType: string,
+  target: string,
+  includePart: boolean,
+): OpcRelationship[] {
+  const next = relationships.map((relationship) => ({ ...relationship }));
+  if (!includePart) {
+    return next;
+  }
+
+  const existing = next.find((relationship) => relationship.type === relationshipType);
+  if (existing) {
+    return next;
+  }
+
+  const fallbackId =
+    existingRelationships.find((relationship) => relationship.type === relationshipType)?.id ??
+    `rId${next.length + 1}`;
+  next.push({
+    id: fallbackId,
+    type: relationshipType,
+    target,
+    targetMode: "internal",
+  });
+  return next;
+}

package/src/compare/index.ts

@@ -0,0 +1,25 @@
+export {
+  compareDocumentSnapshots,
+  type CompareChange,
+  type CompareChangeKind,
+  type CompareDocumentVersionsOptions,
+  type CompareVersionRef,
+  type VersionCompareResult,
+} from "./diff-engine.ts";
+
+export {
+  exportComparedDocumentRedlines,
+  type ExportComparedDocumentOptions,
+  type ExportComparedDocumentResult,
+} from "./export-redlines.ts";
+
+export {
+  buildVersionAuditTrail,
+  createDocumentVersionSnapshot,
+  createDocumentVersionSnapshotId,
+  lockDocumentVersionSnapshot,
+  saveDocumentVersionSnapshot,
+  type CreateDocumentVersionSnapshotOptions,
+  type DocumentVersionSnapshot,
+  type VersionAuditEntry,
+} from "./snapshot.ts";

package/src/compare/snapshot.ts

@@ -0,0 +1,97 @@
+import {
+  createCanonicalDocumentSignature,
+  projectCanonicalDocument,
+  type CanonicalDocument,
+} from "../model/canonical-document.ts";
+
+export interface DocumentVersionSnapshot {
+  snapshotVersion: "document-version-snapshot/1";
+  versionId: string;
+  name: string;
+  createdAt: string;
+  documentId: string;
+  documentSignature: string;
+  canonicalDocument: CanonicalDocument;
+}
+
+export interface CreateDocumentVersionSnapshotOptions {
+  versionId?: string;
+  name: string;
+  createdAt?: string;
+}
+
+export function createDocumentVersionSnapshotId(
+  document: Pick<CanonicalDocument, "docId">,
+  name: string,
+): string {
+  return `${document.docId}:${name}`;
+}
+
+export function createDocumentVersionSnapshot(
+  document: CanonicalDocument,
+  options: CreateDocumentVersionSnapshotOptions,
+): DocumentVersionSnapshot {
+  const canonicalDocument = projectCanonicalDocument(document);
+  return {
+    snapshotVersion: "document-version-snapshot/1",
+    versionId:
+      options.versionId ?? createDocumentVersionSnapshotId(canonicalDocument, options.name),
+    name: options.name,
+    createdAt: options.createdAt ?? canonicalDocument.updatedAt,
+    documentId: canonicalDocument.docId,
+    documentSignature: createCanonicalDocumentSignature(canonicalDocument),
+    canonicalDocument,
+  };
+}
+
+export function saveDocumentVersionSnapshot(
+  snapshots: readonly DocumentVersionSnapshot[],
+  snapshot: DocumentVersionSnapshot,
+): DocumentVersionSnapshot[] {
+  const next = snapshots.filter((entry) => entry.versionId !== snapshot.versionId);
+  next.push(snapshot);
+  return next.sort(compareDocumentVersionSnapshots);
+}
+
+export interface VersionAuditEntry {
+  versionId: string;
+  name: string;
+  createdAt: string;
+  documentSignature: string;
+  action: "created" | "compared" | "locked";
+}
+
+export function buildVersionAuditTrail(
+  snapshots: readonly DocumentVersionSnapshot[],
+): VersionAuditEntry[] {
+  return snapshots.map((snapshot) => ({
+    versionId: snapshot.versionId,
+    name: snapshot.name,
+    createdAt: snapshot.createdAt,
+    documentSignature: snapshot.documentSignature,
+    action: "created",
+  }));
+}
+
+export function lockDocumentVersionSnapshot(
+  snapshot: DocumentVersionSnapshot,
+): DocumentVersionSnapshot {
+  return {
+    ...snapshot,
+    name: snapshot.name.startsWith("[locked] ")
+      ? snapshot.name
+      : `[locked] ${snapshot.name}`,
+  };
+}
+
+function compareDocumentVersionSnapshots(
+  left: DocumentVersionSnapshot,
+  right: DocumentVersionSnapshot,
+): number {
+  const createdAtComparison = right.createdAt.localeCompare(left.createdAt);
+  if (createdAtComparison !== 0) {
+    return createdAtComparison;
+  }
+
+  return left.versionId.localeCompare(right.versionId);
+}

package/src/component-inventory.md

@@ -0,0 +1,99 @@
+# Component Inventory
+
+This file is the source-owned inventory for the major subsystems in the active docx implementation.
+
+Wave 0 established the scaffold and ownership boundaries. Wave 1 froze the contract surface for the editor-side components listed below. That promotion does not claim implementation completeness; it means the subsystem boundaries, contract artifacts, and proof expectations are now explicit enough for later docx waves to build against without reopening the architecture.
+
+This inventory does not yet track:
+
+- shared OOXML platform extraction as a separate source area
+- a future xlsx runtime inventory
+- future pdf work
+
+## Inventory Table
+
+| Component | Current target | Primary paths | Scope in this repo phase | Contract and proof surfaces |
+| --- | --- | --- | --- | --- |
+| `canonical-document-model` | `contract-frozen` | `src/model/`, `src/api/` | Versioned canonical envelope, persisted snapshot shape, migration boundary, document metadata ownership | `docs/plans/waves/specs/wave-1-component-boundaries.md`, `docs/plans/waves/specs/wave-1-runtime-contracts.md`, schema docs, canonical JSON examples, model tests |
+| `command-and-transaction-runtime` | `contract-frozen` | `src/core/`, `src/runtime/` | Deterministic commands, transactions, mapping, selection semantics, runtime mutation boundary | `docs/plans/waves/specs/wave-1-component-boundaries.md`, `docs/plans/waves/specs/wave-1-runtime-contracts.md`, command tests, mapping tests, state-transition proofs |
+| `comments-and-anchor-mapping` | `contract-frozen` | `src/review/`, `src/core/selection/` | Comment threads, anchor remapping, review selectors, edit-safe anchor mapping policy | `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`, `docs/plans/waves/specs/wave-1-runtime-contracts.md`, anchor remap tests, threaded comment fixtures, review model docs |
+| `tracked-changes-and-review-actions` | `contract-frozen` | `src/review/`, `src/ui/review/` | Revision records, display modes, accept/reject boundaries, review-oriented commands | `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`, revision fixtures, accept/reject tests, review-state mapping tests |
+| `docx-import-and-normalization` | `contract-frozen` | `src/io/opc/`, `src/io/ooxml/`, `src/io/normalize/` | OPC opening, WordprocessingML parsing, normalization into canonical state, support classification inputs | `docs/plans/waves/specs/wave-1-ooxml-contracts.md`, `.docx` import fixtures, normalization tests, supported-feature mapping docs |
+| `docx-export-and-serialization` | `contract-frozen` | `src/io/export/`, `src/io/opc/` | Regenerated OOXML parts, package writing, relationship integrity, supported-feature serialization | `docs/plans/waves/specs/wave-1-ooxml-contracts.md`, round-trip fixtures, export validation tests, serializer docs |
+| `unsupported-ooxml-preservation` | `contract-frozen` | `src/preservation/`, `src/io/` | Opaque fragment capture, untouched package-part retention, reattachment policy, locked editing regions | `docs/plans/waves/specs/wave-1-ooxml-contracts.md`, preservation fixtures, fragment retention tests, export reattachment tests |
+| `compatibility-and-word-validation` | `contract-frozen` | `src/validation/`, `src/ui/compatibility/`, `services/openxml-validator/` | Editor-side compatibility reporting, support classification, export-risk reporting, validator-service integration boundary | `docs/plans/waves/specs/wave-1-ooxml-contracts.md`, `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`, feature matrix, compatibility tests, Word reopen evidence |
+| `react-editor-ui` | `contract-frozen` | `src/ui-tailwind/`, `src/ui/headless/`, `src/runtime/`, `src/api/` | Tailwind-based React shell with Radix UI primitives. Headless logic in `src/ui/headless/`. Legacy inline-CSSProperties components removed. | `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`, component tests, selection behavior checks, review-surface checks, token and theme checks |
+
+## Boundary Notes
+
+### Canonical data stays outside React
+
+- `src/model/`, `src/core/`, `src/review/`, `src/io/`, `src/preservation/`, and `src/validation/` should remain framework-light and serializable.
+- The DOM is a rendering target, not canonical state.
+
+### Runtime is the mutation choke point
+
+- UI surfaces call into `src/runtime/`.
+- Commands and transactions are owned by `src/core/`.
+- Review actions remain explicit state transitions rather than implicit UI side effects.
+
+### DOCX handling is package-first
+
+- `src/io/opc/` owns ZIP/package and relationship handling.
+- `src/io/ooxml/` owns WordprocessingML parsing.
+- `src/preservation/` owns unsupported-content retention and untouched package parts.
+
+### Broader repo work is planned, not landed
+
+- The repo now documents a target source layout under `src/platform/` and `src/formats/*`, but this file still inventories the landed docx-first tree.
+- Shared platform and xlsx architecture are currently defined in docs, not in source ownership tables here.
+
+### Review semantics are first-class
+
+- Comments and tracked changes are not annotations layered loosely on top of text rendering.
+- Anchors and revisions must stay mappable through edits and export.
+
+## Service-Backed Wave 0 Components
+
+The following components have a higher Wave 0 target because they already have repo-landed scaffolds:
+
+| Component | Wave 0 target | Primary paths | Landed scaffold evidence |
+| --- | --- | --- | --- |
+| `railway-test-harness` | `repo-landed` | `services/react-word-editor/` | Next.js service package, layout shell, harness dashboard stub, Dockerfile, Railway-oriented README |
+| `openxml-sdk-validator-service` | `repo-landed` | `services/openxml-validator/` | .NET 8 minimal API, `GET /health`, `POST /validate`, Dockerfile, SDK-backed validation README |
+
+## Out Of Scope For Wave 0
+
+- No canonical schema implementation yet
+- No command engine implementation yet
+- No comment or revision persistence yet
+- No OOXML transformer or serializer yet
+- No production `WordReviewEditor` React runtime yet
+- No live Railway persistence or private networking integration yet
+
+Those surfaces move in later waves. This inventory only establishes where they belong and what proof each promotion will require.
+
+## Contract Freeze References
+
+Wave 1 froze the owned architecture in the following durable spec set:
+
+- `docs/plans/waves/design/wave-1-a1.md`
+- `docs/plans/waves/specs/wave-1-component-boundaries.md`
+- `docs/plans/waves/specs/wave-1-runtime-contracts.md`
+- `docs/plans/waves/specs/wave-1-ooxml-contracts.md`
+- `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`
+
+## Future Source Direction
+
+Target broader layout:
+
+```text
+src/
+  platform/
+  formats/
+    docx/
+    xlsx/
+    pdf/
+```
+
+That future layout is a planning direction only. Do not treat it as a landed source move until the actual implementation is reorganized.

package/src/core/README.md

@@ -0,0 +1,10 @@
+# Core
+
+Commands, transactions, selection, mapping, schema, and deterministic state transitions belong here.
+
+Key subdirectories:
+
+- `schema/`
+- `state/`
+- `commands/`
+- `selection/`

package/src/core/commands/README.md

@@ -0,0 +1,3 @@
+# Core Commands
+
+Command handlers, transaction builders, and editor mutation policies belong here.