fix(doc-api): stabilize bibliography.configure targets in citations stories (#2507)

* fix(doc-api): stabilize bibliography.configure targets in citations stories

* fix(doc-api): stringify numeric sdBlockId in bibliography resolver

Author: harbournick

packages/super-editor/src/document-api-adapters/citations-export.integration.test.ts

@@ -206,6 +206,14 @@ describe('citations export integration', () => {
     );
 
     expect(configureResult.success).toBe(true);
+    if (!configureResult.success) return;
+
+    const bibliographyInfo = editor.doc.citations.bibliography.get({
+      target: configureResult.bibliography,
+    });
+
+    expect(bibliographyInfo.style).toBe('MLA');
+    expect(bibliographyInfo.address.nodeId).toBe(configureResult.bibliography.nodeId);
     expect(findBibliographyNode(editor)?.attrs.style).toBe('MLA');
   });
 });

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

@@ -7,7 +7,7 @@ import {
   resolvePostMutationBibliographyId,
 } from './citation-resolver.js';
 
-function makeBibliographyDoc(sdBlockId: string | undefined = 'bib-runtime', style = 'APA') {
+function makeBibliographyDoc(sdBlockId: string | number | undefined = 'bib-runtime', style = 'APA') {
   return {
     descendants: (cb: (node: unknown, pos: number) => boolean | void) => {
       cb(
@@ -49,6 +49,27 @@ describe('citation-resolver bibliography ids', () => {
     expect(resolved.nodeId).toMatch(/^bibliography-auto-[0-9a-f]{8}$/);
   });
 
+  it('coerces a numeric sdBlockId to string in commandNodeId', () => {
+    const doc = makeBibliographyDoc(42 as unknown as string);
+    const [resolved] = findAllBibliographies(doc);
+
+    expect(typeof resolved.commandNodeId).toBe('string');
+    expect(resolved.commandNodeId).toBe('42');
+  });
+
+  it('resolves bibliography target when sdBlockId is numeric', () => {
+    const doc = makeBibliographyDoc(42 as unknown as string);
+    const [resolved] = findAllBibliographies(doc);
+
+    // Should be findable via the stringified commandNodeId
+    const found = resolveBibliographyTarget(doc, {
+      kind: 'block',
+      nodeType: 'bibliography',
+      nodeId: '42',
+    });
+    expect(found.nodeId).toBe(resolved.nodeId);
+  });
+
   it('extracts bibliography info with the public address and persisted style', () => {
     const doc = makeBibliographyDoc('bib-runtime', 'MLA');
     const [resolved] = findAllBibliographies(doc);

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

@@ -121,7 +121,8 @@ export function findAllBibliographies(doc: ProseMirrorNode): ResolvedBibliograph
   let occurrenceIndex = 0;
   doc.descendants((node, pos) => {
     if (node.type.name === 'bibliography') {
-      const commandNodeId = node.attrs?.sdBlockId as string | undefined;
+      const rawBlockId = node.attrs?.sdBlockId;
+      const commandNodeId = rawBlockId != null ? String(rawBlockId) : undefined;
       const nodeId = resolvePublicReferenceBlockNodeId(node, occurrenceIndex);
       occurrenceIndex += 1;
       results.push({ node, pos, nodeId, commandNodeId });
@@ -258,8 +259,8 @@ function resolveParentBlockId(doc: ProseMirrorNode, pos: number): string {
   const resolved = doc.resolve(pos);
   for (let depth = resolved.depth; depth >= 0; depth--) {
     const node = resolved.node(depth);
-    const blockId = node.attrs?.sdBlockId as string | undefined;
-    if (blockId) return blockId;
+    const rawBlockId = node.attrs?.sdBlockId;
+    if (rawBlockId != null) return String(rawBlockId);
   }
   return '';
 }

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

@@ -37,6 +37,7 @@ import type {
 } from '@superdoc/document-api';
 import { buildDiscoveryResult, buildDiscoveryItem, buildResolvedHandle } from '@superdoc/document-api';
 import {
+  findAllBibliographies,
   findAllCitations,
   resolveCitationTarget,
   extractCitationInfo,
@@ -421,7 +422,8 @@ export function bibliographyConfigureWrapper(
   rejectTrackedMode('citations.bibliography.configure', options);
 
   const resolved = resolveBibliographyTarget(editor.state.doc, input.target);
-  const address: BibliographyAddress = { kind: 'block', nodeType: 'bibliography', nodeId: resolved.nodeId };
+  const stableNodeId = resolved.commandNodeId ?? resolved.nodeId;
+  const address: BibliographyAddress = { kind: 'block', nodeType: 'bibliography', nodeId: stableNodeId };
 
   if (options?.dryRun) return bibSuccess(address);
 
@@ -445,7 +447,13 @@ export function bibliographyConfigureWrapper(
 
   syncBibliographyStyleToConverter(editor, input.style);
 
-  return bibSuccess(address);
+  const bibliographies = findAllBibliographies(editor.state.doc);
+  const postMutationBibliography =
+    bibliographies.find((bibliography) => bibliography.pos === resolved.pos) ??
+    bibliographies.find((bibliography) => bibliography.commandNodeId === stableNodeId);
+  const postMutationId =
+    postMutationBibliography?.nodeId ?? resolvePostMutationBibliographyId(editor.state.doc, stableNodeId);
+  return bibSuccess({ kind: 'block', nodeType: 'bibliography', nodeId: postMutationId });
 }
 
 export function bibliographyRebuildWrapper(

tests/doc-api-stories/package.json

@@ -7,7 +7,7 @@
     "test": "pnpm --silent --prefix ../../packages/sdk run generate && pnpm --silent --prefix ../../packages/superdoc run build:es && pnpm --silent --prefix ../../apps/cli run build && pnpm --silent --prefix ../../packages/sdk/langs/node run build && vitest run --config ./vitest.config.ts"
   },
   "dependencies": {
-    "@superdoc-dev/sdk": "file:../../packages/sdk/langs/node"
+    "@superdoc-dev/sdk": "workspace:*"
   },
   "devDependencies": {
     "vitest": "catalog:"

tests/doc-api-stories/tests/citations/all-commands.ts

@@ -486,17 +486,24 @@ describe('document-api story: all citations commands', () => {
           throw new Error('citations.bibliography.configure requires a bibliography target fixture.');
         }
 
-        const configureResult = await callDocOperation<any>('citations.bibliography.configure', {
+        const beforeInfo = await callDocOperation<any>('citations.bibliography.get', {
           sessionId,
           target: f.bibliographyTarget,
+        });
+        const configureTarget = (beforeInfo?.address as BibliographyAddress | undefined) ?? f.bibliographyTarget;
+
+        const configureResult = await callDocOperation<any>('citations.bibliography.configure', {
+          sessionId,
+          target: configureTarget,
           style: 'APA',
         });
+        const configuredTarget = (configureResult?.bibliography as BibliographyAddress | undefined) ?? configureTarget;
 
         const info = await callDocOperation<any>('citations.bibliography.get', {
           sessionId,
-          target: f.bibliographyTarget,
+          target: configuredTarget,
         });
-        expect(typeof info?.style).toBe('string');
+        expect(info?.style).toBe('APA');
 
         return configureResult;
       },