@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/session/import/styles-consolidation.ts

@@ -0,0 +1,281 @@
+/**
+ * Styles-catalog + secondary-story media-catalog consolidation helpers.
+ *
+ * Slice 5e-6b of refactor/01 package-session. Extracted from
+ * `src/io/docx-session.ts`:
+ *
+ * - `buildStylesCatalog` — build the final `styles` facet from the
+ *   parsed `styles.xml` (or a synthetic fallback) plus any referenced
+ *   style ids the package didn't define.
+ * - `filterValidStyleIds` — narrow a parsed catalog to entries whose
+ *   styleId matches the canonical model pattern.
+ * - `mergeSecondaryStoryMediaCatalog` — walk header / footer / footnote
+ *   / endnote blocks and register every referenced media id into the
+ *   media catalog (so images referenced only from a secondary story
+ *   surface in `MediaCatalog.items`).
+ *
+ * Plus the one supporting helper these three compose over:
+ * `collectReferencedParagraphStyleIds`.
+ *
+ * Contract P6 clean: depends only on `src/model/**` + `src/io/**`
+ * type surfaces. No runtime / UI / core / review imports.
+ */
+
+import type {
+  BlockNode,
+  CanonicalDocument,
+  FootnoteCollection,
+  FooterDocument,
+  HeaderDocument,
+  InlineNode,
+  MediaCatalog,
+  SubPartsCatalog,
+} from "../../model/canonical-document.ts";
+import type { ParseStylesResult } from "../../io/ooxml/parse-styles.ts";
+
+/**
+ * Canonical model styleId validation pattern — styleIds that don't match
+ * are excluded from the catalog to avoid snapshot validation failures.
+ */
+export const VALID_STYLE_ID = /^[A-Za-z_][A-Za-z0-9._-]{0,127}$/;
+
+/** Walk the canonical content tree (and optional sub-parts) and collect
+ * every `styleId` referenced by a paragraph / table / structural block. */
+export function collectReferencedParagraphStyleIds(
+  content: CanonicalDocument["content"],
+  subParts?: SubPartsCatalog,
+): Set<string> {
+  const styleIds = new Set<string>();
+
+  const visitBlocks = (blocks: ReadonlyArray<BlockNode>) => {
+    for (const block of blocks) {
+      if ("styleId" in block && typeof block.styleId === "string" && block.styleId.length > 0) {
+        styleIds.add(block.styleId);
+      }
+      if (block.type === "table") {
+        for (const row of block.rows) {
+          for (const cell of row.cells) {
+            visitBlocks(cell.children);
+          }
+        }
+      } else if (block.type === "sdt" || block.type === "custom_xml") {
+        visitBlocks(block.children);
+      }
+    }
+  };
+
+  visitBlocks(content.children);
+  if (subParts) {
+    for (const header of subParts.headers) {
+      visitBlocks(header.blocks);
+    }
+    for (const footer of subParts.footers) {
+      visitBlocks(footer.blocks);
+    }
+    if (subParts.footnoteCollection) {
+      for (const note of Object.values(subParts.footnoteCollection.footnotes)) {
+        visitBlocks(note.blocks);
+      }
+      for (const note of Object.values(subParts.footnoteCollection.endnotes)) {
+        visitBlocks(note.blocks);
+      }
+    }
+  }
+
+  return styleIds;
+}
+
+/** Narrow a parsed catalog to entries whose styleId matches the
+ * canonical model pattern. Used defensively when the package
+ * `styles.xml` carries legacy entries (e.g. numeric-only ids from Word). */
+export function filterValidStyleIds(
+  catalog: CanonicalDocument["styles"],
+): CanonicalDocument["styles"] {
+  const filterRecord = <T extends { styleId: string }>(
+    record: Record<string, T>,
+  ): Record<string, T> => {
+    const result: Record<string, T> = {};
+    for (const [key, value] of Object.entries(record)) {
+      if (VALID_STYLE_ID.test(key)) {
+        result[key] = value;
+      }
+    }
+    return result;
+  };
+
+  return {
+    paragraphs: filterRecord(catalog.paragraphs),
+    characters: filterRecord(catalog.characters),
+    tables: filterRecord(catalog.tables),
+    ...(catalog.latentStyles ? { latentStyles: catalog.latentStyles } : {}),
+    ...(catalog.docDefaults ? { docDefaults: catalog.docDefaults } : {}),
+    ...(catalog.fromPackage !== undefined ? { fromPackage: catalog.fromPackage } : {}),
+  };
+}
+
+/** Build the `styles` facet. When the package shipped a `styles.xml`,
+ * the parsed catalog is filtered through {@link filterValidStyleIds}
+ * and any referenced-but-undefined style ids are synthesized as
+ * default entries. When there is no `styles.xml`, every referenced
+ * paragraph style becomes a synthetic entry. */
+export function buildStylesCatalog(
+  parsedStyles: ParseStylesResult | undefined,
+  content: CanonicalDocument["content"],
+  subParts?: SubPartsCatalog,
+): CanonicalDocument["styles"] {
+  if (parsedStyles?.fromPackage) {
+    const catalog = filterValidStyleIds(parsedStyles.catalog);
+
+    const referencedIds = collectReferencedParagraphStyleIds(content, subParts);
+    for (const styleId of referencedIds) {
+      if (!catalog.paragraphs[styleId] && VALID_STYLE_ID.test(styleId)) {
+        catalog.paragraphs[styleId] = {
+          styleId,
+          displayName: styleId,
+          kind: "paragraph",
+          isDefault: styleId === "Normal",
+        };
+      }
+    }
+    return {
+      ...catalog,
+      fromPackage: true,
+    };
+  }
+
+  const paragraphStyles = Object.fromEntries(
+    [...collectReferencedParagraphStyleIds(content, subParts)]
+      .sort((left, right) => left.localeCompare(right))
+      .filter((styleId) => VALID_STYLE_ID.test(styleId))
+      .map((styleId) => [
+        styleId,
+        {
+          styleId,
+          displayName: styleId,
+          kind: "paragraph" as const,
+          isDefault: styleId === "Normal",
+        },
+      ]),
+  );
+  return {
+    paragraphs: paragraphStyles,
+    characters: {},
+    tables: {},
+    fromPackage: false,
+  };
+}
+
+/** Walk the secondary-story blocks (headers, footers, footnotes,
+ * endnotes) and register every referenced image / drawing-frame
+ * media id into the media catalog. Called after the primary story
+ * has contributed its own entries so we only ADD here — existing
+ * entries win. */
+export function mergeSecondaryStoryMediaCatalog(
+  media: MediaCatalog,
+  input: {
+    headers: readonly HeaderDocument[];
+    footers: readonly FooterDocument[];
+    footnoteCollection?: FootnoteCollection;
+    mediaParts: ReadonlyMap<string, { path: string; contentType: string }>;
+  },
+): MediaCatalog {
+  const items = { ...media.items };
+  let changed = false;
+
+  const registerMediaItem = (
+    mediaId: string,
+    record: Omit<NonNullable<MediaCatalog["items"][string]>, "mediaId">,
+  ) => {
+    const existing = items[mediaId];
+    items[mediaId] = existing
+      ? {
+          ...existing,
+          ...record,
+          mediaId,
+        }
+      : {
+          mediaId,
+          ...record,
+        };
+    changed = true;
+  };
+
+  const visitInline = (node: InlineNode) => {
+    if (node.type === "image") {
+      const packagePartName = `/${node.mediaId.slice("media:".length)}`;
+      registerMediaItem(node.mediaId, {
+        contentType:
+          items[node.mediaId]?.contentType ??
+          input.mediaParts.get(packagePartName)?.contentType ??
+          "application/octet-stream",
+        filename: packagePartName.slice(packagePartName.lastIndexOf("/") + 1) || "image.bin",
+        packagePartName,
+        ...(node.altText ? { altText: node.altText } : {}),
+      });
+      return;
+    }
+    if (node.type === "drawing_frame" && node.content.type === "picture" && node.content.mediaId) {
+      const packagePartName =
+        typeof node.content.packagePartName === "string" && node.content.packagePartName.length > 0
+          ? node.content.packagePartName
+          : `/${node.content.mediaId.slice("media:".length)}`;
+      registerMediaItem(node.content.mediaId, {
+        contentType:
+          items[node.content.mediaId]?.contentType ??
+          input.mediaParts.get(packagePartName)?.contentType ??
+          "application/octet-stream",
+        filename: packagePartName.slice(packagePartName.lastIndexOf("/") + 1) || "image.bin",
+        packagePartName,
+        relationshipId: node.content.blipRef,
+        ...(node.anchor.docPr?.descr ? { altText: node.anchor.docPr.descr } : {}),
+        widthEmu: node.anchor.extent.widthEmu,
+        heightEmu: node.anchor.extent.heightEmu,
+      });
+      return;
+    }
+    if (node.type === "hyperlink" || node.type === "field") {
+      for (const child of node.children) {
+        visitInline(child);
+      }
+    }
+  };
+
+  const visitBlocks = (blocks: ReadonlyArray<BlockNode>) => {
+    for (const block of blocks) {
+      if (block.type === "paragraph") {
+        for (const child of block.children) {
+          visitInline(child);
+        }
+        continue;
+      }
+      if (block.type === "table") {
+        for (const row of block.rows) {
+          for (const cell of row.cells) {
+            visitBlocks(cell.children);
+          }
+        }
+        continue;
+      }
+      if (block.type === "sdt" || block.type === "custom_xml") {
+        visitBlocks(block.children);
+      }
+    }
+  };
+
+  for (const header of input.headers) {
+    visitBlocks(header.blocks);
+  }
+  for (const footer of input.footers) {
+    visitBlocks(footer.blocks);
+  }
+  if (input.footnoteCollection) {
+    for (const note of Object.values(input.footnoteCollection.footnotes)) {
+      visitBlocks(note.blocks);
+    }
+    for (const note of Object.values(input.footnoteCollection.endnotes)) {
+      visitBlocks(note.blocks);
+    }
+  }
+
+  return changed ? { ...media, items } : media;
+}

package/src/session/import/workflow-scope-import.ts

@@ -0,0 +1,256 @@
+/**
+ * CLM-workflow translation helpers extracted from `src/io/docx-session.ts`
+ * (slice 5e-6e). These functions lift `CLM:<TAG>:<description>` comment
+ * directives into workflow scopes + work items on a `WorkflowOverlay`,
+ * and auto-resolve the originating comment threads.
+ *
+ * P6-clean: `CommentThread` reaches through `src/model/review/`; every
+ * workflow type comes from `src/api/public-types.ts` (an allowed surface
+ * for the session layer). Anchor-shape conversion reaches through the
+ * shared boundary helper at `src/api/anchor-conversion.ts` (relocated in
+ * slice 5e-6g).
+ */
+
+import { toPublicAnchorProjection } from "../../api/anchor-conversion.ts";
+import type {
+  WorkflowMetadataSnapshot,
+  WorkflowOverlay,
+  WorkflowScope,
+  WorkflowScopeMetadataField,
+  WorkflowWorkItem,
+} from "../../api/public-types.ts";
+import type { CommentThread } from "../../model/review/comment-types.ts";
+import {
+  rangesIntersect,
+  resolveImportedCommentThreadOnTranslation,
+} from "./review-import.ts";
+
+export function translateClmCommentsToWorkflow(input: {
+  comments: readonly CommentThread[];
+  workflowOverlay?: WorkflowOverlay;
+  workflowMetadata?: WorkflowMetadataSnapshot;
+  timestamp: string;
+}): {
+  comments: CommentThread[];
+  workflowOverlay?: WorkflowOverlay;
+  workflowMetadata?: WorkflowMetadataSnapshot;
+} {
+  const nextComments = input.comments.map((thread) => structuredClone(thread));
+  let nextOverlay = input.workflowOverlay ? structuredClone(input.workflowOverlay) : undefined;
+  let overlayChanged = false;
+
+  for (const [index, thread] of nextComments.entries()) {
+    const directive = parseClmCommentDirective(thread);
+    if (!directive || thread.anchor.kind !== "range") {
+      continue;
+    }
+
+    if (!nextOverlay) {
+      nextOverlay = {
+        overlayVersion: "workflow-overlay/1",
+        scopes: [],
+      };
+    }
+
+    const existingScope = findExistingClmScope(nextOverlay.scopes, directive);
+    if (!existingScope) {
+      const version = getNextClmScopeVersion(nextOverlay.scopes, thread.anchor);
+      const scopeId = `clm-scope-${thread.commentId}-v${version}`;
+      const workItem = directive.tag === "TASK"
+        ? createClmWorkflowWorkItem(thread, directive.description, scopeId)
+        : undefined;
+      const scope = createClmWorkflowScope(thread, directive, version, scopeId, workItem?.workItemId);
+
+      nextOverlay.scopes = [...nextOverlay.scopes, scope];
+      if (workItem) {
+        nextOverlay.workItems = [...(nextOverlay.workItems ?? []), workItem];
+        if (!nextOverlay.activeWorkItemId) {
+          nextOverlay.activeWorkItemId = workItem.workItemId;
+        }
+      }
+      overlayChanged = true;
+    }
+
+    nextComments[index] = resolveImportedCommentThreadOnTranslation(thread, input.timestamp);
+  }
+
+  return {
+    comments: nextComments,
+    workflowOverlay: overlayChanged || input.workflowOverlay ? nextOverlay : undefined,
+    workflowMetadata: input.workflowMetadata,
+  };
+}
+
+export function parseClmCommentDirective(
+  thread: CommentThread,
+): { tag: "TASK" | "READ" | "COMMENT" | "EDIT"; description: string; sourceCommentId: string; sourceCommentDurableId?: string; sourceCommentParaId?: string; mode: WorkflowScope["mode"] } | undefined {
+  if (thread.metadata?.rootParaId === undefined && thread.entries[0]?.metadata?.parentParaId) {
+    return undefined;
+  }
+  const firstMeaningfulLine = thread.entries
+    .flatMap((entry) => entry.body.split(/\r?\n/u))
+    .map((line) => line.trim())
+    .find((line) => line.length > 0);
+  if (!firstMeaningfulLine) {
+    return undefined;
+  }
+  const match = /^CLM:([A-Z]+):(.*)$/u.exec(firstMeaningfulLine);
+  if (!match) {
+    return undefined;
+  }
+  const tag = match[1] as "TASK" | "READ" | "COMMENT" | "EDIT";
+  const description = (match[2] ?? "").trim();
+  const mode = getClmWorkflowScopeMode(tag);
+  if (!mode || description.length === 0) {
+    return undefined;
+  }
+  return {
+    tag,
+    description,
+    sourceCommentId: thread.metadata?.rootOoxmlCommentId ?? thread.commentId,
+    sourceCommentDurableId: thread.entries[0]?.metadata?.durableId,
+    sourceCommentParaId: thread.metadata?.rootParaId ?? thread.entries[0]?.metadata?.paraId,
+    mode,
+  };
+}
+
+export function getClmWorkflowScopeMode(tag: string): WorkflowScope["mode"] | undefined {
+  switch (tag) {
+    case "TASK":
+      return "suggest";
+    case "READ":
+      return "view";
+    case "COMMENT":
+      return "comment";
+    case "EDIT":
+      return "edit";
+    default:
+      return undefined;
+  }
+}
+
+export function createClmWorkflowWorkItem(
+  thread: CommentThread,
+  description: string,
+  scopeId: string,
+): WorkflowWorkItem {
+  return {
+    workItemId: `clm-task-${thread.commentId}`,
+    title: description,
+    description,
+    status: "pending",
+    scopeIds: [scopeId],
+  };
+}
+
+export function createClmWorkflowScope(
+  thread: CommentThread,
+  directive: NonNullable<ReturnType<typeof parseClmCommentDirective>>,
+  version: number,
+  scopeId: string,
+  workItemId?: string,
+): WorkflowScope {
+  if (workItemId) {
+    return {
+      scopeId,
+      version,
+      mode: directive.mode,
+      anchor: toPublicAnchorProjection(thread.anchor),
+      storyTarget: { kind: "main" },
+      workItemId,
+      label: directive.description,
+      metadata: createClmScopeMetadata(directive),
+    };
+  }
+  return {
+    scopeId,
+    version,
+    mode: directive.mode,
+    anchor: toPublicAnchorProjection(thread.anchor),
+    storyTarget: { kind: "main" },
+    label: directive.description,
+    metadata: createClmScopeMetadata(directive),
+  };
+}
+
+export function createClmScopeMetadata(
+  directive: NonNullable<ReturnType<typeof parseClmCommentDirective>>,
+): WorkflowScopeMetadataField[] {
+  return [
+    {
+      key: "workblock.clm.tag",
+      valueType: "string",
+      value: directive.tag,
+    },
+    {
+      key: "workblock.clm.description",
+      valueType: "string",
+      value: directive.description,
+    },
+    {
+      key: "workblock.sourceCommentId",
+      valueType: "string",
+      value: directive.sourceCommentId,
+    },
+    ...(directive.sourceCommentDurableId
+      ? [{
+          key: "workblock.sourceCommentDurableId",
+          valueType: "string" as const,
+          value: directive.sourceCommentDurableId,
+        }]
+      : []),
+    ...(directive.sourceCommentParaId
+      ? [{
+          key: "workblock.sourceCommentParaId",
+          valueType: "string" as const,
+          value: directive.sourceCommentParaId,
+        }]
+      : []),
+  ];
+}
+
+export function findExistingClmScope(
+  scopes: readonly WorkflowScope[],
+  directive: NonNullable<ReturnType<typeof parseClmCommentDirective>>,
+): WorkflowScope | undefined {
+  return scopes.find((scope) => {
+    const sourceCommentId = getWorkflowScopeMetadataValue(scope.metadata, "workblock.sourceCommentId");
+    const sourceCommentDurableId = getWorkflowScopeMetadataValue(
+      scope.metadata,
+      "workblock.sourceCommentDurableId",
+    );
+    return (
+      sourceCommentId === directive.sourceCommentId ||
+      (directive.sourceCommentDurableId !== undefined &&
+        sourceCommentDurableId === directive.sourceCommentDurableId)
+    );
+  });
+}
+
+export function getWorkflowScopeMetadataValue(
+  metadata: WorkflowScope["metadata"] | undefined,
+  key: string,
+): string | undefined {
+  const field = metadata?.find((entry) => entry.key === key);
+  return typeof field?.value === "string" ? field.value : undefined;
+}
+
+export function getNextClmScopeVersion(
+  scopes: readonly WorkflowScope[],
+  anchor: Extract<CommentThread["anchor"], { kind: "range" }>,
+): number {
+  const anchorRange = {
+    from: anchor.range.from,
+    to: anchor.range.to,
+  };
+  const overlappingVersions = scopes.flatMap((scope) => {
+    if (scope.anchor.kind !== "range") {
+      return [];
+    }
+    return rangesIntersect(scope.anchor, anchorRange) && typeof scope.version === "number"
+      ? [scope.version]
+      : [];
+  });
+  return overlappingVersions.length > 0 ? Math.max(...overlappingVersions) + 1 : 1;
+}
+

package/src/session/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Public barrel for Layer 01 (package / session).
+ *
+ * Reserved shape — matches `docs/architecture/01-package-session.md`
+ * § Public entry points. Consumers should import from `src/session`
+ * (or the `@beyondwork/docx-react-component/session` package subpath)
+ * rather than reaching into `src/io/docx-session.ts`. The legacy entry
+ * points remain exported from the root barrel for back-compat until
+ * Slice 5 deletes them.
+ */
+
+export {
+  DocxSession,
+  SessionNotOpenError,
+  SessionNotWiredError,
+} from "./session.ts";
+export { isReopenBarrier } from "./types.ts";
+export type { EditorSessionState } from "./session-state.ts";
+export type {
+  // Reserved Layer-01 contract types.
+  OpenOptions,
+  OpenResult,
+  ExportOptions,
+  ValidateOptions,
+  ValidationReport,
+  ValidationFinding,
+  PreservationSnapshot,
+  EmbeddedDocumentManifest,
+  // P8 Step 7 offload surface.
+  ReopenBarrier,
+  // Transitional re-exports from the legacy IO layer.
+  ExportResult,
+  EditorHostAdapter,
+  ExportDocxOptions,
+  LoadStage,
+  PersistedEditorSnapshot,
+} from "./types.ts";

package/src/session/session-state.ts

@@ -0,0 +1,69 @@
+/**
+ * Canonical definition of `EditorSessionState` — the host-facing session
+ * contract produced by Layer 01 on open and consumed on export.
+ *
+ * Moved here from `src/api/public-types.ts` in refactor/01 slice 3f
+ * (F5). `src/api/public-types.ts` now re-exports for back-compat; the
+ * owning module is this file.
+ *
+ * P6 clean: imports only from `src/model/**` (allowed) and `src/api/**`
+ * (allowed; type-only to avoid runtime coupling with the presentation
+ * surface).
+ */
+
+import type { PersistedEditorSnapshot as ModelPersistedEditorSnapshot } from "../model/snapshot.ts";
+import type {
+  CompatibilityReport,
+  EditorWarning,
+  OverlayVisibilityPolicy,
+  ProtectionSnapshot,
+  WorkflowMarkupModePolicy,
+  WorkflowMetadataSnapshot,
+  WorkflowOverlay,
+} from "../api/public-types.ts";
+
+/**
+ * Durable projection of an editor session suitable for persistence and
+ * rehydration. The shape is versioned independently from the model
+ * snapshot so that host-facing fields (e.g. `editorBuild`, warning log)
+ * can evolve without forcing model-layer version bumps.
+ *
+ * Semantic contract:
+ *   - `canonicalDocument` round-trips exactly through the `src/model/**`
+ *     serializer/validator. Layer 01 does not mutate canonical fields
+ *     during open/export.
+ *   - `sourcePackage`, when present, carries the opaque OPC package
+ *     reference the session opened from. Omit to materialize a session
+ *     with no byte-source (host-authored content, test fixtures).
+ */
+export interface EditorSessionState {
+  sessionVersion: "editor-session-state/1";
+  schemaVersion: ModelPersistedEditorSnapshot["schemaVersion"];
+  documentId: string;
+  docId: string;
+  createdAt: string;
+  updatedAt: string;
+  editorBuild: string;
+  canonicalDocument: ModelPersistedEditorSnapshot["canonicalDocument"];
+  compatibility: CompatibilityReport;
+  warningLog: EditorWarning[];
+  protectionSnapshot?: ProtectionSnapshot;
+  sourcePackage?: ModelPersistedEditorSnapshot["sourcePackage"];
+  workflowOverlay?: WorkflowOverlay;
+  workflowMetadata?: WorkflowMetadataSnapshot;
+  /**
+   * W10 — class-A overlay-visibility policies. Zero or more entries,
+   * at most one per `OverlayKind`. Empty array when the document
+   * carries no authored policy (consumers fall back to class-C local
+   * preference defaults). Persists via `customXml/item1.xml` under the
+   * `bw:overlayVisibility` namespace.
+   */
+  visibilityPolicies?: readonly OverlayVisibilityPolicy[];
+  /**
+   * X5 — class-A markup-mode policy. Single record; `undefined` when
+   * the document carries no authored mode (consumers fall back to the
+   * class-C local preference). Persists via `customXml/item1.xml`
+   * under the `bw:markupModePolicy` namespace.
+   */
+  markupModePolicy?: WorkflowMarkupModePolicy;
+}