@semiont/react-ui 0.5.26 → 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,56 +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 () => {
-    const context = { annotation: { id: 'ann-1' }, sourceContext: 'text' };
-    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 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(), {});
 
@@ -142,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(), {
@@ -196,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 { 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,34 +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) {
-      try { gatheredContext$.next(JSON.parse(params.storedContext)); } catch { /* ignore malformed */ }
-    }
-    loading$.next(false);
-  } else if (isCloneMode) {
+  if (isCloneMode) {
     void (async () => {
       try {
         const tokenResult = await client.yield.fromToken(params.token!);
@@ -175,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;
   };
 
@@ -191,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,
@@ -200,8 +159,6 @@ export function createComposePageStateUnit(
       mode$.complete();
       loading$.complete();
       cloneData$.complete();
-      referenceData$.complete();
-      gatheredContext$.complete();
       uploadProgress$.complete();
       disposer.dispose();
     },

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">