@beyondwork/docx-react-component 1.0.106 → 1.0.108

package/src/model/layout/page-graph-types.ts

@@ -88,10 +88,23 @@ export interface RuntimeResolvedRegions {
 export interface RuntimeExclusionZone {
   rectTwips: RuntimeTwipsRect;
   objectId: string;
-  wrapMode: string;
+  wrapMode: RuntimeAnchorWrapMode;
   layoutInCell?: boolean;
 }
 
+/**
+ * Project-canonical wrap mode union. Mirrors `AnchorGeometry["wrapMode"]` and
+ * `FloatingImageProperties["wrap"]` in `src/model/canonical-document.ts`.
+ * `behindText` / `inFrontOfText` are *not* wrap modes here — they live as the
+ * `behindDoc?: boolean` flag on the canonical floating shape.
+ */
+export type RuntimeAnchorWrapMode =
+  | "none"
+  | "square"
+  | "tight"
+  | "through"
+  | "topAndBottom";
+
 export type RuntimeLayoutDivergenceKind =
   | "frame-collision"
   | "intentional-overflow"
@@ -116,6 +129,14 @@ export interface RuntimePageFrame {
   pageIndex: number;
   sectionIndex: number;
   displayPageNumber: number;
+  /**
+   * PE2 v73 — explicit page-frame realization state for downstream runtime
+   * readers. L04-built frames are "complete" when every emitted region has a
+   * twips rect, "partial" when the graph exists but any region rect is absent,
+   * and "absent" is reserved for adapters describing a page without an L04
+   * frame.
+   */
+  completeness: RuntimePageFrameCompleteness;
   physicalBoundsTwips: RuntimeTwipsRect;
   regions: RuntimeResolvedRegions;
   pageLocalStories: RuntimePageLocalStoryInstance[];
@@ -123,6 +144,8 @@ export interface RuntimePageFrame {
   signature: string;
 }
 
+export type RuntimePageFrameCompleteness = "complete" | "partial" | "absent";
+
 export interface RuntimePageLocalStoryInstance {
   instanceId: string;
   storyKey: string;
@@ -156,11 +179,18 @@ export interface RuntimeStoryAnchoredObject {
     | "ole-embed"
     | "opaque-inline";
   display: "inline" | "floating" | "unknown";
+  /**
+   * Source wrap mode for floating objects when L04 can read it. This stays as
+   * source/layout truth in twips-space; exact projected object bboxes remain
+   * a Layer 05 geometry concern.
+   */
+  wrapMode?: RuntimeAnchorWrapMode;
   extentTwips?: {
     widthTwips: number;
     heightTwips: number;
   };
   relationshipIds?: readonly string[];
+  mediaIds?: readonly string[];
   preserveOnly: boolean;
   divergenceIds: string[];
 }
@@ -194,9 +224,16 @@ export interface RuntimeTableContinuationCursor {
   continuesFromPreviousPage: boolean;
   continuesToNextPage: boolean;
   repeatedHeaderRowIndexes: readonly number[];
+  splitRowCarry?: readonly RuntimeTableSplitRowCarry[];
   verticalMergeCarry: readonly RuntimeTableVerticalMergeCarry[];
 }
 
+export interface RuntimeTableSplitRowCarry {
+  rowIndex: number;
+  continuesFromPreviousPage: boolean;
+  continuesToNextPage: boolean;
+}
+
 export interface RuntimeTableVerticalMergeCarry {
   columnIndex: number;
   restartRowIndex: number;
@@ -221,6 +258,86 @@ export interface RuntimeFragmentLayoutObject {
     widthTwips?: number;
   };
   fieldFamilies?: readonly string[];
+  /**
+   * Field-region identities whose visible result participates in this
+   * page-local fragment. L04 owns the fragment/page membership; L01/L02 own the
+   * source and canonical ids copied here for Debug/L05 joins.
+   */
+  fieldRegions?: readonly RuntimeFieldRegionLayoutFacts[];
+  /**
+   * KI-005 — source numbering facts for geometry/debug consumers.
+   * L04 owns the page-local fragment and measured extent; this payload carries
+   * the resolved marker/text-column facts that L05 can project without
+   * re-reading the surface snapshot, DOM, or numbering resolver.
+   */
+  numbering?: RuntimeNumberingLayoutFacts;
+  /**
+   * Joinable numbering facts for every numbered paragraph represented by this
+   * fragment, including paragraphs nested inside tables and block content
+   * controls. `numbering` remains the direct-paragraph compatibility field;
+   * consumers that need runtime fragment/page joins should prefer this list.
+   */
+  numberingRows?: readonly RuntimeNumberingLayoutFacts[];
+}
+
+export interface RuntimeFieldRegionLayoutFacts {
+  fieldRegionId: string;
+  regionId: string;
+  canonicalFieldId: string;
+  regionKind: "field" | "toc-region" | "hyperlink-field";
+  storyKey: string;
+  fieldIndex: number;
+  paragraphIndex: number;
+  fieldFamily: string;
+  refreshStatus: string;
+  sourceRef?: {
+    sourceId: string;
+    partPath?: string;
+    storyKind?: string;
+    element?: string;
+    ordinal?: number;
+    startOffset?: number;
+    endOffset?: number;
+  };
+  fieldEvidence?: {
+    sourceRef?: RuntimeFieldRegionLayoutFacts["sourceRef"];
+    instructionHash?: string;
+    resultHash?: string;
+    locked?: boolean;
+    dirty?: boolean;
+  };
+}
+
+export interface RuntimeNumberingLayoutFacts {
+  numberingLayoutId?: string;
+  numberingKey?: string;
+  sourceBlockPath?: string;
+  sourceBlockId?: string;
+  paragraphIndex?: number;
+  numberingInstanceId?: string;
+  level?: number;
+  format?: string;
+  markerText?: string;
+  markerSuffix?: "tab" | "space" | "nothing";
+  markerJustification?: "left" | "center" | "right" | "both" | "distribute";
+  markerLane?: {
+    startTwips: number;
+    widthTwips: number;
+    textStartTwips: number;
+  };
+  textColumn?: {
+    startTwips: number;
+    rightTwips?: number;
+    firstLineTwips?: number;
+    hangingTwips?: number;
+  };
+  tabStops?: readonly RuntimeNumberingTabStopFacts[];
+}
+
+export interface RuntimeNumberingTabStopFacts {
+  positionTwips: number;
+  align?: string;
+  leader?: string;
 }
 
 // ---------------------------------------------------------------------------

package/src/model/review/revision-types.ts

@@ -29,7 +29,13 @@ export type RevisionActionability = "actionable" | "preserve-only";
 export type RevisionAnchorState = "active" | "detached";
 
 export interface PropertyChangeData {
-  xmlTag: "pPrChange" | "sectPrChange" | "tblPrChange" | "rPrChange";
+  xmlTag:
+    | "pPrChange"
+    | "sectPrChange"
+    | "tblPrChange"
+    | "trPrChange"
+    | "tcPrChange"
+    | "rPrChange";
   beforeXml: string;
 }
 
@@ -152,8 +158,9 @@ export function getRevisionActionability(
   // preserve-only (see revision-store.ts), which covers both `kind: "move"`
   // and `kind: "formatting"`. The overrides below flip the default back to
   // actionable for the specific shapes that Lane 7b promoted: cellIns
-  // structural-table revisions, and linked-pair move revisions. Do not add a
-  // `&& !preserveOnlyReason` guard here — that would re-lock these shapes
+  // structural-table revisions, linked container-form move revisions, and
+  // linked range-marker move revisions. Do not add a
+  // `&& !preserveOnlyReason` guard here — that would re-lock promoted shapes
   // against the injected default and regress 7b.
   if (
     typeof revision !== "string" &&
@@ -167,6 +174,10 @@ export function getRevisionActionability(
   if (
     typeof revision !== "string" &&
     revision.kind === "move" &&
+    (revision.metadata.originalRevisionType === "moveFrom" ||
+      revision.metadata.originalRevisionType === "moveTo" ||
+      revision.metadata.originalRevisionType === "moveFromRangeStart" ||
+      revision.metadata.originalRevisionType === "moveToRangeStart") &&
     typeof revision.metadata.moveData?.linkedRevisionId === "string" &&
     revision.metadata.moveData.linkedRevisionId.length > 0
   ) {

package/src/preservation/store.ts

@@ -22,6 +22,14 @@ export interface OpaqueFragmentDescriptor {
   detail: string;
 }
 
+export interface StructuredWrapperDescriptorOptions {
+  /**
+   * TOC doc-part SDTs are preserve-only workflow objects, but the surface
+   * projection must keep their cached result paragraphs visible.
+   */
+  projectVisibleTocContentControls?: boolean;
+}
+
 const BLOCKED_IMPORT_FEATURE_KEYS = new Set<OpaqueFragmentDescriptor["featureKey"]>([
   "alt-chunk",
   "custom-xml",
@@ -160,13 +168,21 @@ export function describeOpaqueFragment(
 
 export function describeStructuredWrapperBlock(
   block: BlockNode,
+  options: StructuredWrapperDescriptorOptions = {},
 ): OpaqueFragmentDescriptor | null {
   if (block.type === "sdt") {
     if (isTocContentControl(block)) {
-      // CCEP SOW templates wrap the visible cached TOC result paragraphs in a
-      // docPartObj SDT. Collapsing that wrapper hides LibreOffice-visible
-      // content, so keep the wrapper in the surface tree and project children.
-      return null;
+      if (options.projectVisibleTocContentControls) {
+        // CCEP SOW templates wrap the visible cached TOC result paragraphs in
+        // a docPartObj SDT. Collapsing that wrapper hides visible content, so
+        // callers that project the editing surface keep the wrapper recursive.
+        return null;
+      }
+      return {
+        featureKey: "content-controls",
+        label: "TOC content control",
+        detail: "Table of Contents doc-part content control remains package-backed and read-only.",
+      };
     }
     if (block.properties.sdtType === "docPartObj") {
       // coord-02 §11 P0 — a Template content control that wraps a

package/src/review/README.md

@@ -9,7 +9,7 @@ Frozen Wave 1 contract:
 - all review mutations flow through runtime commands and transactions
 - detached comments or revisions remain addressable with reason metadata; they are not silently dropped
 - v1 authoring is limited to single-paragraph comments, thread replies, tracked insertions, tracked deletions, and accept/reject flows
-- preserve-only review structures such as multi-paragraph editable comment ranges, tracked moves, and structural list/table revisions stay locked and warning-backed
+- preserve-only review structures such as multi-paragraph editable comment ranges, unlinked move revisions, and unsupported structural list/table revisions stay locked and warning-backed
 
 Key subdirectories:
 

package/src/review/store/revision-actions.ts

@@ -111,6 +111,7 @@ export function applyRevisionAction(
 
   if (
     revision.kind === "move" &&
+    isLinkedMoveActionRevision(revision) &&
     typeof revision.metadata.moveData?.linkedRevisionId === "string" &&
     revision.metadata.moveData.linkedRevisionId.length > 0
   ) {
@@ -212,7 +213,9 @@ export function applyRevisionAction(
   if (
     slice.some(
       (unit) =>
-        unit.kind === "paragraph_break" || unit.kind === "opaque_block",
+        unit.kind === "paragraph_break" ||
+        unit.kind === "opaque_block" ||
+        unit.kind === "structural_block",
     )
   ) {
     return skippedResult(
@@ -312,6 +315,15 @@ function applyPairedMoveAction(
   };
 }
 
+function isLinkedMoveActionRevision(revision: RevisionRecord): boolean {
+  return (
+    revision.metadata.originalRevisionType === "moveFrom" ||
+    revision.metadata.originalRevisionType === "moveTo" ||
+    revision.metadata.originalRevisionType === "moveFromRangeStart" ||
+    revision.metadata.originalRevisionType === "moveToRangeStart"
+  );
+}
+
 function applyRowStructuralAction(
   options: ApplyRevisionActionOptions,
   revision: RevisionRecord,
@@ -862,7 +874,7 @@ function mapParagraphRanges(
       continue;
     }
 
-    if (unit.kind === "opaque_block") {
+    if (unit.kind === "opaque_block" || unit.kind === "structural_block") {
       if (hasPendingParagraph) {
         paragraphs.push({ start, end: index });
       }

package/src/runtime/collab/event-types.ts

@@ -1,4 +1,4 @@
-import type { EditorCommand } from "../../core/commands/index.ts";
+import type { CommandOrigin, EditorCommand } from "../../core/commands/index.ts";
 import type { SelectionSnapshot } from "../../core/state/editor-state.ts";
 import type { EditorStoryTarget } from "../../api/public-types.ts";
 
@@ -63,6 +63,8 @@ export interface CommandEvent {
   authorId: string;
   /** ISO-8601 UTC timestamp at origin. */
   timestamp: string;
+  /** Normalized origin classification for remote replay/audit consumers. */
+  origin: CommandEventOriginMetadata;
   /** The exact `EditorCommand` that produced this delta. */
   command: EditorCommand;
   /** Context required for deterministic replay on remote clients. */
@@ -86,6 +88,23 @@ export interface CommandEvent {
   };
 }
 
+export type CommandEventOriginKind =
+  | "local-typing"
+  | "local-command"
+  | "runtime"
+  | "agent"
+  | "import"
+  | "field-refresh"
+  | "unknown";
+
+export type CommandEventOriginSource = CommandOrigin["source"] | "agent" | "import" | "field_refresh" | "unspecified";
+
+export interface CommandEventOriginMetadata {
+  readonly channel: "runtime-command-event";
+  readonly source: CommandEventOriginSource;
+  readonly kind: CommandEventOriginKind;
+}
+
 /**
  * Command types that are broadcast to all collaborators.
  *
@@ -184,6 +203,52 @@ export function isBroadcastCommand(command: EditorCommand): boolean {
   return BROADCAST_COMMAND_TYPES.has(command.type);
 }
 
+const TYPING_COMMAND_TYPES: ReadonlySet<EditorCommand["type"]> = new Set<EditorCommand["type"]>([
+  "text.insert",
+  "text.delete-backward",
+  "text.delete-forward",
+  "text.insert-tab",
+  "text.insert-hard-break",
+  "text.outdent-tab",
+  "paragraph.split",
+]);
+
+export function classifyCommandEventOriginSource(
+  source: CommandEventOriginSource,
+  commandType: EditorCommand["type"],
+): CommandEventOriginKind {
+  if (source === "agent") return "agent";
+  if (source === "import") return "import";
+  if (source === "field_refresh") return "field-refresh";
+  if (source === "runtime") return "runtime";
+  if (source === "keyboard" && TYPING_COMMAND_TYPES.has(commandType)) return "local-typing";
+  if (
+    source === "keyboard" ||
+    source === "toolbar" ||
+    source === "context_menu" ||
+    source === "comment_panel" ||
+    source === "review_panel" ||
+    source === "api"
+  ) {
+    return "local-command";
+  }
+  if (TYPING_COMMAND_TYPES.has(commandType)) return "local-typing";
+  return "unknown";
+}
+
+export function classifyCommandEventOrigin(command: EditorCommand): CommandEventOriginKind {
+  return classifyCommandEventOriginSource(command.origin?.source ?? "unspecified", command.type);
+}
+
+export function commandEventOriginMetadata(command: EditorCommand): CommandEventOriginMetadata {
+  const source = command.origin?.source ?? "unspecified";
+  return {
+    channel: "runtime-command-event",
+    source,
+    kind: classifyCommandEventOriginSource(source, command.type),
+  };
+}
+
 export interface CreateCommandEventInput {
   command: EditorCommand;
   originClientId: number;
@@ -203,6 +268,7 @@ export function createCommandEvent(input: CreateCommandEventInput): CommandEvent
     originClientId: input.originClientId,
     authorId: input.authorId,
     timestamp: input.timestamp,
+    origin: commandEventOriginMetadata(input.command),
     command: input.command,
     context: {
       documentMode: input.context?.documentMode,

package/src/runtime/collab/runtime-collab-sync.ts

@@ -11,6 +11,11 @@ import type {
   BlockNode,
   MutableCanonicalDocument,
 } from "../../model/canonical-document.ts";
+import type {
+  Assoc,
+  BoundaryAssoc,
+  InternalEditorAnchorProjection,
+} from "../../model/anchor.ts";
 import type {
   CommandAppliedMeta,
   DocumentRuntime,
@@ -19,6 +24,7 @@ import type {
 } from "../document-runtime.ts";
 import {
   createCommandEvent,
+  commandEventOriginMetadata,
   isBroadcastCommand,
   isLocalOnlyCommand,
   COMMAND_EVENT_SCHEMA_VERSION,
@@ -784,11 +790,58 @@ function asCommandEvent(value: unknown): CommandEvent | null {
     originClientId: value.originClientId,
     authorId: value.authorId,
     timestamp,
+    origin: asCommandEventOrigin(value.origin, command),
     command,
     context,
   };
 }
 
+function asCommandEventOrigin(value: unknown, command: EditorCommand): CommandEvent["origin"] {
+  if (!isRecord(value)) {
+    return commandEventOriginMetadata(command);
+  }
+  if (
+    value.channel === "runtime-command-event" &&
+    isCommandEventOriginSource(value.source) &&
+    isCommandEventOriginKind(value.kind)
+  ) {
+    return {
+      channel: "runtime-command-event",
+      source: value.source,
+      kind: value.kind,
+    };
+  }
+  return commandEventOriginMetadata(command);
+}
+
+function isCommandEventOriginSource(value: unknown): value is CommandEvent["origin"]["source"] {
+  return (
+    value === "keyboard" ||
+    value === "toolbar" ||
+    value === "context_menu" ||
+    value === "comment_panel" ||
+    value === "review_panel" ||
+    value === "api" ||
+    value === "runtime" ||
+    value === "agent" ||
+    value === "import" ||
+    value === "field_refresh" ||
+    value === "unspecified"
+  );
+}
+
+function isCommandEventOriginKind(value: unknown): value is CommandEvent["origin"]["kind"] {
+  return (
+    value === "local-typing" ||
+    value === "local-command" ||
+    value === "runtime" ||
+    value === "agent" ||
+    value === "import" ||
+    value === "field-refresh" ||
+    value === "unknown"
+  );
+}
+
 function normalizeTimestamp(value: unknown): string | null {
   if (typeof value === "string" && value.length > 0) {
     return value;
@@ -824,16 +877,131 @@ function asCommandEventContext(value: unknown): CommandEvent["context"] | null {
 
 function asSelectionSnapshot(value: unknown): CommandEvent["context"]["preSelection"] {
   if (!isRecord(value)) return undefined;
-  if (typeof value.anchor !== "number" || typeof value.head !== "number") return undefined;
+  if (!isFiniteNumber(value.anchor) || !isFiniteNumber(value.head)) return undefined;
   if (typeof value.isCollapsed !== "boolean") return undefined;
-  if (!isRecord(value.activeRange)) return undefined;
-  return value as unknown as CommandEvent["context"]["preSelection"];
+  const activeRange = asEditorAnchorProjection(value.activeRange);
+  if (!activeRange) return undefined;
+  return {
+    anchor: value.anchor,
+    head: value.head,
+    isCollapsed: value.isCollapsed,
+    activeRange,
+  };
 }
 
 function asStoryTarget(value: unknown): CommandEvent["context"]["activeStory"] {
   if (!isRecord(value)) return undefined;
-  if (typeof value.kind !== "string") return undefined;
-  return value as unknown as CommandEvent["context"]["activeStory"];
+  switch (value.kind) {
+    case "main":
+      return { kind: "main" };
+    case "header":
+    case "footer": {
+      if (typeof value.relationshipId !== "string" || value.relationshipId.length === 0) {
+        return undefined;
+      }
+      if (!isHeaderFooterVariant(value.variant)) {
+        return undefined;
+      }
+      if (value.sectionIndex != null && !isFiniteNumber(value.sectionIndex)) {
+        return undefined;
+      }
+      return value.sectionIndex == null
+        ? {
+            kind: value.kind,
+            relationshipId: value.relationshipId,
+            variant: value.variant,
+          }
+        : {
+            kind: value.kind,
+            relationshipId: value.relationshipId,
+            variant: value.variant,
+            sectionIndex: value.sectionIndex,
+          };
+    }
+    case "footnote":
+    case "endnote":
+      if (typeof value.noteId !== "string" || value.noteId.length === 0) {
+        return undefined;
+      }
+      return {
+        kind: value.kind,
+        noteId: value.noteId,
+      };
+    default:
+      return undefined;
+  }
+}
+
+function asEditorAnchorProjection(value: unknown): InternalEditorAnchorProjection | undefined {
+  if (!isRecord(value)) return undefined;
+  if (value.kind == null && isFiniteNumber(value.from) && isFiniteNumber(value.to)) {
+    return {
+      kind: "range",
+      from: value.from,
+      to: value.to,
+      assoc: { start: -1, end: 1 },
+    };
+  }
+
+  switch (value.kind) {
+    case "range": {
+      if (!isFiniteNumber(value.from) || !isFiniteNumber(value.to)) return undefined;
+      const assoc = asBoundaryAssoc(value.assoc);
+      if (!assoc) return undefined;
+      const range = value.range == null ? undefined : asDocRange(value.range);
+      if (value.range != null && !range) return undefined;
+      return range == null
+        ? { kind: "range", from: value.from, to: value.to, assoc }
+        : { kind: "range", from: value.from, to: value.to, range, assoc };
+    }
+    case "node": {
+      if (!isFiniteNumber(value.at)) return undefined;
+      const assoc = asAssoc(value.assoc);
+      if (assoc == null) return undefined;
+      return { kind: "node", at: value.at, assoc };
+    }
+    case "detached": {
+      const lastKnownRange = asDocRange(value.lastKnownRange);
+      if (!lastKnownRange) return undefined;
+      if (!isDetachedReason(value.reason)) return undefined;
+      return { kind: "detached", lastKnownRange, reason: value.reason };
+    }
+    default:
+      return undefined;
+  }
+}
+
+function asDocRange(value: unknown): { from: number; to: number } | undefined {
+  if (!isRecord(value)) return undefined;
+  if (!isFiniteNumber(value.from) || !isFiniteNumber(value.to)) return undefined;
+  return { from: value.from, to: value.to };
+}
+
+function asBoundaryAssoc(value: unknown): BoundaryAssoc | undefined {
+  if (isAssoc(value)) {
+    return { start: value, end: value };
+  }
+  if (!isRecord(value)) return undefined;
+  if (!isAssoc(value.start) || !isAssoc(value.end)) return undefined;
+  return { start: value.start, end: value.end };
+}
+
+function asAssoc(value: unknown): Assoc | undefined {
+  return isAssoc(value) ? value : undefined;
+}
+
+function isAssoc(value: unknown): value is Assoc {
+  return value === -1 || value === 1;
+}
+
+function isDetachedReason(
+  value: unknown,
+): value is Extract<InternalEditorAnchorProjection, { kind: "detached" }>["reason"] {
+  return value === "deleted" || value === "invalidatedByStructureChange" || value === "importAmbiguity";
+}
+
+function isHeaderFooterVariant(value: unknown): value is "default" | "first" | "even" {
+  return value === "default" || value === "first" || value === "even";
 }
 
 function isCommandDocumentMode(
@@ -848,3 +1016,7 @@ function isCommandDocumentMode(
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}

package/src/runtime/diagnostics/layout-guard-warning.ts

@@ -0,0 +1,18 @@
+export type LayoutWarningEmitter = (
+  type: string,
+  guard: string,
+  inputs: Record<string, unknown>,
+) => void;
+
+let activeLayoutWarningEmitter: LayoutWarningEmitter | undefined;
+
+export function setActiveLayoutWarningEmitter(fn: LayoutWarningEmitter | undefined): void {
+  activeLayoutWarningEmitter = fn;
+}
+
+export function emitLayoutGuardWarning(
+  guard: string,
+  inputs: Record<string, unknown>,
+): void {
+  activeLayoutWarningEmitter?.("layout.guard.return-empty", guard, inputs);
+}