@beyondwork/docx-react-component 1.0.87 → 1.0.89

package/src/runtime/scopes/compiler-service.ts

@@ -63,12 +63,18 @@ import {
   applyScopeReplacement,
   type ApplyScopeReplacementResult,
 } from "./replacement/apply.ts";
+import {
+  applyScopeFormatting,
+  type ApplyScopeFormattingResult,
+} from "./formatting/apply.ts";
 import { proposeReplacement } from "./replacement/propose.ts";
 import type {
   ReplacementOperationKind,
   ReplacementPreservePolicy,
   ReplacementScope,
   RuntimeOperationPlan,
+  ScopeFormattingAction,
+  ScopeFormattingScope,
   ScopeBundle,
   ScopeHandle,
   SemanticScope,
@@ -95,6 +101,7 @@ export interface CompilerServiceRuntime {
   setWorkflowMetadataEntries(entries: readonly WorkflowMetadataEntry[]): void;
   getSessionState(): ScopeSessionState;
   applyScopeReplacement(plan: RuntimeOperationPlan): void;
+  applyScopeFormatting(plan: RuntimeOperationPlan): boolean;
   debug?: { bus: TelemetryBus };
 }
 
@@ -123,6 +130,7 @@ export interface ApplyReplacementRequest {
    * dispatch shipped (see `cross-layer-coord-08.md §8`).
    */
   readonly proposedContent?: ReplacementScope["proposedContent"];
+  readonly formatting?: ReplacementScope["formatting"];
   readonly preserve?: ReplacementPreservePolicy;
   readonly reason?: string;
   readonly actionId?: AIAction;
@@ -131,6 +139,16 @@ export interface ApplyReplacementRequest {
   readonly emittedAtUtc: string;
 }
 
+export interface ApplyFormattingRequest {
+  readonly targetScopeId: string;
+  readonly action: ScopeFormattingAction;
+  readonly reason?: string;
+  readonly actionId?: AIAction;
+  readonly actorId: string;
+  readonly origin: "ui" | "agent" | "host";
+  readonly emittedAtUtc: string;
+}
+
 export interface AttachExplanationRequest {
   readonly scopeId: string;
   readonly explanation: string;
@@ -181,6 +199,7 @@ export interface ScopeCompilerService {
     input: {
       readonly operation: ReplacementOperationKind;
       readonly proposedText?: string;
+      readonly formatting?: ReplacementScope["formatting"];
       readonly preserve?: ReplacementPreservePolicy;
       readonly reason?: string;
       readonly proposedAtUtc: string;
@@ -196,6 +215,13 @@ export interface ScopeCompilerService {
    */
   applyReplacement(request: ApplyReplacementRequest): ApplyScopeReplacementResult;
 
+  /**
+   * Apply an exact text-mark formatting action to a resolved scope. This
+   * is the supported route for agent/user scope edits such as "remove only
+   * highlight" because it does not replace the text payload.
+   */
+  applyFormatting(request: ApplyFormattingRequest): ApplyScopeFormattingResult;
+
   /**
    * Attach an agent-authored explanation via the Layer-06
    * `attachScopeMetadata` writer. Resolves against the workflow
@@ -315,6 +341,7 @@ export function createScopeCompilerService(
           typeof input.proposedText === "string"
             ? { kind: "text", text: input.proposedText }
             : { kind: "text", text: "" },
+        ...(input.formatting ? { formatting: input.formatting } : {}),
         ...(input.preserve ? { preserve: input.preserve } : {}),
         ...(input.reason ? { reason: input.reason } : {}),
         proposedAtUtc: input.proposedAtUtc,
@@ -350,6 +377,7 @@ export function createScopeCompilerService(
             targetHandle: compiled.scope.handle,
             operation: request.operation,
             proposedContent: request.proposedContent,
+            ...(request.formatting ? { formatting: request.formatting } : {}),
             ...(request.preserve ? { preserve: request.preserve } : {}),
             ...(request.reason ? { reason: request.reason } : {}),
             proposedAtUtc: request.emittedAtUtc,
@@ -359,6 +387,7 @@ export function createScopeCompilerService(
             ...(request.proposedText !== undefined
               ? { proposedText: request.proposedText }
               : {}),
+            ...(request.formatting ? { formatting: request.formatting } : {}),
             ...(request.preserve ? { preserve: request.preserve } : {}),
             ...(request.reason ? { reason: request.reason } : {}),
             proposedAtUtc: request.emittedAtUtc,
@@ -381,6 +410,47 @@ export function createScopeCompilerService(
       });
     },
 
+    applyFormatting(request: ApplyFormattingRequest): ApplyScopeFormattingResult {
+      const compiled = this.compileScopeById(request.targetScopeId);
+      if (!compiled) {
+        return {
+          applied: false,
+          reason: "scope-not-resolvable",
+          validation: {
+            safe: false,
+            blockedReasons: Object.freeze([
+              `scope-not-resolvable:${request.targetScopeId}`,
+            ]),
+            warnings: Object.freeze([]),
+          },
+          authoredRevisionIds: Object.freeze([]),
+        };
+      }
+      const proposed: ScopeFormattingScope = {
+        targetHandle: compiled.scope.handle,
+        operation: "formatting",
+        action: request.action,
+        ...(request.reason ? { reason: request.reason } : {}),
+        proposedAtUtc: request.emittedAtUtc,
+      };
+      return applyScopeFormatting({
+        sink: {
+          getCanonicalDocument: () => runtime.getCanonicalDocument(),
+          getWorkflowOverlay: () => runtime.getWorkflowOverlay(),
+          getInteractionGuardSnapshot: () =>
+            runtime.getInteractionGuardSnapshot(),
+          getCompatibilityReport: () => runtime.getCompatibilityReport(),
+          applyScopeFormatting: (plan) => runtime.applyScopeFormatting(plan),
+        },
+        proposed,
+        ...(request.actionId ? { actionId: request.actionId } : {}),
+        actorId: request.actorId,
+        origin: request.origin,
+        emittedAtUtc: request.emittedAtUtc,
+        ...(runtime.debug?.bus ? { bus: runtime.debug.bus } : {}),
+      });
+    },
+
     attachExplanation(
       request: AttachExplanationRequest,
     ): AttachExplanationResult {

package/src/runtime/scopes/formatting/apply.ts

@@ -0,0 +1,262 @@
+/**
+ * Scope-scoped formatting apply pipeline.
+ *
+ * This is intentionally parallel to replacement/apply.ts but narrower:
+ * the caller supplies a scope id plus an exact text-mark action, we resolve
+ * the scope on live state, validate global/scope guards, lower to one
+ * formatting-apply runtime step, dispatch once, and emit exactly one
+ * ScopeActionAudit when the document actually changed.
+ */
+
+import type { TelemetryBus } from "../../debug/telemetry-bus.ts";
+import type { AIAction } from "../../workflow/ai-action-policy.ts";
+import type {
+  CompatibilityReport,
+  InteractionGuardSnapshot,
+  WorkflowOverlay,
+} from "../_scope-dependencies.ts";
+import type { CanonicalDocumentEnvelope } from "../../../core/state/editor-state.ts";
+
+import { composeScopeValidation } from "../action-validation.ts";
+import {
+  buildParagraphIndexMap,
+  buildSectionIndexByBlockIndex,
+  compileScope,
+} from "../compile-scope.ts";
+import { enumerateScopes, type EnumeratedScope } from "../enumerate-scopes.ts";
+import { emitScopeActionAudit } from "../audit-bundle.ts";
+import { buildScopePositionMap } from "../position-map.ts";
+import { resolveScopeRange } from "../scope-range.ts";
+import type {
+  RuntimeOperationPlan,
+  ScopeActionAudit,
+  ScopeFormattingScope,
+  SemanticScope,
+  ValidationResult,
+} from "../semantic-scope-types.ts";
+
+export interface ApplyScopeFormattingSink {
+  readonly getCanonicalDocument: () => CanonicalDocumentEnvelope;
+  readonly getWorkflowOverlay: () => WorkflowOverlay | null;
+  readonly getInteractionGuardSnapshot: () => InteractionGuardSnapshot;
+  readonly getCompatibilityReport: () => CompatibilityReport;
+  readonly applyScopeFormatting: (plan: RuntimeOperationPlan) => boolean;
+}
+
+export interface ApplyScopeFormattingInputs {
+  readonly sink: ApplyScopeFormattingSink;
+  readonly proposed: ScopeFormattingScope;
+  readonly actionId?: AIAction;
+  readonly actorId: string;
+  readonly origin: "ui" | "agent" | "host";
+  readonly emittedAtUtc: string;
+  readonly bus?: TelemetryBus;
+}
+
+export interface ApplyScopeFormattingResult {
+  readonly applied: boolean;
+  readonly reason?: string;
+  readonly validation: ValidationResult;
+  readonly audit?: ScopeActionAudit;
+  readonly plan?: RuntimeOperationPlan;
+  readonly scope?: SemanticScope;
+  readonly authoredRevisionIds: readonly string[];
+}
+
+function documentHash(doc: CanonicalDocumentEnvelope): string {
+  let textLength = 0;
+  let markSignatureLength = 0;
+  for (const block of doc.content.children) {
+    if (block.type !== "paragraph") continue;
+    for (const child of block.children) {
+      if (child.type !== "text") continue;
+      textLength += child.text.length;
+      markSignatureLength += JSON.stringify(child.marks ?? []).length;
+    }
+  }
+  return `blocks:${doc.content.children.length}|text:${textLength}|marks:${markSignatureLength}`;
+}
+
+function compileFormattingPlan(
+  scope: SemanticScope,
+  enumeratedScope: EnumeratedScope,
+  proposed: ScopeFormattingScope,
+  document: CanonicalDocumentEnvelope,
+  posture: "direct-edit" | "suggest-mode",
+): RuntimeOperationPlan | null {
+  if (posture === "suggest-mode") {
+    return null;
+  }
+
+  switch (enumeratedScope.kind) {
+    case "paragraph":
+    case "heading":
+    case "list-item":
+    case "scope":
+      break;
+    default:
+      return null;
+  }
+
+  const positionMap = buildScopePositionMap(document);
+  const range = resolveScopeRange(enumeratedScope, scope.handle, positionMap);
+  if (!range || range.to <= range.from) {
+    return null;
+  }
+  if (!Number.isInteger(range.from) || !Number.isInteger(range.to)) {
+    return null;
+  }
+
+  return {
+    scopeId: proposed.targetHandle.scopeId,
+    targetKind: scope.kind,
+    operation: "formatting",
+    steps: Object.freeze([
+      {
+        kind: "formatting-apply",
+        summary:
+          proposed.action.kind === "clear-mark"
+            ? `clear ${proposed.action.mark} mark in ${scope.kind} scope [${range.from}..${range.to}]`
+            : `set ${proposed.action.mark.type} mark in ${scope.kind} scope [${range.from}..${range.to}]`,
+        range: { from: range.from, to: range.to },
+        formattingAction: proposed.action,
+      },
+    ]),
+    posture,
+  };
+}
+
+export function applyScopeFormatting(
+  inputs: ApplyScopeFormattingInputs,
+): ApplyScopeFormattingResult {
+  const proposed = inputs.proposed;
+  const docBefore = inputs.sink.getCanonicalDocument();
+  const overlay = inputs.sink.getWorkflowOverlay() ?? undefined;
+  const paragraphIndexByBlockIndex = buildParagraphIndexMap(docBefore);
+  const sectionIndexByBlockIndex = buildSectionIndexByBlockIndex(docBefore);
+
+  let resolvedScope: SemanticScope | null = null;
+  let resolvedEnumerated: EnumeratedScope | null = null;
+  const enumerateInputs = overlay ? { overlay } : {};
+  for (const entry of enumerateScopes(docBefore, enumerateInputs)) {
+    if (entry.handle.scopeId !== proposed.targetHandle.scopeId) continue;
+    const compiled = compileScope(entry, {
+      document: docBefore,
+      ...(overlay ? { overlay } : {}),
+      paragraphIndexByBlockIndex,
+      sectionIndexByBlockIndex,
+    });
+    if (compiled) {
+      resolvedScope = compiled;
+      resolvedEnumerated = entry;
+      break;
+    }
+  }
+
+  if (!resolvedScope || !resolvedEnumerated) {
+    const validation: ValidationResult = {
+      safe: false,
+      blockedReasons: Object.freeze([
+        `scope-not-resolvable:${proposed.targetHandle.scopeId}`,
+      ]),
+      warnings: Object.freeze([]),
+    };
+    return {
+      applied: false,
+      reason: "scope-not-resolvable",
+      validation,
+      authoredRevisionIds: Object.freeze([]),
+    };
+  }
+
+  const verdict = composeScopeValidation({
+    scope: resolvedScope,
+    operation: "formatting",
+    proposedContent: { kind: "text", text: "" },
+    runtime: {
+      getInteractionGuardSnapshot: () => inputs.sink.getInteractionGuardSnapshot(),
+      getCompatibilityReport: () => inputs.sink.getCompatibilityReport(),
+    },
+    document: docBefore,
+    enumeratedScope: resolvedEnumerated,
+    skipPreservation: true,
+    ...(inputs.actionId ? { actionId: inputs.actionId } : {}),
+  });
+
+  if (!verdict.safe) {
+    return {
+      applied: false,
+      reason: "validation-blocked",
+      validation: verdict,
+      scope: resolvedScope,
+      authoredRevisionIds: Object.freeze([]),
+    };
+  }
+
+  const posture: "direct-edit" | "suggest-mode" =
+    verdict.warnings.some((w) => w.code === "guard:suggest-mode")
+      ? "suggest-mode"
+      : "direct-edit";
+  const plan = compileFormattingPlan(
+    resolvedScope,
+    resolvedEnumerated,
+    proposed,
+    docBefore,
+    posture,
+  );
+  if (!plan) {
+    const blocker =
+      posture === "suggest-mode"
+        ? `compile-refused:${resolvedScope.kind}:formatting-suggesting-not-implemented`
+        : `compile-refused:${resolvedScope.kind}:formatting-not-implemented`;
+    const refused: ValidationResult = {
+      safe: false,
+      blockedReasons: Object.freeze([blocker]),
+      warnings: verdict.warnings,
+    };
+    return {
+      applied: false,
+      reason: blocker,
+      validation: refused,
+      scope: resolvedScope,
+      authoredRevisionIds: Object.freeze([]),
+    };
+  }
+
+  const documentHashBefore = documentHash(docBefore);
+  const changed = inputs.sink.applyScopeFormatting(plan);
+  if (!changed) {
+    return {
+      applied: false,
+      reason: "no-op",
+      validation: verdict,
+      plan,
+      scope: resolvedScope,
+      authoredRevisionIds: Object.freeze([]),
+    };
+  }
+
+  const docAfter = inputs.sink.getCanonicalDocument();
+  const audit = emitScopeActionAudit({
+    actionId: inputs.actionId ?? "fix_formatting",
+    actorId: inputs.actorId,
+    origin: inputs.origin,
+    documentHashBefore,
+    documentHashAfter: documentHash(docAfter),
+    targetScopeSnapshot: resolvedScope,
+    proposed,
+    plan,
+    validation: verdict,
+    emittedAtUtc: inputs.emittedAtUtc,
+    ...(inputs.bus ? { bus: inputs.bus } : {}),
+  });
+
+  return {
+    applied: true,
+    validation: verdict,
+    audit,
+    plan,
+    scope: resolvedScope,
+    authoredRevisionIds: Object.freeze([]),
+  };
+}

package/src/runtime/scopes/index.ts

@@ -26,10 +26,15 @@ export type {
   ReplacementOperationKind,
   ReplacementPreservePolicy,
   ReplacementScope,
+  ScopeActionOperationKind,
+  ScopeActionProposal,
   RuntimeOperationPlan,
   RuntimeOperationStep,
   RuntimeOperationStepKind,
   ScopeActionAudit,
+  ScopeFormattingAction,
+  ScopeFormattingClearTarget,
+  ScopeFormattingScope,
   ScopeBundle,
   ScopeBundleEvidence,
   ScopeBundleNeighborhood,
@@ -128,6 +133,12 @@ export {
   type ApplyScopeReplacementResult,
   type ApplyScopeReplacementSink,
 } from "./replacement/apply.ts";
+export {
+  applyScopeFormatting,
+  type ApplyScopeFormattingInputs,
+  type ApplyScopeFormattingResult,
+  type ApplyScopeFormattingSink,
+} from "./formatting/apply.ts";
 export {
   attachExplanation,
   AI_EXPLANATION_METADATA_ID,
@@ -144,6 +155,7 @@ export {
 } from "./create-issue.ts";
 export {
   createScopeCompilerService,
+  type ApplyFormattingRequest,
   type ApplyReplacementRequest,
   type AttachExplanationRequest,
   type CompileScopeByIdResult,

package/src/runtime/scopes/replacement/propose.ts

@@ -23,6 +23,7 @@ export interface ReplacementProposalInput {
   readonly targetHandle: ScopeHandle;
   readonly operation: ReplacementOperationKind;
   readonly proposedContent: ReplacementScope["proposedContent"];
+  readonly formatting?: ReplacementScope["formatting"];
   readonly preserve?: ReplacementPreservePolicy;
   readonly reason?: string;
   readonly proposedAtUtc: string;
@@ -35,6 +36,7 @@ export function proposeReplacement(
     targetHandle: input.targetHandle,
     operation: input.operation,
     proposedContent: input.proposedContent,
+    ...(input.formatting ? { formatting: input.formatting } : {}),
     ...(input.preserve ? { preserve: input.preserve } : {}),
     ...(input.reason ? { reason: input.reason } : {}),
     proposedAtUtc: input.proposedAtUtc,

package/src/runtime/scopes/scope-kinds/paragraph.ts

@@ -299,6 +299,7 @@ export function compileParagraphReplacement(
               : `suggest-mode ${summaryScope} text replace (len ${text.length})`,
           range: { from: effectiveRange.from, to: effectiveRange.to },
           text,
+          ...(proposed.formatting ? { formatting: proposed.formatting } : {}),
         },
       ]),
       ...(proposed.preserve ? { preserve: proposed.preserve } : {}),

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

@@ -24,7 +24,11 @@
  * compatibility event.
  */
 
-import type { EditorStoryTarget } from "./_scope-dependencies.ts";
+import type { TextMark } from "../../model/canonical-document.ts";
+import type {
+  EditorStoryTarget,
+  TextFormattingDirective,
+} from "./_scope-dependencies.ts";
 
 /**
  * 13-value kind taxonomy — purely structural.
@@ -317,6 +321,24 @@ export interface ReplacementPreservePolicy {
   readonly opaqueFragments?: boolean;
 }
 
+export type ScopeFormattingClearTarget = TextMark["type"] | "visualHighlight";
+
+export type ScopeFormattingAction =
+  | {
+      readonly kind: "clear-mark";
+      /**
+       * Exact source-layer clear. Use `"highlight"` to remove only
+       * `w:highlight`, `"backgroundColor"` to remove only shading, and
+       * `"visualHighlight"` to remove both visual highlight layers.
+       */
+      readonly mark: ScopeFormattingClearTarget;
+    }
+  | {
+      readonly kind: "set-mark";
+      /** Full canonical mark to apply over the target scope range. */
+      readonly mark: TextMark;
+    };
+
 export interface ReplacementScope {
   readonly targetHandle: ScopeHandle;
   readonly operation: ReplacementOperationKind;
@@ -337,11 +359,26 @@ export interface ReplacementScope {
      */
     readonly structured?: unknown;
   };
+  /**
+   * Formatting directive for flat-text replacement. When absent, the
+   * runtime keeps the historic paragraph-default replacement behavior.
+   */
+  readonly formatting?: TextFormattingDirective;
   readonly preserve?: ReplacementPreservePolicy;
   readonly reason?: string;
   readonly proposedAtUtc: string;
 }
 
+export interface ScopeFormattingScope {
+  readonly targetHandle: ScopeHandle;
+  readonly operation: "formatting";
+  readonly action: ScopeFormattingAction;
+  readonly reason?: string;
+  readonly proposedAtUtc: string;
+}
+
+export type ScopeActionProposal = ReplacementScope | ScopeFormattingScope;
+
 /**
  * Structural guard for `proposedContent.structured` when it carries a
  * fragment payload (L02's `CanonicalDocumentFragment`). Callers that
@@ -396,7 +433,8 @@ export type RuntimeOperationStepKind =
   | "text-replace"
   | "text-insert-tracked"
   | "text-delete-tracked"
-  | "fragment-replace";
+  | "fragment-replace"
+  | "formatting-apply";
 
 export interface RuntimeOperationStep {
   readonly kind: RuntimeOperationStepKind;
@@ -412,6 +450,10 @@ export interface RuntimeOperationStep {
   };
   /** New text for text-replace / text-insert-tracked. */
   readonly text?: string;
+  /** Optional inserted-text formatting directive for text replacement. */
+  readonly formatting?: TextFormattingDirective;
+  /** Scope-bounded formatting action for formatting-apply. */
+  readonly formattingAction?: ScopeFormattingAction;
   /**
    * `CanonicalDocumentFragment`-shaped payload for `fragment-replace`.
    * Plain-value boundary (S9) — no live references; safe to serialise.
@@ -421,10 +463,12 @@ export interface RuntimeOperationStep {
   readonly fragment?: StructuredReplacementContent;
 }
 
+export type ScopeActionOperationKind = ReplacementOperationKind | "formatting";
+
 export interface RuntimeOperationPlan {
   readonly scopeId: string;
   readonly targetKind: SemanticScopeKind;
-  readonly operation: ReplacementOperationKind;
+  readonly operation: ScopeActionOperationKind;
   readonly steps: readonly RuntimeOperationStep[];
   readonly preserve?: ReplacementPreservePolicy;
   /** Posture the apply pipeline should dispatch under. */
@@ -438,7 +482,7 @@ export interface ScopeActionAudit {
   readonly documentHashBefore: string;
   readonly documentHashAfter?: string;
   readonly targetScopeSnapshot: SemanticScope;
-  readonly proposed: ReplacementScope;
+  readonly proposed: ScopeActionProposal;
   readonly compiledOperations: readonly {
     readonly kind: string;
     readonly summary: string;

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

@@ -3,9 +3,9 @@
  *
  * 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 enforced `effectiveMode` across scopes
- * whose `guardPolicy` participates in editing + `blockedReasons` when a
- * read-only overlap blocks the scope.
+ * the range + the most-restrictive scope action posture. `guardPolicy`
+ * decides whether selection-driven edits are gated; it does not erase a
+ * target scope's own suggest/comment posture for scope-targeted writes.
  *
  * The most-restrictive rule matches layer 06's `InteractionGuardSnapshot`
  * composition for guard-participating scopes (see
@@ -37,10 +37,6 @@ 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) {
@@ -107,10 +103,12 @@ export function resolveWorkflowOverlap(
     if (!rangesOverlap(range, scopeRange)) continue;
     overlappingIds.push(scope.scopeId);
     const guardPolicy = getScopeGuardPolicy(scope);
-    if (guardPolicy === "none") continue;
-    const guardMode = getScopeGuardMode(scope);
-    mode = mergeModes(mode, guardMode);
-    if (guardMode === "view") {
+    if (guardPolicy === "none" && scope.mode === "view") {
+      continue;
+    }
+    const scopeMode = guardPolicy === "read-only" ? "view" : scope.mode;
+    mode = mergeModes(mode, scopeMode);
+    if (scopeMode === "view") {
       blockedReasons.push(`workflow-scope-view:${scope.scopeId}`);
     }
   }

package/src/shell/session-bootstrap.ts

@@ -1100,6 +1100,7 @@ function createLoadingRuntimeBridge(input: {
     replaceText: () => undefined,
     applyFormattingOperation: () => undefined,
     applyScopeReplacement: () => undefined,
+    applyScopeFormatting: () => false,
     insertFragment: () => undefined,
     copy: () => undefined,
     cut: () => undefined,