@semiont/react-ui 0.5.25 → 0.5.27

package/src/components/resource/panels/__tests__/ResourceInfoPanel.test.tsx

@@ -95,7 +95,9 @@ const renderWithEventBus = (component: React.ReactElement<{ session: SemiontSess
   );
   // The component is provider-free: inject the factory session so it is the
   // SAME session whose client the tracker spies on / whose bus it subscribes.
-  return render(React.cloneElement(component, { session }), { wrapper: Wrapper });
+  // The injected session/client are returned too: a test that spies on what the
+  // panel calls has to spy on THIS client, not a second factory's.
+  return { ...render(React.cloneElement(component, { session }), { wrapper: Wrapper }), session, client };
 };
 
 describe('ResourceInfoPanel Component', () => {
@@ -359,6 +361,40 @@ describe('ResourceInfoPanel Component', () => {
       expect(screen.getByText('urn:semiont:resource:abc123')).toBeInTheDocument();
     });
 
+    it('a derived-from id is a LINK, and clicking it opens that resource', () => {
+      // Rendering the id is half the feature; the provenance chain is only
+      // walkable if the id navigates. The click goes through the session's
+      // client, so a panel handed no session must not throw either — the
+      // optional chain below is load-bearing, not defensive noise.
+      // `renderWithEventBus` injects its own per-test session via cloneElement,
+      // so the spy has to go on THAT client — one created here would never be
+      // the one the button calls.
+      const { client } = renderWithEventBus(
+        <ResourceInfoPanel
+          {...defaultProps}
+          wasDerivedFrom="urn:semiont:resource:abc123"
+        />
+      );
+      const openSpy = vi.spyOn(client.browse, 'openResource');
+
+      fireEvent.click(screen.getByText('urn:semiont:resource:abc123'));
+      expect(openSpy).toHaveBeenCalledTimes(1);
+      expect(String(openSpy.mock.calls[0]![0])).toBe('urn:semiont:resource:abc123');
+    });
+
+    it('renders every id when the resource derives from several', () => {
+      renderWithEventBus(
+        <ResourceInfoPanel
+          {...defaultProps}
+          wasDerivedFrom={['urn:semiont:resource:a', 'urn:semiont:resource:b'] as never}
+        />
+      );
+      // The separator lives inside the button (`{i > 0 && ', '}{id}`), so the
+      // second one's text node is ", urn:…:b" — matched loosely on purpose.
+      expect(screen.getByText(/urn:semiont:resource:a/)).toBeInTheDocument();
+      expect(screen.getByText(/urn:semiont:resource:b/)).toBeInTheDocument();
+    });
+
     it('falls back to generator for attribution when wasAttributedTo is absent', () => {
       renderWithEventBus(
         <ResourceInfoPanel

package/src/components/resource/panels/__tests__/TagEntry.test.tsx

@@ -183,7 +183,6 @@ describe('TagEntry', () => {
 
       expect(clickHandler).toHaveBeenCalledWith({
         annotationId: 'tag-1',
-        motivation: 'tagging',
       });
 
       subscription.unsubscribe();

package/src/components/settings/SettingsPanel.css

@@ -15,10 +15,6 @@
   color: var(--semiont-text-primary);
 }
 
-[data-theme="dark"] .semiont-settings-panel__title {
-  color: var(--semiont-text-primary);
-}
-
 .semiont-settings-panel__content {
   display: flex;
   flex-direction: column;

package/src/features/auth/auth.css

@@ -53,19 +53,11 @@
   margin-bottom: 0.5rem;
 }
 
-[data-theme="dark"] .semiont-auth__welcome {
-  color: var(--semiont-text-primary);
-}
-
 .semiont-auth__subtitle {
   font-size: 1rem;
   color: var(--semiont-text-secondary);
 }
 
-[data-theme="dark"] .semiont-auth__subtitle {
-  color: var(--semiont-text-secondary);
-}
-
 /* Error display */
 .semiont-auth__error-container {
   margin-bottom: 1.5rem;
@@ -129,10 +121,6 @@
   letter-spacing: 0.05em;
 }
 
-[data-theme="dark"] .semiont-auth__divider-text {
-  color: var(--semiont-text-secondary);
-}
-
 /* Info text */
 .semiont-auth__info {
   text-align: center;
@@ -227,10 +215,6 @@
   margin-bottom: 0.5rem;
 }
 
-[data-theme="dark"] .semiont-auth__signup-title {
-  color: var(--semiont-text-primary);
-}
-
 .semiont-auth__signup-content {
   display: flex;
   flex-direction: column;
@@ -244,10 +228,6 @@
   line-height: 1.5;
 }
 
-[data-theme="dark"] .semiont-auth__signup-info {
-  color: var(--semiont-text-secondary);
-}
-
 .semiont-auth__signup-footer {
   text-align: center;
   padding-top: 1rem;
@@ -316,12 +296,12 @@
 }
 
 .semiont-form__input-row:focus-visible {
-  outline: 2px solid var(--semiont-focus-ring, #3b82f6);
+  outline: 2px solid var(--semiont-focus-ring);
   outline-offset: 2px;
 }
 
 [data-theme="dark"] .semiont-form__input-row:focus-visible {
-  outline-color: var(--semiont-focus-ring, #60a5fa);
+  outline-color: var(--semiont-focus-ring);
 }
 
 .semiont-form__input-row .semiont-input {
@@ -329,12 +309,12 @@
 }
 
 .semiont-form__input-row .semiont-input:focus-visible {
-  outline: 2px solid var(--semiont-focus-ring, #3b82f6);
+  outline: 2px solid var(--semiont-focus-ring);
   outline-offset: 2px;
 }
 
 [data-theme="dark"] .semiont-form__input-row .semiont-input:focus-visible {
-  outline-color: var(--semiont-focus-ring, #60a5fa);
+  outline-color: var(--semiont-focus-ring);
 }
 
 .semiont-form__url-status {
@@ -345,27 +325,23 @@
 }
 
 .semiont-form__url-status--checking {
-  color: var(--semiont-text-muted, #888888);
+  color: var(--semiont-text-tertiary);
   animation: spin 1s linear infinite;
   display: inline-block;
 }
 
-[data-theme="dark"] .semiont-form__url-status--checking {
-  color: var(--semiont-text-muted, #888888);
-}
-
 .semiont-form__url-status--ok {
-  color: var(--semiont-success, #22c55e);
+  color: var(--semiont-color-success);
 }
 
 [data-theme="dark"] .semiont-form__url-status--ok {
-  color: var(--semiont-success, #22c55e);
+  color: var(--semiont-color-success-light);
 }
 
 .semiont-form__url-status--error {
-  color: var(--semiont-error, #ef4444);
+  color: var(--semiont-color-error);
 }
 
 [data-theme="dark"] .semiont-form__url-status--error {
-  color: var(--semiont-error, #ef4444);
+  color: var(--semiont-color-error-light);
 }

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

@@ -83,7 +83,14 @@ describe('createComposePageStateUnit', () => {
   });
 
   it('parses storedContext in reference mode', async () => {
-    const context = { annotation: { id: 'ann-1' }, sourceContext: 'text' };
+    // 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',
@@ -97,6 +104,23 @@ describe('createComposePageStateUnit', () => {
     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',

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 { resourceId as makeResourceId, annotationId as makeAnnotationId } from '@semiont/core';
+import { isGatheredContext, resourceId as makeResourceId, annotationId as makeAnnotationId } from '@semiont/core';
 import { createDisposer } from '@semiont/sdk';
 import type { StateUnit } from '@semiont/core';
 import type { ShellStateUnit } from '../../../state/shell-state-unit';
@@ -102,7 +102,16 @@ export function createComposePageStateUnit(
       entityTypes,
     });
     if (params.storedContext) {
-      try { gatheredContext$.next(JSON.parse(params.storedContext)); } catch { /* ignore malformed */ }
+      // 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) {

package/src/features/resource-discovery/__tests__/ResourceDiscoveryPage.test.tsx

@@ -45,6 +45,7 @@ const createMockProps = (overrides?: Partial<ResourceDiscoveryPageProps>): Resou
     searchPlaceholder: 'Search resources...',
     searchButton: 'Search',
     searching: 'Searching...',
+    semanticFallbackNotice: 'No title matches — showing related documents.',
     filterByEntityType: 'Filter by type',
     all: 'All',
     recentResources: 'Recent Resources',
@@ -70,6 +71,60 @@ const renderWithProviders = (ui: React.ReactElement) => {
 };
 
 describe('ResourceDiscoveryPage', () => {
+  // SEMANTIC-FALLBACK P3b / S11. The distinction is asserted through a stable
+  // hook, never the sentence: decision 3 set the wording and it will be revised
+  // from use, so a copy-pinned test would rot on the first edit and teach the
+  // next reader to weaken it.
+  describe('semantic fallback notice', () => {
+    const NOTICE = 'semiont-semantic-match-notice';
+
+    it('marks a semantic result set as distinct from a lexical one', () => {
+      const props = createMockProps({
+        searchQuery: 'kitten',
+        searchDocuments: [createMockResource('r1', 'All about cats')],
+        searchMatchKind: 'semantic',
+      });
+      renderWithProviders(<ResourceDiscoveryPage {...props} />);
+
+      expect(screen.getByTestId(NOTICE)).toBeTruthy();
+    });
+
+    it('says nothing when the answer was lexical', () => {
+      const props = createMockProps({
+        searchQuery: 'cats',
+        searchDocuments: [createMockResource('r1', 'All about cats')],
+        searchMatchKind: 'lexical',
+      });
+      renderWithProviders(<ResourceDiscoveryPage {...props} />);
+
+      expect(screen.queryByTestId(NOTICE)).toBeNull();
+    });
+
+    it('does not carry a stale label onto the no-query view', () => {
+      // Clearing the box returns to "recent", which no label describes; a
+      // leftover `semantic` must not annotate that list.
+      const props = createMockProps({
+        searchQuery: '',
+        searchDocuments: [],
+        searchMatchKind: 'semantic',
+      });
+      renderWithProviders(<ResourceDiscoveryPage {...props} />);
+
+      expect(screen.queryByTestId(NOTICE)).toBeNull();
+    });
+
+    it('renders exactly as today when the prop is absent', () => {
+      const props = createMockProps({
+        searchQuery: 'cats',
+        searchDocuments: [createMockResource('r1', 'All about cats')],
+      });
+      renderWithProviders(<ResourceDiscoveryPage {...props} />);
+
+      expect(screen.queryByTestId(NOTICE)).toBeNull();
+    });
+  });
+
+
   beforeEach(() => {
   });
 

package/src/features/resource-discovery/components/ResourceDiscoveryPage.tsx

@@ -28,6 +28,16 @@ export interface ResourceDiscoveryPageProps {
   recentError?: Error | null;
   onRetryRecent?: () => void;
   isSearching: boolean;
+  /**
+   * How the current search answer was produced — `'lexical'` (title/metadata
+   * matching) or `'semantic'` (the vector fallback that runs only when lexical
+   * matching returned nothing). Undefined before the first answer, and on the
+   * no-query view where `recent` renders and no label describes it.
+   *
+   * Optional so hosts that never wire it — including external consumers —
+   * render exactly as before (SEMANTIC-FALLBACK P3b).
+   */
+  searchMatchKind?: 'lexical' | 'semantic';
 
   // Controlled search state
   searchQuery: string;
@@ -53,6 +63,7 @@ export interface ResourceDiscoveryPageProps {
     searchPlaceholder: string;
     searchButton: string;
     searching: string;
+    semanticFallbackNotice: string;
     filterByEntityType: string;
     all: string;
     recentResources: string;
@@ -80,6 +91,7 @@ export function ResourceDiscoveryPage({
   recentError = null,
   onRetryRecent,
   isSearching,
+  searchMatchKind,
   searchQuery,
   onSearchQueryChange,
   selectedEntityType,
@@ -232,6 +244,23 @@ export function ResourceDiscoveryPage({
               }
             </h3>
 
+            {/* Decision 3: label it, minimally. Someone who searches "kitten"
+                and gets documents about cats otherwise has no way to know why,
+                and an unexplained answer is a worse trust outcome than the
+                empty page this replaced. Only ever appears where the
+                alternative was that empty page (S5), so it never competes with
+                a better answer. `aria-live` because the results it explains
+                arrive without any control being activated. */}
+            {hasSearchQuery && searchMatchKind === 'semantic' && searchDocuments.length > 0 && (
+              <p
+                className="semiont-card__documents-note"
+                data-testid="semiont-semantic-match-notice"
+                aria-live="polite"
+              >
+                {t.semanticFallbackNotice}
+              </p>
+            )}
+
             {showNoResultsWarning && (
               <div className="semiont-card__warning">
                 <p className="semiont-card__warning-text">

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

@@ -123,6 +123,15 @@ vi.mock('../../../contexts/ResourceAnnotationsContext', () => ({
   ResourceAnnotationsProvider: ({ children }: any) => children,
 }));
 
+// Capture what ResourceViewerPage passes to useOutcomeToasts. The real hook is a
+// pure event subscription, so standing it in costs the other specs nothing.
+const outcomeToastsCalls = vi.hoisted(() => [] as unknown[]);
+vi.mock('../../../hooks/useOutcomeToasts', () => ({
+  useOutcomeToasts: (resourceId: unknown) => {
+    outcomeToastsCalls.push(resourceId);
+  },
+}));
+
 // Mock useEventSubscription at the direct path used by ResourceViewerPage
 // (the barrel export mock doesn't intercept direct context imports)
 const mockUseEventSubscriptions = vi.fn();
@@ -180,6 +189,23 @@ const renderWithProviders = (ui: React.ReactElement) => {
   );
 };
 
+describe('ResourceViewerPage — outcome toasts reach the user', () => {
+  // The decline/success toast was dropped for EVERY resource:
+  // `useOutcomeToasts(resource.id as string)` read a property
+  // `ResourceDescriptor` does not declare (it carries `@id`). The descriptor's
+  // open index signature made the access legal and the `as string` silenced its
+  // `unknown` type, so the hook's `event.resourceId !== resourceId` guard
+  // compared a real id against `undefined` and returned early every time.
+  it('subscribes with the resource id, not a property the descriptor lacks', () => {
+    outcomeToastsCalls.length = 0;
+    renderWithProviders(<ResourceViewerPage {...createMockProps()} />);
+
+    expect(outcomeToastsCalls).not.toHaveLength(0);
+    // Must be the resource's identity — `undefined` here silences every toast.
+    expect(outcomeToastsCalls[0]).toBe('test-123');
+  });
+});
+
 describe('ResourceViewerPage', () => {
   beforeEach(() => {
   });