fix(document-api): invalidate stale header/footer story runtimes on part and ref mutations

Author: harbournick

packages/super-editor/src/document-api-adapters/header-footers-adapter.ts

@@ -37,6 +37,7 @@ import {
 } from './helpers/header-footer-refs-mutation.js';
 import { createHeaderFooterPart, type ConverterWithHeaderFooterParts } from './helpers/header-footer-parts.js';
 import { rejectTrackedMode } from './helpers/mutation-helpers.js';
+import { getStoryRuntimeCache } from './story-runtime/resolve-story-runtime.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -68,6 +69,23 @@ function requireConverter(editor: Editor, operationName: string): ConverterWithH
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Invalidates all cached header/footer *slot* runtimes after a ref-only
+ * mutation (set, clear, setLinkedToPrevious). These operations retarget
+ * which part a slot resolves to without touching the part itself, so the
+ * generic `partChanged` event never fires for a header/footer part. The
+ * cached slot runtimes would keep serving the old part's editor otherwise.
+ */
+function invalidateSlotRuntimesAfterRefChange(
+  editor: Editor,
+  result: SectionMutationResult,
+  options?: MutationOptions,
+): void {
+  if (!result.success || options?.dryRun) return;
+  const cache = getStoryRuntimeCache(editor);
+  if (cache) cache.invalidateByPrefix('hf:slot:');
+}
+
 function effectiveLimitOf(limit: number | undefined, total: number): number {
   return limit ?? total;
 }
@@ -204,7 +222,7 @@ export function headerFootersRefsSetAdapter(
   const { section, headerFooterKind, variant } = input.target;
   const sectionTarget = { target: section };
 
-  return sectionMutationBySectPr(
+  const result = sectionMutationBySectPr(
     editor,
     sectionTarget,
     options,
@@ -222,6 +240,8 @@ export function headerFootersRefsSetAdapter(
       );
     },
   );
+  invalidateSlotRuntimesAfterRefChange(editor, result, options);
+  return result;
 }
 
 export function headerFootersRefsClearAdapter(
@@ -232,7 +252,7 @@ export function headerFootersRefsClearAdapter(
   const { section, headerFooterKind, variant } = input.target;
   const sectionTarget = { target: section };
 
-  return sectionMutationBySectPr(
+  const result = sectionMutationBySectPr(
     editor,
     sectionTarget,
     options,
@@ -242,6 +262,8 @@ export function headerFootersRefsClearAdapter(
       clearHeaderFooterRefMutation(sectPr, headerFooterKind, variant, converter, dryRun);
     },
   );
+  invalidateSlotRuntimesAfterRefChange(editor, result, options);
+  return result;
 }
 
 export function headerFootersRefsSetLinkedToPreviousAdapter(
@@ -252,7 +274,7 @@ export function headerFootersRefsSetLinkedToPreviousAdapter(
   const { section, headerFooterKind, variant } = input.target;
   const sectionTarget = { target: section };
 
-  return sectionMutationBySectPr(
+  const result = sectionMutationBySectPr(
     editor,
     sectionTarget,
     options,
@@ -271,6 +293,8 @@ export function headerFootersRefsSetLinkedToPreviousAdapter(
       );
     },
   );
+  invalidateSlotRuntimesAfterRefChange(editor, result, options);
+  return result;
 }
 
 // ---------------------------------------------------------------------------

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

@@ -105,6 +105,15 @@ function encodeTestRef(rev: string, segments: Array<{ blockId: string; start: nu
   return `text:${btoa(JSON.stringify({ v: 3, rev, segments }))}`;
 }
 
+/** Encodes a V4 text ref with story key support. */
+function encodeV4TestRef(
+  rev: string,
+  storyKey: string,
+  segments: Array<{ blockId: string; start: number; end: number }>,
+): string {
+  return `text:v4:${btoa(JSON.stringify({ v: 4, rev, storyKey, scope: 'match', segments }))}`;
+}
+
 // ---------------------------------------------------------------------------
 // Fixtures
 // ---------------------------------------------------------------------------
@@ -374,7 +383,7 @@ describe('resolveRange', () => {
         end: { kind: 'document', edge: 'end' },
       };
 
-      expect(() => resolveRange(editor, input)).toThrow('Invalid text ref encoding');
+      expect(() => resolveRange(editor, input)).toThrow('Only text refs');
     });
 
     it('rejects ref with no segments', () => {
@@ -403,6 +412,50 @@ describe('resolveRange', () => {
       expect(() => resolveRange(editor, input)).toThrow(PlanError);
       expect(() => resolveRange(editor, input)).toThrow('REVISION_MISMATCH');
     });
+
+    it('resolves V4 text refs (text:v4: prefix) just like V3 refs', () => {
+      const { editor, index } = singleParagraph();
+      mocks.getBlockIndex.mockReturnValue(index);
+
+      const ref = encodeV4TestRef('0', 'fn:1', [{ blockId: 'p1', start: 1, end: 4 }]);
+      mocks.resolveSelectionPointPosition
+        .mockReturnValueOnce(2) // start boundary → pos 2
+        .mockReturnValueOnce(5); // end boundary   → pos 5
+
+      const input: ResolveRangeInput = {
+        start: { kind: 'ref', ref, boundary: 'start' },
+        end: { kind: 'ref', ref, boundary: 'end' },
+      };
+
+      const result = resolveRange(editor, input);
+
+      expect(mocks.resolveSelectionPointPosition).toHaveBeenCalledWith(editor, {
+        kind: 'text',
+        blockId: 'p1',
+        offset: 1,
+      });
+      expect(mocks.resolveSelectionPointPosition).toHaveBeenCalledWith(editor, {
+        kind: 'text',
+        blockId: 'p1',
+        offset: 4,
+      });
+      expect(result.evaluatedRevision).toBe('0');
+      expect(result.target.kind).toBe('selection');
+    });
+
+    it('rejects stale V4 ref with REVISION_MISMATCH', () => {
+      const { editor, index } = singleParagraph();
+      mocks.getBlockIndex.mockReturnValue(index);
+
+      const ref = encodeV4TestRef('99', 'fn:1', [{ blockId: 'p1', start: 0, end: 3 }]);
+      const input: ResolveRangeInput = {
+        start: { kind: 'ref', ref, boundary: 'start' },
+        end: { kind: 'document', edge: 'end' },
+      };
+
+      expect(() => resolveRange(editor, input)).toThrow(PlanError);
+      expect(() => resolveRange(editor, input)).toThrow('REVISION_MISMATCH');
+    });
   });
 
   // -----------------------------------------------------------------------

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

@@ -27,6 +27,7 @@ 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';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -75,52 +76,40 @@ function resolveDocumentEnd(editor: Editor, index: BlockIndex): number {
 /**
  * Decodes a text ref and extracts the start or end boundary as an absolute position.
  *
- * Only accepts `text:` prefixed refs (V3 text refs from query.match or ranges.resolve).
+ * Accepts both V3 (`text:...`) and V4 (`text:v4:...`) refs from query.match or ranges.resolve.
  */
 function resolveRefAnchor(editor: Editor, ref: string, boundary: 'start' | 'end', revision: string): number {
-  if (!ref.startsWith('text:')) {
+  const decoded = decodeRef(ref);
+
+  if (!decoded) {
     throw new DocumentApiAdapterError(
       'INVALID_TARGET',
-      `Only text refs (from query.match or ranges.resolve) are valid range anchors. Got prefix: "${ref.split(':')[0]}".`,
+      `Only text refs (from query.match or ranges.resolve) are valid range anchors. Got: "${ref}".`,
       { ref, boundary },
     );
   }
 
-  const encoded = ref.slice('text:'.length);
-  let payload: unknown;
-  try {
-    payload = JSON.parse(atob(encoded));
-  } catch {
-    throw new DocumentApiAdapterError('INVALID_TARGET', 'Invalid text ref encoding.', { ref, boundary });
-  }
-
-  const data = payload as {
-    v?: number;
-    rev?: string;
-    segments?: Array<{ blockId: string; start: number; end: number }>;
-  };
-
-  if (!data.segments?.length) {
+  const segments = decoded.segments;
+  if (!segments?.length) {
     throw new DocumentApiAdapterError('INVALID_TARGET', 'Ref contains no segments.', { ref, boundary });
   }
 
-  if (data.rev !== revision) {
+  if (decoded.rev !== revision) {
     throw new PlanError(
       'REVISION_MISMATCH',
-      `REVISION_MISMATCH — ref was created at revision ${data.rev} but document is at revision ${revision}. Re-run the discovery operation to obtain a fresh ref.`,
+      `REVISION_MISMATCH — ref was created at revision ${decoded.rev} but document is at revision ${revision}. Re-run the discovery operation to obtain a fresh ref.`,
       undefined,
       {
         ref,
         boundary,
-        refRevision: data.rev,
+        refRevision: decoded.rev,
         currentRevision: revision,
         refStability: 'ephemeral',
         remediation: 'Re-run ranges.resolve or query.match to obtain a fresh ref valid for the current revision.',
       },
     );
   }
-
-  const seg = boundary === 'start' ? data.segments[0] : data.segments[data.segments.length - 1];
+  const seg = boundary === 'start' ? segments[0] : segments[segments.length - 1];
   const offset = boundary === 'start' ? seg.start : seg.end;
   const point: SelectionPoint = { kind: 'text', blockId: seg.blockId, offset };