@beyondwork/docx-react-component 1.0.93 → 1.0.95

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.93",
+  "version": "1.0.95",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

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

@@ -384,9 +384,9 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
     },
 
     applyScopeAction(input: ApplyScopeActionInput): ApplyResult {
-      // @endStateApi — live-with-adapter. Routes through the scope
-      // compiler's applyFormatting + the same ApplyResult projection
-      // used by applyReplacementScope.
+      // @endStateApi — live-with-adapter. Routes scope actions through the
+      // shipped compiler/applyFormatting facade so AI-triggered formatting
+      // mutations share validation, audit, and undo semantics.
       const proposalId =
         input.proposalId ??
         mockId(

package/src/api/v3/runtime/formatting.ts

@@ -216,9 +216,9 @@ export function createFormattingFamily(runtime: RuntimeApiHandle) {
     },
 
     applyToScope(input: FormattingApplyToScopeInput): FormattingApplyToScopeResult {
-      // @endStateApi — live-with-adapter. Routes through the scope
-      // compiler's applyFormatting with actor=user + origin=ui; returns
-      // the authored-revision + audit shape projected for v3 callers.
+      // @endStateApi — live-with-adapter. Routes through the scope-compiler
+      // facade so scope-targeted formatting shares Layer-08 validation,
+      // audit, and runtime-owned mutation semantics.
       const result = compiler.applyFormatting({
         targetScopeId: input.scopeId,
         action: input.action,

package/src/core/commands/formatting-commands.ts

@@ -591,7 +591,7 @@ export function applyFormattingOperationToDocument(
 export type TextMarkClearTarget = TextMark["type"] | "visualHighlight";
 
 export type TextMarkRangeOperation =
-  | { type: "clear-mark"; mark: TextMarkClearTarget }
+  | { type: "clear-mark"; mark: TextMarkClearTarget; expandToFullHighlight?: boolean }
   | { type: "set-mark"; mark: TextMark };
 
 /**
@@ -605,8 +605,14 @@ export function applyTextMarkOperationToDocumentRange(
   range: { from: number; to: number },
   operation: TextMarkRangeOperation,
 ): FormattingMutationResult {
-  const selectionFrom = Math.min(range.from, range.to);
-  const selectionTo = Math.max(range.from, range.to);
+  const inputFrom = Math.min(range.from, range.to);
+  const inputTo = Math.max(range.from, range.to);
+  const expandedRange =
+    operation.type === "clear-mark" && operation.expandToFullHighlight === true
+      ? expandRangeToCanonicalHighlightExtent(document, inputFrom, inputTo)
+      : { from: inputFrom, to: inputTo };
+  const selectionFrom = expandedRange.from;
+  const selectionTo = expandedRange.to;
   const selection: RuntimeRenderSnapshot["selection"] = {
     anchor: selectionFrom,
     head: selectionTo,
@@ -671,6 +677,143 @@ export function applyTextMarkOperationToDocumentRange(
   };
 }
 
+function expandRangeToCanonicalHighlightExtent(
+  document: CanonicalDocumentEnvelope,
+  inputFrom: number,
+  inputTo: number,
+): { from: number; to: number } {
+  let from = inputFrom;
+  let to = inputTo;
+  const root = document.content as DocumentRootNode;
+  let cursor = 0;
+
+  for (let blockIndex = 0; blockIndex < root.children.length; blockIndex += 1) {
+    const block = root.children[blockIndex]!;
+    const blockFrom = cursor;
+    const blockLength =
+      block.type === "paragraph"
+        ? block.children.reduce(
+            (total, child) => total + inlineNodeLength(child as InlineNode),
+            0,
+          )
+        : 1;
+    const blockTo = blockFrom + blockLength;
+
+    if (
+      block.type === "paragraph" &&
+      rangesOverlap(inputFrom, inputTo, blockFrom, blockTo)
+    ) {
+      const spans = collectInlineHighlightSpans(block.children, blockFrom).spans;
+      const expanded = expandRangeWithinHighlightSpans(spans, inputFrom, inputTo);
+      if (expanded.from < from) from = expanded.from;
+      if (expanded.to > to) to = expanded.to;
+    }
+
+    cursor = blockTo;
+    if (blockIndex < root.children.length - 1) {
+      cursor += 1;
+    }
+  }
+
+  return { from, to };
+}
+
+interface HighlightSpan {
+  readonly from: number;
+  readonly to: number;
+  readonly highlighted: boolean;
+}
+
+function collectInlineHighlightSpans(
+  nodes: readonly InlineNode[],
+  start: number,
+): { spans: HighlightSpan[]; nextPosition: number } {
+  const spans: HighlightSpan[] = [];
+  let position = start;
+
+  for (const node of nodes) {
+    if (node.type === "text") {
+      const length = Array.from(node.text).length;
+      if (length > 0) {
+        spans.push({
+          from: position,
+          to: position + length,
+          highlighted: marksHaveVisualHighlight(node.marks),
+        });
+      }
+      position += length;
+      continue;
+    }
+
+    if (node.type === "hyperlink") {
+      const nested = collectInlineHighlightSpans(node.children as InlineNode[], position);
+      spans.push(...nested.spans);
+      position = nested.nextPosition;
+      continue;
+    }
+
+    const length = inlineNodeLength(node);
+    if (length > 0) {
+      spans.push({
+        from: position,
+        to: position + length,
+        highlighted: false,
+      });
+    }
+    position += length;
+  }
+
+  return { spans, nextPosition: position };
+}
+
+function expandRangeWithinHighlightSpans(
+  spans: readonly HighlightSpan[],
+  inputFrom: number,
+  inputTo: number,
+): { from: number; to: number } {
+  let from = inputFrom;
+  let to = inputTo;
+  let touchedLeftIndex = -1;
+  let touchedRightIndex = -1;
+
+  for (let i = 0; i < spans.length; i += 1) {
+    const span = spans[i]!;
+    if (!span.highlighted) continue;
+    if (rangesOverlap(inputFrom, inputTo, span.from, span.to)) {
+      if (touchedLeftIndex === -1) touchedLeftIndex = i;
+      touchedRightIndex = i;
+    }
+  }
+
+  if (touchedLeftIndex === -1) {
+    return { from, to };
+  }
+
+  for (let i = touchedLeftIndex; i >= 0; i -= 1) {
+    const span = spans[i]!;
+    if (!span.highlighted) break;
+    if (span.to < from) break;
+    if (span.from < from) from = span.from;
+  }
+
+  for (let i = touchedRightIndex; i < spans.length; i += 1) {
+    const span = spans[i]!;
+    if (!span.highlighted) break;
+    if (span.from > to) break;
+    if (span.to > to) to = span.to;
+  }
+
+  return { from, to };
+}
+
+function marksHaveVisualHighlight(marks: readonly TextMark[] | undefined): boolean {
+  return (
+    marks?.some((mark) =>
+      mark.type === "highlight" || mark.type === "backgroundColor"
+    ) ?? false
+  );
+}
+
 function resolveTextMarkRangeUpdater(
   operation: TextMarkRangeOperation,
 ): (marks?: TextMark[]) => TextMark[] | undefined {

package/src/core/state/text-transaction.ts

@@ -130,9 +130,12 @@ function applyLinearTextTransaction(
 
   // `normalizedRange.{from,to}` are logical positions (scope markers = 0 width,
   // matching surface-projection). Translate to unit-array indices so scope
-  // marker units preserved at the boundary stay intact on either side.
-  const unitFrom = logicalPositionToUnitIndex(story.units, normalizedRange.from, "before");
-  const unitTo = logicalPositionToUnitIndex(story.units, normalizedRange.to, "after");
+  // marker units sitting exactly on the replacement boundaries stay intact:
+  // start-boundary markers remain before the inserted payload, end-boundary
+  // markers remain after it. Markers strictly inside the range are still part
+  // of the replacement/delete slice.
+  const unitFrom = logicalPositionToUnitIndex(story.units, normalizedRange.from, "after");
+  const unitTo = logicalPositionToUnitIndex(story.units, normalizedRange.to, "before");
 
   ensureEditableRange(story.units.slice(unitFrom, unitTo));
 

package/src/runtime/document-runtime.ts

@@ -3531,6 +3531,9 @@ export function createDocumentRuntime(
             ? {
                 type: "clear-mark" as const,
                 mark: step.formattingAction.mark,
+                ...(step.formattingAction.expandToFullHighlight === true
+                  ? { expandToFullHighlight: true as const }
+                  : {}),
               }
             : {
                 type: "set-mark" as const,

package/src/runtime/scopes/semantic-scope-types.ts

@@ -332,6 +332,15 @@ export type ScopeFormattingAction =
        * `"visualHighlight"` to remove both visual highlight layers.
        */
       readonly mark: ScopeFormattingClearTarget;
+      /**
+       * When true, expand the target range to the full contiguous visual
+       * highlight span that touches it before clearing. Mirrors
+       * `clearHighlight({expandToFullHighlight:true})`; the clear remains
+       * source-layer exact, so `mark:"highlight"` still removes only
+       * `w:highlight`, while `mark:"visualHighlight"` removes highlight +
+       * shading across the expanded span.
+       */
+      readonly expandToFullHighlight?: boolean;
     }
   | {
       readonly kind: "set-mark";

package/src/ui/WordReviewEditor.tsx

@@ -3931,18 +3931,11 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         }}
         onDeselectObject={() => activeRuntime.deselectObject()}
         onScopeAskAgent={(payload) => {
-          // Resolve the scope's anchor + story from the workflow
-          // facet's card model so the agent request carries the
-          // canonical range. Layer-06 Slice 4 made `runtime.workflow`
-          // the canonical source for scope-card data.
-          const models = activeRuntime.workflow.getAllScopeCardModels();
-          const model = models.find((entry) => entry.scopeId === payload.scopeId);
-          if (!model) return;
-          const scopeSnapshot = activeRuntime.getWorkflowScopeSnapshot();
-          const scopes = scopeSnapshot?.scopes ?? [];
-          const scope = scopes.find((entry) => entry.scopeId === payload.scopeId);
-          if (!scope) return;
-          const anchor = scope.anchor;
+          // Resolve scope card + story through the mounted UI API seam so
+          // the shell root does not re-own workflow facet reads.
+          const model = api.ui?.scope.card(payload.scopeId) ?? null;
+          const bundle = api.ui?.scope.getBundle(payload.scopeId) ?? null;
+          const anchor = payload.anchor ?? model?.anchor;
           if (!anchor) return;
           const requestId =
             typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
@@ -3957,8 +3950,10 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
             requestId,
             scopeId: payload.scopeId,
             anchor,
-            selectionText: model.label ?? "",
-            ...(scope.storyTarget ? { storyTarget: scope.storyTarget } : {}),
+            selectionText: model?.label ?? "",
+            ...(bundle?.scope.handle.storyTarget
+              ? { storyTarget: bundle.scope.handle.storyTarget }
+              : {}),
           };
           onEventRef.current?.(eventPayload);
         }}

package/src/ui/editor-shell-view.tsx

@@ -162,7 +162,10 @@ export interface EditorShellViewProps {
     groupId: string;
   }) => void;
   /** K2 — forwarded from workspace to WordReviewEditor. */
-  onScopeAskAgent?: (payload: { scopeId: string }) => void;
+  onScopeAskAgent?: (payload: {
+    scopeId: string;
+    anchor?: import("../api/public-types.ts").EditorAnchorProjection;
+  }) => void;
   /** N6 — deselects the currently grabbed object; wired to runtime.deselectObject(). */
   onDeselectObject?: () => void;
   mediaPreviews?: Record<string, MediaPreviewDescriptor>;

package/src/ui-tailwind/chrome/tw-display-mode-selector.tsx

@@ -13,14 +13,15 @@
  * names sees the right option highlighted without code changes.
  */
 
-import React, { useState } from "react";
-import * as Popover from "@radix-ui/react-popover";
+import React, { useLayoutEffect, useRef, useState, type CSSProperties } from "react";
+import { createPortal } from "react-dom";
 import { ChevronDown, Eye, EyeOff, Highlighter, Scroll } from "lucide-react";
 
 import {
   normalizeMarkupDisplay,
   type MarkupDisplay,
 } from "../../ui/headless/comment-decoration-model";
+import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
 
 export type DisplayMode = "all-markup" | "simple-markup" | "no-markup" | "original";
 
@@ -67,70 +68,136 @@ const MODES: readonly ModeEntry[] = [
 
 export function TwDisplayModeSelector(props: TwDisplayModeSelectorProps): React.ReactElement {
   const [open, setOpen] = useState(false);
+  const triggerRef = useRef<HTMLButtonElement>(null);
   const canonical = normalizeMarkupDisplay(props.value);
   const activeEntry = MODES.find((m) => m.mode === canonical) ?? MODES[0]!;
 
   return (
-    <Popover.Root open={open} onOpenChange={setOpen}>
-      <Popover.Trigger asChild>
+    <>
         <button
+          ref={triggerRef}
           type="button"
           disabled={props.disabled}
           data-testid={props["data-testid"] ?? "display-mode-selector-trigger"}
           aria-label={`Display mode: ${activeEntry.label}`}
-          className="inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-[11px] font-medium text-primary hover:bg-surface focus-visible:outline-none focus-visible:bg-surface disabled:opacity-50"
+          aria-expanded={open}
+          aria-haspopup="menu"
+          onMouseDown={preserveEditorSelectionMouseDown}
+          onClick={(event) => {
+            event.preventDefault();
+            setOpen((value) => !value);
+          }}
+          className={[
+            "inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-[11px] font-medium text-primary",
+            "hover:bg-surface focus-visible:outline-none focus-visible:bg-surface disabled:opacity-50",
+            open ? "bg-canvas text-accent ring-1 ring-accent/30 shadow-sm" : "",
+          ].join(" ")}
         >
           <activeEntry.icon className="h-3.5 w-3.5 text-tertiary" />
           <span>{activeEntry.label}</span>
           <ChevronDown className="h-3.5 w-3.5 text-tertiary" />
         </button>
-      </Popover.Trigger>
-      <Popover.Portal>
-        <Popover.Content
-          className="z-50 w-[260px] rounded-lg bg-canvas p-1 shadow-lg ring-1 ring-border"
-          sideOffset={8}
-          align="end"
-          data-testid="display-mode-selector-content"
-        >
+      <DisplayModePortalMenu anchorRef={triggerRef} open={open}>
           <div className="mb-1 px-2 py-1 text-[10px] font-semibold uppercase tracking-[0.12em] text-tertiary">
             Display mode
           </div>
           {MODES.map((entry) => {
             const isActive = entry.mode === canonical;
             return (
-              <Popover.Close key={entry.mode} asChild>
-                <button
-                  type="button"
-                  role="menuitemradio"
-                  aria-checked={isActive}
-                  onClick={() => {
-                    props.onChange(entry.mode);
-                  }}
-                  className="flex w-full items-start gap-2 rounded-md px-2 py-1.5 text-left text-[11px] transition-colors hover:bg-surface focus-visible:outline-none focus-visible:bg-surface"
-                  data-testid={`display-mode-option-${entry.mode}`}
-                  data-mode={entry.mode}
-                  data-active={isActive ? "true" : undefined}
-                >
-                  <entry.icon
-                    className={[
-                      "mt-0.5 h-3.5 w-3.5 shrink-0",
-                      isActive ? "text-accent" : "text-tertiary",
-                    ].join(" ")}
-                  />
-                  <span className="flex flex-col">
-                    <span className={`font-medium ${isActive ? "text-accent" : "text-primary"}`}>
-                      {entry.label}
-                    </span>
-                    <span className="text-[10px] text-secondary">{entry.hint}</span>
+              <button
+                key={entry.mode}
+                type="button"
+                role="menuitemradio"
+                aria-checked={isActive}
+                onClick={() => {
+                  props.onChange(entry.mode);
+                  setOpen(false);
+                }}
+                className="flex w-full items-start gap-2 rounded-md px-2 py-1.5 text-left text-[11px] transition-colors hover:bg-surface focus-visible:outline-none focus-visible:bg-surface"
+                data-testid={`display-mode-option-${entry.mode}`}
+                data-mode={entry.mode}
+                data-active={isActive ? "true" : undefined}
+              >
+                <entry.icon
+                  className={[
+                    "mt-0.5 h-3.5 w-3.5 shrink-0",
+                    isActive ? "text-accent" : "text-tertiary",
+                  ].join(" ")}
+                />
+                <span className="flex flex-col">
+                  <span className={`font-medium ${isActive ? "text-accent" : "text-primary"}`}>
+                    {entry.label}
                   </span>
-                </button>
-              </Popover.Close>
+                  <span className="text-[10px] text-secondary">{entry.hint}</span>
+                </span>
+              </button>
             );
           })}
-        </Popover.Content>
-      </Popover.Portal>
-    </Popover.Root>
+      </DisplayModePortalMenu>
+    </>
+  );
+}
+
+function DisplayModePortalMenu(props: {
+  anchorRef: React.RefObject<HTMLButtonElement | null>;
+  children: React.ReactNode;
+  open: boolean;
+}): React.ReactPortal | null {
+  const style = useDisplayModePortalPosition(props.anchorRef, props.open);
+  const body = props.anchorRef.current?.ownerDocument?.body;
+  if (!props.open || !body) return null;
+  return createPortal(
+    <div
+      className="z-50 w-[260px] rounded-lg bg-canvas p-1 shadow-lg ring-1 ring-border"
+      data-testid="display-mode-selector-content"
+      style={style}
+    >
+      {props.children}
+    </div>,
+    body,
   );
 }
 
+function useDisplayModePortalPosition(
+  anchorRef: React.RefObject<HTMLButtonElement | null>,
+  open: boolean,
+): CSSProperties {
+  const [style, setStyle] = useState<CSSProperties>({
+    left: 8,
+    position: "fixed",
+    top: 8,
+    zIndex: 50,
+  });
+
+  useLayoutEffect(() => {
+    if (!open) return;
+    const anchor = anchorRef.current;
+    const ownerWindow = anchor?.ownerDocument?.defaultView;
+    if (!anchor || !ownerWindow) return;
+    const update = () => {
+      const rect = anchor.getBoundingClientRect();
+      const width = 260;
+      const left = Math.min(
+        Math.max(8, rect.right - width),
+        Math.max(8, (ownerWindow.innerWidth || width + 16) - width - 8),
+      );
+      setStyle({
+        left,
+        position: "fixed",
+        top: Math.max(8, rect.bottom + 8),
+        zIndex: 50,
+      });
+    };
+    update();
+    ownerWindow.addEventListener("resize", update);
+    ownerWindow.addEventListener("scroll", update, true);
+    return () => {
+      ownerWindow.removeEventListener("resize", update);
+      ownerWindow.removeEventListener("scroll", update, true);
+    };
+  }, [anchorRef, open]);
+
+  return style;
+}
+
 export default TwDisplayModeSelector;

package/src/ui-tailwind/chrome-overlay/tw-chrome-overlay.tsx

@@ -14,7 +14,7 @@
 
 import * as React from "react";
 import type { OverlayCoordinateSpace } from "./chrome-overlay-projector";
-import type { ScopeRailSegment } from "../../api/public-types.ts";
+import type { ScopeRailPosture, ScopeRailSegment } from "../../api/public-types.ts";
 import type {
   EditorRole,
   EditorStoryTarget,
@@ -28,6 +28,7 @@ import { TwScopeCardLayer } from "./tw-scope-card-layer";
 import { TwPageStackChromeLayer, type PmPortalView } from "../page-stack/tw-page-stack-chrome-layer";
 import { TwTableGripLayer } from "../chrome/tw-table-grip-layer";
 import { TwObjectSelectionOverlay } from "./tw-object-selection-overlay";
+import { useUiApi } from "../ui-api-context";
 
 export interface TwChromeOverlayProps {
   /** Layout facet the overlay layers read from (layout-semantic data). */
@@ -39,16 +40,17 @@ export interface TwChromeOverlayProps {
    */
   geometryFacet: import("../../runtime/geometry/index.ts").GeometryFacet;
   /**
-   * Workflow facet — Layer-06 canonical source of scope rail segments
-   * + scope card models (`runtime.workflow`). Required for scope-rail
-   * / scope-card rendering; pass `null` when no runtime is attached
-   * (e.g., during initial mount).
+   * Workflow facet — no-provider fallback for scope rail/card reads.
+   * Mounted editor paths prefer `api.ui.scope.*`; pass `null` when no
+   * runtime is attached (e.g., during initial mount).
    */
   workflowFacet: import("../../runtime/workflow/rail/types.ts").WorkflowFacet | null;
   /** Optional coordinate space override.  Defaults to the overlay origin. */
   space?: OverlayCoordinateSpace;
   /** Active scope id (for emphasis + rail tab sync). */
   activeScopeId?: string | null;
+  /** Posture filters shared with the Workflow rail. Omitted means all scopes render. */
+  visibleScopePostures?: ReadonlySet<ScopeRailPosture>;
   /**
    * Click handler fired when the user clicks a scope rail stripe.
    * P0 wires this to open the scope card (P1 ships the card layer).
@@ -213,6 +215,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
   geometryFacet,
   space,
   activeScopeId,
+  visibleScopePostures,
   onScopeStripeClick,
   onScopeSegmentClick,
   onScopeCardClose,
@@ -242,6 +245,25 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
   mediaPreviews,
   activeBandRibbonProps,
 }) => {
+  const ui = useUiApi();
+  const scopeRailSegments = React.useMemo(
+    () =>
+      ui?.scope.rail().segments ??
+      workflowFacet?.getAllRailSegments() ??
+      [],
+    [ui, workflowFacet, renderFrameRevision],
+  );
+  const visibleScopeIds = React.useMemo(() => {
+    if (!visibleScopePostures) return undefined;
+    const ids = new Set<string>();
+    for (const segment of scopeRailSegments) {
+      if (visibleScopePostures.has(segment.posture)) {
+        ids.add(segment.scopeId);
+      }
+    }
+    return ids;
+  }, [scopeRailSegments, visibleScopePostures]);
+
   return (
     <div
       className="wre-chrome-overlay pointer-events-none absolute inset-0 z-30"
@@ -266,8 +288,10 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
       <TwScopeRailLayer
         geometryFacet={geometryFacet}
         workflowFacet={workflowFacet}
+        scopeRailSegments={scopeRailSegments}
         space={space}
         activeScopeId={activeScopeId}
+        visibleScopePostures={visibleScopePostures}
         onStripeClick={onScopeStripeClick}
         onSegmentClick={onScopeSegmentClick}
       />
@@ -275,6 +299,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
         facet={facet}
         workflowFacet={workflowFacet}
         activeScopeId={activeScopeId ?? null}
+        visibleScopeIds={visibleScopeIds}
         onClose={onScopeCardClose ?? noop}
         onModeChange={onScopeCardModeChange ?? noopModeChange}
         onIssueAction={onScopeCardIssueAction ?? noopIssueAction}