@beyondwork/docx-react-component 1.0.88 → 1.0.90

package/package.json

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

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

@@ -117,6 +117,10 @@ export type RuntimeApiHandle = Pick<
   // ReplacementScope` + `runtime.content.replaceText(scopeId, …)`
   // route compiled plans through this seam.
   | "applyScopeReplacement"
+  // Layer-08 scoped formatting actions. `ai.applyScopeAction` and
+  // `runtime.formatting.applyToScope` route exact mark mutations through
+  // this seam so formatting edits do not replace text payloads.
+  | "applyScopeFormatting"
   // Nested facets (runtime.layout + runtime.geometry families,
   // plus debug telemetry bus for UxResponse emission)
   | "debug"
@@ -187,6 +191,7 @@ export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true
   compileScopeCardById: true,
   compileScopeRailSnapshot: true,
   applyScopeReplacement: true,
+  applyScopeFormatting: true,
   debug: true,
   layout: true,
   geometry: true,

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

@@ -28,14 +28,17 @@ import {
 import type {
   ReplacementOperationKind,
   ReplacementPreservePolicy,
+  ScopeFormattingAction,
   ValidationResult as CompilerValidationResult,
 } from "../../../runtime/scopes/index.ts";
 import type { AIAction } from "../../../runtime/workflow/ai-action-policy.ts";
+import type { TextFormattingDirective } from "../../public-types.ts";
 
 export interface ReplacementProposalInput {
   readonly targetScopeId: string;
   readonly operation: ReplacementOperationKind;
   readonly proposedText?: string;
+  readonly formatting?: TextFormattingDirective;
   readonly preserve?: ReplacementPreservePolicy;
   readonly reason?: string;
   readonly actionId?: AIAction;
@@ -150,6 +153,7 @@ export interface ApplyReplacementScopeInput {
     readonly text?: string;
     readonly structured?: unknown;
   };
+  readonly formatting?: TextFormattingDirective;
   readonly preserve?: ReplacementPreservePolicy;
   readonly reason?: string;
   readonly actionId?: AIAction;
@@ -185,6 +189,42 @@ export const applyReplacementScopeMetadata: ApiV3FnMetadata = {
     "§AI API § ai.applyReplacementScope. Adapter: widened to {targetScopeId, operation, proposedText?, preserve?, actionId?, proposalId?}; routes through applyScopeReplacement (re-validates live state, compiles per-kind plan, dispatches via DocumentRuntime.applyScopeReplacement, emits one ScopeActionAudit on the scope telemetry channel).",
 };
 
+export interface ApplyScopeActionInput {
+  readonly targetScopeId: string;
+  readonly action: ScopeFormattingAction;
+  readonly reason?: string;
+  readonly actionId?: AIAction;
+  readonly actorId?: string;
+  readonly origin?: "ui" | "agent" | "host";
+  readonly proposalId?: string;
+}
+
+export const applyScopeActionMetadata: ApiV3FnMetadata = {
+  name: "ai.applyScopeAction",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest: "test/runtime/scopes/formatting-actions.test.ts",
+    commit: "refactor-08-scope-formatting-actions",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "formatting inside target scope changes",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "scope",
+    auditCategory: "formatting-apply",
+    policyHints: ["requires-approval-for-formatting"],
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§AI API § ai.applyScopeAction. Scope-targeted formatting writer over Layer-08; validates live scope/global guards, dispatches one undoable runtime edit, and emits one ScopeActionAudit. Use for exact mark actions such as clearing only w:highlight.",
+};
+
 /**
  * Input shape for `validateReplacementScope`. Slice 4 widens the input
  * to carry enough information for a fresh compile + compose, since the
@@ -314,6 +354,7 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
           : input.proposedText !== undefined
             ? { proposedText: input.proposedText }
             : {}),
+        ...(input.formatting ? { formatting: input.formatting } : {}),
         ...(input.preserve ? { preserve: input.preserve } : {}),
         ...(input.reason ? { reason: input.reason } : {}),
         ...(input.actionId ? { actionId: input.actionId } : {}),
@@ -341,6 +382,47 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         authoredRevisionIds: result.authoredRevisionIds,
       };
     },
+
+    applyScopeAction(input: ApplyScopeActionInput): ApplyResult {
+      // @endStateApi — live-with-adapter. Routes through the scope
+      // compiler's applyFormatting + the same ApplyResult projection
+      // used by applyReplacementScope.
+      const proposalId =
+        input.proposalId ??
+        mockId(
+          runtime.getSessionState().documentId,
+          `scope-action-${input.targetScopeId}-${input.action.kind}`,
+        );
+
+      const result = compiler.applyFormatting({
+        targetScopeId: input.targetScopeId,
+        action: input.action,
+        ...(input.reason ? { reason: input.reason } : {}),
+        ...(input.actionId ? { actionId: input.actionId } : {}),
+        actorId: input.actorId ?? "agent",
+        origin: input.origin ?? "agent",
+        emittedAtUtc: new Date(0).toISOString(),
+      });
+
+      emitUxResponse(runtime, {
+        apiFn: applyScopeActionMetadata.name,
+        intent: applyScopeActionMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: applyScopeActionMetadata.uxIntent.expectedDelta,
+      });
+
+      return {
+        proposalId,
+        applied: result.applied,
+        ...(result.reason ? { reason: result.reason } : {}),
+        ...(result.validation.blockedReasons.length > 0
+          ? { blockers: Object.freeze([...result.validation.blockedReasons]) }
+          : {}),
+        ...(result.audit ? { auditHint: result.audit.actionId } : {}),
+        authoredRevisionIds: result.authoredRevisionIds,
+      };
+    },
   };
 }
 

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

@@ -17,6 +17,7 @@ import type {
   EditorAnchorProjection,
   SurfaceBlockSnapshot,
   SurfaceInlineSegment,
+  TextFormattingDirective,
 } from "../../public-types.ts";
 import { emitUxResponse } from "../_ux-response.ts";
 import { createScopeCompilerService } from "../../../runtime/scopes/index.ts";
@@ -78,6 +79,7 @@ export const getLocationMetadata: ApiV3FnMetadata = {
 export interface ReplaceTextInput {
   readonly scopeId: string;
   readonly replacement: string;
+  readonly formatting?: TextFormattingDirective;
 }
 
 export interface ReplaceTextResult {
@@ -200,6 +202,7 @@ export function createContentFamily(runtime: RuntimeApiHandle) {
         targetScopeId: input.scopeId,
         operation: "replace",
         proposedText: input.replacement,
+        ...(input.formatting ? { formatting: input.formatting } : {}),
         actorId: "user",
         origin: "ui",
         emittedAtUtc: new Date(0).toISOString(),

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

@@ -14,6 +14,10 @@
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import { emitUxResponse } from "../_ux-response.ts";
+import {
+  createScopeCompilerService,
+  type ScopeFormattingAction,
+} from "../../../runtime/scopes/index.ts";
 import {
   resolveEffectiveFormatting,
   createFormattingContext,
@@ -159,7 +163,43 @@ export const applyMetadata: ApiV3FnMetadata = {
     "§Runtime API § runtime.formatting.apply. Live adapter over DocumentRuntime.applyFormattingOperation(); supports direct formatting/paragraph alignment/indentation and authors bounded property-change suggestions when the effective mode is suggesting. Style suggestions are intentionally not accepted by this operation shape.",
 };
 
+export interface FormattingApplyToScopeInput {
+  readonly scopeId: string;
+  readonly action: ScopeFormattingAction;
+}
+
+export interface FormattingApplyToScopeResult {
+  readonly applied: boolean;
+  readonly reason?: string;
+}
+
+export const applyToScopeMetadata: ApiV3FnMetadata = {
+  name: "runtime.formatting.applyToScope",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest: "test/runtime/scopes/formatting-actions.test.ts",
+    commit: "refactor-08-scope-formatting-actions",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "formatting changes inside the target scope",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "scope",
+    auditCategory: "formatting-write",
+  },
+  rwdReference:
+    "§Runtime API § runtime.formatting.applyToScope. Scope-targeted formatting writer over Layer-08; resolves target scope by id, validates scope/global guards, applies exact text-mark action, emits one ScopeActionAudit, and enters the normal undo stack.",
+};
+
 export function createFormattingFamily(runtime: RuntimeApiHandle) {
+  const compiler = createScopeCompilerService(runtime);
   return {
     apply(operation: FormattingOperation): void {
       // @endStateApi — live. Delegates to the runtime-owned mutation seam
@@ -175,6 +215,30 @@ 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.
+      const result = compiler.applyFormatting({
+        targetScopeId: input.scopeId,
+        action: input.action,
+        actorId: "user",
+        origin: "ui",
+        emittedAtUtc: new Date(0).toISOString(),
+      });
+      emitUxResponse(runtime, {
+        apiFn: applyToScopeMetadata.name,
+        intent: applyToScopeMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: applyToScopeMetadata.uxIntent.expectedDelta,
+      });
+      return {
+        applied: result.applied,
+        ...(result.reason ? { reason: result.reason } : {}),
+      };
+    },
+
     getEffective(
       nodeRef: FormattingNodeRef,
       opts?: FormattingGetEffectiveOpts,

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

@@ -588,6 +588,113 @@ export function applyFormattingOperationToDocument(
   };
 }
 
+export type TextMarkClearTarget = TextMark["type"] | "visualHighlight";
+
+export type TextMarkRangeOperation =
+  | { type: "clear-mark"; mark: TextMarkClearTarget }
+  | { type: "set-mark"; mark: TextMark };
+
+/**
+ * Apply an exact canonical text-mark mutation over a document-coordinate
+ * range without relying on the current selection or a mounted render surface.
+ * This is the scope-action path for source-layer edits such as removing only
+ * `w:highlight` while preserving shading and every unrelated run mark.
+ */
+export function applyTextMarkOperationToDocumentRange(
+  document: CanonicalDocumentEnvelope,
+  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 selection: RuntimeRenderSnapshot["selection"] = {
+    anchor: selectionFrom,
+    head: selectionTo,
+    isCollapsed: selectionFrom === selectionTo,
+    activeRange: {
+      kind: "range",
+      from: selectionFrom,
+      to: selectionTo,
+      assoc: { start: -1, end: 1 },
+    },
+  };
+
+  if (selectionFrom === selectionTo) {
+    return { document, selection, changed: false };
+  }
+
+  const nextDocument = structuredClone(document);
+  const root = nextDocument.content as DocumentRootNode;
+  const updateMarks = resolveTextMarkRangeUpdater(operation);
+  let changed = false;
+  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(selectionFrom, selectionTo, blockFrom, blockTo)
+    ) {
+      const transformed = transformInlineNodes(
+        block.children,
+        blockFrom,
+        selectionFrom,
+        selectionTo,
+        updateMarks,
+      );
+      if (transformed.changed) {
+        block.children = transformed.nodes;
+        changed = true;
+      }
+    }
+
+    cursor = blockTo;
+    if (blockIndex < root.children.length - 1) {
+      cursor += 1;
+    }
+  }
+
+  return {
+    document: changed ? nextDocument : document,
+    selection,
+    changed,
+  };
+}
+
+function resolveTextMarkRangeUpdater(
+  operation: TextMarkRangeOperation,
+): (marks?: TextMark[]) => TextMark[] | undefined {
+  if (operation.type === "set-mark") {
+    return (marks) => {
+      const nextMarks = cloneMarks(marks).filter(
+        (candidate) => candidate.type !== operation.mark.type,
+      );
+      nextMarks.push({ ...operation.mark } as TextMark);
+      return nextMarks.length > 0 ? nextMarks : undefined;
+    };
+  }
+
+  return (marks) => {
+    const nextMarks = cloneMarks(marks).filter((candidate) => {
+      if (operation.mark === "visualHighlight") {
+        return candidate.type !== "highlight" && candidate.type !== "backgroundColor";
+      }
+      return candidate.type !== operation.mark;
+    });
+    return nextMarks.length > 0 ? nextMarks : undefined;
+  };
+}
+
 function resolveMarkUpdater(
   snapshot: RuntimeRenderSnapshot,
   operation: Exclude<

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

@@ -829,7 +829,7 @@ function createInsertionUnits(
  *   - If the range is collapsed, use the marks of the text unit immediately left of
  *     the caret (Word-matching behavior for empty-range inserts).
  *   - Otherwise walk text units in `[from, to)`. If every text unit shares the same
- *     marks (by type), use them. Mixed → fall back to paragraph-default (`undefined`).
+ *     marks (by type and value), use them. Mixed → fall back to paragraph-default (`undefined`).
  */
 function resolveMarksForInsertion(
   intent: TextTransactionIntent,
@@ -887,9 +887,16 @@ function marksAreEqual(left: TextMark[] | undefined, right: TextMark[] | undefin
   if (!left && !right) return true;
   if (!left || !right) return false;
   if (left.length !== right.length) return false;
-  const sortedLeft = [...left].map((mark) => mark.type).sort();
-  const sortedRight = [...right].map((mark) => mark.type).sort();
-  return sortedLeft.every((type, index) => type === sortedRight[index]);
+  const sortedLeft = [...left].map(stableMarkKey).sort();
+  const sortedRight = [...right].map(stableMarkKey).sort();
+  return sortedLeft.every((key, index) => key === sortedRight[index]);
+}
+
+function stableMarkKey(mark: TextMark): string {
+  const entries = Object.entries(mark).sort(([left], [right]) =>
+    left.localeCompare(right),
+  );
+  return JSON.stringify(entries);
 }
 
 function resolveParagraphPropertiesAtPosition(

package/src/runtime/document-runtime.ts

@@ -191,6 +191,7 @@ import {
 } from "../core/commands/add-scope.ts";
 import {
   applyFormattingOperationToDocument,
+  applyTextMarkOperationToDocumentRange,
   type FormattingOperation,
 } from "../core/commands/formatting-commands.ts";
 import { resolveActiveParagraphIndex } from "../core/commands/paragraph-layout-commands.ts";
@@ -450,6 +451,12 @@ export interface DocumentRuntime {
    * UI paths.
    */
   applyScopeReplacement(plan: RuntimeOperationPlan): void;
+  /**
+   * Layer-08 scoped formatting dispatch. Returns true when at least one
+   * document.replace transaction was committed, which lets the compiler
+   * suppress no-op audits.
+   */
+  applyScopeFormatting(plan: RuntimeOperationPlan): boolean;
   dispatch(command: EditorCommand): void;
   /**
    * Apply a command received from a remote collaborator. The command
@@ -3384,6 +3391,7 @@ export function createDocumentRuntime(
               {
                 type: "text.insert",
                 text: step.text,
+                ...(step.formatting ? { formatting: step.formatting } : {}),
                 origin: createOrigin("api", timestamp),
               },
               {
@@ -3458,6 +3466,7 @@ export function createDocumentRuntime(
               {
                 type: "text.insert",
                 text: step.text,
+                ...(step.formatting ? { formatting: step.formatting } : {}),
                 origin: createOrigin("api", timestamp),
               },
               {
@@ -3506,6 +3515,48 @@ export function createDocumentRuntime(
         }
       }
     },
+    applyScopeFormatting(plan: RuntimeOperationPlan) {
+      let changed = false;
+      for (const step of plan.steps) {
+        if (
+          step.kind !== "formatting-apply" ||
+          !step.range ||
+          !step.formattingAction
+        ) {
+          continue;
+        }
+
+        const operation =
+          step.formattingAction.kind === "clear-mark"
+            ? {
+                type: "clear-mark" as const,
+                mark: step.formattingAction.mark,
+              }
+            : {
+                type: "set-mark" as const,
+                mark: step.formattingAction.mark,
+              };
+        const result = applyTextMarkOperationToDocumentRange(
+          state.document,
+          step.range,
+          operation,
+        );
+        if (!result.changed) {
+          continue;
+        }
+
+        const timestamp = clock();
+        this.dispatch({
+          type: "document.replace",
+          document: { ...result.document, updatedAt: timestamp },
+          mapping: createEmptyMapping(),
+          selection: toInternalSelectionSnapshot(result.selection),
+          origin: createOrigin("api", timestamp),
+        });
+        changed = true;
+      }
+      return changed;
+    },
     insertFragment(fragment, target) {
       // I2 Tier B Slice 1 — dispatch `fragment.insert` against the active story. The
       // runtime command handler routes into `applyFragmentInsert` (structure-ops).

package/src/runtime/scopes/_scope-dependencies.ts

@@ -32,6 +32,7 @@ export type {
   EditorStoryTarget,
   EffectiveSelectionMode,
   InteractionGuardSnapshot,
+  TextFormattingDirective,
   WorkflowBlockedCommandReason,
   WorkflowMetadataEntry,
   WorkflowMetadataSnapshot,

package/src/runtime/scopes/action-validation.ts

@@ -62,8 +62,8 @@ import {
 } from "./preservation-boundary.ts";
 import { resolveScopeRange } from "./scope-range.ts";
 import type {
-  ReplacementOperationKind,
   ReplacementScope,
+  ScopeActionOperationKind,
   SemanticScope,
   ValidationApproval,
   ValidationIssue,
@@ -85,7 +85,7 @@ export interface ScopeValidationRuntime {
 
 export interface ComposeScopeValidationInputs {
   readonly scope: SemanticScope;
-  readonly operation: ReplacementOperationKind;
+  readonly operation: ScopeActionOperationKind;
   readonly proposedContent: ReplacementScope["proposedContent"];
   readonly runtime: ScopeValidationRuntime;
   /**
@@ -119,6 +119,11 @@ export interface ComposeScopeValidationInputs {
    * here; the compile step consumes them to drive per-step behavior.
    */
   readonly preservePolicy?: ReplacementScope["preserve"];
+  /**
+   * Formatting-only actions do not destroy opaque fragments or nested scope
+   * markers, so they bypass the replacement preservation-boundary check.
+   */
+  readonly skipPreservation?: boolean;
 }
 
 /**
@@ -127,9 +132,12 @@ export interface ComposeScopeValidationInputs {
  * entry in the 37-op policy matrix.
  */
 function inferActionId(
-  operation: ReplacementOperationKind,
+  operation: ScopeActionOperationKind,
   content: ReplacementScope["proposedContent"],
 ): AIAction {
+  if (operation === "formatting") {
+    return "fix_formatting";
+  }
   switch (operation) {
     case "replace":
       return content.kind === "text" ? "rewrite_paragraph" : "generate_text";
@@ -287,6 +295,7 @@ function collectPreservationVerdict(
   warnings: ValidationIssue[],
 ): void {
   const { document, scope, positionMap } = inputs;
+  if (inputs.skipPreservation === true) return;
   if (!document) return;
   const pm = positionMap ?? buildScopePositionMap(document);
   const range = inputs.enumeratedScope

package/src/runtime/scopes/audit-bundle.ts

@@ -10,9 +10,9 @@
 
 import type { TelemetryBus } from "../debug/telemetry-bus.ts";
 import type {
-  ReplacementScope,
   RuntimeOperationPlan,
   ScopeActionAudit,
+  ScopeActionProposal,
   SemanticScope,
   ValidationResult,
 } from "./semantic-scope-types.ts";
@@ -24,7 +24,7 @@ export interface EmitScopeActionAuditInputs {
   readonly documentHashBefore: string;
   readonly documentHashAfter?: string;
   readonly targetScopeSnapshot: SemanticScope;
-  readonly proposed: ReplacementScope;
+  readonly proposed: ScopeActionProposal;
   readonly plan: RuntimeOperationPlan;
   readonly validation: ValidationResult;
   readonly emittedAtUtc: string;