@semiont/react-ui 0.5.27 → 0.5.28

package/src/features/resource-compose/components/ResourceComposePage.tsx

@@ -2,15 +2,15 @@
  * ResourceComposePage Component
  *
  * Pure React component for creating and editing resources.
- * Supports three modes: new resource, clone, and reference completion.
+ * Supports two modes: new resource and clone. (Reference completion moved
+ * into the resolve wizard — COMPOSE-IN-MODAL.)
  * All dependencies passed as props - no Next.js hooks!
  */
 
 import React, { useState, useEffect } from 'react';
-import { deriveViews, type GatheredContext } from '@semiont/core';
 import { capabilitiesOf, AUTHORABLE_MEDIA_TYPES, MEDIA_TYPES, mediaTypeForExtension, isSupportedMediaType, LOCALES } from '@semiont/core';
 import type { UploadProgress } from '@semiont/sdk';
-import { type CloneData, type ReferenceData } from '../state/compose-page-state-unit';
+import { type CloneData } from '../state/compose-page-state-unit';
 import { COMMON_PANELS, type ToolbarPanelType } from '../../../state/shell-state-unit';
 import { buttonStyles } from '../../../lib/button-styles';
 import { CodeMirrorRenderer } from '../../../components/CodeMirrorRenderer';
@@ -42,10 +42,8 @@ function detectUploadMediaType(file: File): string {
 }
 
 export interface ResourceComposePageProps {
-  mode: 'new' | 'clone' | 'reference';
+  mode: 'new' | 'clone';
   cloneData?: CloneData | null;
-  referenceData?: ReferenceData | null;
-  gatheredContext?: GatheredContext | null;
 
   // Available options
   availableEntityTypes: string[];
@@ -74,10 +72,7 @@ export interface ResourceComposePageProps {
   translations: {
     title: string;
     titleEditClone: string;
-    titleCompleteReference: string;
     subtitleClone: string;
-    subtitleReference: string;
-    linkedNoticePrefix: string;
     resourceName: string;
     resourceNamePlaceholder: string;
     entityTypes: string;
@@ -99,9 +94,7 @@ export interface ResourceComposePageProps {
     cancel: string;
     saving: string;
     creating: string;
-    creatingAndLinking: string;
     saveClonedResource: string;
-    createAndLinkResource: string;
     createResource: string;
   };
 
@@ -111,7 +104,7 @@ export interface ResourceComposePageProps {
 }
 
 export interface SaveResourceParams {
-  mode: 'new' | 'clone' | 'reference';
+  mode: 'new' | 'clone';
   name: string;
   storageUri: string;
   content?: string;
@@ -121,15 +114,11 @@ export interface SaveResourceParams {
   entityTypes?: string[];
   language: string;
   archiveOriginal?: boolean;
-  annotationUri?: string;
-  sourceDocumentId?: string;
 }
 
 export function ResourceComposePage({
   mode,
   cloneData,
-  referenceData,
-  gatheredContext,
   availableEntityTypes,
   initialLocale,
   theme,
@@ -184,13 +173,8 @@ export function ResourceComposePage({
     if (mode === 'clone' && cloneData) {
       setNewResourceName(cloneData.sourceResource.name);
       setNewResourceContent(cloneData.sourceContent);
-    } else if (mode === 'reference' && referenceData) {
-      setNewResourceName(referenceData.name);
-      if (referenceData.entityTypes.length > 0) {
-        setSelectedEntityTypes(referenceData.entityTypes);
-      }
     }
-  }, [mode, cloneData, referenceData]);
+  }, [mode, cloneData]);
 
   // Handle file upload
   const handleFileUpload = (e: React.ChangeEvent<HTMLInputElement>) => {
@@ -266,20 +250,12 @@ export function ResourceComposePage({
       if (mode === 'clone') {
         params.archiveOriginal = archiveOriginal;
       }
-      if (referenceData?.annotationUri) {
-        params.annotationUri = referenceData.annotationUri;
-      }
-      if (referenceData?.sourceDocumentId) {
-        params.sourceDocumentId = referenceData.sourceDocumentId;
-      }
 
       await onSaveResource(params);
 
       // Announce success based on mode
       const successMessage = mode === 'clone'
         ? 'Resource cloned successfully'
-        : mode === 'reference'
-        ? 'Reference completed successfully'
         : 'Resource created successfully';
       announceFormSuccess(successMessage);
     } catch (error) {
@@ -291,13 +267,6 @@ export function ResourceComposePage({
   };
 
   const isClone = mode === 'clone';
-  const isReferenceCompletion = mode === 'reference';
-
-  // Gathered-context panel — annotation-focus only for now.
-  const composeFocus = gatheredContext?.focus.kind === 'annotation' ? gatheredContext.focus : null;
-  const composeConnections = gatheredContext && composeFocus
-    ? deriveViews(gatheredContext.graph, String(composeFocus.sourceResource.id)).connections
-    : [];
 
   return (
     <div className={`semiont-page${activePanel && COMMON_PANELS.includes(activePanel as ToolbarPanelType) ? ' semiont-page--panel-open' : ''}`}>
@@ -306,73 +275,15 @@ export function ResourceComposePage({
         {/* Page Title */}
         <div className="semiont-page__header">
           <h1 className="semiont-page__title">
-            {isClone ? t.titleEditClone : isReferenceCompletion ? t.titleCompleteReference : t.title}
+            {isClone ? t.titleEditClone : t.title}
           </h1>
-          {(isClone || isReferenceCompletion) && (
+          {isClone && (
             <p className="semiont-page__subtitle">
-              {isClone ? t.subtitleClone : t.subtitleReference}
+              {t.subtitleClone}
             </p>
           )}
-          {isReferenceCompletion && (
-            <div className="semiont-page__reference-notice">
-              <p className="semiont-page__reference-notice-text">
-                {t.linkedNoticePrefix}
-              </p>
-            </div>
-          )}
         </div>
 
-        {/* Gathered Context Panel (from wizard) */}
-        {gatheredContext && (
-          <div className="semiont-form__field" style={{
-            marginBottom: '1.5rem',
-            padding: '1rem',
-            backgroundColor: 'var(--semiont-bg-secondary)',
-            borderRadius: 'var(--semiont-radius-md)',
-            border: '1px solid var(--semiont-border-primary)',
-          }}>
-            <h3 className="semiont-form__label" style={{ marginBottom: '0.75rem' }}>Gathered Context</h3>
-            {composeFocus?.selected && (
-              <div style={{
-                padding: '0.75rem',
-                backgroundColor: 'var(--semiont-bg-primary)',
-                borderRadius: 'var(--semiont-radius-md)',
-                border: '1px solid var(--semiont-border-primary)',
-                maxHeight: '150px',
-                overflowY: 'auto',
-                marginBottom: '0.5rem',
-              }}>
-                <div style={{ fontSize: 'var(--semiont-text-sm)', fontFamily: 'monospace', whiteSpace: 'pre-wrap', color: 'var(--semiont-text-secondary)' }}>
-                  {composeFocus.selected.before && <span>{composeFocus.selected.before}</span>}
-                  <span style={{
-                    backgroundColor: 'var(--semiont-color-primary-100)',
-                    padding: '0 0.25rem',
-                    fontWeight: 600,
-                    color: 'var(--semiont-color-primary-900)',
-                  }}>
-                    {composeFocus.selected.text}
-                  </span>
-                  {composeFocus.selected.after && <span>{composeFocus.selected.after}</span>}
-                </div>
-              </div>
-            )}
-            {composeConnections.length > 0 && (
-              <div style={{
-                padding: '0.5rem 0',
-                fontSize: 'var(--semiont-text-sm)',
-                color: 'var(--semiont-text-secondary)',
-              }}>
-                <span style={{ fontSize: 'var(--semiont-text-xs)', fontWeight: 500, marginRight: '0.5rem' }}>Connections:</span>
-                {composeConnections.map(conn => (
-                  <span key={conn.resourceId} className="semiont-chip" style={{ fontSize: 'var(--semiont-text-xs)', padding: '0.125rem 0.5rem', marginRight: '0.25rem' }}>
-                    {conn.resourceName}
-                  </span>
-                ))}
-              </div>
-            )}
-          </div>
-        )}
-
         {/* Create Form */}
         <div className="semiont-form">
         <form onSubmit={handleSaveResource} className="semiont-form__fields semiont-compose-grid">
@@ -416,7 +327,7 @@ export function ResourceComposePage({
           </div>
 
           {/* Entity Types Selection */}
-          {(!isReferenceCompletion || selectedEntityTypes.length === 0) && (
+          {(
             <div className="semiont-form__field semiont-form__entity-types">
               <div className="semiont-form__label">
                 {t.entityTypes}
@@ -462,30 +373,6 @@ export function ResourceComposePage({
             </div>
           )}
 
-          {/* Entity Types Display for reference completion */}
-          {isReferenceCompletion && selectedEntityTypes.length > 0 && (
-            <div className="semiont-form__field semiont-form__entity-types-display" role="region" aria-labelledby="selected-entity-types-label">
-              <h3 id="selected-entity-types-label" className="semiont-form__label">
-                {t.entityTypes}
-              </h3>
-              <div className="semiont-form__entity-type-tags" role="list">
-                {selectedEntityTypes.map((type) => (
-                  <span
-                    key={type}
-                    role="listitem"
-                    className="semiont-form__entity-type-tag"
-                    aria-label={`Entity type: ${type}`}
-                  >
-                    {type}
-                  </span>
-                ))}
-              </div>
-              <p className="semiont-form__helper-text" id="reference-entity-types-description">
-                These entity types were selected when creating the reference
-              </p>
-            </div>
-          )}
-
           {/* Language Selector */}
           <div className="semiont-form__field">
             <label htmlFor="language-select" className="semiont-form__label">
@@ -512,7 +399,7 @@ export function ResourceComposePage({
           <div className="semiont-compose-grid__content">
 
           {/* Content Source Toggle - only show for new resources */}
-          {!isClone && !isReferenceCompletion && (
+          {!isClone && (
             <div className="semiont-form__field">
               <label className="semiont-form__label">
                 {t.contentSource}
@@ -554,7 +441,7 @@ export function ResourceComposePage({
           )}
 
           {/* Upload File Section */}
-          {!isClone && !isReferenceCompletion && inputMethod === 'upload' && (
+          {!isClone && inputMethod === 'upload' && (
             <div className="semiont-form__upload-section">
               <div>
                 <div className="semiont-form__upload-container">
@@ -631,10 +518,10 @@ export function ResourceComposePage({
           )}
 
           {/* Write Content Section */}
-          {(isClone || isReferenceCompletion || inputMethod === 'write') && (
+          {(isClone || inputMethod === 'write') && (
             <div className="semiont-form__write-section">
               {/* Format Selector - only for manual entry, not clones */}
-              {!isClone && !isReferenceCompletion && (
+              {!isClone && (
                 <div className="semiont-form__field">
                   <label htmlFor="format-select" className="semiont-form__label">
                     {t.format}
@@ -673,7 +560,7 @@ export function ResourceComposePage({
               </div>
 
               {/* Encoding Selector - only for manual text entry */}
-              {!isClone && !isReferenceCompletion && (
+              {!isClone && (
                 <div className="semiont-form__field">
                   <label htmlFor="charset-select" className="semiont-form__label">
                     {t.encoding}
@@ -731,8 +618,8 @@ export function ResourceComposePage({
               className={buttonStyles.primary.base}
             >
               {isCreating
-                ? (isClone ? t.saving : isReferenceCompletion ? t.creatingAndLinking : t.creating)
-                : (isClone ? t.saveClonedResource : isReferenceCompletion ? t.createAndLinkResource : t.createResource)}
+                ? (isClone ? t.saving : t.creating)
+                : (isClone ? t.saveClonedResource : t.createResource)}
             </button>
           </div>
 

package/src/features/resource-compose/state/__tests__/compose-page-state-unit.test.ts

@@ -64,80 +64,6 @@ describe('createComposePageStateUnit', () => {
     stateUnit.dispose();
   });
 
-  it('detects reference mode from params', async () => {
-    const stateUnit = createComposePageStateUnit(sessionOf(mockClient()), mockBrowse(), {
-      annotationUri: 'ann-1',
-      sourceDocumentId: 'doc-1',
-      name: 'Reference Doc',
-      entityTypes: 'Person,Place',
-    });
-
-    const mode = await firstValueFrom(stateUnit.mode$);
-    expect(mode).toBe('reference');
-
-    const ref = await firstValueFrom(stateUnit.referenceData$.pipe(filter((r) => r !== null)));
-    expect(ref!.annotationUri).toBe('ann-1');
-    expect(ref!.entityTypes).toEqual(['Person', 'Place']);
-
-    stateUnit.dispose();
-  });
-
-  it('parses storedContext in reference mode', async () => {
-    // A real `GatheredContext` shape. The old fixture here was
-    // `{ annotation, sourceContext }` — not a context at all — and it round-tripped
-    // because nothing checked. That is the hole the guard closes.
-    const context = {
-      focus: { kind: 'annotation', annotation: { id: 'ann-1' }, sourceResource: { id: 'doc-1' } },
-      graph: { nodes: [], edges: [] },
-      metadata: {},
-    };
-    const stateUnit = createComposePageStateUnit(sessionOf(mockClient()), mockBrowse(), {
-      annotationUri: 'ann-1',
-      sourceDocumentId: 'doc-1',
-      name: 'Ref',
-      storedContext: JSON.stringify(context),
-    });
-
-    const gathered = await firstValueFrom(stateUnit.gatheredContext$.pipe(filter((g) => g !== null)));
-    expect(gathered).toEqual(context);
-
-    stateUnit.dispose();
-  });
-
-  it('ignores a stash that parses but is not a GatheredContext', async () => {
-    // The realistic case: an entry written by an older build, read back after a
-    // deploy. It used to sail through and reach `deriveViews`, which maps
-    // `graph.nodes` during render and throws instead of degrading.
-    const stateUnit = createComposePageStateUnit(sessionOf(mockClient()), mockBrowse(), {
-      annotationUri: 'ann-1',
-      sourceDocumentId: 'doc-1',
-      name: 'Ref',
-      storedContext: JSON.stringify({ annotation: { id: 'ann-1' }, sourceContext: 'text' }),
-    });
-
-    // Treated as NO stash: the ordinary gather path owns the outcome from here.
-    expect(await firstValueFrom(stateUnit.gatheredContext$)).toBeNull();
-
-    stateUnit.dispose();
-  });
-
-  it('ignores malformed storedContext', async () => {
-    const stateUnit = createComposePageStateUnit(sessionOf(mockClient()), mockBrowse(), {
-      annotationUri: 'ann-1',
-      sourceDocumentId: 'doc-1',
-      name: 'Ref',
-      storedContext: 'not-json{{{',
-    });
-
-    const loading = await firstValueFrom(stateUnit.loading$.pipe(filter((l) => !l)));
-    expect(loading).toBe(false);
-
-    const gathered = await firstValueFrom(stateUnit.gatheredContext$);
-    expect(gathered).toBeNull();
-
-    stateUnit.dispose();
-  });
-
   it('exposes entity types', async () => {
     const stateUnit = createComposePageStateUnit(sessionOf(mockClient()), mockBrowse(), {});
 
@@ -166,31 +92,6 @@ describe('createComposePageStateUnit', () => {
     stateUnit.dispose();
   });
 
-  it('save in reference mode calls yield.resource then bind.body', async () => {
-    const resource = mockUpload('new-4');
-    const body = vi.fn().mockResolvedValue(undefined);
-    const stateUnit = createComposePageStateUnit(sessionOf(mockClient({ resource, body })), mockBrowse(), {
-      annotationUri: 'ann-1',
-      sourceDocumentId: 'doc-1',
-      name: 'Ref',
-    });
-
-    const id = await stateUnit.save({
-      mode: 'reference',
-      name: 'Ref Doc',
-      storageUri: '/docs/ref.md',
-      content: 'content',
-      language: 'en',
-      annotationUri: 'ann-1',
-      sourceDocumentId: 'doc-1',
-    });
-
-    expect(id).toBe('new-4');
-    expect(body).toHaveBeenCalledOnce();
-
-    stateUnit.dispose();
-  });
-
   it('save in clone mode calls yield.createFromToken', async () => {
     const createFromToken = vi.fn().mockResolvedValue({ resourceId: 'cloned-1' });
     const stateUnit = createComposePageStateUnit(sessionOf(mockClient({ createFromToken })), mockBrowse(), {
@@ -220,7 +121,7 @@ describe('ComposePageStateUnit — StateUnit axioms', () => {
         const browse = disposeProbe();
         return { unit: createComposePageStateUnit(sessionOf(mockClient()), browse as unknown as ShellStateUnit, {}), passedIn: [browse] };
       },
-      surfaces: (u) => [u.mode$, u.loading$, u.cloneData$, u.referenceData$, u.gatheredContext$, u.uploadProgress$],
+      surfaces: (u) => [u.mode$, u.loading$, u.cloneData$, u.uploadProgress$],
     });
   });
 });

package/src/features/resource-compose/state/compose-page-state-unit.ts

@@ -1,6 +1,6 @@
 import { BehaviorSubject, type Observable } from 'rxjs';
-import type { GatheredContext, AnnotationId, AccessToken, ResourceDescriptor, ResourceId } from '@semiont/core';
-import { isGatheredContext, resourceId as makeResourceId, annotationId as makeAnnotationId } from '@semiont/core';
+import type { AccessToken, ResourceDescriptor, ResourceId } from '@semiont/core';
+import { resourceId as makeResourceId } from '@semiont/core';
 import { createDisposer } from '@semiont/sdk';
 import type { StateUnit } from '@semiont/core';
 import type { ShellStateUnit } from '../../../state/shell-state-unit';
@@ -9,16 +9,11 @@ import type { SemiontSession } from '@semiont/sdk';
 import { decodeWithCharset, extensionForMediaType } from '@semiont/core';
 import type { UploadProgress } from '@semiont/sdk';
 
-export type ComposeMode = 'new' | 'clone' | 'reference';
+export type ComposeMode = 'new' | 'clone';
 
 export interface ComposeParams {
   mode?: string | undefined;
   token?: string | undefined;
-  annotationUri?: string | undefined;
-  sourceDocumentId?: string | undefined;
-  name?: string | undefined;
-  entityTypes?: string | undefined;
-  storedContext?: string | undefined;
 }
 
 export interface CloneData {
@@ -26,13 +21,6 @@ export interface CloneData {
   sourceContent: string;
 }
 
-export interface ReferenceData {
-  annotationUri: string;
-  sourceDocumentId: string;
-  name: string;
-  entityTypes: string[];
-}
-
 export interface SaveResourceParams {
   mode: ComposeMode;
   name: string;
@@ -44,8 +32,6 @@ export interface SaveResourceParams {
   entityTypes?: string[];
   language: string;
   archiveOriginal?: boolean;
-  annotationUri?: string;
-  sourceDocumentId?: string;
 }
 
 export interface ComposePageStateUnit extends StateUnit {
@@ -53,8 +39,6 @@ export interface ComposePageStateUnit extends StateUnit {
   mode$: Observable<ComposeMode>;
   loading$: Observable<boolean>;
   cloneData$: Observable<CloneData | null>;
-  referenceData$: Observable<ReferenceData | null>;
-  gatheredContext$: Observable<GatheredContext | null>;
   entityTypes: ListState<string[]>;
   /**
    * Live upload-progress for the in-flight `save(...)` call. Emits the
@@ -78,43 +62,19 @@ export function createComposePageStateUnit(
   // (`useShellStateUnit`), not this unit — do NOT add it to the disposer (it's the
   // shared, app-scoped shell). See packages/sdk/docs/STATE-UNITS.md (composition rule).
 
-  const isReferenceMode = Boolean(params.annotationUri && params.sourceDocumentId && params.name);
   const isCloneMode = params.mode === 'clone' && Boolean(params.token);
-  const pageMode: ComposeMode = isCloneMode ? 'clone' : isReferenceMode ? 'reference' : 'new';
+  const pageMode: ComposeMode = isCloneMode ? 'clone' : 'new';
 
   const mode$ = new BehaviorSubject<ComposeMode>(pageMode);
   const loading$ = new BehaviorSubject<boolean>(true);
   const cloneData$ = new BehaviorSubject<CloneData | null>(null);
-  const referenceData$ = new BehaviorSubject<ReferenceData | null>(null);
-  const gatheredContext$ = new BehaviorSubject<GatheredContext | null>(null);
   const uploadProgress$ = new BehaviorSubject<UploadProgress | null>(null);
 
   const entityTypes = trackList<string[]>(() => client.browse.entityTypes(), []);
   disposer.add(entityTypes.dispose);
 
   // Initialize based on mode
-  if (isReferenceMode) {
-    const entityTypes = params.entityTypes ? params.entityTypes.split(',') : [];
-    referenceData$.next({
-      annotationUri: params.annotationUri!,
-      sourceDocumentId: params.sourceDocumentId!,
-      name: params.name!,
-      entityTypes,
-    });
-    if (params.storedContext) {
-      // The stash is the one place a `GatheredContext` arrives with its type
-      // history severed (sessionStorage → JSON.parse), so it is checked here and
-      // trusted everywhere after. A stale entry — a tab held open across a deploy
-      // — used to reach `deriveViews`, which maps `graph.nodes` during render and
-      // throws rather than degrading. A failed guard is treated as NO stash: the
-      // ordinary gather path runs, with the loading and error states it already has.
-      try {
-        const parsed: unknown = JSON.parse(params.storedContext);
-        if (isGatheredContext(parsed)) gatheredContext$.next(parsed);
-      } catch { /* ignore malformed */ }
-    }
-    loading$.next(false);
-  } else if (isCloneMode) {
+  if (isCloneMode) {
     void (async () => {
       try {
         const tokenResult = await client.yield.fromToken(params.token!);
@@ -184,14 +144,6 @@ export function createComposePageStateUnit(
       });
     });
 
-    if (saveParams.mode === 'reference' && saveParams.annotationUri && saveParams.sourceDocumentId) {
-      await client.bind.body(
-        makeResourceId(saveParams.sourceDocumentId),
-        makeAnnotationId(saveParams.annotationUri) as AnnotationId,
-        [{ op: 'add', item: { type: 'SpecificResource' as const, source: newResourceId, purpose: 'linking' as const } }],
-      );
-    }
-
     return newResourceId;
   };
 
@@ -200,8 +152,6 @@ export function createComposePageStateUnit(
     mode$: mode$.asObservable(),
     loading$: loading$.asObservable(),
     cloneData$: cloneData$.asObservable(),
-    referenceData$: referenceData$.asObservable(),
-    gatheredContext$: gatheredContext$.asObservable(),
     entityTypes: entityTypes.state,
     uploadProgress$: uploadProgress$.asObservable(),
     save,
@@ -209,8 +159,6 @@ export function createComposePageStateUnit(
       mode$.complete();
       loading$.complete();
       cloneData$.complete();
-      referenceData$.complete();
-      gatheredContext$.complete();
       uploadProgress$.complete();
       disposer.dispose();
     },

package/src/features/resource-viewer/__tests__/ResourceViewerPage.test.tsx

@@ -14,7 +14,8 @@ import { ToastProvider } from '../../../components/Toast';
 import { ThemeProvider } from '../../../contexts/ThemeContext';
 import { LineNumbersProvider } from '../../../contexts/LineNumbersContext';
 import { createTestSemiontWrapper } from '../../../test-utils';
-import type { ResourceId } from '@semiont/core';
+import type { BodyOperation, EventMap, ResourceId, UserId } from '@semiont/core';
+import { annotationId as makeAnnotationId, resourceId as makeResourceId } from '@semiont/core';
 
 // jsdom doesn't implement window.matchMedia — mock it for useTheme
 Object.defineProperty(window, 'matchMedia', {
@@ -102,24 +103,22 @@ useDebouncedCallback: (fn: any) => fn,
       announceResourceLoaded: vi.fn(),
     }),
     useEventSubscriptions: vi.fn(),
-    useResourceAnnotations: () => ({
-      clearNewAnnotationId: vi.fn(),
-      newAnnotationIds: new Set(),
-      markAnnotation: vi.fn(),
-      deleteAnnotation: vi.fn(),
-      triggerSparkleAnimation: vi.fn(),
-    }),
+    useResourceAnnotations: () => sparkleContext,
   };
 });
 
+// Shared, assertable spies — the page's sparkle wiring is pinned against
+// these (a per-call `vi.fn()` object would be unobservable from the tests).
+const sparkleContext = vi.hoisted(() => ({
+  clearSparkle: vi.fn(),
+  sparkleAnnotationIds: new Set<string>(),
+  markAnnotation: vi.fn(),
+  deleteAnnotation: vi.fn(),
+  triggerSparkleAnimation: vi.fn(),
+}));
+
 vi.mock('../../../contexts/ResourceAnnotationsContext', () => ({
-  useResourceAnnotations: () => ({
-    clearNewAnnotationId: vi.fn(),
-    newAnnotationIds: new Set(),
-    markAnnotation: vi.fn(),
-    deleteAnnotation: vi.fn(),
-    triggerSparkleAnimation: vi.fn(),
-  }),
+  useResourceAnnotations: () => sparkleContext,
   ResourceAnnotationsProvider: ({ children }: any) => children,
 }));
 
@@ -206,6 +205,63 @@ describe('ResourceViewerPage — outcome toasts reach the user', () => {
   });
 });
 
+// RESOLUTION-SPARKLE D2: a reference resolving — from ANY strategy, local or
+// remote — arrives as mark:body-updated with a linking-add operation, and the
+// page turns exactly that into a sparkle. The harness mocks
+// useEventSubscriptions, so the pin drives the captured handler directly.
+describe('ResourceViewerPage — resolution sparkles', () => {
+  const bodyUpdated = (operations: BodyOperation[]): EventMap['mark:body-updated'] => ({
+    id: 'evt-1',
+    timestamp: '2026-08-21T12:00:00Z',
+    resourceId: makeResourceId('test-123'),
+    userId: 'did:web:example.com:users:alice' as UserId,
+    version: 1,
+    type: 'mark:body-updated',
+    payload: { annotationId: makeAnnotationId('ann-7'), operations },
+    metadata: { sequenceNumber: 1 },
+  });
+
+  const renderAndGetHandler = () => {
+    mockUseEventSubscriptions.mockClear();
+    sparkleContext.triggerSparkleAnimation.mockClear();
+    renderWithProviders(<ResourceViewerPage {...createMockProps()} />);
+    const map = mockUseEventSubscriptions.mock.calls.at(-1)?.[0] as
+      Record<string, (event: EventMap['mark:body-updated']) => void>;
+    return map['mark:body-updated'];
+  };
+
+  it('an operation adding a linking SpecificResource sparkles the annotation', () => {
+    const handler = renderAndGetHandler();
+    expect(handler).toBeDefined();
+
+    handler!(bodyUpdated([
+      { op: 'add', item: { type: 'SpecificResource', source: 'res-target', purpose: 'linking' } },
+    ]));
+
+    expect(sparkleContext.triggerSparkleAnimation).toHaveBeenCalledWith('ann-7');
+  });
+
+  it('unlink (remove-only operations) stays dark — A2', () => {
+    const handler = renderAndGetHandler();
+
+    handler?.(bodyUpdated([
+      { op: 'remove', item: { type: 'SpecificResource', source: 'res-target', purpose: 'linking' } },
+    ]));
+
+    expect(sparkleContext.triggerSparkleAnimation).not.toHaveBeenCalled();
+  });
+
+  it('a TextualBody add stays dark', () => {
+    const handler = renderAndGetHandler();
+
+    handler?.(bodyUpdated([
+      { op: 'add', item: { type: 'TextualBody', value: 'Person', purpose: 'tagging' } },
+    ]));
+
+    expect(sparkleContext.triggerSparkleAnimation).not.toHaveBeenCalled();
+  });
+});
+
 describe('ResourceViewerPage', () => {
   beforeEach(() => {
   });