@beyondwork/docx-react-component 1.0.36 → 1.0.38

package/src/runtime/scope-tag-registry.ts

@@ -0,0 +1,95 @@
+/**
+ * Scope tag registry — describes how each annotation family responds to
+ * ordinary text edits. The predicted-text lane uses this registry to:
+ *   - classify an `adjusted` ack (comment anchor extended, revision trimmed)
+ *   - decide whether to bail on prediction when an unknown tag is in range
+ *   - drive decoration redraws after a reconciled commit
+ *
+ * Known annotation families ship as `DEFAULT_REGISTRY_ENTRIES`. Host
+ * integrations can register additional families; unknown families default
+ * to "bailIfCrossed" so the lane falls back to the canonical round-trip.
+ */
+
+export interface ScopeTagBehavior {
+  /** Inserting text at the left edge extends the tag leftward. */
+  extendOnInsertLeft: boolean;
+  /** Inserting text at the right edge extends the tag rightward. */
+  extendOnInsertRight: boolean;
+  /** Deleting a tag edge trims the tag boundary. */
+  trimOnDelete: boolean;
+  /** Any edit that crosses this tag must abort prediction and rebuild canonically. */
+  bailIfCrossed: boolean;
+}
+
+export const DEFAULT_UNKNOWN_BEHAVIOR: ScopeTagBehavior = {
+  extendOnInsertLeft: false,
+  extendOnInsertRight: false,
+  trimOnDelete: false,
+  bailIfCrossed: true,
+};
+
+export const DEFAULT_REGISTRY_ENTRIES: Readonly<Record<string, ScopeTagBehavior>> = {
+  comment: {
+    extendOnInsertLeft: true,
+    extendOnInsertRight: true,
+    trimOnDelete: true,
+    bailIfCrossed: false,
+  },
+  revision: {
+    extendOnInsertLeft: true,
+    extendOnInsertRight: true,
+    trimOnDelete: true,
+    bailIfCrossed: false,
+  },
+  field: {
+    extendOnInsertLeft: false,
+    extendOnInsertRight: false,
+    trimOnDelete: false,
+    bailIfCrossed: true,
+  },
+  bookmark: {
+    extendOnInsertLeft: true,
+    extendOnInsertRight: true,
+    trimOnDelete: true,
+    bailIfCrossed: false,
+  },
+  sdt: {
+    extendOnInsertLeft: false,
+    extendOnInsertRight: false,
+    trimOnDelete: false,
+    bailIfCrossed: true,
+  },
+  opaque: {
+    extendOnInsertLeft: false,
+    extendOnInsertRight: false,
+    trimOnDelete: false,
+    bailIfCrossed: true,
+  },
+};
+
+export interface ScopeTagRegistry {
+  get(tagType: string): ScopeTagBehavior;
+  register(tagType: string, behavior: ScopeTagBehavior): void;
+  has(tagType: string): boolean;
+  list(): ReadonlyArray<readonly [string, ScopeTagBehavior]>;
+}
+
+export function createScopeTagRegistry(): ScopeTagRegistry {
+  const entries = new Map<string, ScopeTagBehavior>(
+    Object.entries(DEFAULT_REGISTRY_ENTRIES),
+  );
+  return {
+    get(tagType) {
+      return entries.get(tagType) ?? DEFAULT_UNKNOWN_BEHAVIOR;
+    },
+    register(tagType, behavior) {
+      entries.set(tagType, behavior);
+    },
+    has(tagType) {
+      return entries.has(tagType);
+    },
+    list() {
+      return Array.from(entries.entries());
+    },
+  };
+}

package/src/runtime/surface-projection.ts

@@ -553,6 +553,7 @@ function createParagraphBlock(
     ...(paragraph.keepNext ? { keepNext: true } : {}),
     ...(paragraph.keepLines ? { keepLines: true } : {}),
     ...(paragraph.pageBreakBefore ? { pageBreakBefore: true } : {}),
+    ...(paragraph.widowControl !== undefined ? { widowControl: paragraph.widowControl } : {}),
     ...(paragraph.outlineLevel !== undefined ? { outlineLevel: paragraph.outlineLevel } : {}),
     ...(paragraph.bidi ? { bidi: true } : {}),
     ...(paragraph.suppressLineNumbers ? { suppressLineNumbers: true } : {}),

package/src/runtime/text-ack-range.ts

@@ -0,0 +1,49 @@
+/**
+ * Computes the post-edit range that the runtime's text-command ack reports
+ * as `adjustedRange`. The semantics: the union of all step post-edit ranges
+ * (where each step covers `[step.from, step.from + step.insertSize]` in the
+ * new document). When the transaction has no steps (e.g., a non-main-story
+ * `document.replace` that uses `createEmptyMapping()`), fall back to the
+ * normalized prior selection range so consumers still receive a meaningful
+ * pointer.
+ *
+ * Note: only `step.from` and `step.insertSize` are considered; `step.to`
+ * (the pre-edit end of the replaced range) is intentionally ignored. A pure
+ * delete (`insertSize === 0`) therefore yields a zero-width range at the
+ * post-delete cursor position, not the pre-edit affected span. If a consumer
+ * needs the source span of a delete, derive it from `step.to` directly.
+ */
+export interface PriorSelectionRange {
+  from: number;
+  to: number;
+}
+
+export interface TextAckStepShape {
+  from: number;
+  insertSize: number;
+}
+
+export interface AdjustedRuntimeRange {
+  fromRuntime: number;
+  toRuntime: number;
+}
+
+export function computeAdjustedRange(
+  priorSelection: PriorSelectionRange,
+  steps: readonly TextAckStepShape[],
+): AdjustedRuntimeRange {
+  if (steps.length === 0) {
+    return {
+      fromRuntime: Math.min(priorSelection.from, priorSelection.to),
+      toRuntime: Math.max(priorSelection.from, priorSelection.to),
+    };
+  }
+  let from = Infinity;
+  let to = -Infinity;
+  for (const step of steps) {
+    if (step.from < from) from = step.from;
+    const stepEnd = step.from + step.insertSize;
+    if (stepEnd > to) to = stepEnd;
+  }
+  return { fromRuntime: from, toRuntime: to };
+}

package/src/runtime/view-state.ts

@@ -19,13 +19,17 @@ import type {
   ActiveListContext,
   ActiveNoteContext,
   CaretAffinity,
+  ChromePinsState,
+  ChromePinSurface,
   DocumentMode,
+  EditorRole,
   EditorStoryTarget,
   EditorSurfaceSnapshot,
   EditorViewStateSnapshot,
   LayoutMeasurement,
   PageLayoutSnapshot,
   PageRegionHitTest,
+  PinState,
   SelectionSnapshot,
   SurfaceBlockSnapshot,
   SurfaceInlineSegment,
@@ -44,6 +48,20 @@ export interface ViewState {
   caretAffinity: CaretAffinity;
   activePageRegion: PageRegionHitTest | null;
   activeObjectFrame: LayoutMeasurement["objectFrame"] | null;
+  /**
+   * Role-scoped chrome dimension (spec §6.4).  Host apps drive the role via
+   * `setEditorRole`; the mounted shell reads this to pick a per-role
+   * toolbar action set.  Independent of `viewMode` — one user session may
+   * start in "review" role and switch to "editor" without changing
+   * workspace or document mode.
+   */
+  editorRole: EditorRole;
+  /**
+   * Pin state for detachable chrome surfaces (topnav, selection tier).
+   * Lives here so it survives snapshot rebuilds within one session.
+   * Absent key ⇒ docked default.
+   */
+  chromePins: ChromePinsState;
 }
 
 const MIN_ZOOM_PERCENT = 50;
@@ -58,6 +76,8 @@ const DEFAULT_VIEW_STATE: ViewState = {
   caretAffinity: "none",
   activePageRegion: null,
   activeObjectFrame: null,
+  editorRole: "editor",
+  chromePins: {},
 };
 
 export function createViewState(initial?: Partial<ViewState>): ViewState {
@@ -113,6 +133,37 @@ export function setActiveObjectFrame(
   return { ...state, activeObjectFrame: frame };
 }
 
+export function setEditorRole(state: ViewState, role: EditorRole): ViewState {
+  if (state.editorRole === role) return state;
+  return { ...state, editorRole: role };
+}
+
+export function setChromePin(
+  state: ViewState,
+  surface: ChromePinSurface,
+  pin: PinState | null,
+): ViewState {
+  const next: ChromePinsState = { ...state.chromePins };
+  if (pin === null) {
+    if (next[surface] === undefined) {
+      return state;
+    }
+    delete next[surface];
+  } else {
+    const current = next[surface];
+    if (
+      current &&
+      current.detached === pin.detached &&
+      current.offset.x === pin.offset.x &&
+      current.offset.y === pin.offset.y
+    ) {
+      return state;
+    }
+    next[surface] = pin;
+  }
+  return { ...state, chromePins: next };
+}
+
 /**
  * Derive list context from the surface block at the current selection head.
  */
@@ -219,9 +270,25 @@ export function createEditorViewStateSnapshot(
     activeObjectFrame: derivedViewState.activeObjectFrame,
     measurement,
     isFocused: derivedViewState.isFocused,
+    editorRole: derivedViewState.editorRole,
+    chromePins: cloneChromePins(derivedViewState.chromePins),
   };
 }
 
+function cloneChromePins(pins: ChromePinsState): ChromePinsState {
+  const out: ChromePinsState = {};
+  for (const key of Object.keys(pins) as ChromePinSurface[]) {
+    const pin = pins[key];
+    if (pin) {
+      out[key] = {
+        detached: pin.detached,
+        offset: { x: pin.offset.x, y: pin.offset.y },
+      };
+    }
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------

package/src/runtime/workflow-markup.ts

@@ -341,11 +341,7 @@ function collectOpaqueFragmentMarkup(
   const seen = new Set(existing.map((item) => item.fragmentId));
 
   return Object.values(preservation.opaqueFragments)
-    .filter(
-      (fragment) =>
-        !seen.has(fragment.fragmentId)
-        && fragment.packagePartName === "/word/document.xml",
-    )
+    .filter((fragment) => !seen.has(fragment.fragmentId))
     .map((fragment) => {
       const descriptor = describeOpaqueFragment(fragment);
       const blockedReasonCode = isBlockedImportFeatureKey(descriptor.featureKey)

package/src/runtime/workflow-rail-segments.ts

@@ -0,0 +1,280 @@
+/**
+ * Workflow rail-segment projection.
+ *
+ * Per runtime-rendering-and-chrome-phase.md §5, the action rail v2 renders
+ * OUTSIDE the PM NodeView tree as an overlay layer positioned from
+ * canonical scope data.  This module joins the host-supplied
+ * `WorkflowOverlay` (scopes, candidates) + blocked-reason ranges +
+ * locked-zone data with the runtime page graph to produce
+ * `ScopeRailSegment[]` — the shape chrome consumes to render the
+ * left-gutter label column and the flat block-tint.
+ *
+ * The segments are pure reads over canonical state; no DOM, no PM.
+ */
+
+import type {
+  EditorAnchorProjection,
+  EditorStoryTarget,
+  WorkflowBlockedCommandReason,
+  WorkflowCandidateRange,
+  WorkflowLockedZone,
+  WorkflowScope,
+} from "../api/public-types";
+import { MAIN_STORY_TARGET, storyTargetsEqual } from "../core/selection/mapping.ts";
+import type { RuntimePageGraph } from "./layout/page-graph.ts";
+import type { RenderFrameRect } from "./render/render-frame-types.ts";
+
+// ---------------------------------------------------------------------------
+// Public shape
+// ---------------------------------------------------------------------------
+
+export type ScopeRailPosture =
+  | "edit"
+  | "suggest"
+  | "comment"
+  | "view"
+  | "candidate"
+  | "preserve-only"
+  | "blocked-import";
+
+export interface ScopeRailSegment {
+  /** Identifier the chrome uses to sync with the Workflow rail tab. */
+  scopeId: string;
+  /** Visual+accessibility posture keyed off the scope mode or block reason. */
+  posture: ScopeRailPosture;
+  /** Human label; empty string when none was supplied by the host. */
+  label: string;
+  /** Runtime offsets (inclusive from, exclusive to) this segment spans on the active story. */
+  fromOffset: number;
+  toOffset: number;
+  /** Story the segment sits on. */
+  storyTarget: EditorStoryTarget;
+  /** Page index the segment renders on (may span multiple pages; emitted per page). */
+  pageIndex: number;
+  /** Section index derived from the page graph. */
+  sectionIndex: number;
+  /** True when the scope is the active work item. */
+  isActiveWorkItem: boolean;
+  /**
+   * Body-tint rect in overlay-space pixels, populated when the render kernel
+   * is available.  Chrome consumers read this directly instead of
+   * re-projecting per render via the overlay projector.  `null` when the
+   * segment is produced without a kernel (e.g., in tests or before the
+   * facet is bound to a page graph) — consumers fall back to per-render
+   * anchor resolution in that case.
+   */
+  bodyTintRect: RenderFrameRect | null;
+}
+
+// ---------------------------------------------------------------------------
+// Collector input
+// ---------------------------------------------------------------------------
+
+export interface CollectScopeRailSegmentsInput {
+  scopes: readonly WorkflowScope[] | undefined;
+  candidates?: readonly WorkflowCandidateRange[];
+  blockedReasons?: readonly WorkflowBlockedCommandReason[];
+  lockedZones?: readonly WorkflowLockedZone[];
+  activeWorkItemScopeIds?: readonly string[];
+  /** Active story scopes render on; segments for other stories are skipped. */
+  activeStory?: EditorStoryTarget;
+  pageGraph: RuntimePageGraph;
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Build segments for every page in the graph.  Callers that only want a
+ * single page can filter by `segment.pageIndex` on the returned list.
+ */
+export function collectScopeRailSegments(
+  input: CollectScopeRailSegmentsInput,
+): ScopeRailSegment[] {
+  const segments: ScopeRailSegment[] = [];
+  const activeStory = input.activeStory ?? MAIN_STORY_TARGET;
+  const activeIds = new Set(input.activeWorkItemScopeIds ?? []);
+
+  for (const scope of input.scopes ?? []) {
+    const range = anchorToRuntimeRange(scope.anchor);
+    if (!range) continue;
+    const storyTarget = scope.storyTarget ?? MAIN_STORY_TARGET;
+    if (!storyTargetsEqual(storyTarget, activeStory)) continue;
+
+    const posture = resolveScopePosture(scope);
+    const isActiveWorkItem = activeIds.has(scope.scopeId);
+    for (const page of pagesCoveringRange(input.pageGraph, range.from, range.to)) {
+      const { from, to } = clipRangeToPage(range.from, range.to, page);
+      if (from >= to) continue;
+      segments.push({
+        scopeId: scope.scopeId,
+        posture,
+        label: scope.label ?? "",
+        fromOffset: from,
+        toOffset: to,
+        storyTarget,
+        pageIndex: page.pageIndex,
+        sectionIndex: page.sectionIndex,
+        isActiveWorkItem,
+        bodyTintRect: null,
+      });
+    }
+  }
+
+  // Candidates render as a faint "candidate" posture so the reader knows
+  // where the host is proposing scopes before they're committed.
+  for (const candidate of input.candidates ?? []) {
+    const range = anchorToRuntimeRange(candidate.anchor);
+    if (!range) continue;
+    const storyTarget = candidate.storyTarget ?? MAIN_STORY_TARGET;
+    if (!storyTargetsEqual(storyTarget, activeStory)) continue;
+
+    for (const page of pagesCoveringRange(input.pageGraph, range.from, range.to)) {
+      const { from, to } = clipRangeToPage(range.from, range.to, page);
+      if (from >= to) continue;
+      segments.push({
+        scopeId: candidate.candidateId,
+        posture: "candidate",
+        label: candidate.label ?? "",
+        fromOffset: from,
+        toOffset: to,
+        storyTarget,
+        pageIndex: page.pageIndex,
+        sectionIndex: page.sectionIndex,
+        isActiveWorkItem: false,
+        bodyTintRect: null,
+      });
+    }
+  }
+
+  // Blocked-reason anchors: render a "blocked-import" or "preserve-only"
+  // posture so the rail signal matches the chrome message in image copy.png.
+  for (const reason of input.blockedReasons ?? []) {
+    if (!reason.anchor) continue;
+    const range = anchorToRuntimeRange(reason.anchor);
+    if (!range) continue;
+    const storyTarget = reason.storyTarget ?? MAIN_STORY_TARGET;
+    if (!storyTargetsEqual(storyTarget, activeStory)) continue;
+
+    const posture: ScopeRailPosture =
+      reason.code === "workflow_blocked_import"
+        ? "blocked-import"
+        : reason.code === "workflow_preserve_only"
+          ? "preserve-only"
+          : "view";
+    for (const page of pagesCoveringRange(input.pageGraph, range.from, range.to)) {
+      const { from, to } = clipRangeToPage(range.from, range.to, page);
+      if (from >= to) continue;
+      segments.push({
+        scopeId: `blocked:${reason.code}:${range.from}-${range.to}`,
+        posture,
+        label: reason.label ?? reason.message ?? "",
+        fromOffset: from,
+        toOffset: to,
+        storyTarget,
+        pageIndex: page.pageIndex,
+        sectionIndex: page.sectionIndex,
+        isActiveWorkItem: false,
+        bodyTintRect: null,
+      });
+    }
+  }
+
+  // Locked zones project as their own preserve-only / blocked-import rails so
+  // locked cells, locked images, and locked runs show the lock posture in
+  // the gutter even without a workflow scope covering them.
+  for (const zone of input.lockedZones ?? []) {
+    const range = anchorToRuntimeRange(zone.anchor);
+    if (!range) continue;
+    const storyTarget = zone.storyTarget ?? MAIN_STORY_TARGET;
+    if (!storyTargetsEqual(storyTarget, activeStory)) continue;
+
+    const posture: ScopeRailPosture =
+      zone.code === "workflow_blocked_import"
+        ? "blocked-import"
+        : "preserve-only";
+    for (const page of pagesCoveringRange(input.pageGraph, range.from, range.to)) {
+      const { from, to } = clipRangeToPage(range.from, range.to, page);
+      if (from >= to) continue;
+      segments.push({
+        scopeId: zone.fragmentId ?? `locked:${range.from}-${range.to}`,
+        posture,
+        label: zone.label ?? "",
+        fromOffset: from,
+        toOffset: to,
+        storyTarget,
+        pageIndex: page.pageIndex,
+        sectionIndex: page.sectionIndex,
+        isActiveWorkItem: false,
+        bodyTintRect: null,
+      });
+    }
+  }
+
+  return segments;
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function anchorToRuntimeRange(
+  anchor: EditorAnchorProjection,
+): { from: number; to: number } | null {
+  if (anchor.kind === "range") {
+    const from = Math.min(anchor.from, anchor.to);
+    const to = Math.max(anchor.from, anchor.to);
+    return from < to ? { from, to } : null;
+  }
+  if (anchor.kind === "node") {
+    return { from: anchor.at, to: anchor.at + 1 };
+  }
+  // detached anchors cannot be rendered; use the last-known range as a
+  // best-effort ghost until the scope is re-anchored or dismissed.
+  if (anchor.lastKnownRange) {
+    const from = Math.min(anchor.lastKnownRange.from, anchor.lastKnownRange.to);
+    const to = Math.max(anchor.lastKnownRange.from, anchor.lastKnownRange.to);
+    return from < to ? { from, to } : null;
+  }
+  return null;
+}
+
+function pagesCoveringRange(
+  graph: RuntimePageGraph,
+  from: number,
+  to: number,
+): RuntimePageGraph["pages"] {
+  return graph.pages.filter(
+    (page) =>
+      !page.isBlankFiller &&
+      page.endOffset > from &&
+      page.startOffset < to,
+  );
+}
+
+function clipRangeToPage(
+  from: number,
+  to: number,
+  page: RuntimePageGraph["pages"][number],
+): { from: number; to: number } {
+  return {
+    from: Math.max(from, page.startOffset),
+    to: Math.min(to, page.endOffset),
+  };
+}
+
+function resolveScopePosture(scope: WorkflowScope): ScopeRailPosture {
+  switch (scope.mode) {
+    case "edit":
+      return "edit";
+    case "suggest":
+      return "suggest";
+    case "comment":
+      return "comment";
+    case "view":
+      return "view";
+    default:
+      return "view";
+  }
+}