@beyondwork/docx-react-component 1.0.42 → 1.0.45

package/src/io/ooxml/workflow-payload-validator.ts

@@ -19,7 +19,14 @@ export type ValidatorIssueCode =
   | "external_field_body_ignored"
   | "internal_entry_unexpected_storage_ref"
   | "internal_field_unexpected_storage_ref"
-  | "unsupported_version";
+  | "unsupported_version"
+  // Schema 1.2 editor-state codes
+  | "editor_state_unknown_namespace"
+  | "editor_state_duplicate_content"
+  | "editor_state_empty_content"
+  | "editor_state_invalid_inline_json"
+  | "editor_state_missing_entry_key"
+  | "editor_state_invalid_location";
 
 export type ValidatorIssueSeverity = "error" | "warning";
 
@@ -145,6 +152,95 @@ export function validateWorkflowPayloadEnvelope(xml: string): ValidatorIssue[] {
     }
   }
 
+  // Schema 1.2: <bw:editorState> checks.
+  const editorStateMatch = xml.match(/<bw:editorState\b[^>]*>([\s\S]*?)<\/bw:editorState>/u);
+  if (editorStateMatch) {
+    const editorStateBody = editorStateMatch[1] ?? "";
+    const nsRe = /<bw:namespace\b([^>]*)>([\s\S]*?)<\/bw:namespace>/gu;
+    for (const nsMatch of editorStateBody.matchAll(nsRe)) {
+      const attrsStr = nsMatch[1] ?? "";
+      const nsBody = nsMatch[2] ?? "";
+      const attrs = parseAttrs(attrsStr);
+      const name = attrs.name ?? "";
+      const nsPath = `bw:editorState/bw:namespace[@name='${name}']`;
+
+      // 1. Unknown namespace name (not in closed set) → warning.
+      const knownNames = ["hostAnnotations", "workflowOverlay", "workflowMetadata", "workItems"];
+      if (!knownNames.includes(name)) {
+        issues.push({
+          code: "editor_state_unknown_namespace",
+          path: nsPath,
+          severity: "warning",
+          value: name,
+        });
+        // Still check structural rules below for forward-compat awareness.
+      }
+
+      // 2. Detect presence of storageRef and inline.
+      const hasStorageRef = /<bw:storageRef\b/u.test(nsBody);
+      const hasInline = /<bw:inline\b/u.test(nsBody);
+
+      if (hasStorageRef && hasInline) {
+        // Both present → duplicate_content error.
+        issues.push({
+          code: "editor_state_duplicate_content",
+          path: nsPath,
+          severity: "error",
+        });
+      } else if (!hasStorageRef && !hasInline) {
+        // Neither present → empty_content error.
+        issues.push({
+          code: "editor_state_empty_content",
+          path: nsPath,
+          severity: "error",
+        });
+      } else if (hasStorageRef) {
+        // 3a. storageRef checks.
+        const refMatch = nsBody.match(/<bw:storageRef\b([^>]*)\/>/u);
+        if (refMatch) {
+          const refAttrs = parseAttrs(refMatch[1] ?? "");
+          const entryKey = refAttrs.entryKey ?? "";
+          const location = refAttrs.location ?? "";
+
+          if (entryKey === "") {
+            issues.push({
+              code: "editor_state_missing_entry_key",
+              path: `${nsPath}/bw:storageRef`,
+              severity: "error",
+            });
+          }
+
+          const knownLocations = ["rowstore", "key-only"];
+          if (location !== "" && !knownLocations.includes(location)) {
+            issues.push({
+              code: "editor_state_invalid_location",
+              path: `${nsPath}/bw:storageRef/@location`,
+              severity: "warning",
+              value: location,
+            });
+          }
+        }
+      } else if (hasInline) {
+        // 3b. inline JSON parse check.
+        const inlineMatch = nsBody.match(/<bw:inline\b[^>]*>([\s\S]*?)<\/bw:inline>/u);
+        if (inlineMatch) {
+          const rawContent = inlineMatch[1] ?? "";
+          // Strip CDATA markers (handles split CDATA too).
+          const text = rawContent.replace(/<!\[CDATA\[|\]\]>/g, "").trim();
+          try {
+            JSON.parse(text);
+          } catch {
+            issues.push({
+              code: "editor_state_invalid_inline_json",
+              path: `${nsPath}/bw:inline`,
+              severity: "error",
+            });
+          }
+        }
+      }
+    }
+  }
+
   // Top-level entries (bw:metadata body, outside scopes).
   // These resolve against overlay-only (no scope context available unless
   // the entry carries its own `scope="scope:{id}"` attribute, in which case

package/src/io/ooxml/workflow-payload.ts

@@ -12,11 +12,36 @@ import type {
   WorkflowScope,
   WorkflowWorkItem,
 } from "../../api/public-types.ts";
+import type { EditorStateNamespace, EditorStateLocation } from "../../api/editor-state-types.ts";
 import {
   validateWorkflowPayloadEnvelope,
   type ValidatorIssue,
 } from "./workflow-payload-validator.ts";
 
+// ---------------------------------------------------------------------------
+// Schema 1.2 editor-state types (edge-of-module shape, channel-free)
+// ---------------------------------------------------------------------------
+
+export interface EditorStatePayloadNamespaceEntry {
+  namespace: EditorStateNamespace;
+  schemaVersion: string;
+  /** JSON-serializable blob (CDATA-wrapped on serialize). Exactly one of inline/storageRef. */
+  inline?: unknown;
+  storageRef?: { location: Exclude<EditorStateLocation, "in-document">; entryKey: string };
+  /**
+   * Parser-internal flag: set when the `<bw:inline>` CDATA block contained
+   * malformed JSON.  Hydration surfaces this as `editor_state_part_load_failed`
+   * rather than silently dropping the entry.
+   */
+  malformedInline?: boolean;
+}
+
+export interface EditorStatePayload {
+  entries: EditorStatePayloadNamespaceEntry[];
+  /** Unknown namespaces preserved for round-trip — raw XML fragment per entry, keyed by name. */
+  unknownNamespaces?: Array<{ name: string; rawXml: string }>;
+}
+
 // ---------------------------------------------------------------------------
 // Schema 1.1 parser helpers (fail-closed per spec §8.2)
 // ---------------------------------------------------------------------------
@@ -62,6 +87,8 @@ type EmbeddedWorkflowPayloadDescriptor = {
 export interface WorkflowPayloadEnvelope {
   workflowMetadata: WorkflowMetadataSnapshot;
   workflowOverlay?: WorkflowOverlay;
+  /** Present only when the payload was version 1.2+ and carried a non-empty <bw:editorState> block. */
+  editorState?: EditorStatePayload;
   validatorIssues?: readonly ValidatorIssue[];
 }
 
@@ -87,6 +114,8 @@ export function buildWorkflowPayloadParts(input: {
   sourcePackage: OpcPackage;
   workflowMetadata: WorkflowMetadataSnapshot | undefined;
   workflowOverlay?: WorkflowOverlay;
+  /** Optional schema 1.2 editor-state block. Omitted when empty. */
+  editorState?: EditorStatePayload;
   documentId: string;
   createdAt: string;
   updatedAt: string;
@@ -126,6 +155,7 @@ export function buildWorkflowPayloadParts(input: {
     producerVersion: input.producerVersion,
     workflowMetadata,
     workflowOverlay: input.workflowOverlay,
+    editorState: input.editorState,
     preservedExtensionsXml: getPreservedExtensionsXml(input.sourcePackage, descriptor.payloadPartPath),
   });
   const itemPropsXml = buildItemPropsXml(descriptor.itemId);
@@ -238,12 +268,14 @@ export function parseWorkflowPayloadEnvelopeFromPackage(
   }
 
   const validatorIssues = validateWorkflowPayloadEnvelope(xml);
+  const editorState = parseEditorStateXml(xml);
   return {
     workflowMetadata: {
       definitions,
       entries,
     },
     workflowOverlay: parseWorkflowOverlay(xml),
+    ...(editorState !== undefined ? { editorState } : {}),
     ...(validatorIssues.length > 0 ? { validatorIssues } : {}),
   };
 }
@@ -287,6 +319,136 @@ function needsSchemaV11(input: {
   return false;
 }
 
+/** Returns true when the payload has at least one namespace entry or unknown namespace to emit. */
+function hasNonEmptyEditorState(es: EditorStatePayload | undefined): boolean {
+  if (!es) return false;
+  return (es.entries.length > 0) || ((es.unknownNamespaces?.length ?? 0) > 0);
+}
+
+// ---------------------------------------------------------------------------
+// Known namespace names (closed set for round-trip; unknown names are opaque)
+// ---------------------------------------------------------------------------
+
+const KNOWN_EDITOR_STATE_NAMESPACES: readonly EditorStateNamespace[] = [
+  "hostAnnotations",
+  "workflowOverlay",
+  "workflowMetadata",
+  "workItems",
+];
+
+const KNOWN_STORAGE_LOCATIONS: ReadonlyArray<Exclude<EditorStateLocation, "in-document">> = [
+  "rowstore",
+  "key-only",
+];
+
+/**
+ * Escapes `]]>` inside CDATA content using the standard XML split:
+ * `]]>` → `]]]]><![CDATA[>`
+ */
+function escapeCdata(text: string): string {
+  return text.replace(/\]\]>/g, "]]]]><![CDATA[>");
+}
+
+/**
+ * Builds the `<bw:editorState>…</bw:editorState>` block.
+ * Returns an empty string when both entries and unknownNamespaces are empty.
+ */
+export function buildEditorStateXml(payload: EditorStatePayload): string {
+  if (!hasNonEmptyEditorState(payload)) {
+    return "";
+  }
+
+  const knownLines = payload.entries.map((entry) => {
+    const nsOpen = `<bw:namespace name="${escapeXml(entry.namespace)}" schemaVersion="${escapeXml(entry.schemaVersion)}">`;
+    let content: string;
+    if (entry.storageRef !== undefined) {
+      content = `<bw:storageRef location="${escapeXml(entry.storageRef.location)}" entryKey="${escapeXml(entry.storageRef.entryKey)}" />`;
+    } else {
+      const json = escapeCdata(JSON.stringify(entry.inline));
+      content = `<bw:inline><![CDATA[${json}]]></bw:inline>`;
+    }
+    return `${nsOpen}${content}</bw:namespace>`;
+  });
+
+  const unknownLines = (payload.unknownNamespaces ?? []).map((u) => u.rawXml);
+
+  const innerXml = [...knownLines, ...unknownLines].join("\n");
+  return `<bw:editorState>\n${indentLines(innerXml, 2)}\n</bw:editorState>`;
+}
+
+/**
+ * Parses the `<bw:editorState>` block from a full workflow payload XML string.
+ * Returns `undefined` when no block is present.
+ * Malformed JSON is silently skipped (validator flags it separately).
+ */
+export function parseEditorStateXml(xml: string): EditorStatePayload | undefined {
+  const blockMatch = xml.match(/<bw:editorState\b[^>]*>([\s\S]*?)<\/bw:editorState>/u);
+  if (!blockMatch) {
+    return undefined;
+  }
+  const blockBody = blockMatch[1] ?? "";
+
+  const entries: EditorStatePayloadNamespaceEntry[] = [];
+  const unknownNamespaces: Array<{ name: string; rawXml: string }> = [];
+
+  // Match each <bw:namespace ... > ... </bw:namespace>
+  const nsRe = /<bw:namespace\b([^>]*)>([\s\S]*?)<\/bw:namespace>/gu;
+  for (const nsMatch of blockBody.matchAll(nsRe)) {
+    const attrsStr = nsMatch[1] ?? "";
+    const nsBody = nsMatch[2] ?? "";
+    const rawXml = nsMatch[0] ?? "";
+    const attrs = parseAttributes(attrsStr);
+    const name = attrs.name ?? "";
+    const schemaVersion = attrs.schemaVersion ?? "";
+
+    if (!(KNOWN_EDITOR_STATE_NAMESPACES as readonly string[]).includes(name)) {
+      unknownNamespaces.push({ name, rawXml });
+      continue;
+    }
+
+    const namespace = name as EditorStateNamespace;
+
+    // Parse <bw:storageRef ... />
+    const storageRefMatch = nsBody.match(/<bw:storageRef\b([^>]*)\/>/u);
+    if (storageRefMatch) {
+      const refAttrs = parseAttributes(storageRefMatch[1] ?? "");
+      const location = refAttrs.location as Exclude<EditorStateLocation, "in-document"> | undefined;
+      const entryKey = refAttrs.entryKey ?? "";
+      entries.push({
+        namespace,
+        schemaVersion,
+        storageRef: { location: location ?? "rowstore", entryKey },
+      });
+      continue;
+    }
+
+    // Parse <bw:inline>...</bw:inline> — extract CDATA content
+    const inlineMatch = nsBody.match(/<bw:inline\b[^>]*>([\s\S]*?)<\/bw:inline>/u);
+    if (inlineMatch) {
+      const raw = inlineMatch[1] ?? "";
+      // Extract CDATA content — handles split CDATA sections from ]]> escaping
+      const cdataText = raw.replace(/<!\[CDATA\[|\]\]>/g, "").trim();
+      try {
+        const parsed = JSON.parse(cdataText) as unknown;
+        entries.push({ namespace, schemaVersion, inline: parsed });
+      } catch {
+        // Malformed JSON: surface to the runtime so the host sees a
+        // load-failure event rather than silently losing the entry.
+        entries.push({ namespace, schemaVersion, malformedInline: true });
+      }
+    }
+  }
+
+  if (entries.length === 0 && unknownNamespaces.length === 0) {
+    return undefined;
+  }
+
+  return {
+    entries,
+    ...(unknownNamespaces.length > 0 ? { unknownNamespaces } : {}),
+  };
+}
+
 function buildPayloadXml(input: {
   descriptor: EmbeddedWorkflowPayloadDescriptor;
   createdAt: string;
@@ -294,9 +456,15 @@ function buildPayloadXml(input: {
   producerVersion: string;
   workflowMetadata: WorkflowMetadataSnapshot;
   workflowOverlay?: WorkflowOverlay;
+  editorState?: EditorStatePayload;
   preservedExtensionsXml: string;
 }): string {
-  const schemaVersion = needsSchemaV11(input) ? "1.1" : "1.0";
+  const hasEditorState = hasNonEmptyEditorState(input.editorState);
+  const schemaVersion = hasEditorState
+    ? "1.2"
+    : needsSchemaV11(input)
+      ? "1.1"
+      : "1.0";
 
   const definitionEntriesXml = input.workflowMetadata.definitions
     .map((definition) => [
@@ -351,6 +519,8 @@ function buildPayloadXml(input: {
     .filter((value) => value.trim().length > 0)
     .join("\n");
 
+  const editorStateXml = hasEditorState ? buildEditorStateXml(input.editorState!) : "";
+
   return [
     `<?xml version="1.0" encoding="UTF-8"?>`,
     `<bw:workflowPayload xmlns:bw="urn:beyondwork:workflow-payload:1" version="${schemaVersion}" payloadId="${escapeXml(input.descriptor.payloadId)}" itemId="${escapeXml(input.descriptor.itemId)}" documentId="${escapeXml(input.descriptor.documentId)}" createdAt="${escapeXml(input.createdAt)}" updatedAt="${escapeXml(input.updatedAt)}">`,
@@ -362,6 +532,7 @@ function buildPayloadXml(input: {
     definitionEntriesXml ? indentLines(definitionEntriesXml, 4) : "",
     metadataEntriesXml ? indentLines(metadataEntriesXml, 4) : "",
     `  </bw:metadata>`,
+    editorStateXml,
     extensionsXml
       ? `  <bw:extensions>\n${indentLines(extensionsXml, 4)}\n  </bw:extensions>`
       : `  <bw:extensions />`,

package/src/preservation/opaque-region.ts

@@ -121,6 +121,11 @@ export function createOpaqueRegionSurfaceModel(
 export function createOpaqueRegionSurfaceModelFromSurfaceBlock(
   block: Extract<SurfaceBlockSnapshot, { kind: "opaque_block" }>,
 ): OpaqueRegionSurfaceModel {
+  if (block.state === "placeholder-culled") {
+    throw new Error(
+      "createOpaqueRegionSurfaceModelFromSurfaceBlock: placeholder-culled block has no real fragment",
+    );
+  }
   return {
     fragmentId: block.fragmentId,
     warningId: block.warningId,

package/src/review/store/comment-remapping.ts

@@ -4,7 +4,7 @@ import {
   getAnchorRange,
   mapReviewAnchor,
   mappingTouchesAnchorContent,
-  rangeStaysWithinSingleParagraph,
+  rangeStaysWithinCommentableStory,
   type ReviewAnchor,
 } from "../../core/selection/review-anchors.ts";
 import type { TransactionMapping } from "../../core/selection/mapping.ts";
@@ -85,7 +85,7 @@ function normalizeCommentAnchor(
 
   if (
     mappedAnchor.kind === "range" &&
-    !rangeStaysWithinSingleParagraph(nextContent, mappedAnchor.range)
+    !rangeStaysWithinCommentableStory(nextContent, mappedAnchor.range)
   ) {
     return detachReviewAnchor(previousRange, "invalidatedByStructureChange");
   }

package/src/runtime/collab-session.ts

@@ -64,7 +64,7 @@ export interface AttachPayloadArgs {
 
 export type SendToExternalCallArgs = Omit<
   RuntimeSendToExternalArgs,
-  "bridge" | "tamperGate" | "signer" | "role"
+  "bridge" | "tamperGate" | "signer" | "role" | "resolver"
 > & {
   role?: "author" | "reviewer" | "observer";
 };