fix: make story-aware refs, ranges, and writes route correctly

Author: harbournick

packages/document-api/src/ranges/ranges.types.ts

@@ -8,6 +8,7 @@
 
 import type { SelectionTarget, SelectionPoint } from '../types/address.js';
 import type { BlockNodeType } from '../types/base.js';
+import type { StoryLocator } from '../types/story.types.js';
 
 // ---------------------------------------------------------------------------
 // Anchor types
@@ -52,6 +53,8 @@ export interface ResolveRangeInput {
   end: RangeAnchor;
   /** Optional expected revision for consistency checking. */
   expectedRevision?: string;
+  /** Story to resolve the range against. Defaults to body when absent. */
+  in?: StoryLocator;
 }
 
 /** Per-block preview metadata within the resolved range. */

packages/document-api/src/ranges/resolve.ts

@@ -10,6 +10,7 @@ import type { ResolveRangeInput, ResolveRangeOutput, RangeResolverAdapter, Range
 import { DocumentApiValidationError } from '../errors.js';
 import { isRecord, assertNoUnknownFields } from '../validation-primitives.js';
 import { isSelectionPoint } from '../validation/selection-target-validator.js';
+import { validateStoryLocator } from '../validation/story-validator.js';
 
 // ---------------------------------------------------------------------------
 // Anchor validation
@@ -76,7 +77,7 @@ function validateAnchor(value: unknown, fieldName: string): asserts value is Ran
 // Input validation
 // ---------------------------------------------------------------------------
 
-const RESOLVE_RANGE_ALLOWED_KEYS = new Set(['start', 'end', 'expectedRevision']);
+const RESOLVE_RANGE_ALLOWED_KEYS = new Set(['start', 'end', 'expectedRevision', 'in']);
 
 function validateResolveRangeInput(input: unknown): asserts input is ResolveRangeInput {
   if (!isRecord(input)) {
@@ -107,6 +108,8 @@ function validateResolveRangeInput(input: unknown): asserts input is ResolveRang
       { field: 'expectedRevision', value: input.expectedRevision },
     );
   }
+
+  validateStoryLocator(input.in, 'in');
 }
 
 // ---------------------------------------------------------------------------

packages/super-editor/src/document-api-adapters/helpers/range-resolver.test.ts

@@ -15,6 +15,7 @@ const mocks = vi.hoisted(() => ({
   encodeV3Ref: vi.fn(() => 'text:mock-encoded'),
   getRevision: vi.fn(() => '0'),
   checkRevision: vi.fn(),
+  resolveStoryRuntime: vi.fn(),
 }));
 
 vi.mock('./index-cache.js', () => ({
@@ -40,6 +41,13 @@ vi.mock('./node-address-resolver.js', () => ({
     Boolean(candidate.node?.inlineContent || candidate.node?.isTextblock),
 }));
 
+// Story runtime resolution: return a passthrough body runtime wrapping the
+// editor that was passed in. Tests that exercise non-body story targeting
+// should override this mock as needed.
+vi.mock('../story-runtime/resolve-story-runtime.js', () => ({
+  resolveStoryRuntime: mocks.resolveStoryRuntime,
+}));
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -170,6 +178,15 @@ beforeEach(() => {
   vi.clearAllMocks();
   mocks.getRevision.mockReturnValue('0');
   mocks.encodeV3Ref.mockReturnValue('text:mock-encoded');
+
+  // Default: resolveStoryRuntime returns a passthrough body runtime
+  // wrapping the editor that was passed in.
+  mocks.resolveStoryRuntime.mockImplementation((hostEditor: Editor) => ({
+    locator: { kind: 'story', storyType: 'body' },
+    storyKey: 'body',
+    editor: hostEditor,
+    kind: 'body',
+  }));
 });
 
 // ---------------------------------------------------------------------------

packages/super-editor/src/document-api-adapters/helpers/range-resolver.ts

@@ -4,9 +4,10 @@
  *
  * Composes existing primitives:
  * - SelectionPoint resolution (selection-target-resolver.ts)
- * - V3 ref encoding (query-match-adapter.ts)
+ * - V3/V4 ref encoding (query-match-adapter.ts, story-ref-codec.ts)
  * - Revision tracking (revision-tracker.ts)
  * - Block index (index-cache.ts)
+ * - Story runtime resolution (resolve-story-runtime.ts)
  */
 
 import type {
@@ -17,8 +18,9 @@ import type {
   SelectionTarget,
   SelectionPoint,
   SelectionEdgeNodeType,
+  StoryLocator,
 } from '@superdoc/document-api';
-import { SELECTION_EDGE_NODE_TYPES } from '@superdoc/document-api';
+import { SELECTION_EDGE_NODE_TYPES, storyLocatorToKey } from '@superdoc/document-api';
 import type { Editor } from '../../core/Editor.js';
 import { getBlockIndex } from './index-cache.js';
 import { isTextBlockCandidate, type BlockCandidate, type BlockIndex } from './node-address-resolver.js';
@@ -27,7 +29,10 @@ import { encodeV3Ref } from '../plan-engine/query-match-adapter.js';
 import { getRevision, checkRevision } from '../plan-engine/revision-tracker.js';
 import { PlanError } from '../plan-engine/errors.js';
 import { DocumentApiAdapterError } from '../errors.js';
-import { decodeRef } from '../story-runtime/story-ref-codec.js';
+import { decodeRef, encodeV4Ref } from '../story-runtime/story-ref-codec.js';
+import { resolveStoryFromRef, resolveStoryFromInput } from '../story-runtime/resolve-story-context.js';
+import { resolveStoryRuntime } from '../story-runtime/resolve-story-runtime.js';
+import { BODY_STORY_KEY, buildStoryKey } from '../story-runtime/story-key.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -236,11 +241,21 @@ function resolveGapPosition(index: BlockIndex, absPos: number): SelectionPoint {
 // SelectionTarget construction
 // ---------------------------------------------------------------------------
 
-function buildSelectionTarget(editor: Editor, index: BlockIndex, absFrom: number, absTo: number): SelectionTarget {
+function buildSelectionTarget(
+  editor: Editor,
+  index: BlockIndex,
+  absFrom: number,
+  absTo: number,
+  story?: StoryLocator,
+): SelectionTarget {
   return {
     kind: 'selection',
     start: absPositionToSelectionPoint(editor, index, absFrom),
     end: absPositionToSelectionPoint(editor, index, absTo),
+    // Attach story metadata for non-body stories so that callers can chain
+    // the target into mutations without repeating `in`. Body stories omit
+    // the field for backward compatibility (body is the default).
+    ...(story && { story }),
   };
 }
 
@@ -333,6 +348,7 @@ function encodeRangeRef(
   absFrom: number,
   absTo: number,
   revision: string,
+  storyKey?: string,
 ): string | null {
   const segments: Array<{ blockId: string; start: number; end: number }> = [];
 
@@ -370,6 +386,19 @@ function encodeRangeRef(
     return null;
   }
 
+  // Non-body stories use V4 refs to preserve the storyKey for downstream
+  // mutations. Body stories keep V3 for backward compatibility.
+  if (storyKey && storyKey !== BODY_STORY_KEY) {
+    return encodeV4Ref({
+      v: 4,
+      rev: revision,
+      storyKey,
+      scope: 'match',
+      matchId: `range:${absFrom}-${absTo}`,
+      segments,
+    });
+  }
+
   return encodeV3Ref({
     v: 3,
     rev: revision,
@@ -419,7 +448,7 @@ function rangeContainsOnlyTextBlocks(index: BlockIndex, absFrom: number, absTo:
  */
 export function resolveAbsoluteRange(
   editor: Editor,
-  input: { absFrom: number; absTo: number; expectedRevision?: string },
+  input: { absFrom: number; absTo: number; expectedRevision?: string; storyLocator?: StoryLocator },
 ): ResolveRangeOutput {
   const revision = getRevision(editor);
 
@@ -433,7 +462,14 @@ export function resolveAbsoluteRange(
   const absFrom = Math.min(input.absFrom, input.absTo);
   const absTo = Math.max(input.absFrom, input.absTo);
 
-  const target = buildSelectionTarget(editor, index, absFrom, absTo);
+  // Non-body stories attach metadata to the target and encode V4 refs.
+  // Body stories (undefined or explicit body locator) omit the field for
+  // backward compatibility.
+  const isNonBody = input.storyLocator !== undefined && input.storyLocator.storyType !== 'body';
+  const storyForTarget = isNonBody ? input.storyLocator : undefined;
+  const storyKey = isNonBody ? buildStoryKey(input.storyLocator!) : undefined;
+
+  const target = buildSelectionTarget(editor, index, absFrom, absTo, storyForTarget);
 
   // The V3 text ref can only encode text-block content segments. The ref is
   // lossy when the target uses nodeEdge endpoints (structural block boundaries)
@@ -445,7 +481,7 @@ export function resolveAbsoluteRange(
   return {
     evaluatedRevision: revision,
     handle: {
-      ref: encodeRangeRef(editor, index, absFrom, absTo, revision),
+      ref: encodeRangeRef(editor, index, absFrom, absTo, revision, storyKey),
       refStability: 'ephemeral',
       coversFullTarget,
     },
@@ -454,23 +490,95 @@ export function resolveAbsoluteRange(
   };
 }
 
+// ---------------------------------------------------------------------------
+// Story resolution for range anchors
+// ---------------------------------------------------------------------------
+
+/**
+ * Extracts the story locator embedded in a range anchor's ref, if any.
+ *
+ * Only `ref`-kind anchors can carry story information (via V4 refs).
+ * `document` and `point` anchors are story-agnostic.
+ */
+function extractStoryFromAnchor(anchor: RangeAnchor): StoryLocator | undefined {
+  if (anchor.kind !== 'ref') return undefined;
+  return resolveStoryFromRef(anchor.ref);
+}
+
+/**
+ * Reconciles stories extracted from the start and end anchors.
+ *
+ * Both anchors must target the same story — a range cannot span multiple stories.
+ * Returns `undefined` when neither anchor carries story information.
+ */
+function reconcileAnchorStories(
+  startStory: StoryLocator | undefined,
+  endStory: StoryLocator | undefined,
+): StoryLocator | undefined {
+  if (!startStory) return endStory;
+  if (!endStory) return startStory;
+
+  if (storyLocatorToKey(startStory) !== storyLocatorToKey(endStory)) {
+    throw new DocumentApiAdapterError(
+      'INVALID_INPUT',
+      `Range anchor story mismatch: start ref targets "${storyLocatorToKey(startStory)}" ` +
+        `but end ref targets "${storyLocatorToKey(endStory)}". A range cannot span multiple stories.`,
+      { startStory: storyLocatorToKey(startStory), endStory: storyLocatorToKey(endStory) },
+    );
+  }
+
+  return startStory;
+}
+
+/**
+ * Resolves the effective story locator for a range operation.
+ *
+ * Merges three potential sources using the standard precedence rules:
+ * 1. `input.in` — explicit story targeting on the operation input
+ * 2. Ref anchors — V4 refs in `start` or `end` that embed a storyKey
+ *
+ * All sources must agree; mismatches produce a clear error.
+ */
+function resolveRangeStory(input: ResolveRangeInput): StoryLocator | undefined {
+  const startStory = extractStoryFromAnchor(input.start);
+  const endStory = extractStoryFromAnchor(input.end);
+  const anchorStory = reconcileAnchorStories(startStory, endStory);
+
+  return resolveStoryFromInput({ in: input.in }, anchorStory ? { story: anchorStory } : undefined);
+}
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
 /**
  * Resolves two explicit anchors into a contiguous document range.
  *
- * Returns a transparent SelectionTarget, a mutation-ready ref, and preview metadata.
+ * Story-aware: resolves the target story from `input.in` and/or V4 ref
+ * anchors, then evaluates all anchors against the correct story editor's
+ * document state and revision counter.
+ *
+ * @param hostEditor - The body (host) editor — used to resolve story runtimes.
+ * @param input      - The range resolution input with anchors and optional story locator.
+ * @returns A transparent SelectionTarget, a mutation-ready ref, and preview metadata.
  */
-export function resolveRange(editor: Editor, input: ResolveRangeInput): ResolveRangeOutput {
-  const revision = getRevision(editor);
+export function resolveRange(hostEditor: Editor, input: ResolveRangeInput): ResolveRangeOutput {
+  // Determine which story to resolve against (defaults to body).
+  const storyLocator = resolveRangeStory(input);
+  const runtime = resolveStoryRuntime(hostEditor, storyLocator);
+  const storyEditor = runtime.editor;
+
+  const revision = getRevision(storyEditor);
 
   if (input.expectedRevision !== undefined) {
-    checkRevision(editor, input.expectedRevision);
+    checkRevision(storyEditor, input.expectedRevision);
   }
 
-  const index = getBlockIndex(editor);
+  const index = getBlockIndex(storyEditor);
 
-  // Resolve both anchors to absolute PM positions
-  const rawFrom = resolveAnchor(editor, input.start, revision, index);
-  const rawTo = resolveAnchor(editor, input.end, revision, index);
+  // Resolve both anchors to absolute PM positions in the story's document
+  const rawFrom = resolveAnchor(storyEditor, input.start, revision, index);
+  const rawTo = resolveAnchor(storyEditor, input.end, revision, index);
 
-  return resolveAbsoluteRange(editor, { absFrom: rawFrom, absTo: rawTo });
+  return resolveAbsoluteRange(storyEditor, { absFrom: rawFrom, absTo: rawTo, storyLocator });
 }

packages/super-editor/src/document-api-adapters/plan-engine/plan-wrappers.ts

@@ -78,10 +78,9 @@ import {
 } from '../helpers/node-address-resolver.js';
 import { getInlinePropertyCapabilityIssue, getTrackedInlinePropertySupportIssue } from './inline-property-guards.js';
 import { resolveStoryRuntime } from '../story-runtime/resolve-story-runtime.js';
-import { resolveStoryFromInput } from '../story-runtime/resolve-story-context.js';
+import { resolveMutationStory } from '../story-runtime/resolve-story-context.js';
 import type { StoryRuntime } from '../story-runtime/story-types.js';
 import { decodeRef } from '../story-runtime/story-ref-codec.js';
-import { parseStoryKey } from '../story-runtime/story-key.js';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -146,31 +145,12 @@ export function disposeEphemeralWriteRuntime(runtime: StoryRuntime): void {
   }
 }
 
-function resolveStoryFromMutationRef(ref: string | undefined): StoryLocator | undefined {
-  if (!ref) return undefined;
-
-  const decodedRef = decodeRef(ref);
-  if (!decodedRef || decodedRef.v !== 4) {
-    return undefined;
-  }
-
-  try {
-    return parseStoryKey(decodedRef.storyKey);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new DocumentApiAdapterError('INVALID_TARGET', `Mutation ref carries an invalid story key: ${message}`, {
-      ref,
-      storyKey: decodedRef.storyKey,
-    });
-  }
-}
-
 function resolveSelectionMutationStory(request: SelectionMutationRequest): StoryLocator | undefined {
-  const targetWithStory = request.target as { story?: StoryLocator } | undefined;
-  const storyFromRef = resolveStoryFromMutationRef(request.ref);
-  const effectiveTargetStory = targetWithStory?.story ?? storyFromRef;
-
-  return resolveStoryFromInput({ in: request.in }, effectiveTargetStory ? { story: effectiveTargetStory } : undefined);
+  return resolveMutationStory({
+    in: request.in,
+    target: request.target as { story?: StoryLocator } | undefined,
+    ref: request.ref,
+  });
 }
 
 /**
@@ -1350,8 +1330,16 @@ export function replaceStructuredWrapper(
     );
   }
 
-  // Resolve story runtime from the input's `in` field.
-  const runtime = resolveWriteStoryRuntime(editor, (input as { in?: StoryLocator }).in);
+  // Resolve story from the full mutation context:
+  // - explicit input.in
+  // - target.story threaded by discovery APIs
+  // - V4 ref storyKey when the mutation is ref-only
+  const effectiveLocator = resolveMutationStory({
+    in: (input as { in?: StoryLocator }).in,
+    target: input.target as { story?: StoryLocator } | undefined,
+    ref: input.ref,
+  });
+  const runtime = resolveWriteStoryRuntime(editor, effectiveLocator);
 
   try {
     const storyEditor = runtime.editor;
@@ -1364,7 +1352,14 @@ export function replaceStructuredWrapper(
         : undefined;
 
     const textReceipt = executeStructuralReplaceWrapper(storyEditor, input, options);
-    if (runtime.commit) runtime.commit(editor);
+
+    // Only persist non-body story changes when the replace actually succeeded.
+    // Committing on failure would write unchanged content back to OOXML,
+    // potentially materializing inherited header/footer slots or emitting
+    // spurious partChanged events.
+    if (textReceipt.success && runtime.commit) {
+      runtime.commit(editor);
+    }
 
     if (!blockTarget) return textReceiptToSDReceipt(textReceipt);
 

packages/super-editor/src/document-api-adapters/story-runtime/index.ts

@@ -32,7 +32,7 @@ export { StoryRuntimeCache } from './runtime-cache.js';
 
 // Resolution
 export { resolveStoryRuntime, getStoryRuntimeCache } from './resolve-story-runtime.js';
-export { resolveStoryFromInput } from './resolve-story-context.js';
+export { resolveStoryFromInput, resolveStoryFromRef, resolveMutationStory } from './resolve-story-context.js';
 
 // Story-specific resolvers
 export { resolveHeaderFooterSlotRuntime, resolveHeaderFooterPartRuntime } from './header-footer-story-runtime.js';