@beyondwork/docx-react-component 1.0.83 → 1.0.85

package/src/runtime/scopes/workflow-overlap.ts

@@ -3,11 +3,13 @@
  *
  * Given a scope's canonical range and the workflow overlay, returns the
  * `SemanticScopeWorkflow` projection: the ids of overlay scopes overlapping
- * the range + the most-restrictive `effectiveMode` across them +
- * `blockedReasons` when a `view`-mode overlap blocks the scope.
+ * the range + the most-restrictive enforced `effectiveMode` across scopes
+ * whose `guardPolicy` participates in editing + `blockedReasons` when a
+ * read-only overlap blocks the scope.
  *
  * The most-restrictive rule matches layer 06's `InteractionGuardSnapshot`
- * composition (see `docs/architecture/06-workflow-review.md` §W3):
+ * composition for guard-participating scopes (see
+ * `docs/architecture/06-workflow-review.md` §W3):
  *   view > comment > suggest > edit
  *
  * When no overlay is threaded, or no overlap exists, the returned shape
@@ -19,7 +21,11 @@
  * overlap on top.
  */
 
-import type { WorkflowOverlay, WorkflowScope } from "./_scope-dependencies.ts";
+import type {
+  WorkflowOverlay,
+  WorkflowScope,
+  WorkflowScopeGuardPolicy,
+} from "./_scope-dependencies.ts";
 
 import type { ScopePositionMap, ScopePositionRange } from "./position-map.ts";
 import { rangesOverlap } from "./scope-range.ts";
@@ -27,6 +33,14 @@ import type { SemanticScopeWorkflow } from "./semantic-scope-types.ts";
 
 type WorkflowMode = "edit" | "suggest" | "comment" | "view";
 
+function getScopeGuardPolicy(scope: WorkflowScope): WorkflowScopeGuardPolicy {
+  return scope.guardPolicy ?? (scope.mode === "view" ? "read-only" : "none");
+}
+
+function getScopeGuardMode(scope: WorkflowScope): WorkflowMode {
+  return getScopeGuardPolicy(scope) === "read-only" ? "view" : scope.mode;
+}
+
 function modeRank(mode: WorkflowMode): number {
   // Higher = more restrictive (wins the merge).
   switch (mode) {
@@ -45,6 +59,21 @@ function mergeModes(a: WorkflowMode, b: WorkflowMode): WorkflowMode {
   return modeRank(a) >= modeRank(b) ? a : b;
 }
 
+function rangeForWorkflowScope(
+  scope: WorkflowScope,
+  positionMap: ScopePositionMap,
+): ScopePositionRange | null {
+  const markerRange = positionMap.markerScopes.get(scope.scopeId);
+  if (markerRange) return markerRange;
+  if (scope.anchor.kind === "range") {
+    return { from: scope.anchor.from, to: scope.anchor.to };
+  }
+  if (scope.anchor.kind === "node") {
+    return { from: scope.anchor.at, to: scope.anchor.at };
+  }
+  return null;
+}
+
 export interface WorkflowOverlapInputs {
   readonly overlay: WorkflowOverlay | null | undefined;
   readonly positionMap: ScopePositionMap;
@@ -73,12 +102,15 @@ export function resolveWorkflowOverlap(
   let mode: WorkflowMode = "edit";
   for (const scope of overlay.scopes as readonly WorkflowScope[]) {
     if (selfScopeIds && selfScopeIds.has(scope.scopeId)) continue;
-    const markerRange = positionMap.markerScopes.get(scope.scopeId);
-    if (!markerRange) continue;
-    if (!rangesOverlap(range, markerRange)) continue;
+    const scopeRange = rangeForWorkflowScope(scope, positionMap);
+    if (!scopeRange) continue;
+    if (!rangesOverlap(range, scopeRange)) continue;
     overlappingIds.push(scope.scopeId);
-    mode = mergeModes(mode, scope.mode);
-    if (scope.mode === "view") {
+    const guardPolicy = getScopeGuardPolicy(scope);
+    if (guardPolicy === "none") continue;
+    const guardMode = getScopeGuardMode(scope);
+    mode = mergeModes(mode, guardMode);
+    if (guardMode === "view") {
       blockedReasons.push(`workflow-scope-view:${scope.scopeId}`);
     }
   }

package/src/runtime/suggestions-snapshot.ts

@@ -68,6 +68,26 @@ function summarizeActionability(
     : "actionable";
 }
 
+function collectLinkedCommentThreadIds(
+  revisions: TrackedChangeEntrySnapshot[],
+): string[] | undefined {
+  const ids = new Set<string>();
+  for (const revision of revisions) {
+    for (const commentThreadId of revision.commentThreadIds ?? []) {
+      ids.add(commentThreadId);
+    }
+  }
+  return ids.size > 0 ? [...ids] : undefined;
+}
+
+function countLinkedReplies(revisions: TrackedChangeEntrySnapshot[]): number {
+  let count = 0;
+  for (const revision of revisions) {
+    count += revision.replyCount ?? 0;
+  }
+  return count;
+}
+
 export function createSuggestionsSnapshot(
   trackedChanges: TrackedChangesSnapshot,
 ): SuggestionsSnapshot {
@@ -89,6 +109,8 @@ export function createSuggestionsSnapshot(
       const kind = toSemanticKind(primary);
       const status = summarizeStatus(revisions);
       const actionability = summarizeActionability(revisions);
+      const commentThreadIds = collectLinkedCommentThreadIds(revisions);
+      const replyCount = countLinkedReplies(revisions);
       return {
         suggestionId,
         kind,
@@ -108,6 +130,8 @@ export function createSuggestionsSnapshot(
         preserveOnlyReason: primary.preserveOnlyReason,
         excerpt: primary.excerpt,
         detail: primary.detail,
+        ...(commentThreadIds ? { commentThreadIds } : {}),
+        ...(replyCount > 0 ? { replyCount } : {}),
       };
     })
     .sort(compareSuggestions);

package/src/runtime/surface-projection.ts

@@ -1536,7 +1536,34 @@ function appendInlineSegments(
         node.fieldFamily === "NOTEREF" ||
         node.fieldFamily === "TOC" ||
         node.fieldFamily === "PAGE" ||
-        node.fieldFamily === "NUMPAGES";
+        node.fieldFamily === "NUMPAGES" ||
+        node.fieldFamily === "SECTIONPAGES";
+      const isPageScopedField =
+        node.fieldFamily === "PAGE" ||
+        node.fieldFamily === "NUMPAGES" ||
+        node.fieldFamily === "SECTIONPAGES";
+      if (isPageScopedField) {
+        const fieldLabel =
+          node.fieldFamily === "PAGE"
+            ? "Current page number"
+            : node.fieldFamily === "NUMPAGES"
+              ? "Total pages"
+              : "Section pages";
+        const displayText = flattenSurfaceFieldDisplayText(node.children);
+        paragraph.segments.push({
+          segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+          kind: "field_ref",
+          from: start,
+          to: start + 1,
+          fieldFamily: node.fieldFamily,
+          fieldTarget: node.fieldTarget,
+          instruction: node.instruction,
+          refreshStatus: node.refreshStatus ?? "stale",
+          label: fieldLabel,
+          ...(displayText ? { displayText } : {}),
+        } as SurfaceInlineSegment);
+        return { nextCursor: start + 1, lockedFragmentIds: [] };
+      }
       if (node.children && node.children.length > 0) {
         // For REF \h, pass the bookmark as a hyperlink href so child text gets hyperlink styling
         const refHyperlinkHref =
@@ -1574,7 +1601,9 @@ function appendInlineSegments(
               ? "Current page number"
               : node.fieldFamily === "NUMPAGES"
                 ? "Total pages"
-                : `${node.fieldFamily ?? "Field"}: ${node.fieldTarget ?? node.instruction.trim()}`;
+                : node.fieldFamily === "SECTIONPAGES"
+                  ? "Section pages"
+                  : `${node.fieldFamily ?? "Field"}: ${node.fieldTarget ?? node.instruction.trim()}`;
         paragraph.segments.push({
           segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
           kind: "field_ref",
@@ -1743,6 +1772,34 @@ function normalizeSafeCssHexColor(value: string | undefined): string | undefined
   return trimmed.replace(/^#/, "").toUpperCase();
 }
 
+function flattenSurfaceFieldDisplayText(
+  children: readonly InlineNode[] | undefined,
+): string {
+  if (!children || children.length === 0) return "";
+  const parts: string[] = [];
+  for (const child of children) {
+    switch (child.type) {
+      case "text":
+        parts.push(child.text);
+        break;
+      case "tab":
+      case "hard_break":
+        parts.push(" ");
+        break;
+      case "symbol":
+        parts.push(child.char ? String.fromCodePoint(parseInt(child.char, 16)) : "\uFFFD");
+        break;
+      case "field":
+      case "hyperlink":
+        parts.push(flattenSurfaceFieldDisplayText(child.children));
+        break;
+      default:
+        break;
+    }
+  }
+  return parts.join("");
+}
+
 /**
  * V2c.5 — Extract the first paragraph's plain text from a parsed
  * `txbxBlocks` tree for the `txbxText` segment preview.  The recursion

package/src/runtime/workflow/coordinator.ts

@@ -64,6 +64,7 @@ import type {
   WorkflowMetadataSnapshot,
   WorkflowOverlay,
   WorkflowScope,
+  WorkflowScopeGuardPolicy,
   WorkflowScopeMode,
   WorkflowScopeSnapshot,
 } from "../../api/public-types.ts";
@@ -227,6 +228,11 @@ export interface WorkflowCoordinator {
   addInvisibleScope(params: AddScopeParams): AddScopeResult;
   setScopeVisibility(scopeId: string, visibility: ScopeVisibility): void;
   getScopeVisibility(scopeId: string): ScopeVisibility;
+  setScopeGuardPolicy(
+    scopeId: string,
+    guardPolicy: WorkflowScopeGuardPolicy,
+  ): void;
+  getScopeGuardPolicy(scopeId: string): WorkflowScopeGuardPolicy;
   getScope(scopeId: string): WorkflowScope | null;
   getMarkerBackedScopeIds(): ReadonlySet<string>;
   /* --- scope chrome visibility (local view state) --- */
@@ -316,6 +322,18 @@ const MODE_RESTRICTIVENESS: Record<WorkflowScopeMode, number> = {
   view: 3,
 };
 
+function resolveScopeGuardPolicy(scope: WorkflowScope): WorkflowScopeGuardPolicy {
+  return scope.guardPolicy ?? (scope.mode === "view" ? "read-only" : "none");
+}
+
+function getScopeGuardMode(scope: WorkflowScope): WorkflowScopeMode {
+  return resolveScopeGuardPolicy(scope) === "read-only" ? "view" : scope.mode;
+}
+
+function participatesInInteractionGuard(scope: WorkflowScope): boolean {
+  return resolveScopeGuardPolicy(scope) !== "none";
+}
+
 export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordinator {
   const { overlayStore, clock } = deps;
 
@@ -413,8 +431,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     };
     const activeScopes = getEffectiveWorkflowScopes(overlay);
     const matching = activeScopes.filter((scope) => {
-      // §C8: invisible non-view scopes are transparent to the guard.
-      if (scope.visibility === "invisible" && scope.mode !== "view") return false;
+      if (!participatesInInteractionGuard(scope)) return false;
       if (scope.anchor.kind === "detached") return false;
       const scopeFrom =
         scope.anchor.kind === "range" ? scope.anchor.from : scope.anchor.at;
@@ -450,8 +467,8 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     if (stack.length === 0) return null;
     // §C6 — most-restrictive-wins across overlapping scopes.
     return stack.reduce((best, scope) =>
-      (MODE_RESTRICTIVENESS[scope.mode] ?? 0) >
-      (MODE_RESTRICTIVENESS[best.mode] ?? 0)
+      (MODE_RESTRICTIVENESS[getScopeGuardMode(scope)] ?? 0) >
+      (MODE_RESTRICTIVENESS[getScopeGuardMode(best)] ?? 0)
         ? scope
         : best,
     );
@@ -463,7 +480,9 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     const mode = deps.getDocumentMode();
     if (mode === "viewing" || mode === "commenting") return mode;
     const matchingScope = getMatchingWorkflowScope(selection);
-    if (matchingScope?.mode === "suggest") return "suggesting";
+    if (matchingScope && getScopeGuardMode(matchingScope) === "suggest") {
+      return "suggesting";
+    }
     return mode;
   }
 
@@ -536,17 +555,18 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     if (normalized) {
       const matchingScope = getMatchingWorkflowScope(selection);
       const activeScopes = getEffectiveWorkflowScopes(normalized);
-      const guardingScopes = activeScopes.filter(
-        (s) => !(s.visibility === "invisible" && s.mode !== "view"),
+      const insertOnlyScopes = activeScopes.filter(
+        (s) => resolveScopeGuardPolicy(s) === "insert-only",
       );
 
-      if (!matchingScope && guardingScopes.length > 0) {
+      if (!matchingScope && insertOnlyScopes.length > 0) {
         reasons.push({
           code: "outside_workflow_scope",
-          message: "Selection is outside any active workflow scope.",
+          message: "Selection is outside any active insert-only workflow scope.",
         });
       } else if (matchingScope) {
-        if (matchingScope.mode === "comment") {
+        const guardMode = getScopeGuardMode(matchingScope);
+        if (guardMode === "comment") {
           const isCommentCommand = commandType?.startsWith("comment.") ?? false;
           if (!isCommentCommand) {
             reasons.push({
@@ -556,7 +576,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
               workItemId: matchingScope.workItemId,
             });
           }
-        } else if (matchingScope.mode === "view") {
+        } else if (guardMode === "view") {
           reasons.push({
             code: "workflow_view_only",
             message: `Scope "${matchingScope.label ?? matchingScope.scopeId}" is view-only.`,
@@ -618,6 +638,9 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     const matchingScope = getMatchingWorkflowScope(state.selection);
     const scopeStack = buildMatchingScopeStack(state.selection);
     const primaryBlockedReason = blockedReasons[0];
+    const matchingGuardMode = matchingScope
+      ? getScopeGuardMode(matchingScope)
+      : undefined;
     const effectiveMode = primaryBlockedReason
       ? primaryBlockedReason.code === "workflow_comment_only"
         ? "comment"
@@ -626,19 +649,19 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           : "blocked"
       : getEffectiveDocumentMode(state.selection) === "suggesting"
         ? "suggest"
-        : matchingScope?.mode ?? "edit";
+        : matchingGuardMode ?? "edit";
     const matchedScopeStack: InteractionGuardSnapshot["matchedScopeStack"] =
       scopeStack.length > 0
         ? scopeStack.map((s) => ({
             scopeId: s.scopeId,
-            mode: s.mode,
+            mode: getScopeGuardMode(s),
             visibility: s.visibility ?? "visible",
           }))
         : undefined;
     const snapshot: InteractionGuardSnapshot = {
       effectiveMode,
       ...(matchingScope?.scopeId ? { matchedScopeId: matchingScope.scopeId } : {}),
-      ...(matchingScope?.mode ? { matchedScopeMode: matchingScope.mode } : {}),
+      ...(matchingGuardMode ? { matchedScopeMode: matchingGuardMode } : {}),
       ...(matchedScopeStack ? { matchedScopeStack } : {}),
       targetAccess:
         effectiveMode === "edit"
@@ -888,6 +911,8 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
       anchor: publicAnchor,
       ...(params.storyTarget ? { storyTarget: params.storyTarget } : {}),
       ...(params.label ? { label: params.label } : {}),
+      ...(params.visibility ? { visibility: params.visibility } : {}),
+      ...(params.guardPolicy ? { guardPolicy: params.guardPolicy } : {}),
       ...(params.scopeMetadataFields && params.scopeMetadataFields.length > 0
         ? { metadata: [...params.scopeMetadataFields] }
         : {}),
@@ -1004,6 +1029,31 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     return scope?.visibility ?? "visible";
   }
 
+  function setScopeGuardPolicy(
+    scopeId: string,
+    guardPolicy: WorkflowScopeGuardPolicy,
+  ): void {
+    const overlay = overlayStore.getOverlay();
+    if (!overlay) return;
+    const idx = overlay.scopes.findIndex((s) => s.scopeId === scopeId);
+    if (idx === -1) return;
+    const nextScopes = overlay.scopes.map((s) =>
+      s.scopeId === scopeId ? { ...s, guardPolicy } : s,
+    );
+    deps.dispatch({
+      type: "workflow.set-overlay",
+      overlay: { ...overlay, scopes: nextScopes },
+      origin: { source: "api", at: clock() },
+    });
+  }
+
+  function getScopeGuardPolicy(scopeId: string): WorkflowScopeGuardPolicy {
+    const overlay = overlayStore.getOverlay();
+    if (!overlay) return "none";
+    const scope = overlay.scopes.find((s) => s.scopeId === scopeId);
+    return scope ? resolveScopeGuardPolicy(scope) : "none";
+  }
+
   function getScope(scopeId: string): WorkflowScope | null {
     const normalized = getNormalizedOverlay();
     const fromOverlay = normalized?.scopes.find((s) => s.scopeId === scopeId);
@@ -1360,6 +1410,8 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     addInvisibleScope,
     setScopeVisibility,
     getScopeVisibility,
+    setScopeGuardPolicy,
+    getScopeGuardPolicy,
     getScope,
     getMarkerBackedScopeIds: () => overlayStore.getMarkerBackedScopeIds(),
     setScopeChromeVisibility,

package/src/runtime/workflow/scope-writer.ts

@@ -37,6 +37,8 @@ import type {
   EditorAnchorProjection,
   EditorStoryTarget,
   RuntimeRenderSnapshot,
+  ScopeVisibility,
+  WorkflowScopeGuardPolicy,
   WorkflowMetadataEntry,
   WorkflowMetadataPersistence,
   WorkflowScopeMetadataField,
@@ -62,6 +64,8 @@ export interface CreateScopeFromBlockIdInput {
   readonly persistence?: WorkflowMetadataPersistence;
   readonly metadata?: Partial<WorkflowMetadataEntry>;
   readonly storyTarget?: EditorStoryTarget;
+  readonly visibility?: ScopeVisibility;
+  readonly guardPolicy?: WorkflowScopeGuardPolicy;
   /**
    * Coord-06 §13d — per-scope edge stickiness for the range anchor.
    * Defaults to `{ start: 1, end: -1 }` (greedy — absorbs boundary
@@ -98,7 +102,23 @@ export interface CreateScopeFromBlockIdInput {
 
 export type CreateScopeFromBlockIdResult =
   | { readonly status: "created"; readonly scopeId: string; readonly anchor: EditorAnchorProjection }
-  | { readonly status: "block-not-found"; readonly blockId: string };
+  | { readonly status: "block-not-found"; readonly blockId: string }
+  | {
+      readonly status: "range-invalid";
+      readonly scopeId: "";
+      readonly reason:
+        | "range-exceeds-story-length"
+        | "non-paragraph-target"
+        | "empty-document";
+      readonly from: number;
+      readonly to: number;
+      readonly storyLength: number;
+      /** Non-paragraph target only — the offending block's index and kind. */
+      readonly blockIndex?: number;
+      readonly blockKind?: string;
+      readonly message: string;
+      readonly nextStep: string;
+    };
 
 function inlineLength(node: InlineNode): number {
   switch (node.type) {
@@ -190,8 +210,9 @@ export function createScopeFromBlockId(
   runtime: ScopeWriterRuntime,
   input: CreateScopeFromBlockIdInput,
 ): CreateScopeFromBlockIdResult {
+  const document = runtime.getCanonicalDocument();
   const anchor = resolveBlockAnchorFromCanonical(
-    runtime.getCanonicalDocument(),
+    document,
     input.blockId,
     input.assoc,
   );
@@ -216,10 +237,63 @@ export function createScopeFromBlockId(
     metadata: input.metadata,
     storyTarget: input.storyTarget,
     label: input.label,
+    ...(input.visibility ? { visibility: input.visibility } : {}),
+    ...(input.guardPolicy ? { guardPolicy: input.guardPolicy } : {}),
     ...(scopeMetadataFields.length > 0
       ? { scopeMetadataFields }
       : {}),
   });
+  if (result.plantStatus && result.plantStatus.planted === false) {
+    const ps = result.plantStatus;
+    const from = anchor.kind === "range" ? anchor.from : 0;
+    const to = anchor.kind === "range" ? anchor.to : from;
+    const storyLength = ps.storyLength ?? computeMainStoryLength(document);
+    if (ps.reason === "non-paragraph-target") {
+      return {
+        status: "range-invalid",
+        scopeId: "",
+        reason: "non-paragraph-target",
+        from,
+        to,
+        storyLength,
+        blockIndex: ps.blockIndex ?? -1,
+        blockKind: ps.blockKind ?? "unknown",
+        message:
+          `createScope refused blockId "${input.blockId}": it resolves to a ` +
+          `${ps.blockKind ?? "non-paragraph"} block (index ${ps.blockIndex}). ` +
+          `Marker-backed scopes only plant inside paragraphs today; choose a ` +
+          `paragraph block or create an overlay-only scope for table/SDT metadata.`,
+        nextStep: "pick-a-paragraph-block-or-use-overlay-only-scope",
+      };
+    }
+    if (ps.reason === "range-out-of-bounds") {
+      return {
+        status: "range-invalid",
+        scopeId: "",
+        reason: "range-exceeds-story-length",
+        from,
+        to,
+        storyLength,
+        message:
+          `createScope refused blockId "${input.blockId}": resolved range ` +
+          `[${from}, ${to}] exceeds the current story length (${storyLength}). ` +
+          `Re-query block ids from the current render snapshot before retrying.`,
+        nextStep: "re-query-current-block-id",
+      };
+    }
+    return {
+      status: "range-invalid",
+      scopeId: "",
+      reason: "empty-document",
+      from,
+      to,
+      storyLength,
+      message:
+        `createScope refused blockId "${input.blockId}": the target document ` +
+        `has no blocks, so scope markers cannot be planted.`,
+      nextStep: "initialize-document-before-creating-scopes",
+    };
+  }
   return { status: "created", scopeId: result.scopeId, anchor: result.anchor };
 }
 
@@ -251,6 +325,8 @@ export interface CreateScopeFromAnchorInput {
   readonly scopeId?: string;
   readonly persistence?: WorkflowMetadataPersistence;
   readonly metadata?: Partial<WorkflowMetadataEntry>;
+  readonly visibility?: ScopeVisibility;
+  readonly guardPolicy?: WorkflowScopeGuardPolicy;
   /**
    * Per-scope edge stickiness for the range anchor. Defaults to
    * `{ start: 1, end: -1 }` (greedy — absorbs boundary inserts). See
@@ -423,6 +499,8 @@ export function createScopeFromAnchor(
     metadata: input.metadata,
     storyTarget,
     label: input.label,
+    ...(input.visibility ? { visibility: input.visibility } : {}),
+    ...(input.guardPolicy ? { guardPolicy: input.guardPolicy } : {}),
     ...(scopeMetadataFields.length > 0 ? { scopeMetadataFields } : {}),
   });
 
@@ -448,9 +526,9 @@ export function createScopeFromAnchor(
         message:
           `createScopeFromAnchor refused: range [${from}, ${to}] targets a ` +
           `${ps.blockKind ?? "non-paragraph"} block (index ${ps.blockIndex}). ` +
-          `Marker scopes only plant inside paragraphs today. Pick a paragraph ` +
-          `target, or use runtime.workflow.createScope({blockId}) for ` +
-          `whole-block scopes on the containing structure.`,
+          `Marker-backed scopes only plant inside paragraphs today. Pick a ` +
+          `paragraph target, or create an overlay-only scope for table/SDT ` +
+          `metadata until structural marker support lands.`,
         nextStep: "pick-a-paragraph-target",
       };
     }