@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/session/import/parse-orchestration.ts

@@ -0,0 +1,105 @@
+/**
+ * Parse-orchestration primitives shared by the sync and async load paths.
+ *
+ * Slice 5e-6 of refactor/01 package-session. Extracted from
+ * `src/io/docx-session.ts` (`createStageEmitter`, `loadStageNow`,
+ * `createImportDiagnosticsFromError`, `isPackageImportError`).
+ *
+ * Contract P6 clean: depends only on `src/io/**` +
+ * `src/validation/**` (import-diagnostic producers). No runtime /
+ * UI / core / review imports.
+ */
+
+import type { LoadStage } from "../../api/public-types.ts";
+import { classifyCorruptPackageError } from "../../io/opc/corrupt-package.ts";
+import {
+  createPackageImportDiagnostics,
+  createValidationImportDiagnostics,
+  type ImportDiagnosticsResult,
+} from "../../validation/import-diagnostics.ts";
+
+/**
+ * Stage-event emitter. When no callback is supplied the emitter is a
+ * zero-cost no-op. Shared between the sync and async load orchestrators
+ * so both paths emit `load-stage` events at the same four boundaries:
+ * `opc` → `body` → `styles-numbering-comments` → `skeleton-ready`.
+ */
+export interface StageEmitter {
+  emit(stage: LoadStage): void;
+}
+
+export type LoadStageCallback = (stage: LoadStage, durationMs: number) => void;
+
+export function createStageEmitter(
+  onStage: LoadStageCallback | undefined,
+): StageEmitter {
+  if (!onStage) {
+    return {
+      emit() {
+        /* no-op */
+      },
+    };
+  }
+  let cursor = loadStageNow();
+  return {
+    emit(stage) {
+      const nextMark = loadStageNow();
+      onStage(stage, nextMark - cursor);
+      cursor = nextMark;
+    },
+  };
+}
+
+/**
+ * Monotonic millisecond clock shared by the stage emitter. Falls back to
+ * `Date.now()` in environments without `performance.now()` (older Node,
+ * certain SSR runtimes).
+ */
+export function loadStageNow(): number {
+  return typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+}
+
+/**
+ * Classify a thrown error from `readOpcPackage()` / downstream parse into
+ * a typed `ImportDiagnosticsResult`. Routes package-shaped errors through
+ * `classifyCorruptPackageError`; everything else becomes a generic
+ * validation diagnostic.
+ */
+export function createImportDiagnosticsFromError(error: unknown): ImportDiagnosticsResult {
+  if (isPackageImportError(error)) {
+    return createPackageImportDiagnostics({
+      issue: classifyCorruptPackageError(error),
+    });
+  }
+
+  return createValidationImportDiagnostics({
+    message:
+      error instanceof Error
+        ? error.message
+        : "DOCX import failed during validation.",
+  });
+}
+
+/**
+ * Heuristic: does this error look like it originated inside the OPC
+ * package reader (zip/relationship/content-types parse failure) as
+ * opposed to further downstream validation?
+ */
+export function isPackageImportError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  const normalized = error.message.toLowerCase();
+  return (
+    normalized.includes("zip") ||
+    normalized.includes("opc package") ||
+    normalized.includes("compression") ||
+    normalized.includes("relationship") ||
+    normalized.includes("/[content_types].xml") ||
+    normalized.includes("/word/document.xml") ||
+    normalized.includes("xml")
+  );
+}

package/src/session/import/part-constants.ts

@@ -0,0 +1,70 @@
+/**
+ * OOXML part-path + relationship-type + content-type constants shared
+ * by the sync + async load paths + the export pipeline.
+ *
+ * Slice 5e-7.d.1 — relocated from `src/io/docx-session.ts`. Neutral
+ * shared home so both the load-sync / load-async migrations (5e-7.d.2
+ * + 5e-7.d.3) and the existing `src/session/export/stateful-export-
+ * pipeline.ts` can reach a single source of truth. Historically the
+ * 6 core-/app-properties constants were extracted alongside the
+ * export helpers in 5e-6f.1; these 27 siblings belong with the
+ * load-pipeline group.
+ *
+ * P6-clean: string literals only, no imports.
+ */
+
+// -----------------------------------------------------------------------------
+// Part paths
+// -----------------------------------------------------------------------------
+
+export const NUMBERING_PART_PATH = "/word/numbering.xml";
+export const COMMENTS_EXTENDED_PART_PATH = "/word/commentsExtended.xml";
+export const COMMENTS_IDS_PART_PATH = "/word/commentsIds.xml";
+export const PEOPLE_PART_PATH = "/word/people.xml";
+export const STYLES_PART_PATH = "/word/styles.xml";
+export const FONT_TABLE_PART_PATH = "/word/fontTable.xml";
+export const FOOTNOTES_PART_PATH = "/word/footnotes.xml";
+export const ENDNOTES_PART_PATH = "/word/endnotes.xml";
+export const SETTINGS_PART_PATH = "/word/settings.xml";
+
+// -----------------------------------------------------------------------------
+// Content types
+// -----------------------------------------------------------------------------
+
+export const MAIN_DOCUMENT_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml";
+export const COMMENTS_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml";
+export const COMMENTS_EXTENDED_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml";
+export const COMMENTS_IDS_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml";
+export const PEOPLE_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.people+xml";
+
+// -----------------------------------------------------------------------------
+// Relationship types
+// -----------------------------------------------------------------------------
+
+export const NUMBERING_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering";
+export const COMMENTS_EXTENDED_RELATIONSHIP_TYPE =
+  "http://schemas.microsoft.com/office/2011/relationships/commentsExtended";
+export const COMMENTS_IDS_RELATIONSHIP_TYPE =
+  "http://schemas.microsoft.com/office/2016/09/relationships/commentsIds";
+export const PEOPLE_RELATIONSHIP_TYPE =
+  "http://schemas.microsoft.com/office/2011/relationships/people";
+export const HEADER_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header";
+export const FOOTER_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer";
+export const FOOTNOTES_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes";
+export const ENDNOTES_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes";
+export const SETTINGS_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings";
+export const STYLES_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
+export const FONT_TABLE_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable";

package/src/session/import/part-discovery.ts

@@ -0,0 +1,94 @@
+/**
+ * Part-path discovery against an OPC package.
+ *
+ * First extraction under Slice 2 of refactor/01 package-session.
+ * Pure: takes an `OpcPackage` + optional part-relationship input,
+ * returns a part path (or undefined). No runtime / UI / core / review
+ * imports — contract P6 clean.
+ *
+ * Legacy home: `src/io/docx-session.ts` lines 3667–3712 (pre-Slice 2).
+ * The legacy file now imports the resolvers from here so the two paths
+ * share one implementation while further load-orchestration extraction
+ * progresses.
+ */
+
+import type { OpcPackage } from "../../io/opc/package-reader.ts";
+import {
+  resolveRelationshipTarget,
+  type OpcRelationship,
+} from "../../io/ooxml/part-manifest.ts";
+
+/** Default `/word/document.xml` fallback when the package relationships omit the link. */
+export const MAIN_DOCUMENT_PATH = "/word/document.xml";
+
+/** Default `/word/comments.xml` fallback when the main-document relationships omit the link. */
+export const COMMENTS_PART_PATH = "/word/comments.xml";
+
+/** `officeDocument` relationship type — identifies the main-document part. */
+export const OFFICE_DOCUMENT_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument";
+
+/** `comments` relationship type — identifies the comments part. */
+export const COMMENTS_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
+
+/**
+ * Resolve the main-document part path from package-level relationships.
+ * Returns the declared target if the relationship is present and
+ * internal; otherwise the default `/word/document.xml` if that part
+ * exists in the package; otherwise `undefined` (triggers a fatal
+ * diagnostic at the caller).
+ */
+export function resolveMainDocumentPartPath(
+  sourcePackage: OpcPackage,
+): string | undefined {
+  const relationship = sourcePackage.manifest.packageRelationships.find(
+    (candidate) =>
+      candidate.type === OFFICE_DOCUMENT_RELATIONSHIP_TYPE &&
+      candidate.targetMode === "internal",
+  );
+  if (relationship) {
+    return resolveRelationshipTarget(null, relationship);
+  }
+  return sourcePackage.parts.has(MAIN_DOCUMENT_PATH) ? MAIN_DOCUMENT_PATH : undefined;
+}
+
+/**
+ * Resolve an arbitrary document-related part path by relationship type.
+ * Used by comment / header / footer / footnote / endnote / theme /
+ * numbering lookups. Returns the relationship target when present;
+ * otherwise the fallback path when the package has it; otherwise
+ * `undefined`.
+ */
+export function resolveDocumentRelatedPartPath(
+  sourcePackage: OpcPackage,
+  sourceDocumentPartPath: string,
+  relationships: readonly OpcRelationship[],
+  relationshipType: string,
+  fallbackPartPath: string,
+): string | undefined {
+  const relationship = relationships.find(
+    (candidate) =>
+      candidate.type === relationshipType && candidate.targetMode === "internal",
+  );
+  if (!relationship) {
+    return sourcePackage.parts.has(fallbackPartPath) ? fallbackPartPath : undefined;
+  }
+  const targetPath = resolveRelationshipTarget(sourceDocumentPartPath, relationship);
+  return sourcePackage.parts.has(targetPath) ? targetPath : undefined;
+}
+
+/** Narrow resolver for the comments part (fallback `/word/comments.xml`). */
+export function resolveCommentsPartPath(
+  sourcePackage: OpcPackage,
+  sourceDocumentPartPath: string,
+  relationships: readonly OpcRelationship[],
+): string | undefined {
+  return resolveDocumentRelatedPartPath(
+    sourcePackage,
+    sourceDocumentPartPath,
+    relationships,
+    COMMENTS_RELATIONSHIP_TYPE,
+    COMMENTS_PART_PATH,
+  );
+}

package/src/session/import/preservation-index.ts

@@ -0,0 +1,46 @@
+/**
+ * Preservation-field orchestration for the import load path.
+ *
+ * Slice 3c of refactor/01 package-session. Extracted from
+ * src/io/docx-session.ts (duplication of the preservation-field
+ * spread at the createImportedCanonicalDocument call site in both the
+ * sync and async load paths).
+ *
+ * The helper merges the parser-side `PreservationStore` (which already
+ * carries `opaqueFragments` accumulated by the normalize pass) with the
+ * package-part records gathered from the OPC package, yielding a
+ * complete `PreservationStore` ready to pass to
+ * `createImportedCanonicalDocument`.
+ *
+ * Contract P6 clean. Depends on:
+ *   - src/model/canonical-document.ts (allowed)
+ *   - src/io/opc/package-reader.ts (allowed)
+ *   - ./package-parts.ts (peer session module)
+ */
+
+import type { PreservationStore } from "../../model/canonical-document.ts";
+import type { OpcPackage } from "../../io/opc/package-reader.ts";
+import { collectPreservedPackageParts } from "./package-parts.ts";
+
+/**
+ * Build the complete `PreservationStore` for a freshly imported document.
+ *
+ * Merges the opaque fragments already written by the parser/normalize
+ * pass (`basePreservation`) with the verbatim-round-trip package parts
+ * collected from the OPC package. `ownedPartPaths` lists every part
+ * that the runtime will regenerate on export — those must NOT be added
+ * to `packageParts` (they won't be byte-stable).
+ */
+export function buildImportPreservation(
+  basePreservation: PreservationStore,
+  sourcePackage: OpcPackage,
+  ownedPartPaths: ReadonlyArray<string | undefined>,
+): PreservationStore {
+  return {
+    ...basePreservation,
+    packageParts: {
+      ...basePreservation.packageParts,
+      ...collectPreservedPackageParts(sourcePackage, ownedPartPaths),
+    },
+  };
+}

package/src/{runtime/read-only-diagnostics-runtime.ts → session/import/read-only-diagnostics.ts}

@@ -1,3 +1,24 @@
+/**
+ * Read-only diagnostics snapshot builder.
+ *
+ * Called from the session load path's error branches
+ * (`createDiagnosticsSession` in `src/io/docx-session.ts`) when import
+ * has hit a fatal parse / OPC / validation error and can't produce a
+ * real editor session. Returns a degenerate `ReadOnlyDiagnosticsRuntime`
+ * that exposes the diagnostic payload as an always-read-only editor
+ * state — every dispatch / undo / redo / export call throws, while
+ * `getPersistedSnapshot()` + `getCompatibilityReport()` return the
+ * pre-built snapshot carrying the fatal error + any preceding warnings.
+ *
+ * Slice 5e-7.c — relocated from `src/runtime/read-only-diagnostics-
+ * runtime.ts`. Despite the `Runtime` suffix on the interface name this
+ * function does not own runtime state: it builds pure data from an
+ * `ImportDiagnosticsResult`. Session layer is the right home — it
+ * imports only from `src/model/**`, `src/api/**`, and
+ * `src/validation/**`, all P6-allowed. One less forbidden
+ * runtime-layer transit for `docx-session.ts` to carry into 5e-9.
+ */
+
 import type {
   CompatibilityReport,
   EditorWarning,
@@ -5,9 +26,9 @@ import type {
   ExportResult,
   PersistedEditorSnapshot,
   RuntimeRenderSnapshot,
-} from "../api/public-types.ts";
-import { createCanonicalDocumentId } from "../core/state/editor-state.ts";
-import type { ImportDiagnosticsResult } from "../validation/import-diagnostics.ts";
+} from "../../api/public-types.ts";
+import { createCanonicalDocumentId } from "../../model/canonical-document.ts";
+import type { ImportDiagnosticsResult } from "../../validation/import-diagnostics.ts";
 
 export interface ReadOnlyDiagnosticsRuntime {
   getRenderSnapshot(): RuntimeRenderSnapshot;