@beyondwork/docx-react-component 1.0.0

package/src/runtime/read-only-diagnostics-runtime.ts

@@ -0,0 +1,232 @@
+import type {
+  CompatibilityReport,
+  EditorWarning,
+  ExportDocxOptions,
+  ExportResult,
+  PersistedEditorSnapshot,
+  RuntimeRenderSnapshot,
+} from "../api/public-types.ts";
+import { createCanonicalDocumentId } from "../core/state/editor-state.ts";
+import type { ImportDiagnosticsResult } from "../validation/import-diagnostics.ts";
+
+export interface ReadOnlyDiagnosticsRuntime {
+  getRenderSnapshot(): RuntimeRenderSnapshot;
+  getPersistedSnapshot(): PersistedEditorSnapshot;
+  getCompatibilityReport(): CompatibilityReport;
+  getWarnings(): EditorWarning[];
+  dispatch(command: { type: string }): never;
+  undo(): never;
+  redo(): never;
+  exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
+}
+
+export function createReadOnlyDiagnosticsRuntime(input: {
+  documentId: string;
+  sourceLabel?: string;
+  editorBuild: string;
+  generatedAt: string;
+  diagnostics: ImportDiagnosticsResult;
+}): ReadOnlyDiagnosticsRuntime {
+  const persistedSnapshot = createDiagnosticsSnapshot(input);
+  const renderSnapshot = createDiagnosticsRenderSnapshot(input, persistedSnapshot);
+
+  return {
+    getRenderSnapshot() {
+      return renderSnapshot;
+    },
+    getPersistedSnapshot() {
+      return persistedSnapshot;
+    },
+    getCompatibilityReport() {
+      return persistedSnapshot.compatibility;
+    },
+    getWarnings() {
+      return persistedSnapshot.warningLog;
+    },
+    dispatch(command) {
+      throw createReadOnlyDiagnosticsModeError(command.type);
+    },
+    undo() {
+      throw createReadOnlyDiagnosticsModeError("history.undo");
+    },
+    redo() {
+      throw createReadOnlyDiagnosticsModeError("history.redo");
+    },
+    async exportDocx(options) {
+      void options;
+      throw new Error(
+        "DOCX export is blocked in read-only diagnostics mode because the imported package is not safe to rewrite.",
+      );
+    },
+  };
+}
+
+function createDiagnosticsSnapshot(input: {
+  documentId: string;
+  editorBuild: string;
+  generatedAt: string;
+  diagnostics: ImportDiagnosticsResult;
+}): PersistedEditorSnapshot {
+  const docId = createCanonicalDocumentId(input.documentId);
+  const diagnosticId = `diagnostic:${sanitizeDiagnosticsToken(input.documentId)}`;
+
+  return {
+    snapshotVersion: "persisted-editor-snapshot/1",
+    schemaVersion: "cds/1.0.0",
+    documentId: input.documentId,
+    docId,
+    createdAt: input.generatedAt,
+    updatedAt: input.generatedAt,
+    savedAt: input.generatedAt,
+    editorBuild: input.editorBuild,
+    canonicalDocument: {
+      schemaVersion: "cds/1.0.0",
+      docId,
+      createdAt: input.generatedAt,
+      updatedAt: input.generatedAt,
+      metadata: {
+        customProperties: {},
+        importMode: input.diagnostics.mode,
+      },
+      styles: {
+        paragraphs: {},
+        characters: {},
+        tables: {},
+      },
+      numbering: {
+        abstractDefinitions: {},
+        instances: {},
+      },
+      media: {
+        items: {},
+      },
+      content: {
+        type: "doc",
+        children: [{ type: "paragraph", children: [] }],
+      },
+      review: {
+        comments: {},
+        revisions: {},
+      },
+      preservation: {
+        opaqueFragments: {},
+        packageParts: {},
+      },
+      diagnostics: {
+        warnings: [],
+        errors: [
+          {
+            diagnosticId,
+            code: input.diagnostics.fatalError.code,
+            message: input.diagnostics.fatalError.message,
+            isFatal: input.diagnostics.fatalError.isFatal,
+            source: input.diagnostics.fatalError.source,
+            details: input.diagnostics.fatalError.details,
+          },
+        ],
+      },
+    },
+    compatibility: {
+      reportVersion: "compatibility-report/1",
+      generatedAt: input.generatedAt,
+      blockExport: true,
+      featureEntries: [...input.diagnostics.diagnostics.featureEntries],
+      warnings: [...input.diagnostics.diagnostics.warnings],
+      errors: [...input.diagnostics.diagnostics.errors],
+    },
+    warningLog: [],
+  };
+}
+
+function createDiagnosticsRenderSnapshot(
+  input: {
+    documentId: string;
+    sourceLabel?: string;
+    diagnostics: ImportDiagnosticsResult;
+  },
+  persistedSnapshot: PersistedEditorSnapshot,
+): RuntimeRenderSnapshot {
+  return {
+    documentId: input.documentId,
+    sessionId: `${input.documentId}-diagnostics`,
+    sourceLabel: input.sourceLabel,
+    revisionToken: `${input.documentId}:diagnostics`,
+    isReady: true,
+    isDirty: false,
+    readOnly: true,
+    selection: collapsedSelection(),
+    documentStats: {
+      storyLength: 0,
+      commentCount: 0,
+      revisionCount: 0,
+      opaqueFragmentCount: 0,
+    },
+    comments: {
+      openCommentIds: [],
+      resolvedCommentIds: [],
+      detachedCommentIds: [],
+      totalCount: 0,
+      threads: [],
+    },
+    trackedChanges: {
+      pendingChangeIds: [],
+      acceptedChangeIds: [],
+      rejectedChangeIds: [],
+      detachedChangeIds: [],
+      actionableChangeIds: [],
+      preserveOnlyChangeIds: [],
+      totalCount: 0,
+      revisions: [],
+    },
+    compatibility: {
+      blockExport: true,
+      blockExportReasons: [persistedSnapshot.compatibility.errors[0]?.message ?? input.diagnostics.featureEntry.message],
+      warningCount: persistedSnapshot.compatibility.warnings.length,
+      errorCount: persistedSnapshot.compatibility.errors.length,
+      featureEntries: [...persistedSnapshot.compatibility.featureEntries],
+    },
+    warnings: [],
+    fatalError: input.diagnostics.fatalError,
+    commandState: {
+      canUndo: false,
+      canRedo: false,
+      readOnly: true,
+    },
+  };
+}
+
+function collapsedSelection(): RuntimeRenderSnapshot["selection"] {
+  return {
+    anchor: 0,
+    head: 0,
+    isCollapsed: true,
+    activeRange: {
+      kind: "range",
+      from: 0,
+      to: 0,
+      assoc: {
+        start: -1,
+        end: 1,
+      },
+    },
+  };
+}
+
+function createReadOnlyDiagnosticsModeError(commandType: string): Error {
+  const error = new Error(
+    `Command ${commandType} is blocked in read-only diagnostics mode.`,
+  );
+  Object.assign(error, {
+    code: "import_failed",
+    details: {
+      mode: "read-only-diagnostics",
+      commandType,
+    },
+  });
+  return error;
+}
+
+function sanitizeDiagnosticsToken(documentId: string): string {
+  const collapsed = documentId.replace(/[^A-Za-z0-9._-]/g, "-");
+  return collapsed.length > 0 ? `read-only-${collapsed}` : "read-only-diagnostics";
+}

package/src/runtime/review-runtime.ts

@@ -0,0 +1,44 @@
+import type {
+  CommentThreadRecord,
+  EditorState,
+  EditorWarning,
+} from "../core/state/editor-state.ts";
+import type { TransactionMapping } from "../core/selection/mapping.ts";
+import { remapCommentThreads } from "../review/store/comment-remapping.ts";
+
+export interface ApplyReviewRuntimeMappingOptions {
+  state: Pick<EditorState, "document" | "warnings" | "runtime">;
+  mapping: TransactionMapping;
+  nextContent: unknown;
+}
+
+export interface ReviewRuntimeMappingResult {
+  comments: Record<string, CommentThreadRecord>;
+  warnings: EditorWarning[];
+  activeCommentId?: string;
+  detachedCommentIds: string[];
+}
+
+export function applyReviewRuntimeMapping(
+  options: ApplyReviewRuntimeMappingOptions,
+): ReviewRuntimeMappingResult {
+  const remapped = remapCommentThreads({
+    comments: options.state.document.review.comments,
+    mapping: options.mapping,
+    nextContent: options.nextContent,
+    existingWarnings: options.state.warnings,
+  });
+
+  const activeCommentId =
+    options.state.runtime.activeCommentId &&
+    remapped.comments[options.state.runtime.activeCommentId]
+      ? options.state.runtime.activeCommentId
+      : undefined;
+
+  return {
+    comments: remapped.comments,
+    warnings: remapped.warnings,
+    activeCommentId,
+    detachedCommentIds: remapped.detachedCommentIds,
+  };
+}

package/src/runtime/revision-runtime.ts

@@ -0,0 +1,107 @@
+import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
+import {
+  getReviewCommandIntent,
+  isSingleRevisionReviewCommand,
+  type ReviewCommand,
+} from "../core/commands/review-commands.ts";
+import type { TransactionMapping } from "../core/selection/mapping.ts";
+import {
+  applyRevisionAction,
+  type RevisionActionOutcome,
+} from "../review/store/revision-actions.ts";
+import { type RevisionStore } from "../review/store/revision-store.ts";
+
+export interface RevisionRuntimeState {
+  document: CanonicalDocumentEnvelope;
+  store: RevisionStore;
+}
+
+export interface ApplyRevisionRuntimeCommandOptions {
+  state: RevisionRuntimeState;
+  command: ReviewCommand;
+  timestamp: string;
+}
+
+export interface RevisionRuntimeCommandEffects {
+  appliedRevisionIds: string[];
+  skippedRevisions: RevisionActionOutcome[];
+  detachedRevisionIds: string[];
+}
+
+export interface RevisionRuntimeCommandResult extends RevisionRuntimeState {
+  outcomes: RevisionActionOutcome[];
+  mappings: Array<{ revisionId: string; mapping: TransactionMapping; steps: number }>;
+  effects: RevisionRuntimeCommandEffects;
+}
+
+export function applyRevisionRuntimeCommand(
+  options: ApplyRevisionRuntimeCommandOptions,
+): RevisionRuntimeCommandResult {
+  const revisionIds = isSingleRevisionReviewCommand(options.command)
+    ? [options.command.revisionId]
+    : listBatchRevisionIds(options.state.store);
+
+  const outcomes: RevisionActionOutcome[] = [];
+  const mappings: Array<{ revisionId: string; steps: number }> = [];
+  const appliedRevisionIds: string[] = [];
+  const detachedRevisionIds = new Set<string>();
+
+  let state = options.state;
+
+  for (const revisionId of revisionIds) {
+    const result = applyRevisionAction({
+      document: state.document,
+      store: state.store,
+      revisionId,
+      intent: getReviewCommandIntent(options.command),
+      timestamp: options.timestamp,
+    });
+
+    state = {
+      document: result.document,
+      store: result.store,
+    };
+    outcomes.push(result.outcome);
+    mappings.push({
+      revisionId,
+      mapping: result.mapping,
+      steps: result.mapping.steps.length,
+    });
+
+    if (result.outcome.kind === "applied") {
+      appliedRevisionIds.push(revisionId);
+    }
+
+    for (const detachedRevisionId of result.detachedRevisionIds) {
+      detachedRevisionIds.add(detachedRevisionId);
+    }
+  }
+
+  return {
+    ...state,
+    outcomes,
+    mappings,
+    effects: {
+      appliedRevisionIds,
+      skippedRevisions: outcomes.filter(
+        (outcome): outcome is Extract<RevisionActionOutcome, { kind: "skipped" }> =>
+          outcome.kind === "skipped",
+      ),
+      detachedRevisionIds: [...detachedRevisionIds],
+    },
+  };
+}
+
+function listBatchRevisionIds(store: RevisionStore): string[] {
+  return Object.values(store.revisions)
+    .filter((revision) => revision.status === "active")
+    .sort((left, right) => {
+      const createdAtDelta = left.createdAt.localeCompare(right.createdAt);
+      if (createdAtDelta !== 0) {
+        return createdAtDelta;
+      }
+
+      return left.revisionId.localeCompare(right.revisionId);
+    })
+    .map((revision) => revision.revisionId);
+}

package/src/runtime/session-capabilities.ts

@@ -0,0 +1,138 @@
+import type { RuntimeRenderSnapshot } from "../api/public-types";
+
+/**
+ * Session capabilities derived from the runtime snapshot.
+ *
+ * All fields are computed from `RuntimeRenderSnapshot` — no local component
+ * state. The UI reads these to decide what controls to enable/disable, what
+ * chrome to show, and what mode the editor is in.
+ */
+export interface SessionCapabilities {
+  // ── Session phase ──
+  /** Current lifecycle phase of the editor session. */
+  phase: "loading" | "ready" | "diagnostics" | "error";
+
+  /** Effective editor mode after accounting for runtime state. */
+  mode: "editing" | "review" | "read-only-diagnostics";
+
+  // ── Command capabilities ──
+  canUndo: boolean;
+  canRedo: boolean;
+  canEdit: boolean;
+  canAddComment: boolean;
+  canExport: boolean;
+  canAcceptChange: boolean;
+  canRejectChange: boolean;
+  canAcceptAll: boolean;
+  canRejectAll: boolean;
+
+  // ── Review visibility ──
+  /** Whether the review rail should be visible by default. */
+  reviewRailVisible: boolean;
+
+  /** Whether tracked changes exist in the document (display toggle is meaningful). */
+  trackChangesSupported: boolean;
+
+  // ── Trust posture ──
+  exportBlocked: boolean;
+  preserveOnlyCount: number;
+  unsupportedFatalCount: number;
+
+  // ── Health ──
+  /** Total count of health issues (preserve-only + unsupported-fatal + warnings). */
+  healthIssueCount: number;
+
+  // ── Status ──
+  isDirty: boolean;
+  isReady: boolean;
+  hasFatalError: boolean;
+}
+
+/**
+ * Derive UI capabilities from the runtime snapshot and requested review mode.
+ *
+ * This is a pure function with no side effects. Call it on every render to
+ * get the current capability state.
+ */
+export function deriveCapabilities(
+  snapshot: RuntimeRenderSnapshot,
+  reviewMode: "editing" | "review",
+): SessionCapabilities {
+  const hasFatalError = Boolean(snapshot.fatalError);
+  const isReady = snapshot.isReady;
+  const isReadOnly = snapshot.readOnly;
+  const exportBlocked = snapshot.compatibility.blockExport;
+
+  // Phase derivation
+  const phase: SessionCapabilities["phase"] = !isReady
+    ? "loading"
+    : hasFatalError
+      ? "diagnostics"
+      : "ready";
+
+  // Mode derivation: if diagnostics or read-only, override the requested mode
+  const mode: SessionCapabilities["mode"] =
+    phase === "diagnostics"
+      ? "read-only-diagnostics"
+      : reviewMode;
+
+  // Command capabilities
+  const canEdit = isReady && !isReadOnly && !hasFatalError;
+  const canUndo = snapshot.commandState.canUndo && canEdit;
+  const canRedo = snapshot.commandState.canRedo && canEdit;
+  const canAddComment = canEdit && !snapshot.selection.isCollapsed;
+  const canExport = isReady && !exportBlocked && !hasFatalError;
+
+  // Revision capabilities
+  const actionableRevisions = snapshot.trackedChanges.revisions.filter(
+    (r) => r.status === "active" && r.actionability === "actionable",
+  );
+  const canAcceptChange = canEdit && actionableRevisions.some((r) => r.canAccept);
+  const canRejectChange = canEdit && actionableRevisions.some((r) => r.canReject);
+  const canAcceptAll = canEdit && actionableRevisions.length > 0;
+  const canRejectAll = canEdit && actionableRevisions.length > 0;
+
+  // Trust posture (computed before review visibility since it depends on these)
+  const preserveOnlyCount = snapshot.compatibility.featureEntries.filter(
+    (e) => e.featureClass === "preserve-only",
+  ).length;
+  const unsupportedFatalCount = snapshot.compatibility.featureEntries.filter(
+    (e) => e.featureClass === "unsupported-fatal",
+  ).length;
+
+  // Review visibility
+  const trackChangesSupported = snapshot.trackedChanges.totalCount > 0;
+  // Rail visible in review/diagnostics mode always.
+  // In editing mode, rail stays visible when there are trust/health concerns
+  // that the user must be able to reach (per DESIGN.md: health/trust info
+  // stays reachable in both modes).
+  const hasTrustConcerns = exportBlocked || preserveOnlyCount > 0 || unsupportedFatalCount > 0
+    || snapshot.warnings.length > 0 || hasFatalError;
+  const reviewRailVisible = mode === "review" || mode === "read-only-diagnostics"
+    || (mode === "editing" && hasTrustConcerns);
+
+  const healthIssueCount = preserveOnlyCount + unsupportedFatalCount + snapshot.warnings.length;
+
+  return {
+    phase,
+    mode,
+    canUndo,
+    canRedo,
+    canEdit,
+    canAddComment,
+    canExport,
+    canAcceptChange,
+    canRejectChange,
+    canAcceptAll,
+    canRejectAll,
+    reviewRailVisible,
+    trackChangesSupported,
+    exportBlocked,
+    preserveOnlyCount,
+    unsupportedFatalCount,
+    healthIssueCount,
+    isDirty: snapshot.isDirty,
+    isReady,
+    hasFatalError,
+  };
+}