@beyondwork/docx-react-component 1.0.10 → 1.0.12

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/bwllaming/React-OOXML-Office/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bwllaming/React-OOXML-Office/actions/workflows/ci.yml)
 
-`@beyondwork/docx-react-component` is the shipped product in this repository: `WordReviewEditor`, a fidelity-first React editor for legal-review-safe `docx` workflows. Wave 21 lands the package-facing docs, npm metadata, publish workflow, and `pnpm pack` proof for this surface.
+`@beyondwork/docx-react-component` is the shipped product in this repository: `WordReviewEditor`, a fidelity-first React editor for legal-review-safe `docx` workflows. Waves 20 through 23 land live table editing, package distribution, validator-backed CI, and legal workflow helpers. Wave 24 is the next production-hardening packet.
 
 The broader repository is still evolving toward a layered `react-ooxml-office` platform, but the source reality is unchanged:
 
@@ -43,6 +43,11 @@ import { WordReviewEditor } from "@beyondwork/docx-react-component";
 - runtime owns the live working session
 - host receives events, warnings, errors, snapshots, and exported artifacts
 
+Snapshot/export note:
+
+- when a session starts from a real `.docx`, persisted snapshots now carry embedded source-package provenance so later snapshot-origin `.docx` export can use the same package-backed exporter
+- legacy snapshots without that provenance still load, but `.docx` export is intentionally blocked rather than falling back to a lossy minimal package
+
 The current public ESM exports are:
 
 - `@beyondwork/docx-react-component` -> `WordReviewEditor`
@@ -87,7 +92,7 @@ Start here:
 Current shipped docx contracts:
 
 - `docs/reference/public-api.md`
-  This doc separates the shipped Wave 21 surface from the future Waves 25 through 27 ref expansion.
+  This doc separates the shipped Waves 20-23 surface from the future Waves 25 through 27 ref expansion.
 - `docs/reference/ooxml-compliance.md`
 - `docs/reference/word-review-editor-frontend-architecture.md`
 - `docs/reference/word-review-editor-ux-guide.md`
@@ -117,6 +122,7 @@ Shared platform and planned xlsx docs:
 - do not silently drop unknown OOXML
 - keep docs honest about shipped versus planned behavior
 - add or extend fixtures for compatibility-critical changes
+- `bash scripts/validate-fixtures.sh` now uses the Railway validator service and requires `OPENXML_VALIDATOR_AUTH_TOKEN` when hitting the public domain
 
 ## Guiding Principle
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [
@@ -33,14 +33,6 @@
       "types": "./src/api/public-types.ts",
       "import": "./src/api/public-types.ts"
     },
-    "./io/docx-session": {
-      "types": "./src/io/docx-session.ts",
-      "import": "./src/io/docx-session.ts"
-    },
-    "./runtime/document-runtime": {
-      "types": "./src/runtime/document-runtime.ts",
-      "import": "./src/runtime/document-runtime.ts"
-    },
     "./ui-tailwind/theme/editor-theme.css": "./src/ui-tailwind/theme/editor-theme.css",
     "./package.json": "./package.json"
   },
@@ -90,7 +82,7 @@
     "tailwindcss": "^4.2.2"
   },
   "devDependencies": {
-    "@chllming/wave-orchestration": "^0.9.12",
+    "@chllming/wave-orchestration": "^0.9.13",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "@typescript/native-preview": "7.0.0-dev.20260409.1",
@@ -110,7 +102,10 @@
   "scripts": {
     "build": "tsup",
     "test": "bash scripts/run-workspace-tests.sh",
-    "test:repo": "pnpm exec tsx --test $(find test -type f \\( -name '*.test.ts' -o -name '*.test.tsx' \\) | sort)",
+    "test:repo": "node scripts/run-repo-tests.mjs core",
+    "test:repo:all": "node scripts/run-repo-tests.mjs all",
+    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
+    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
     "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
     "lint": "pnpm run lint:no-authored-js && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
     "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",

package/src/api/public-types.ts

@@ -127,7 +127,16 @@ export type SurfaceTextMark =
   | "bold"
   | "italic"
   | "underline"
-  | "strikethrough";
+  | "strikethrough"
+  | "doubleStrikethrough"
+  | "superscript"
+  | "subscript"
+  | "vanish"
+  | "emboss"
+  | "imprint"
+  | "shadow"
+  | "smallCaps"
+  | "allCaps";
 
 export type SurfaceInlineSegment =
   | {
@@ -137,6 +146,15 @@ export type SurfaceInlineSegment =
       to: number;
       text: string;
       marks?: SurfaceTextMark[];
+      markAttrs?: {
+        backgroundColor?: string;
+        charSpacing?: number;
+        kerning?: number;
+        textFill?: string;
+        fontFamily?: string;
+        fontSize?: number;
+        textColor?: string;
+      };
       hyperlinkHref?: string;
     }
   | {
@@ -192,6 +210,17 @@ export type SurfaceBlockSnapshot =
         numberingInstanceId: string;
         level: number;
       };
+      alignment?: "left" | "center" | "right" | "both" | "distribute";
+      spacing?: { before?: number; after?: number; line?: number; lineRule?: string };
+      indentation?: { left?: number; right?: number; firstLine?: number; hanging?: number };
+      borders?: { top?: unknown; left?: unknown; bottom?: unknown; right?: unknown; bar?: unknown; between?: unknown };
+      shading?: { fill?: string; color?: string; val?: string };
+      tabStops?: Array<{ pos: number; val?: string; leader?: string }>;
+      keepNext?: boolean;
+      keepLines?: boolean;
+      pageBreakBefore?: boolean;
+      outlineLevel?: number;
+      bidi?: boolean;
       segments: SurfaceInlineSegment[];
     }
   | {
@@ -346,6 +375,7 @@ export interface PersistedEditorSnapshot {
   canonicalDocument: RuntimePersistedEditorSnapshot["canonicalDocument"];
   compatibility: CompatibilityReport;
   warningLog: EditorWarning[];
+  sourcePackage?: RuntimePersistedEditorSnapshot["sourcePackage"];
 }
 
 export interface AddCommentParams {
@@ -509,6 +539,7 @@ export interface WordReviewEditorRef {
   getComments(): CommentSidebarSnapshot;
   getTrackedChanges(): TrackedChangesSnapshot;
   scrollToRevision(revisionId: string): void;
+  scrollToComment(commentId: string): void;
 }
 
 export interface WordReviewEditorProps {

package/src/core/state/editor-state.ts

@@ -1,12 +1,15 @@
 import {
   DEFAULT_BOUNDARY_ASSOC,
   createDetachedAnchor,
+  createNodeAnchor,
   createRangeAnchor,
   type EditorAnchorProjection,
 } from "../selection/mapping.ts";
+import { isUuid } from "../../model/cds-1.0.0.ts";
 import {
   assertPersistedEditorSnapshot as assertModelPersistedEditorSnapshot,
   createPersistedEditorSnapshot as createModelPersistedEditorSnapshot,
+  validatePersistedEditorSnapshot as validateModelPersistedEditorSnapshot,
   type PersistedEditorSnapshot as ModelPersistedEditorSnapshot,
 } from "../../model/snapshot.ts";
 import {
@@ -175,6 +178,7 @@ export interface EditorState {
   documentId: string;
   sessionId: string;
   sourceLabel?: string;
+  sourcePackage?: ModelPersistedEditorSnapshot["sourcePackage"];
   revision: number;
   revisionToken: string;
   isDirty: boolean;
@@ -268,29 +272,32 @@ export function createEmptyCompatibilityReport(generatedAt: string): Compatibili
 
 export function createEditorState(options: CreateEditorStateOptions): EditorState {
   const timestamp = new Date(0).toISOString();
-  if (options.persistedSnapshot) {
-    assertModelPersistedEditorSnapshot(options.persistedSnapshot as unknown);
-  }
+  const normalizedSnapshot = options.persistedSnapshot
+    ? normalizePersistedSnapshotForRuntime(options.persistedSnapshot, options.documentId, timestamp)
+    : undefined;
   if (options.canonicalDocument) {
     assertCanonicalDocument(options.canonicalDocument as unknown);
   }
 
-  const normalizedDocument = options.persistedSnapshot
-    ? structuredClone(options.persistedSnapshot.canonicalDocument)
+  const normalizedDocument = normalizedSnapshot
+    ? structuredClone(normalizedSnapshot.canonicalDocument)
     : options.canonicalDocument
       ? structuredClone(options.canonicalDocument)
       : createDefaultCanonicalDocument(options.documentId, timestamp);
-  const warnings = options.persistedSnapshot?.warningLog ?? options.warnings ?? [];
+  const warnings = normalizedSnapshot
+    ? normalizeWarningLog(normalizedSnapshot.warningLog)
+    : options.warnings ?? [];
   const compatibility =
-    options.persistedSnapshot?.compatibility ??
-    options.compatibility ??
-    createEmptyCompatibilityReport(normalizedDocument.updatedAt);
+    normalizedSnapshot
+      ? normalizeCompatibilityReport(normalizedSnapshot.compatibility)
+      : options.compatibility ?? createEmptyCompatibilityReport(normalizedDocument.updatedAt);
 
   return {
     phase: options.fatalError ? "error" : "ready",
     documentId: options.documentId,
     sessionId: options.sessionId,
     sourceLabel: options.sourceLabel,
+    sourcePackage: normalizedSnapshot?.sourcePackage,
     revision: 0,
     revisionToken: `${options.sessionId}:0`,
     isDirty: false,
@@ -306,6 +313,265 @@ export function createEditorState(options: CreateEditorStateOptions): EditorStat
   };
 }
 
+function normalizePersistedSnapshotForRuntime(
+  snapshot: PersistedEditorSnapshot,
+  documentId: string,
+  timestamp: string,
+): PersistedEditorSnapshot {
+  const issues = validateModelPersistedEditorSnapshot(snapshot as unknown);
+  if (issues.length === 0) {
+    return snapshot;
+  }
+
+  if (!isRecord(snapshot) || !isRecord(snapshot.canonicalDocument)) {
+    assertModelPersistedEditorSnapshot(snapshot as unknown);
+  }
+
+  const normalizedDocument = normalizeCanonicalDocumentEnvelope(
+    snapshot.canonicalDocument,
+    documentId,
+    timestamp,
+  );
+  try {
+    assertCanonicalDocument(normalizedDocument as unknown);
+  } catch {
+    assertModelPersistedEditorSnapshot(snapshot as unknown);
+  }
+  const repairWarning = createSnapshotRepairWarning(issues.length);
+  const compatibility = coerceCompatibilityReport(
+    snapshot.compatibility,
+    normalizedDocument.updatedAt,
+    repairWarning,
+  );
+
+  return {
+    snapshotVersion:
+      snapshot.snapshotVersion === "persisted-editor-snapshot/1" ||
+      snapshot.snapshotVersion === "persisted-editor-snapshot/2"
+        ? snapshot.snapshotVersion
+        : "persisted-editor-snapshot/2",
+    schemaVersion: "cds/1.0.0",
+    documentId:
+      typeof snapshot.documentId === "string" && snapshot.documentId.length > 0
+        ? snapshot.documentId
+        : documentId,
+    docId: normalizedDocument.docId,
+    createdAt: normalizedDocument.createdAt,
+    updatedAt: normalizedDocument.updatedAt,
+    savedAt:
+      typeof snapshot.savedAt === "string" && snapshot.savedAt.length > 0
+        ? snapshot.savedAt
+        : normalizedDocument.updatedAt,
+    editorBuild:
+      typeof snapshot.editorBuild === "string" && snapshot.editorBuild.length > 0
+        ? snapshot.editorBuild
+        : "dev",
+    canonicalDocument: normalizedDocument,
+    compatibility,
+    warningLog: dedupeWarnings([
+      ...coerceWarnings(snapshot.warningLog),
+      repairWarning,
+    ]),
+    sourcePackage: snapshot.sourcePackage,
+  };
+}
+
+function normalizeCanonicalDocumentEnvelope(
+  value: unknown,
+  documentId: string,
+  timestamp: string,
+): CanonicalDocumentEnvelope {
+  const base = createDefaultCanonicalDocument(documentId, timestamp);
+  const record = isRecord(value) ? value : {};
+  const metadata = isRecord(record.metadata) ? record.metadata : {};
+
+  return {
+    ...base,
+    ...record,
+    schemaVersion: "cds/1.0.0",
+    docId: isUuid(record.docId) ? record.docId : createCanonicalDocumentId(documentId),
+    createdAt:
+      typeof record.createdAt === "string" && record.createdAt.length > 0
+        ? record.createdAt
+        : base.createdAt,
+    updatedAt:
+      typeof record.updatedAt === "string" && record.updatedAt.length > 0
+        ? record.updatedAt
+        : base.updatedAt,
+    metadata: {
+      ...base.metadata,
+      ...metadata,
+      customProperties: isRecord(metadata.customProperties)
+        ? (Object.fromEntries(
+            Object.entries(metadata.customProperties).filter(([, entry]) => typeof entry === "string"),
+          ) as Record<string, string>)
+        : {},
+    },
+    styles:
+      record.styles === undefined
+        ? base.styles
+        : (record.styles as CanonicalDocumentEnvelope["styles"]),
+    numbering:
+      record.numbering === undefined
+        ? base.numbering
+        : (record.numbering as CanonicalDocumentEnvelope["numbering"]),
+    media:
+      record.media === undefined
+        ? base.media
+        : (record.media as CanonicalDocumentEnvelope["media"]),
+    content: isRecord(record.content)
+      ? (record.content as unknown as CanonicalDocumentEnvelope["content"])
+      : base.content,
+    review:
+      record.review === undefined
+        ? base.review
+        : (record.review as CanonicalDocumentEnvelope["review"]),
+    preservation:
+      record.preservation === undefined
+        ? base.preservation
+        : (record.preservation as CanonicalDocumentEnvelope["preservation"]),
+    diagnostics:
+      record.diagnostics === undefined
+        ? base.diagnostics
+        : (record.diagnostics as CanonicalDocumentEnvelope["diagnostics"]),
+    ...(isRecord(record.subParts)
+      ? { subParts: record.subParts as unknown as CanonicalDocumentEnvelope["subParts"] }
+      : {}),
+  };
+}
+
+function coerceCompatibilityReport(
+  value: unknown,
+  generatedAt: string,
+  repairWarning: EditorWarning,
+): CompatibilityReport {
+  const record = isRecord(value) ? value : {};
+  const warnings = dedupeWarnings([
+    ...coerceWarnings(record.warnings),
+    repairWarning,
+  ]);
+
+  return {
+    reportVersion: "compatibility-report/1",
+    generatedAt:
+      typeof record.generatedAt === "string" && record.generatedAt.length > 0
+        ? record.generatedAt
+        : generatedAt,
+    blockExport: typeof record.blockExport === "boolean" ? record.blockExport : false,
+    featureEntries: Array.isArray(record.featureEntries)
+      ? record.featureEntries.flatMap((entry) => {
+          if (!isRecord(entry)) {
+            return [];
+          }
+          if (
+            typeof entry.featureEntryId !== "string" ||
+            typeof entry.featureKey !== "string" ||
+            typeof entry.featureClass !== "string" ||
+            typeof entry.message !== "string"
+          ) {
+            return [];
+          }
+          return [{
+            featureEntryId: entry.featureEntryId,
+            featureKey: entry.featureKey,
+            featureClass: entry.featureClass as CompatibilityFeatureEntry["featureClass"],
+            message: entry.message,
+            ...(entry.affectedAnchor && isRecord(entry.affectedAnchor)
+              ? { affectedAnchor: entry.affectedAnchor as unknown as EditorAnchorProjection }
+              : {}),
+            ...(isRecord(entry.details) ? { details: entry.details } : {}),
+          }];
+        })
+      : [],
+    warnings,
+    errors: Array.isArray(record.errors)
+      ? record.errors.flatMap((entry) => {
+          if (!isRecord(entry)) {
+            return [];
+          }
+          if (
+            typeof entry.errorId !== "string" ||
+            typeof entry.code !== "string" ||
+            typeof entry.message !== "string" ||
+            typeof entry.source !== "string" ||
+            typeof entry.isFatal !== "boolean"
+          ) {
+            return [];
+          }
+          return [{
+            errorId: entry.errorId,
+            code: entry.code as EditorError["code"],
+            message: entry.message,
+            source: entry.source as EditorError["source"],
+            isFatal: entry.isFatal,
+            ...(isRecord(entry.details) ? { details: entry.details } : {}),
+          }];
+        })
+      : [],
+  };
+}
+
+function coerceWarnings(value: unknown): EditorWarning[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.flatMap((warning) => {
+    if (!isRecord(warning)) {
+      return [];
+    }
+    if (
+      typeof warning.warningId !== "string" ||
+      typeof warning.code !== "string" ||
+      typeof warning.severity !== "string" ||
+      typeof warning.message !== "string" ||
+      typeof warning.source !== "string"
+    ) {
+      return [];
+    }
+
+    return [{
+      warningId: warning.warningId,
+      code: warning.code as EditorWarning["code"],
+      severity: warning.severity as EditorWarning["severity"],
+      message: warning.message,
+      source: warning.source as EditorWarning["source"],
+      ...(warning.affectedAnchor && isRecord(warning.affectedAnchor)
+        ? { affectedAnchor: warning.affectedAnchor as unknown as EditorAnchorProjection }
+        : {}),
+      ...(typeof warning.featureEntryId === "string"
+        ? { featureEntryId: warning.featureEntryId }
+        : {}),
+      ...(isRecord(warning.details) ? { details: warning.details } : {}),
+    }];
+  });
+}
+
+function createSnapshotRepairWarning(issueCount: number): EditorWarning {
+  return {
+    warningId: `warning:snapshot-repair:${issueCount}`,
+    code: "import_normalized",
+    severity: "warning",
+    message: `Loaded a persisted snapshot after repairing ${issueCount} validation issue${issueCount === 1 ? "" : "s"}.`,
+    source: "validation",
+  };
+}
+
+function dedupeWarnings(warnings: EditorWarning[]): EditorWarning[] {
+  const seen = new Set<string>();
+  const result: EditorWarning[] = [];
+
+  for (const warning of warnings) {
+    if (!warning.warningId || seen.has(warning.warningId)) {
+      continue;
+    }
+    seen.add(warning.warningId);
+    result.push(warning);
+  }
+
+  return result;
+}
+
 export function deriveDocumentStats(state: Pick<EditorState, "document">): DocumentStats {
   const serializedContent = extractText(state.document.content);
 
@@ -381,6 +647,7 @@ export function createPersistedEditorSnapshot(
     canonicalDocument: state.document,
     compatibility: (options.compatibility ?? state.compatibility) as never,
     warningLog: state.warnings as never,
+    sourcePackage: state.sourcePackage,
   });
   return snapshot as PersistedEditorSnapshot;
 }
@@ -397,6 +664,48 @@ function estimateParagraphCount(content: unknown): number {
   return extractText(content).length > 0 ? 1 : 0;
 }
 
+function normalizeWarningLog(warnings: EditorWarning[]): EditorWarning[] {
+  return warnings.map((warning) => ({
+    ...warning,
+    affectedAnchor: warning.affectedAnchor
+      ? normalizeAnchorProjection(warning.affectedAnchor)
+      : undefined,
+  }));
+}
+
+function normalizeCompatibilityReport(report: CompatibilityReport): CompatibilityReport {
+  return {
+    ...report,
+    featureEntries: report.featureEntries.map((entry) => ({
+      ...entry,
+      affectedAnchor: entry.affectedAnchor
+        ? normalizeAnchorProjection(entry.affectedAnchor)
+        : undefined,
+    })),
+    warnings: normalizeWarningLog(report.warnings),
+  };
+}
+
+function normalizeAnchorProjection(anchor: EditorAnchorProjection): EditorAnchorProjection {
+  switch (anchor.kind) {
+    case "range": {
+      const rangeAnchor = anchor as EditorAnchorProjection & {
+        range?: { from: number; to: number };
+        from?: number;
+        to?: number;
+        assoc: { start: -1 | 1; end: -1 | 1 };
+      };
+      return rangeAnchor.range
+        ? createRangeAnchor(rangeAnchor.range.from, rangeAnchor.range.to, rangeAnchor.assoc)
+        : createRangeAnchor(rangeAnchor.from ?? 0, rangeAnchor.to ?? 0, rangeAnchor.assoc);
+    }
+    case "node":
+      return createNodeAnchor(anchor.at, anchor.assoc);
+    case "detached":
+      return createDetachedAnchor(anchor.lastKnownRange, anchor.reason);
+  }
+}
+
 function extractText(value: unknown): string {
   if (typeof value === "string") {
     return value;