@semiont/react-ui 0.5.26 → 0.5.28

package/src/features/resource-discovery/state/__tests__/discover-state-unit.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, vi } from 'vitest';
 import { asStates } from '../../../../__tests__/test-client';
 import { sessionOf } from '../../../../__tests__/test-client';
 import { BehaviorSubject, firstValueFrom } from 'rxjs';
-import { filter, skip, take, toArray } from 'rxjs/operators';
+import { filter, map, skip, take, toArray } from 'rxjs/operators';
 import type { SemiontClient } from '@semiont/sdk';
 import type { ShellStateUnit } from '../../../../state/shell-state-unit';
 import { createDiscoverStateUnit } from '../discover-state-unit';
@@ -23,6 +23,8 @@ function mockClient(overrides: {
   resources$?: BehaviorSubject<unknown[] | undefined>;
   entityTypes$?: BehaviorSubject<string[] | undefined>;
   resourcesFn?: (filters: BrowseFilters) => BehaviorSubject<unknown[] | undefined>;
+  /** What the stubbed list envelope reports as its match kind. */
+  matchKind?: 'lexical' | 'semantic';
 } = {}): { client: SemiontClient; resourceCalls: BrowseFilters[] } {
   const resourceCalls: BrowseFilters[] = [];
   const defaultResources$ =
@@ -36,7 +38,11 @@ function mockClient(overrides: {
     browse: {
       resources: (filters: BrowseFilters = {}) => {
         resourceCalls.push(filters);
-        return asStates(resourcesFn(filters).asObservable());
+        return asStates(resourcesFn(filters).asObservable().pipe(
+          // Arrays get the list envelope `resources()` now emits; explicit
+          // status objects (B15 fixtures) and `undefined` pass through.
+          map((v) => (Array.isArray(v) ? { resources: v, total: v.length, offset: 0, limit: 20, matchKind: overrides.matchKind ?? 'lexical' } : v)),
+        ));
       },
       entityTypes: () => asStates(entityTypes$.asObservable()),
     },
@@ -45,6 +51,50 @@ function mockClient(overrides: {
   return { client, resourceCalls };
 }
 
+describe('createDiscoverStateUnit — search match kind (SEMANTIC-FALLBACK P3b)', () => {
+  // S10 is tier-agnostic: the label and the resources it describes must arrive
+  // as ONE value. Exposing `matchKind$` as a second observable beside
+  // `state$.results` would satisfy the component and still let a render pair
+  // this query's label with the previous query's list.
+  it('emits matchKind in the SAME value as the results it labels', async () => {
+    vi.useFakeTimers();
+    try {
+      const results$ = new BehaviorSubject<unknown[] | undefined>([{ '@id': 'sem-1' }]);
+      const { client } = mockClient({ resourcesFn: () => results$, matchKind: 'semantic' });
+      const stateUnit = createDiscoverStateUnit(sessionOf(client), mockBrowse());
+
+      // Subscribe BEFORE setQuery: `queryInput$` is a plain Subject, so a value
+      // pushed with nothing listening is gone.
+      const collected: Array<{ results: unknown[]; matchKind?: string }> = [];
+      const sub = stateUnit.search.state$.subscribe((st) => collected.push(st));
+
+      stateUnit.search.setQuery('kitten');
+      await vi.advanceTimersByTimeAsync(300);
+
+      const last = collected.at(-1)!;
+      expect(last.results).toEqual([{ '@id': 'sem-1' }]);
+      expect(last.matchKind).toBe('semantic');
+
+      sub.unsubscribe();
+      stateUnit.dispose();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('carries no matchKind on the empty-query view', async () => {
+    // Clearing the box returns to `recent`, which no label describes.
+    const { client } = mockClient();
+    const stateUnit = createDiscoverStateUnit(sessionOf(client), mockBrowse());
+
+    const first = await firstValueFrom(stateUnit.search.state$);
+    expect(first.results).toEqual([]);
+    expect(first.matchKind).toBeUndefined();
+
+    stateUnit.dispose();
+  });
+});
+
 describe('createDiscoverStateUnit', () => {
   it('exposes recent resources from browse namespace', async () => {
     const { client } = mockClient();
@@ -201,7 +251,7 @@ describe('createDiscoverStateUnit', () => {
       stateUnit.search.setQuery('lincoln');
       await vi.advanceTimersByTimeAsync(300);
 
-      expect(collected.at(-1)).toEqual({ results: [{ '@id': 'hit' }], isSearching: false });
+      expect(collected.at(-1)).toEqual({ results: [{ '@id': 'hit' }], isSearching: false, matchKind: 'lexical' });
 
       sub.unsubscribe();
       stateUnit.dispose();

package/src/features/resource-discovery/state/discover-state-unit.ts

@@ -1,5 +1,5 @@
 import { BehaviorSubject, Subject, combineLatest, of, type Observable } from 'rxjs';
-import { readyValue } from '@semiont/sdk';
+import { readyValue, type CacheState } from '@semiont/sdk';
 import { debounceTime, distinctUntilChanged, map, startWith, switchMap, shareReplay } from 'rxjs/operators';
 import type { ResourceDescriptor } from '@semiont/core';
 import type { SemiontSession } from '@semiont/sdk';
@@ -14,7 +14,18 @@ const DEBOUNCE_MS = 250;
 
 export interface DiscoverSearchPipeline {
   query$: Observable<string>;
-  state$: Observable<{ results: ResourceDescriptor[]; isSearching: boolean }>;
+  /**
+   * The page AND the label that describes it, as one value. `matchKind` is
+   * carried here rather than beside it because SEMANTIC-FALLBACK S10 is
+   * tier-agnostic: two separately-observable pieces of state let a render pair
+   * this query's label with the previous query's list. Undefined only before
+   * the first answer (and while a query is empty), never as a third kind.
+   */
+  state$: Observable<{
+    results: ResourceDescriptor[];
+    isSearching: boolean;
+    matchKind?: 'lexical' | 'semantic';
+  }>;
   setQuery(value: string): void;
 }
 
@@ -58,7 +69,11 @@ export function createDiscoverStateUnit(
           limit: RECENT_LIMIT,
           archived: false,
           ...(et ? { entityType: et } : {}),
-        }),
+        }).pipe(
+          // This unit renders only the page; project it out of the list
+          // envelope (`matchKind` rendering is SEMANTIC-FALLBACK P3b's).
+          map((st): CacheState<ResourceDescriptor[]> => (st.status === 'ready' ? { status: 'ready', value: st.value.resources } : st)),
+        ),
       ),
     ),
     [],
@@ -74,11 +89,13 @@ export function createDiscoverStateUnit(
     distinctUntilChanged(),
   );
 
-  const state$: Observable<{ results: ResourceDescriptor[]; isSearching: boolean }> =
+  const state$: DiscoverSearchPipeline['state$'] =
     combineLatest([debouncedQuery$, selectedEntityType$]).pipe(
       switchMap(([q, et]) => {
         const trimmed = q.trim();
         if (!trimmed) {
+          // No query, no answer to label: `recent` is what renders, and no
+          // matchKind describes it.
           return of({ results: [] as ResourceDescriptor[], isSearching: false });
         }
         return client.browse
@@ -88,10 +105,14 @@ export function createDiscoverStateUnit(
             ...(et ? { entityType: et } : {}),
           })
           .pipe(
-            map((st) => ({
-              results: readyValue(st) ?? [],
-              isSearching: st.status === 'pending',
-            })),
+            map((st) => {
+              const ready = readyValue(st);
+              return {
+                results: ready?.resources ?? [],
+                isSearching: st.status === 'pending',
+                ...(ready ? { matchKind: ready.matchKind } : {}),
+              };
+            }),
             startWith({ results: [] as ResourceDescriptor[], isSearching: true }),
           );
       }),

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(() => {
   });