@beyondwork/docx-react-component 1.0.106 → 1.0.108

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.106",
+  "version": "1.0.108",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [
@@ -35,7 +35,8 @@
     },
     "./api/v3": {
       "types": "./src/api/v3/index.ts",
-      "import": "./src/api/v3/index.ts"
+      "import": "./src/api/v3/index.ts",
+      "require": "./src/api/v3/index.ts"
     },
     "./compare": {
       "types": "./src/compare/index.ts",
@@ -43,7 +44,8 @@
     },
     "./session": {
       "types": "./src/session/index.ts",
-      "import": "./src/session/index.ts"
+      "import": "./src/session/index.ts",
+      "require": "./src/session/index.ts"
     },
     "./io/docx-session": {
       "types": "./src/io/docx-session.ts",
@@ -55,7 +57,8 @@
     },
     "./runtime/document-runtime": {
       "types": "./src/runtime/document-runtime.ts",
-      "import": "./src/runtime/document-runtime.ts"
+      "import": "./src/runtime/document-runtime.ts",
+      "require": "./src/runtime/document-runtime.ts"
     },
     "./runtime/collab": {
       "types": "./src/runtime/collab/index.ts",
@@ -212,6 +215,17 @@
     "mcp:tool-runner:visual-smoke": "bash scripts/tool-runner-mcp.sh visual-smoke",
     "mcp:tool-runner:ooxml-validator": "bash scripts/tool-runner-mcp.sh ooxml-validator",
     "mcp:tool-runner:truth": "bash scripts/tool-runner-mcp.sh truth",
-    "mcp:tool-runner:scope-calibration": "bash scripts/tool-runner-mcp.sh scope-calibration"
+    "mcp:tool-runner:scope-calibration": "bash scripts/tool-runner-mcp.sh scope-calibration",
+    "graph-oracle:build-static": "bash scripts/run-tool-workspace-command.sh node --import tsx services/truth-baseline/backends/word-graph-pdf/graph-oracle.ts build-static",
+    "graph-oracle": "bash scripts/run-tool-workspace-command.sh node --import tsx services/truth-baseline/backends/word-graph-pdf/graph-oracle.ts",
+    "graph-oracle:build-static:local": "node --import tsx services/truth-baseline/backends/word-graph-pdf/graph-oracle.ts build-static",
+    "graph-oracle:local": "node --import tsx services/truth-baseline/backends/word-graph-pdf/graph-oracle.ts",
+    "word-oracle:build-static": "bash scripts/run-tool-workspace-command.sh node --import tsx services/truth-baseline/backends/word-com/word-oracle.ts build-static",
+    "word-oracle": "bash scripts/run-tool-workspace-command.sh node --import tsx services/truth-baseline/backends/word-com/word-oracle.ts",
+    "word-oracle:build-static:local": "node --import tsx services/truth-baseline/backends/word-com/word-oracle.ts build-static",
+    "word-oracle:local": "node --import tsx services/truth-baseline/backends/word-com/word-oracle.ts",
+    "corpus-render:layout": "node scripts/organize-corpus-renders.mjs",
+    "corpus-render:assets": "bash scripts/run-corpus-render-assets.sh",
+    "corpus-render:assets:local": "node scripts/generate-corpus-render-assets.mjs"
   }
 }

package/src/api/geometry-overlay-rects.ts

@@ -0,0 +1,5 @@
+export {
+  resolvePageOverlayRectsFromGeometry,
+  type PageOverlayRect,
+  type OverlayVisiblePageIndexRange,
+} from "../runtime/geometry/index.ts";

package/src/api/package-version.ts

@@ -10,4 +10,4 @@
  * the string is committed directly so the runtime works without a build
  * step for tests.
  */
-export const PACKAGE_VERSION = "1.0.55";
+export const PACKAGE_VERSION = "1.0.56";

package/src/api/page-anchor-id.ts

@@ -0,0 +1,5 @@
+export {
+  buildPageAnchorAttributes,
+  buildPageAnchorElementId,
+  buildPageAnchorSelector,
+} from "./v3/_page-anchor-id.ts";

package/src/api/public-types.ts

@@ -182,6 +182,7 @@ export type {
   PublicNoteAllocation,
   PublicPageAnchor,
   PublicPageFrame,
+  PublicPageLocalStoryInstance,
   PublicPageNode,
   PublicPageRegion,
   PublicPageRegions,
@@ -189,9 +190,11 @@ export type {
   PublicRegionBlock,
   PublicRegionKind,
   PublicResolvedPageStories,
+  PublicResolvedStoryField,
   PublicResolvedParagraphFormatting,
   PublicResolvedRunFormatting,
   PublicSectionNode,
+  PublicStoryAnchoredObject,
   PublicTwipsRect,
   // R0.5: named page-format + margin-preset catalogs
   PageFormatDefinition,
@@ -1662,11 +1665,15 @@ export type SurfaceBlockSnapshot =
       alias?: string;
       tag?: string;
       lock?: string;
+      blockedReasonCode?: "workflow_preserve_only" | "workflow_blocked_import";
       checkboxChecked?: boolean;
       dateValue?: string;
       dropdownItems?: Array<{ displayText?: string; value: string }>;
       comboBoxItems?: Array<{ displayText?: string; value: string }>;
       showingPlcHdr?: boolean;
+      label?: string;
+      detail?: string;
+      featureKey?: string;
       children: SurfaceBlockSnapshot[];
     }
   | {
@@ -4856,9 +4863,9 @@ export interface WordReviewEditorRef {
   getCommentSidebarSnapshot(): CommentSidebarSnapshot;
   getTrackedChangesSnapshot(): TrackedChangesSnapshot;
   getSuggestionsSnapshot(): SuggestionsSnapshot;
-  /** @deprecated Use {@link getCommentSidebarSnapshot} instead. */
+  /** @deprecated Use {@link getCommentSidebarSnapshot} instead; remove after the next published API pin refresh. */
   getComments(): CommentSidebarSnapshot;
-  /** @deprecated Use {@link getTrackedChangesSnapshot} instead. */
+  /** @deprecated Use {@link getTrackedChangesSnapshot} instead; remove after the next published API pin refresh. */
   getTrackedChanges(): TrackedChangesSnapshot;
   isDirty(): boolean;
   getFormattingState(): FormattingStateSnapshot;
@@ -5081,7 +5088,10 @@ export interface WordReviewEditorRef {
   getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
   setWorkflowMetadataDefinitions(definitions: WorkflowMetadataDefinition[]): void;
   clearWorkflowMetadataDefinitions(): void;
-  setWorkflowMetadataEntries(entries: WorkflowMetadataEntry[]): void;
+  setWorkflowMetadataEntries(
+    entries: WorkflowMetadataEntry[],
+    origin?: WorkflowEventOrigin,
+  ): void;
   clearWorkflowMetadataEntries(): void;
   getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
   /**
@@ -5911,12 +5921,9 @@ export interface WordReviewEditorChromeVisibility {
   statusBar: boolean;
   reviewRail: boolean;
   /**
-   * TwShellHeader (Edit / Review / Workflow / More mode tabs) at the top
-   * of the workspace. Defaults to `true` on every preset EXCEPT
-   * `selection`, which is intended for minimal embeds and should not paint
-   * a workspace chrome header. coord-11 §21 — regressing this default has
-   * history, particularly for visual-fidelity captures that expect a
-   * truly chrome-less `chrome=none` embed.
+   * Optional host-supplied shell/header slot above the toolbar. Defaults to
+   * `false` for product presets; role switching lives in the main toolbar.
+   * Harness/operator shells must opt in explicitly.
    */
   shellHeader: boolean;
 }

package/src/api/table-node-specs.ts

@@ -0,0 +1,6 @@
+export {
+  tableNodeSpec,
+  tableRowNodeSpec,
+  tableCellNodeSpec,
+  tableHeaderCellNodeSpec,
+} from "../runtime/table-schema.ts";

package/src/api/v3/_create.ts

@@ -111,7 +111,8 @@ export interface CreateApiV3Opts {
   readonly ui?: UiControllerFactory;
   /**
    * Optional PE2 evidence bridge. Hosts/debug services that already have
-   * truth-oracle run metadata can inject it here; omitted means AI reads
+   * truth-oracle run metadata or Graph-PDF lookup records can inject them
+   * here; omitted means AI reads
    * report `pe2Evidence.oracle.status: "not-wired"`.
    */
   readonly pe2Evidence?: AiPe2EvidenceOptions;

package/src/api/v3/_page-anchor-id.ts

@@ -0,0 +1,52 @@
+export function buildPageAnchorElementId(
+  pageId: string | null | undefined,
+  pageIndex: number,
+): string {
+  const stablePageId = normalizePageAnchorId(pageId, pageIndex);
+  return `wre-page-anchor-${pageIndex}-${toDomIdToken(stablePageId)}`;
+}
+
+export function buildPageAnchorSelector(pageIndex: number): string {
+  const stablePageIndex = normalizePageIndex(pageIndex);
+  return `[data-page-anchor="true"][data-page-index="${stablePageIndex}"]`;
+}
+
+export function buildPageAnchorAttributes(
+  pageId: string | null | undefined,
+  pageIndex: number,
+): {
+  readonly id: string;
+  readonly "data-page-anchor": "true";
+  readonly "data-page-index": string;
+  readonly "data-page-id": string;
+} {
+  const stablePageIndex = normalizePageIndex(pageIndex);
+  const stablePageId = normalizePageAnchorId(pageId, stablePageIndex);
+  return {
+    id: buildPageAnchorElementId(stablePageId, stablePageIndex),
+    "data-page-anchor": "true",
+    "data-page-index": String(stablePageIndex),
+    "data-page-id": stablePageId,
+  };
+}
+
+function normalizePageAnchorId(
+  pageId: string | null | undefined,
+  pageIndex: number,
+): string {
+  return pageId && pageId.trim().length > 0 ? pageId : `page-${pageIndex}`;
+}
+
+function normalizePageIndex(pageIndex: number): number {
+  return Number.isFinite(pageIndex) && pageIndex >= 0
+    ? Math.floor(pageIndex)
+    : 0;
+}
+
+function toDomIdToken(value: string): string {
+  const token = value
+    .trim()
+    .replace(/[^A-Za-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return token.length > 0 ? token : "page";
+}

package/src/api/v3/_runtime-handle.ts

@@ -27,6 +27,80 @@
 
 import type { DocumentRuntime } from "../../runtime/document-runtime.ts";
 import type { CollabSession } from "../../runtime/collab-session.ts";
+import type { RuntimeCollabSyncHandle } from "../../runtime/collab/runtime-collab-sync.ts";
+
+export type RuntimeWordFieldMatrixOwner =
+  | "L01"
+  | "L02"
+  | "L03"
+  | "L04"
+  | "L05"
+  | "L06"
+  | "L08"
+  | "L11";
+
+export type RuntimeWordFieldMatrixGroup =
+  | "structuralSummary"
+  | "pageGeometry"
+  | "tableContinuations"
+  | "fields"
+  | "legalNumberingSamples"
+  | "anchorsAndObjects"
+  | "packagePreservation"
+  | "reviewMarkup";
+
+export type RuntimeWordFieldAvailability = "available" | "partial" | "missing";
+
+export interface RuntimeWordFieldMatrixComparisonLane {
+  readonly status: RuntimeWordFieldAvailability | "not-applicable";
+  readonly evidencePath?: string;
+  readonly note?: string;
+}
+
+export interface RuntimeWordFieldMatrixRow {
+  readonly group: RuntimeWordFieldMatrixGroup;
+  readonly field: string;
+  readonly primaryOwner: RuntimeWordFieldMatrixOwner;
+  readonly wordStatus: RuntimeWordFieldAvailability;
+  readonly wordEvidencePath: string;
+  readonly comparison: {
+    readonly libreOffice?: RuntimeWordFieldMatrixComparisonLane;
+    readonly sourcePackage?: RuntimeWordFieldMatrixComparisonLane;
+    readonly graphPdf?: RuntimeWordFieldMatrixComparisonLane;
+  };
+  readonly routingNote: string;
+}
+
+export interface RuntimeWordFieldMatrixArtifact {
+  readonly schemaVersion: "pe2-word-field-matrix/v0";
+  readonly artifactKind: "pe2.word-field-matrix";
+  readonly doc: {
+    readonly docId: string;
+    readonly corpusLane: string;
+    readonly sourceSha256?: string;
+  };
+  readonly generatedAtUtc: string;
+  readonly word: {
+    readonly status: string;
+    readonly oracleName?: string;
+    readonly backend?: string;
+    readonly recordPath?: string;
+    readonly unavailableReason?: string;
+  };
+  readonly summary: {
+    readonly rowCount: number;
+    readonly available: number;
+    readonly partial: number;
+    readonly missing: number;
+    readonly byOwner: Readonly<Record<RuntimeWordFieldMatrixOwner, number>>;
+    readonly byGroup: Readonly<Record<RuntimeWordFieldMatrixGroup, number>>;
+  };
+  readonly rows: readonly RuntimeWordFieldMatrixRow[];
+}
+
+export interface RuntimeWordFieldMatrixProvider {
+  getWordFieldMatrix(): RuntimeWordFieldMatrixArtifact | null | undefined;
+}
 
 /**
  * @endStateApi
@@ -35,13 +109,14 @@ import type { CollabSession } from "../../runtime/collab-session.ts";
  *
  * Optional members (declared via intersection after the Pick) expose
  * surfaces the runtime does not own directly but hosts can wire in —
- * `collabSession` is the first such member, letting v3's
+ * `collabSession` and `collabSync` are the first such members, letting v3's
  * `runtime.collab.*` family graduate its live path when hosts supply it
  * and fall back to deterministic mocks when they don't.
  */
 export type RuntimeApiHandle = Pick<
   DocumentRuntime,
   // Session + export (runtime.document family)
+  | "now"
   | "getSessionState"
   | "setDocumentMode"
   | "exportDocx"
@@ -135,6 +210,19 @@ export type RuntimeApiHandle = Pick<
    * deterministic mock snapshots (peers: [], posture: unattached).
    */
   readonly collabSession?: CollabSession;
+  /**
+   * Optional runtime command-event sync handle. Hosts that wire the
+   * Y.Array-backed command event transport pass it here so
+   * `runtime.collab.getRemoteReplayState()` can expose replay guard
+   * posture without leaking Yjs or the sync object.
+   */
+  readonly collabSync?: RuntimeCollabSyncHandle;
+  /**
+   * Optional Word-first PE2 field matrix provider. Debug/agent hosts can
+   * wire the artifact produced by `services/debug/lib/pe2-word-field-matrix.ts`;
+   * product runtime does not build or fetch Word COM evidence itself.
+   */
+  readonly wordFieldMatrix?: RuntimeWordFieldMatrixProvider;
 };
 
 /**
@@ -150,6 +238,7 @@ export type RuntimeApiHandle = Pick<
  * (this file, via tsgo) and audit-list drift (the test, via node:test).
  */
 export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true> = {
+  now: true,
   getSessionState: true,
   setDocumentMode: true,
   exportDocx: true,
@@ -202,4 +291,6 @@ export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true
   // fail `Record<keyof ...>`. Included explicitly so additions are
   // visible in this single audit roster.
   collabSession: true,
+  collabSync: true,
+  wordFieldMatrix: true,
 };

package/src/api/v3/ai/_audit-time.ts

@@ -0,0 +1,5 @@
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+
+export function currentAuditTimestamp(runtime: RuntimeApiHandle): string {
+  return runtime.now();
+}

package/src/api/v3/ai/_pe2-evidence.ts

@@ -73,6 +73,7 @@ export interface AiPe2LayoutDivergenceEvidence {
   readonly message: string;
   readonly regionKinds?: readonly string[];
   readonly fragmentIds?: readonly string[];
+  readonly objectIds?: readonly string[];
 }
 
 export interface AiPe2LayoutEvidence {
@@ -93,10 +94,23 @@ export type AiPe2OracleVerdict =
   | "runtime-projection-not-wired"
   | "not-compared";
 
+export interface AiPe2GraphOracleReference {
+  readonly mode: "static" | "live";
+  readonly cacheKey: string;
+  readonly lane?: string;
+  readonly docId?: string;
+  readonly pageCount?: number;
+  readonly paragraphCount?: number;
+  readonly pdfSha256?: string;
+  readonly sourceSha256?: string;
+  readonly backendIdentityTag?: string;
+}
+
 export interface AiPe2OracleEvidence {
   readonly status: "available" | "not-wired";
   readonly runIds: readonly string[];
   readonly divergenceIds: readonly string[];
+  readonly graphOracleReferences?: readonly AiPe2GraphOracleReference[];
   readonly verdict?: AiPe2OracleVerdict;
   readonly reason?: "truth-adapter-unavailable" | "truth-adapter-error";
 }
@@ -172,6 +186,27 @@ function copyLayoutDivergence(
     message: divergence.message,
     ...(divergence.regionKinds ? { regionKinds: [...divergence.regionKinds] } : {}),
     ...(divergence.fragmentIds ? { fragmentIds: [...divergence.fragmentIds] } : {}),
+    ...(divergence.objectIds ? { objectIds: [...divergence.objectIds] } : {}),
+  };
+}
+
+function copyGraphOracleReference(
+  reference: AiPe2GraphOracleReference,
+): AiPe2GraphOracleReference {
+  return {
+    mode: reference.mode,
+    cacheKey: reference.cacheKey,
+    ...(reference.lane ? { lane: reference.lane } : {}),
+    ...(reference.docId ? { docId: reference.docId } : {}),
+    ...(reference.pageCount !== undefined ? { pageCount: reference.pageCount } : {}),
+    ...(reference.paragraphCount !== undefined
+      ? { paragraphCount: reference.paragraphCount }
+      : {}),
+    ...(reference.pdfSha256 ? { pdfSha256: reference.pdfSha256 } : {}),
+    ...(reference.sourceSha256 ? { sourceSha256: reference.sourceSha256 } : {}),
+    ...(reference.backendIdentityTag
+      ? { backendIdentityTag: reference.backendIdentityTag }
+      : {}),
   };
 }
 
@@ -232,6 +267,9 @@ function copyOracleEvidence(evidence: AiPe2OracleEvidence): AiPe2OracleEvidence
     status: evidence.status,
     runIds: [...evidence.runIds],
     divergenceIds: [...evidence.divergenceIds],
+    ...(evidence.graphOracleReferences
+      ? { graphOracleReferences: evidence.graphOracleReferences.map(copyGraphOracleReference) }
+      : {}),
     ...(evidence.verdict ? { verdict: evidence.verdict } : {}),
     ...(evidence.reason ? { reason: evidence.reason } : {}),
   };

package/src/api/v3/ai/attach.ts

@@ -41,6 +41,7 @@ import {
   projectAuditReference,
   type AiActionAuditReference,
 } from "./_audit-reference.ts";
+import { currentAuditTimestamp } from "./_audit-time.ts";
 
 export interface AttachExplanationInput {
   readonly scopeId: string;
@@ -146,10 +147,12 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
       );
       const preScope = captureScopeSnapshot(runtime, input.scopeId);
       const documentHashBefore = snapshotDocumentHash(runtime);
+      const emittedAtUtc = currentAuditTimestamp(runtime);
       const primitiveResult = compiler.attachExplanation({
         scopeId: input.scopeId,
         explanation: input.explanation,
         explanationId,
+        createdAtUtc: emittedAtUtc,
       });
       let auditReference: AiActionAuditReference | undefined;
       if (primitiveResult.attached && preScope) {
@@ -169,7 +172,7 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
           },
           compiledOperationKind: "metadata-attach-explanation",
           compiledOperationSummary: `attach explanation ${primitiveResult.explanationId} to scope ${input.scopeId}`,
-          emittedAtUtc: new Date(0).toISOString(),
+          emittedAtUtc,
           documentHashBefore,
         });
         auditReference = projectAuditReference(audit);
@@ -206,11 +209,13 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
       );
       const preScope = captureScopeSnapshot(runtime, input.scopeId);
       const documentHashBefore = snapshotDocumentHash(runtime);
+      const emittedAtUtc = currentAuditTimestamp(runtime);
       const primitiveResult = compiler.createIssue({
         scopeId: input.scopeId,
         summary: input.summary,
         ...(input.severity ? { severity: input.severity } : {}),
         issueId,
+        createdAtUtc: emittedAtUtc,
       });
       let auditReference: AiActionAuditReference | undefined;
       if (primitiveResult.created && preScope) {
@@ -231,7 +236,7 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
           },
           compiledOperationKind: "metadata-attach-issue",
           compiledOperationSummary: `create issue ${primitiveResult.issueId} on scope ${input.scopeId}`,
-          emittedAtUtc: new Date(0).toISOString(),
+          emittedAtUtc,
           documentHashBefore,
         });
         auditReference = projectAuditReference(audit);