@semiont/react-ui 0.5.27 → 0.5.29

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

@@ -2,15 +2,16 @@
  * 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 { capabilitiesOf, AUTHORABLE_MEDIA_TYPES, MEDIA_TYPES, mediaTypeForExtension, isSupportedMediaType, LOCALES, folderOf, proposeStoragePath, getStorageUri } from '@semiont/core';
+import type { SupportedMediaType } 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 +43,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 +73,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 +95,7 @@ export interface ResourceComposePageProps {
     cancel: string;
     saving: string;
     creating: string;
-    creatingAndLinking: string;
     saveClonedResource: string;
-    createAndLinkResource: string;
     createResource: string;
   };
 
@@ -111,7 +105,7 @@ export interface ResourceComposePageProps {
 }
 
 export interface SaveResourceParams {
-  mode: 'new' | 'clone' | 'reference';
+  mode: 'new' | 'clone';
   name: string;
   storageUri: string;
   content?: string;
@@ -121,15 +115,11 @@ export interface SaveResourceParams {
   entityTypes?: string[];
   language: string;
   archiveOriginal?: boolean;
-  annotationUri?: string;
-  sourceDocumentId?: string;
 }
 
 export function ResourceComposePage({
   mode,
   cloneData,
-  referenceData,
-  gatheredContext,
   availableEntityTypes,
   initialLocale,
   theme,
@@ -179,18 +169,27 @@ export function ResourceComposePage({
   // Archive original checkbox (for clones only)
   const [archiveOriginal, setArchiveOriginal] = useState(true);
 
+  // D11 — the Save location starts filled and follows the title until the user
+  // takes it over; `pathTouched` is derived, so clearing restores the proposal.
+  // A clone proposes beside its source; a new resource proposes at the root.
+  const composeFormat: SupportedMediaType =
+    isSupportedMediaType(selectedFormat) ? selectedFormat : 'text/markdown';
+  const pathTouched = storagePath !== '';
+  const effectivePath = pathTouched
+    ? storagePath
+    : proposeStoragePath(
+        mode === 'clone' && cloneData ? folderOf(getStorageUri(cloneData.sourceResource)) : '',
+        newResourceName,
+        composeFormat,
+      );
+
   // Initialize form data based on mode
   useEffect(() => {
     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>) => {
@@ -250,7 +249,7 @@ export function ResourceComposePage({
       const params: SaveResourceParams = {
         mode,
         name: newResourceName,
-        storageUri: `file://${storagePath}`,
+        storageUri: `file://${effectivePath}`,
         content: newResourceContent,
         format: uploadedFile ? fileMimeType : selectedFormat,
         entityTypes: selectedEntityTypes,
@@ -266,20 +265,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 +282,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 +290,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">
@@ -405,7 +331,7 @@ export function ResourceComposePage({
               <input
                 id="storagePath"
                 type="text"
-                value={storagePath}
+                value={effectivePath}
                 onChange={(e) => setStoragePath(e.target.value)}
                 placeholder="docs/my-resource.md"
                 required
@@ -416,7 +342,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 +388,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 +414,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 +456,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 +533,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 +575,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 +633,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-discovery/__tests__/ResourceDiscoveryPage.test.tsx

@@ -354,7 +354,7 @@ describe('ResourceDiscoveryPage', () => {
     });
 
     it('renders the recentDocuments prop as-is without applying any post-filter', () => {
-      // The component is now controlled — backend filtering means
+      // The component is now controlled — gateway filtering means
       // `recentDocuments` already contains only the resources matching the
       // active `selectedEntityType`. The component must not re-filter.
       const props = createMockProps({

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

@@ -44,7 +44,7 @@ export interface ResourceDiscoveryPageProps {
   onSearchQueryChange: (query: string) => void;
 
   // Controlled entity-type filter — owned by the state unit so filtering
-  // pushes to the backend rather than running as a post-fetch array filter.
+  // pushes to the gateway rather than running as a post-fetch array filter.
   selectedEntityType: string;
   onSelectedEntityTypeChange: (entityType: string) => void;
 
@@ -106,7 +106,7 @@ export function ResourceDiscoveryPage({
   const hasSearchQuery = searchQuery.trim() !== '';
 
   // When searching, render search results; otherwise render recent.
-  // Both already arrive entity-type-filtered from the backend — no post-filter here.
+  // Both already arrive entity-type-filtered from the gateway — no post-filter here.
   const filteredResources = hasSearchQuery ? searchDocuments : recentDocuments;
 
   // Roving tabindex for entity type filters

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

@@ -50,7 +50,7 @@ export function createDiscoverStateUnit(
 
   // Selected entity-type chip on the Discover page. Drives both the
   // `recent` list and the search results — filtering happens on the
-  // backend, not via post-fetch array filtering.
+  // gateway, not via post-fetch array filtering.
   const selectedEntityType$ = new BehaviorSubject<string>('');
   disposer.add(() => selectedEntityType$.complete());