@beyondwork/docx-react-component 1.0.76 → 1.0.77

package/src/runtime/scopes/resolve-reference.ts

@@ -1,16 +1,35 @@
 /**
- * Slice 3 — reference resolution.
+ * Reference resolution + position queries.
  *
- * Takes an agent-supplied `ScopeReference` hint + a live document and
- * returns either a resolved `ScopeHandle`, a list of candidate handles
- * (ambiguous), a detached placeholder (scopeId was once valid), or a
- * `not-found`.
+ * Two distinct surfaces live in this module now, matching the two
+ * distinct semantics (KI-P9 fix):
  *
- * Deterministic hint kinds — `scope-id`, `semantic-path`, `offset`,
- * `range` — all resolve live today. Natural-language hints return a
- * `partial` result with `confidence: "low"`; a richer NL matcher lives
- * in a later slice (the AI API will keep the function at status
- * `partial` until then).
+ * 1. `resolveReference(ref)` — **identity lookup**. Takes a durable
+ *    `ScopeReference` (`scope-id`, `semantic-path`, or
+ *    `natural-language` hint) and returns the scope it names. Safe
+ *    across mutations: `scope-id` survives text replaces; missing
+ *    references return typed `not-found` / `detached`. Callers that
+ *    hold a `ScopeReference` across a mutation window should only ever
+ *    be holding one of these durable kinds.
+ *
+ * 2. `queryScopeAtPosition(at)` / `queryScopeInRange(from, to)` —
+ *    **one-shot positional queries**. Return a `ScopeHandle | null`
+ *    against the *current* document state. The caller's next use of
+ *    the returned handle MUST be through its `scopeId` — the position
+ *    is consumed by the query and never round-trips as a reference.
+ *    This is the click-to-scope / hit-test / selection-to-scope
+ *    surface. Positions that lived at time T1 are meaningless at time
+ *    T2 after any intervening mutation, so these functions refuse to
+ *    be part of the stored-reference vocabulary.
+ *
+ * Before 2026-04-24, `ScopeReference` had `offset` and `range` variants
+ * that flowed through `resolveReference` with the same
+ * `{status:"resolved", handle, confidence}` shape as identity lookups.
+ * That conflation is the KI-P9 trap — documented in
+ * `docs/testing/scopes.md §6c` and `KNOWN-ISSUES.md` KI-P9. Removed.
+ *
+ * Natural-language hints continue to resolve through `resolveReference`
+ * with `confidence: "low"`; richer NL matching is a later slice.
  */
 
 import type { CanonicalDocument } from "../../model/canonical-document.ts";
@@ -23,11 +42,28 @@ import { buildScopePositionMap, type ScopePositionRange } from "./position-map.t
 import { resolveScopeRange, scopeSpecificity } from "./scope-range.ts";
 import type { ScopeHandle } from "./semantic-scope-types.ts";
 
+/**
+ * Durable references to a scope. Each kind is safe to cache / store /
+ * round-trip through a tool-call boundary and re-resolve after
+ * arbitrary mutations:
+ *
+ *   - `scope-id` — identity primitive. Preserved through text edits;
+ *     returns `not-found` / `detached` cleanly on delete.
+ *   - `semantic-path` — structural path (`body/paragraph/5`). Stable
+ *     when block structure doesn't change; returns `not-found` when
+ *     the path no longer resolves. Fragile on KI-001-class fixtures
+ *     where a neighbour block drop shifts all later indices by 1.
+ *   - `natural-language` — substring heuristic. Always
+ *     `confidence: "low"`; callers must surface that to humans.
+ *
+ * Positional references (`offset`, `range`) are **not** part of this
+ * union — see `queryScopeAtPosition` / `queryScopeInRange` for those.
+ * They are one-shot queries that return a `ScopeHandle | null`; the
+ * position never becomes a stored reference. Cf. KI-P9.
+ */
 export type ScopeReference =
   | { readonly kind: "scope-id"; readonly value: string }
   | { readonly kind: "semantic-path"; readonly path: readonly string[] }
-  | { readonly kind: "offset"; readonly at: number }
-  | { readonly kind: "range"; readonly from: number; readonly to: number }
   | { readonly kind: "natural-language"; readonly hint: string };
 
 export type ResolveReferenceResult =
@@ -161,50 +197,74 @@ function innermostContaining(
   return best?.entry ?? null;
 }
 
-function resolveByOffset(
+/**
+ * Inputs for the one-shot positional query functions. Narrower than
+ * `ResolveReferenceInputs` because the query functions never need NL
+ * overlay labels — they're pure structural lookups.
+ */
+export interface QueryScopePositionInputs {
+  readonly document:
+    | Pick<CanonicalDocument, "content" | "docId" | "review">
+    | CanonicalDocumentEnvelope;
+  readonly overlay?: WorkflowOverlay | null;
+  readonly scopes?: readonly EnumeratedScope[];
+}
+
+/**
+ * Return the innermost scope whose range contains `at` in the current
+ * document state, or `null` if no scope contains the position.
+ *
+ * **One-shot query, not a stored reference.** The returned handle is
+ * the durable object — its `scopeId` may be stored and re-resolved via
+ * `resolveReference({kind:"scope-id", value: handle.scopeId})`. The
+ * input position must NOT be stored; it is meaningful only against the
+ * document state it was queried against. See KI-P9 for the trap this
+ * separation closes.
+ *
+ * Precision: marker-backed handles (workflow / comment / revision
+ * scopes anchored by inline `scope_marker_*` nodes) are returned with
+ * full confidence; derived handles (paragraph / heading / list-item /
+ * field / table etc. enumerated from the canonical tree) are just as
+ * authoritative — the confidence distinction that previously lived on
+ * the `{status:"resolved", confidence}` return went away with
+ * `resolveReference`'s offset/range cases. Callers that need to know
+ * whether the hit is marker-backed can read `handle.provenance`.
+ */
+export function queryScopeAtPosition(
   at: number,
-  scopes: readonly EnumeratedScope[],
-  positionMap: ReturnType<typeof buildScopePositionMap>,
-): ResolveReferenceResult {
+  inputs: QueryScopePositionInputs,
+): ScopeHandle | null {
+  const scopes = scopesFor({ ...inputs, overlay: inputs.overlay ?? null });
+  const positionMap = buildScopePositionMap(inputs.document);
   const hit = innermostContaining(
     scopes,
     positionMap,
     (range) => range.from <= at && at <= range.to,
   );
-  if (!hit) {
-    return { status: "not-found", reason: `no scope contains offset ${at}` };
-  }
-  return {
-    status: "resolved",
-    handle: hit.handle,
-    confidence: hit.handle.provenance === "marker-backed" ? "high" : "medium",
-  };
+  return hit?.handle ?? null;
 }
 
-function resolveByRange(
+/**
+ * Return the innermost scope that fully contains the range `[from, to]`
+ * in the current document state, or `null` if no single scope contains
+ * the whole range. Same one-shot-query semantics as
+ * `queryScopeAtPosition`.
+ */
+export function queryScopeInRange(
   from: number,
   to: number,
-  scopes: readonly EnumeratedScope[],
-  positionMap: ReturnType<typeof buildScopePositionMap>,
-): ResolveReferenceResult {
+  inputs: QueryScopePositionInputs,
+): ScopeHandle | null {
   const low = Math.min(from, to);
   const high = Math.max(from, to);
+  const scopes = scopesFor({ ...inputs, overlay: inputs.overlay ?? null });
+  const positionMap = buildScopePositionMap(inputs.document);
   const hit = innermostContaining(
     scopes,
     positionMap,
     (range) => range.from <= low && high <= range.to,
   );
-  if (!hit) {
-    return {
-      status: "not-found",
-      reason: `no scope fully contains range [${low}, ${high}]`,
-    };
-  }
-  return {
-    status: "resolved",
-    handle: hit.handle,
-    confidence: hit.handle.provenance === "marker-backed" ? "high" : "medium",
-  };
+  return hit?.handle ?? null;
 }
 
 /**
@@ -329,10 +389,6 @@ export function resolveReference(
       return resolveByScopeId(reference.value, scopes, inputs.overlay, positionMap);
     case "semantic-path":
       return resolveBySemanticPath(reference.path, scopes);
-    case "offset":
-      return resolveByOffset(reference.at, scopes, positionMap);
-    case "range":
-      return resolveByRange(reference.from, reference.to, scopes, positionMap);
     case "natural-language":
       return resolveByNaturalLanguage(
         reference.hint,

package/src/session/import/loader-types.ts

@@ -137,6 +137,32 @@ export interface LoadDocxEditorSessionOptions {
    * inspect every marker.
    */
   stripCosmeticMarkers?: boolean;
+  /**
+   * Phase 2 bookmark-strip allowlist. When `stripCosmeticMarkers` is
+   * `true` (the default), the parser's reference scan retains
+   * bookmarks whose name is referenced by a `<w:hyperlink w:anchor>`
+   * or `<w:instrText>` (REF / PAGEREF / NOTEREF / TOC) AND any name
+   * listed here. Use this when the host depends on a stable
+   * host-authored bookmark name (e.g. `placeholder_party_name`,
+   * `signature_block_2`) that the parser's automatic scan cannot
+   * infer is load-bearing.
+   *
+   * Default: `[]` (only the automatic scan retains names).
+   *
+   * Always-retained, regardless of this list:
+   *   - `_Toc*` (when any TOC field exists in the document)
+   *   - `_Ref*` and any other name explicitly cited by a hyperlink
+   *     anchor or REF/PAGEREF/NOTEREF instruction
+   *   - `bw:scope:*` (workflow scope markers — converted to
+   *     first-class scope markers by the parser before strip runs)
+   *   - everything (defensive blanket-retain) when the document
+   *     contains a `<w:dataBinding>` whose xpath could reference
+   *     bookmarks via paths the scanner cannot statically analyze
+   *
+   * See `services/debug/docs/phase-2-bookmark-strip-audit-2026-04-24.md`
+   * for the corpus categorization that informed this contract.
+   */
+  retainedBookmarkNames?: ReadonlyArray<string>;
 }
 
 /**

package/src/session/import/loader.ts

@@ -540,7 +540,12 @@ export async function loadDocxSessionAsync(
         mediaParts,
         mainDocumentPath,
         chartPartLookup,
-        { stripCosmeticMarkers: options.stripCosmeticMarkers !== false },
+        {
+          stripCosmeticMarkers: options.stripCosmeticMarkers !== false,
+          ...(options.retainedBookmarkNames !== undefined
+            ? { retainedBookmarkNames: options.retainedBookmarkNames }
+            : {}),
+        },
       );
     } finally {
       if (options.telemetryBus) setActiveParseTelemetryBus(undefined);
@@ -1313,7 +1318,12 @@ export function loadDocxSessionSync(
         mediaParts,
         mainDocumentPath,
         chartPartLookup,
-        { stripCosmeticMarkers: options.stripCosmeticMarkers !== false },
+        {
+          stripCosmeticMarkers: options.stripCosmeticMarkers !== false,
+          ...(options.retainedBookmarkNames !== undefined
+            ? { retainedBookmarkNames: options.retainedBookmarkNames }
+            : {}),
+        },
       );
     } finally {
       if (options.telemetryBus) setActiveParseTelemetryBus(undefined);

package/src/ui-tailwind/editor-surface/perf-probe.ts

@@ -12,6 +12,9 @@ export type PerfProbeKind =
   | "snapshot.navigation"
   | "pm.rebuild"
   | "pm.decorations"
+  | "pm.decorations.comments"
+  | "pm.decorations.revisions"
+  | "pm.decorations.workflow"
   | "pm.mount"
   | "shell.render"
   | "workspace.chrome"

package/src/ui-tailwind/editor-surface/pm-decorations.ts

@@ -20,9 +20,26 @@ import type {
   WorkflowScope,
 } from "../../api/public-types";
 import { MAIN_STORY_TARGET, storyTargetsEqual } from "../../api/public-types.ts";
+import {
+  incrementInvalidationCounter,
+  recordPerfSample,
+} from "./perf-probe";
 import type { PositionMap } from "./pm-position-map";
 import type { Node as PMNode } from "prosemirror-model";
 
+/**
+ * Cheap wall-clock delta helper for sub-section probes. `performance.now`
+ * is always defined in the browser surface where this runs; the guard
+ * keeps headless Node contexts (tests) from throwing when the global
+ * isn't polyfilled.
+ */
+function nowMs(): number {
+  return typeof performance !== "undefined" &&
+    typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+}
+
 type RailDecorationSpec = {
   railKind: "scope" | "candidate" | "blocked";
   className: string;
@@ -394,6 +411,8 @@ export function buildDecorations(
   const lockedPmRanges = collectLockedPmRanges(workflowLockedZones, activeStory, positionMap);
 
   // Walk comment threads and create inline decorations
+  const commentsStartMs = nowMs();
+  let commentCount = 0;
   if (commentModel) {
     for (const thread of commentModel.threads) {
       const cls = getCommentHighlightClass(
@@ -413,11 +432,18 @@ export function buildDecorations(
             "data-comment-id": thread.commentId,
           }),
         );
+        commentCount += 1;
       }
     }
   }
+  recordPerfSample("pm.decorations.comments", nowMs() - commentsStartMs);
+  if (commentCount > 0) {
+    incrementInvalidationCounter("pm.decorations.comments.count", commentCount);
+  }
 
   // Walk revision entries and create inline decorations.
+  const revisionsStartMs = nowMs();
+  let revisionCount = 0;
   // Deletion hiding in clean mode ALWAYS applies, even when showTrackedChanges is off.
   // Visual styling (underlines, colors) only applies when showTrackedChanges is on.
   if (revisionModel) {
@@ -442,6 +468,7 @@ export function buildDecorations(
               "data-revision-id": rev.revisionId,
             }),
           );
+          revisionCount += 1;
         }
         continue;
       }
@@ -477,6 +504,7 @@ export function buildDecorations(
               return el;
             }, { side: 1, key: `${rev.revisionId}-close` }),
           );
+          revisionCount += 1;
         } else if (rev.kind === "deletion") {
           decorations.push(
             Decoration.inline(pmFrom, pmTo, {
@@ -484,6 +512,7 @@ export function buildDecorations(
               "data-revision-id": rev.revisionId,
             }),
           );
+          revisionCount += 1;
         }
         continue;
       }
@@ -511,9 +540,16 @@ export function buildDecorations(
           "data-revision-id": rev.revisionId,
         }),
       );
+      revisionCount += 1;
     }
   }
+  recordPerfSample("pm.decorations.revisions", nowMs() - revisionsStartMs);
+  if (revisionCount > 0) {
+    incrementInvalidationCounter("pm.decorations.revisions.count", revisionCount);
+  }
 
+  const workflowStartMs = nowMs();
+  const workflowDecorationsBefore = decorations.length;
   if (effectiveWorkflowScopes.length > 0) {
     for (const scope of effectiveWorkflowScopes) {
       const scopeStoryTarget = scope.storyTarget ?? MAIN_STORY_TARGET;
@@ -655,6 +691,14 @@ export function buildDecorations(
       }, railRangeCache);
     }
   }
+  recordPerfSample("pm.decorations.workflow", nowMs() - workflowStartMs);
+  const workflowDecorationCount = decorations.length - workflowDecorationsBefore;
+  if (workflowDecorationCount > 0) {
+    incrementInvalidationCounter(
+      "pm.decorations.workflow.count",
+      workflowDecorationCount,
+    );
+  }
 
   return DecorationSet.create(doc, decorations);
 }

package/src/ui-tailwind/editor-surface/preserve-position.ts

@@ -161,6 +161,14 @@ export interface ReplaceStateOptions extends PreservePositionOptions {
    * `preserve-position-ordering.test.ts`.
    */
   suppressionRef: EchoSuppressionRef;
+  /**
+   * When `true`, wrap the state swap in `capturePosition` /
+   * `restorePosition` so the scroll anchor block stays at the same
+   * viewport-Y across the replacement. Shipped **disabled by default**
+   * after the 2026-04-24 jump-to-top regression — re-enable under a
+   * diagnosed-safe codepath only.
+   */
+  preserveScrollAnchor?: boolean;
   /**
    * Microtask scheduler. Defaults to the global `queueMicrotask`.
    * Tests override it to capture the release callback.
@@ -169,17 +177,17 @@ export interface ReplaceStateOptions extends PreservePositionOptions {
 }
 
 /**
- * Replace the view's state with `newState` while preserving the user's
- * scroll position AND suppressing the selection-sync echo that would
- * otherwise fire when PM dispatches its internal selection-change
- * notifications during the swap.
+ * Replace the view's state with `newState`, suppressing the
+ * selection-sync echo during the swap.
  *
- * Ordering invariant (regression-guarded):
+ * Ordering invariant (regression-guarded by
+ * `preserve-position-ordering.test.ts`):
  *
- *   1. capture scroll anchor
+ *   1. (optional) capture scroll anchor — gated on
+ *      `preserveScrollAnchor: true` and a live `geometryFacet`
  *   2. suppressionRef.current = true
  *   3. view.updateState(newState)      ← PM may fire selection events here
- *   4. restore scroll anchor
+ *   4. (optional) restore scroll anchor
  *   5. queueMicrotask(() => suppressionRef.current = false)
  *
  * The microtask release guarantees the flag is still `true` for any
@@ -191,15 +199,26 @@ export interface ReplaceStateOptions extends PreservePositionOptions {
  * `requestAnimationFrame` is deliberate — a later scheduler would
  * leave the flag stuck true across a macrotask boundary, causing
  * legitimate post-swap selection changes to be swallowed.
+ *
+ * **Scroll preservation is opt-in.** Shipped disabled by default
+ * after the 2026-04-24 jump-to-top regression report — enabling it
+ * requires evidence that the anchor math holds under the
+ * rebuild-effect's exact timing (PM DOM mid-mutation, observer-driven
+ * scrollTop resets, etc.). The capture/restore helpers are still
+ * exported + unit-tested for the eventual re-enable.
  */
 export function replaceStatePreservingPosition(
   options: ReplaceStateOptions,
   newState: import("prosemirror-state").EditorState,
 ): void {
-  const preserved = capturePosition(options);
+  const preserved = options.preserveScrollAnchor
+    ? capturePosition(options)
+    : null;
   options.suppressionRef.current = true;
   options.view.updateState(newState);
-  restorePosition(preserved, options);
+  if (preserved) {
+    restorePosition(preserved, options);
+  }
   const release = () => {
     options.suppressionRef.current = false;
   };