@semiont/react-ui 0.5.28 → 0.5.30

package/src/components/modals/__tests__/ConfigureGenerationStep.test.tsx

@@ -12,7 +12,9 @@ import { useState } from 'react';
 import { render, screen, fireEvent } from '@testing-library/react';
 import '@testing-library/jest-dom';
 import type { CollaboratorEntry, GatheredContext } from '@semiont/core';
-import { ConfigureGenerationStep } from '../ConfigureGenerationStep';
+import { GENERATABLE_MEDIA_TYPES, capabilitiesOf } from '@semiont/core';
+import { ConfigureGenerationStep, freshGenerationDraft } from '../ConfigureGenerationStep';
+import type { GenerationDraft } from '../ConfigureGenerationStep';
 
 const translations = {
   resourceTitle: 'Title',
@@ -29,6 +31,8 @@ const translations = {
   maxLengthHelp: 'How long the generated resource may be.',
   // Named model + ceiling, so the bound is legible rather than mysterious (D6).
   maxLengthCeiling: 'Limited to {{maxOutputTokens}} tokens by {{model}}.',
+  outputFormat: 'Format',
+  formatExtensionMismatch: 'Save location must end in {{extension}} to match the selected format.',
   back: 'Back',
   generate: 'Generate',
 };
@@ -36,10 +40,7 @@ const translations = {
 const context = { resources: [], annotations: [] } as unknown as GatheredContext;
 
 /** The wizard's initial draft (WIZARD-NAVIGATION D3). */
-const DRAFT = {
-  title: 'Untitled', storagePath: '', prompt: '', language: 'en',
-  temperature: 0.7, maxTokensText: '500',
-};
+const DRAFT: GenerationDraft = freshGenerationDraft('Untitled', 'en');
 
 const agentWithCeiling = (maxOutputTokens: number): CollaboratorEntry =>
   ({
@@ -59,12 +60,13 @@ const agentWithCeiling = (maxOutputTokens: number): CollaboratorEntry =>
  * than the bare component: a `vi.fn()` for `onConfigChange` would swallow every edit
  * and quietly turn each assertion below into a test of nothing.
  */
-function Harness({ generationAgent }: { generationAgent?: CollaboratorEntry }) {
+function Harness({ generationAgent, defaultFolder }: { generationAgent?: CollaboratorEntry; defaultFolder?: string }) {
   const [draft, setDraft] = useState(DRAFT);
   return (
     <ConfigureGenerationStep
       config={draft}
       onConfigChange={setDraft}
+      {...(defaultFolder !== undefined ? { defaultFolder } : {})}
       context={context}
       onBack={vi.fn()}
       onGenerate={onGenerateSpy}
@@ -76,9 +78,14 @@ function Harness({ generationAgent }: { generationAgent?: CollaboratorEntry }) {
 
 let onGenerateSpy = vi.fn();
 
-function renderStep(generationAgent?: CollaboratorEntry) {
+function renderStep(generationAgent?: CollaboratorEntry, defaultFolder?: string) {
   onGenerateSpy = vi.fn();
-  const utils = render(<Harness {...(generationAgent ? { generationAgent } : {})} />);
+  const utils = render(
+    <Harness
+      {...(generationAgent ? { generationAgent } : {})}
+      {...(defaultFolder !== undefined ? { defaultFolder } : {})}
+    />,
+  );
   const input = () => screen.getByLabelText('Max length') as HTMLInputElement;
   return { ...utils, input, props: { onGenerate: onGenerateSpy } };
 }
@@ -266,6 +273,104 @@ describe('ConfigureGenerationStep — the draft is the owner\'s', () => {
   });
 });
 
+// ── GENERATION-OUTPUT-FORMAT P2 — the output format is a choice ─────────────
+// The wire, the worker and the registry have carried three generatable types
+// the whole time; only the control was missing.
+
+describe('ConfigureGenerationStep — the output format (D1, D2)', () => {
+  const formatSelect = () => screen.getByLabelText(translations.outputFormat) as HTMLSelectElement;
+
+  it('offers exactly the registry-generatable types, in registry order, by their registry labels', () => {
+    // DERIVED from GENERATABLE_MEDIA_TYPES, never a literal list: promoting a
+    // fourth row must light it up here for free, and a hand-written array
+    // would silently lie the moment the registry moves.
+    renderStep();
+    const options = Array.from(formatSelect().options);
+    expect(options.map((o) => o.value)).toEqual([...GENERATABLE_MEDIA_TYPES]);
+    expect(options.map((o) => o.textContent)).toEqual(
+      GENERATABLE_MEDIA_TYPES.map((t) => capabilitiesOf(t)!.label),
+    );
+  });
+
+  it('defaults to markdown, and SENDS what it shows (D2)', () => {
+    // The worker already defaults to markdown when the key is absent, so an
+    // unsent field would produce the right artifact by accident. The point is
+    // that the displayed value is the transmitted one.
+    const { props } = renderStep();
+    expect(formatSelect().value).toBe('text/markdown');
+    fillRequired();
+    fireEvent.click(screen.getByText(new RegExp(translations.generate)));
+    expect(props.onGenerate.mock.calls[0]![0]).toMatchObject({ outputMediaType: 'text/markdown' });
+  });
+
+  it('carries a chosen format into the submitted config', () => {
+    const { props } = renderStep();
+    fireEvent.change(screen.getByLabelText('Save location'), { target: { value: 'generated/out.pdf' } });
+    fireEvent.change(formatSelect(), { target: { value: 'application/pdf' } });
+    fireEvent.click(screen.getByText(new RegExp(translations.generate)));
+    expect(props.onGenerate.mock.calls[0]![0]).toMatchObject({ outputMediaType: 'application/pdf' });
+  });
+});
+
+describe('ConfigureGenerationStep — the GUI refuses a format/extension mismatch (D7)', () => {
+  const formatSelect = () => screen.getByLabelText(translations.outputFormat) as HTMLSelectElement;
+  const generateButton = () => screen.getByText(new RegExp(translations.generate)).closest('button')!;
+
+  it('blocks submission and explains, naming the extension the format expects', () => {
+    // D7: the worker is faithful and incurious — it will write a PDF to a .md
+    // path and only log it — so this form is the ONLY refusal in the chain.
+    const { props } = renderStep();
+    fireEvent.change(screen.getByLabelText('Save location'), { target: { value: 'generated/out.md' } });
+    fireEvent.change(formatSelect(), { target: { value: 'application/pdf' } });
+
+    expect(generateButton()).toBeDisabled();
+    expect(screen.getByText(/must end in \.pdf/)).toBeInTheDocument();
+    fireEvent.click(generateButton());
+    expect(props.onGenerate).not.toHaveBeenCalled();
+  });
+
+  it('clears when EITHER control is corrected', () => {
+    const { props } = renderStep();
+    fireEvent.change(screen.getByLabelText('Save location'), { target: { value: 'generated/out.md' } });
+    fireEvent.change(formatSelect(), { target: { value: 'application/pdf' } });
+    expect(generateButton()).toBeDisabled();
+
+    // Fix the path…
+    fireEvent.change(screen.getByLabelText('Save location'), { target: { value: 'generated/out.pdf' } });
+    expect(generateButton()).not.toBeDisabled();
+    expect(screen.queryByText(/must end in/)).toBeNull();
+
+    // …or, from a fresh mismatch, fix the format instead.
+    fireEvent.change(formatSelect(), { target: { value: 'text/plain' } });
+    expect(generateButton()).toBeDisabled();
+    fireEvent.change(formatSelect(), { target: { value: 'application/pdf' } });
+    expect(generateButton()).not.toBeDisabled();
+
+    fireEvent.click(generateButton());
+    expect(props.onGenerate).toHaveBeenCalledTimes(1);
+  });
+
+  it('never greets an untouched form with a refusal — the default state is coherent', () => {
+    // markdown + the placeholder's `.md` shape: a user who has typed nothing
+    // must not be told they are wrong.
+    renderStep();
+    expect(screen.queryByText(/must end in/)).toBeNull();
+    fillRequired(); // generated/out.md, markdown selected
+    expect(generateButton()).not.toBeDisabled();
+  });
+
+  it('refuses an extensionless path, and accepts a differently-cased one', () => {
+    // Open question 2, both edges: the rule is "ends with the registry
+    // extension", so no extension fails it; case is not a real mismatch.
+    renderStep();
+    fireEvent.change(screen.getByLabelText('Save location'), { target: { value: 'generated/notes' } });
+    expect(generateButton()).toBeDisabled();
+
+    fireEvent.change(screen.getByLabelText('Save location'), { target: { value: 'generated/NOTES.MD' } });
+    expect(generateButton()).not.toBeDisabled();
+  });
+});
+
 describe('ConfigureGenerationStep — the hint echo (GEP P1c, D8)', () => {
   it('echoes a non-empty hint, and renders nothing without one', () => {
     const { container, rerender } = render(
@@ -288,3 +393,61 @@ describe('ConfigureGenerationStep — the hint echo (GEP P1c, D8)', () => {
     expect(container.querySelector('.semiont-wizard__hint-echo')).toBeNull();
   });
 });
+
+describe('the Save location proposes a path and stops following once touched (D11)', () => {
+  const path = () => screen.getByLabelText('Save location') as HTMLInputElement;
+  const title = () => screen.getByLabelText('Title') as HTMLInputElement;
+
+  it('opens PRE-FILLED beside the source, named for the title', () => {
+    renderStep(undefined, 'research');
+    expect(path().value).toBe('research/untitled.md');
+  });
+
+  it('proposes a bare filename when the source has no folder', () => {
+    renderStep(undefined, '');
+    expect(path().value).toBe('untitled.md');
+  });
+
+  it('FOLLOWS the title while untouched', () => {
+    renderStep(undefined, 'research');
+    fireEvent.change(title(), { target: { value: 'A New Name' } });
+    expect(path().value).toBe('research/a-new-name.md');
+  });
+
+  it('FOLLOWS the format while untouched — extension included', () => {
+    renderStep(undefined, 'research');
+    fireEvent.change(screen.getByLabelText('Format'), { target: { value: 'application/pdf' } });
+    expect(path().value).toBe('research/untitled.pdf');
+  });
+
+  it('STOPS following once the path is edited — the title then moves freely', () => {
+    renderStep(undefined, 'research');
+    fireEvent.change(path(), { target: { value: 'elsewhere/mine.md' } });
+    fireEvent.change(title(), { target: { value: 'A New Name' } });
+    expect(path().value).toBe('elsewhere/mine.md');
+  });
+
+  it('CLEARING the field un-touches it, restoring the proposal', () => {
+    renderStep(undefined, 'research');
+    fireEvent.change(path(), { target: { value: 'elsewhere/mine.md' } });
+    fireEvent.change(path(), { target: { value: '' } });
+    expect(path().value).toBe('research/untitled.md');
+  });
+
+  it('submits the PROPOSED path when the user never touched it', () => {
+    const { props } = renderStep(undefined, 'research');
+    fireEvent.click(screen.getByRole('button', { name: 'Generate' }));
+    expect(props.onGenerate).toHaveBeenCalledWith(
+      expect.objectContaining({ storageUri: 'file://research/untitled.md' }),
+    );
+  });
+
+  it('a proposed path never trips the D7 mismatch refusal — it carries the right extension', () => {
+    const { props } = renderStep(undefined, 'research');
+    fireEvent.change(screen.getByLabelText('Format'), { target: { value: 'application/pdf' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Generate' }));
+    expect(props.onGenerate).toHaveBeenCalledWith(
+      expect.objectContaining({ storageUri: 'file://research/untitled.pdf' }),
+    );
+  });
+});

package/src/components/modals/__tests__/ReferenceWizardModal.test.tsx

@@ -61,6 +61,8 @@ const T = {
   language: 'Language', languageHelp: '', creativity: 'Creativity',
   creativityFocused: 'Focused', creativityCreative: 'Creative',
   maxLength: 'Max length', maxLengthHelp: '', maxLengthCeiling: 'Limited to {{maxOutputTokens}} by {{model}}.',
+  outputFormat: 'Format',
+  formatExtensionMismatch: 'Save location must end in {{extension}} to match the selected format.',
   maxResults: 'Max Results', semanticScoring: 'Semantic Scoring', semanticScoringHelp: '',
   searchFailed: 'Search failed',
   contentLabel: 'Content', entityTypes: 'Entity types',
@@ -589,15 +591,37 @@ describe('ReferenceWizardModal — the three strategies complete', () => {
   it('generation submits the step\'s config against this annotation, then closes', async () => {
     const { onGenerateSubmit, onClose } = renderWizard();
     await userEvent.click(screen.getByRole('button', { name: `✨ ${T.generate}…` }));
-    await userEvent.type(screen.getByLabelText(/Save location/i), 'generated/out.md');
+    // The field arrives PRE-FILLED with the proposal now (D11). Overriding it
+    // is select-all-then-type, which the DOM delivers as ONE change carrying
+    // the replacement — `clear()` then `type()` would instead empty the field
+    // (restoring the proposal, by design) and append to it.
+    fireEvent.change(screen.getByLabelText(/Save location/i), {
+      target: { value: 'generated/out.md' },
+    });
     await userEvent.click(screen.getByRole('button', { name: T.generate }));
 
     expect(onGenerateSubmit).toHaveBeenCalledTimes(1);
     expect(onGenerateSubmit.mock.calls[0]![0]).toBe('ann-1');
     expect(onGenerateSubmit.mock.calls[0]![1].title).toBe('Caspian Sea');
+    // D8/D2: the payload names the URI what it is, and carries the default
+    // format explicitly rather than leaving the worker to assume it.
+    expect(onGenerateSubmit.mock.calls[0]![1]).toMatchObject({
+      storageUri: 'file://generated/out.md',
+      outputMediaType: 'text/markdown',
+    });
     expect(onClose).toHaveBeenCalledTimes(1);
   });
 
+  it('the annotation flow can choose a format too — one control, both hosts (D4)', async () => {
+    const { onGenerateSubmit } = renderWizard();
+    await userEvent.click(screen.getByRole('button', { name: `✨ ${T.generate}…` }));
+    await userEvent.type(screen.getByLabelText(/Save location/i), 'generated/out.pdf');
+    fireEvent.change(screen.getByLabelText(T.outputFormat), { target: { value: 'application/pdf' } });
+    await userEvent.click(screen.getByRole('button', { name: T.generate }));
+
+    expect(onGenerateSubmit.mock.calls[0]![1]).toMatchObject({ outputMediaType: 'application/pdf' });
+  });
+
   it('retreats from a configure step back to the gather step', async () => {
     renderWizard();
     await userEvent.click(screen.getByRole('button', { name: `✨ ${T.generate}…` }));

package/src/components/modals/__tests__/ResourceGenerateModal.test.tsx

@@ -60,6 +60,8 @@ const T = {
   maxLength: 'Max Length',
   maxLengthHelp: 'Max help',
   maxLengthCeiling: 'Limited to {{maxOutputTokens}} tokens by {{model}}.',
+  outputFormat: 'Format',
+  formatExtensionMismatch: 'Save location must end in {{extension}} to match the selected format.',
   generate: 'Generate',
   discardDraftPrompt: 'Discard this draft?',
   discardDraft: 'Discard',
@@ -214,13 +216,34 @@ describe('ResourceGenerateModal', () => {
       'res-1',
       expect.objectContaining({
         title: 'Generated Doc',
-        storagePath: 'file://generated/out.md',
+        // D8: the submitted payload names this what it IS — a full storage
+        // URI, built here by prefixing `file://`. It was called `storagePath`
+        // while holding a URI, which is why the page handlers had to rename
+        // it field-by-field on the way out.
+        storageUri: 'file://generated/out.md',
+        // D2: the default is sent, not inherited from the worker.
+        outputMediaType: 'text/markdown',
         context: RESOURCE_CONTEXT,
       }),
     );
     expect(onClose).toHaveBeenCalled();
   });
 
+  it('a chosen output format survives the host to onGenerateSubmit', () => {
+    renderModal({ gatherContext: RESOURCE_CONTEXT });
+    fireEvent.click(screen.getByRole('button', { name: /Gather/ }));
+
+    fireEvent.change(screen.getByLabelText(T.resourceTitle), { target: { value: 'Generated Doc' } });
+    fireEvent.change(screen.getByLabelText(T.saveLocation), { target: { value: 'generated/out.pdf' } });
+    fireEvent.change(screen.getByLabelText(T.outputFormat), { target: { value: 'application/pdf' } });
+    fireEvent.click(screen.getByRole('button', { name: /Generate/ }));
+
+    expect(onGenerateSubmit).toHaveBeenCalledWith(
+      'res-1',
+      expect.objectContaining({ outputMediaType: 'application/pdf', storageUri: 'file://generated/out.pdf' }),
+    );
+  });
+
   it('a failed gather shows its failure in place', () => {
     // The props are the state unit's slots verbatim; the modal renders them
     // without owning them (FLC A6).

package/src/components/modals/__tests__/WizardFooter.test.tsx

@@ -14,7 +14,7 @@ import userEvent from '@testing-library/user-event';
 import '@testing-library/jest-dom';
 import { WizardFooter } from '../WizardFooter';
 import { ConfigureSearchStep } from '../ConfigureSearchStep';
-import { ConfigureGenerationStep } from '../ConfigureGenerationStep';
+import { ConfigureGenerationStep, freshGenerationDraft } from '../ConfigureGenerationStep';
 import { SearchResultsStep } from '../SearchResultsStep';
 import { ConfigureGatherStep } from '../ConfigureGatherStep';
 import { GatherContextStep } from '../GatherContextStep';
@@ -116,6 +116,7 @@ const GEN_T = {
   additionalInstructionsPlaceholder: '', language: 'Language', languageHelp: '',
   creativity: 'Creativity', creativityFocused: 'Focused', creativityCreative: 'Creative',
   maxLength: 'Max Length', maxLengthHelp: '', maxLengthCeiling: 'Limited to {{max}} by {{model}}.',
+  outputFormat: 'Format', formatExtensionMismatch: 'Must end in {{extension}}.',
   back: 'Back', generate: 'Generate',
 };
 
@@ -173,10 +174,7 @@ describe('every step footer follows the grammar (A1, A2)', () => {
     const { container } = render(
       <ConfigureGenerationStep
         context={CONTEXT}
-        config={{
-          title: 'Caspian Sea', storagePath: '', prompt: '', language: 'en',
-          temperature: 0.7, maxTokensText: '500',
-        }}
+        config={freshGenerationDraft('Caspian Sea', 'en')}
         onConfigChange={vi.fn()}
         onBack={vi.fn()}
         onGenerate={vi.fn()}

package/src/components/resource/BrowseView.tsx

@@ -12,7 +12,7 @@ import type { AnnotationsCollection } from '../../types/annotation-props';
 import {
   buildSourceToRenderedMap,
   buildTextNodeIndex,
-  resolveAnnotationRanges,
+  resolveAnnotationSpans,
   applyHighlights,
   clearHighlights,
   toOverlayAnnotations,
@@ -122,8 +122,8 @@ export const BrowseView = memo(function BrowseView({
     const container = containerRef.current;
     const offsetMap = buildSourceToRenderedMap(content, container);
     const textNodeIndex = buildTextNodeIndex(container);
-    const ranges = resolveAnnotationRanges(overlayAnnotations, offsetMap, textNodeIndex);
-    applyHighlights(ranges);
+    const spans = resolveAnnotationSpans(overlayAnnotations, offsetMap);
+    applyHighlights(spans, textNodeIndex);
 
     return () => clearHighlights(container);
   }, [content, overlayAnnotations]);

package/src/components/resource/DownloadFileLink.tsx

@@ -8,7 +8,7 @@ import { mediaUrl } from '../../lib/media-url';
 interface Props {
   /** The '@id' of the resource whose bytes to offer. */
   resourceUri: string;
-  /** Session for that resource — its client mints the media token and supplies the backend origin. */
+  /** Session for that resource — its client mints the media token and supplies the gateway origin. */
   session: SemiontSession | null;
 }
 

package/src/components/resource/__tests__/BrowseView.reference-hover.test.tsx

@@ -28,7 +28,7 @@ vi.mock('remark-gfm', () => ({ default: () => ({}) }));
 vi.mock('../../../lib/annotation-overlay', () => ({
   buildSourceToRenderedMap: vi.fn(() => new Map()),
   buildTextNodeIndex: vi.fn(() => []),
-  resolveAnnotationRanges: vi.fn(() => new Map()),
+  resolveAnnotationSpans: vi.fn(() => []),
   applyHighlights: vi.fn(),
   clearHighlights: vi.fn(),
   toOverlayAnnotations: vi.fn(() => []),

package/src/components/resource/__tests__/BrowseView.test.tsx

@@ -39,11 +39,11 @@ vi.mock('remark-gfm', () => ({
   default: vi.fn(),
 }));
 
-// Mock annotation-overlay — DOM Range API is not available in jsdom
+// Mock annotation-overlay — these tests exercise BrowseView wiring, not the overlay
 vi.mock('../../../lib/annotation-overlay', () => ({
   buildSourceToRenderedMap: vi.fn(() => new Map()),
   buildTextNodeIndex: vi.fn(() => []),
-  resolveAnnotationRanges: vi.fn(() => new Map()),
+  resolveAnnotationSpans: vi.fn(() => []),
   applyHighlights: vi.fn(),
   clearHighlights: vi.fn(),
   toOverlayAnnotations: vi.fn(() => []),

package/src/components/resource/__tests__/download-link.test.tsx

@@ -8,7 +8,7 @@
  * so the alias takes bearer + `?token=` only. Both views shipped a bare
  * `/api/resources/${id}` — tokenless, so a 401, AND relative, so under
  * bring-your-own-session embedding it resolves against the HOST app's origin
- * rather than the backend's.
+ * rather than the gateway's.
  *
  * Started RED (both hrefs were `/api/resources/res-1`).
  */
@@ -26,7 +26,7 @@ vi.mock('../../image-annotation/SvgDrawingCanvas', () => ({ SvgDrawingCanvas: ()
 vi.mock('react-markdown', () => ({ default: ({ children }: { children: string }) => <div>{children}</div> }));
 vi.mock('remark-gfm', () => ({ default: () => ({}) }));
 
-const BACKEND = 'http://backend.test:4000';
+const GATEWAY = 'http://gateway.test:4000';
 const UNSUPPORTED = 'application/octet-stream';
 
 const emptyAnnotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
@@ -50,7 +50,7 @@ function sessionPending(): SemiontSession {
 
 /**
  * A transport-only client: `SemiontClient.auth` is `AuthNamespace | undefined`,
- * and a host wiring a bare transport (no `IBackendOperations`) has no `auth`.
+ * and a host wiring a bare transport (no `IGatewayOperations`) has no `auth`.
  */
 function sessionWithoutAuth(): SemiontSession {
   return fakeSession({});
@@ -59,7 +59,7 @@ function sessionWithoutAuth(): SemiontSession {
 function fakeSession(clientExtras: Record<string, unknown>): SemiontSession {
   return {
     client: {
-      baseUrl: BACKEND,
+      baseUrl: GATEWAY,
       mark: { request: vi.fn() },
       browse: { click: vi.fn() },
       beckon: { hover: vi.fn() },
@@ -94,11 +94,11 @@ const VIEWS = [
 ] as const;
 
 describe.each(VIEWS)('$name — unsupported-media download link', ({ render: renderView }) => {
-  it('points at the backend origin and carries the media token', async () => {
+  it('points at the gateway origin and carries the media token', async () => {
     renderView(sessionMinting('tok-abc'));
 
     const link = await screen.findByRole('link', { name: 'Download File' });
-    expect(link).toHaveAttribute('href', `${BACKEND}/api/resources/res-1?token=tok-abc`);
+    expect(link).toHaveAttribute('href', `${GATEWAY}/api/resources/res-1?token=tok-abc`);
     expect(link).toHaveAttribute('download');
   });
 

package/src/components/resource/panels/ReferenceEntry.tsx

@@ -11,7 +11,7 @@ import type { SemiontSession } from '@semiont/sdk';
 import { renderAgentLabel } from './agent-label';
 import { useHoverEmitter } from '../../../hooks/useHoverEmitter';
 
-// Extended annotation type with runtime properties added by backend enrichment
+// Extended annotation type with runtime properties added by gateway enrichment
 interface EnrichedAnnotation extends Annotation {
   _resolvedDocumentName?: string;
   _resolvedDocumentMediaType?: string;
@@ -58,7 +58,7 @@ export function ReferenceEntry({
   const hasSvgSelector = getSvgSelector(selector);
   const annotationType = hasFragmentSelector ? 'Fragment annotation' : hasSvgSelector ? 'Image annotation' : 'Annotation';
 
-  // Extract resolved document name and media type if enriched by backend
+  // Extract resolved document name and media type if enriched by gateway
   const enrichedReference = reference as EnrichedAnnotation;
   const resolvedDocumentName = enrichedReference._resolvedDocumentName;
   const resolvedDocumentMediaType = enrichedReference._resolvedDocumentMediaType;

package/src/components/resource/panels/ReferencesPanel.tsx

@@ -279,7 +279,11 @@ export function ReferencesPanel({
         source: resourceId,
         motivation: 'linking',
         selector: pendingAnnotation.selector,
-        body: entityType ? [{ type: 'TextualBody', value: entityType, purpose: 'tagging' }] : [],
+        // Entity types are optional, and MarkSubmitEvent.body is minItems:1 —
+        // an empty array is a 400, not an empty annotation.
+        ...(entityType
+          ? { body: [{ type: 'TextualBody' as const, value: entityType, purpose: 'tagging' as const }] }
+          : {}),
       });
       setPendingEntityTypes([]);
     }

package/src/components/resource/panels/__tests__/ReferencesPanel.observable-flow.test.tsx

@@ -3,7 +3,7 @@
  *
  * Written after an e2e failure (test 05) where `ReferencesPanel` rendered
  * "No entity types available" even though the client provably received a
- * 9-string entity-types array from the backend.
+ * 9-string entity-types array from the gateway.
  *
  * This test closes the Layer 5-6 gap: the existing `ResourceViewerPage.test.tsx`
  * stubs `UnifiedAnnotationsPanel`/`ReferencesPanel` as `<div data-testid>`s,

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

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import React from 'react';
-import { render, screen, waitFor } from '@testing-library/react';
+import { render, screen, waitFor, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import '@testing-library/jest-dom';
 import { ReferencesPanel } from '../ReferencesPanel';
@@ -20,7 +20,7 @@ function createEventTracker() {
     events,
     clear: () => { events.length = 0; },
     _attach(eventBus: EventBus) {
-      const panelEvents = ['mark:assist-request'] as const;
+      const panelEvents = ['mark:assist-request', 'mark:submit'] as const;
       panelEvents.forEach((eventName) => {
         eventBus.get(eventName).subscribe((payload: any) => {
           events.push({ event: eventName, payload });
@@ -66,6 +66,7 @@ vi.mock('../../../../contexts/TranslationContext', () => ({
       includeDescriptiveReferences: 'Include descriptive references',
       descriptiveReferencesTooltip: 'Also find phrases like \'the CEO\', \'the tech giant\', \'the physicist\' (in addition to names)',
       cancel: 'Cancel',
+      createReference: 'Create Reference',
       annotating: 'Annotating...',
       // CLEAN-PROGRESS D3: the widget's own strings come from the
       // AssistProgress namespace now, not from this panel's.
@@ -179,6 +180,54 @@ describe('ReferencesPanel Component', () => {
     });
   });
 
+  // Entity types are optional on a reference, but `MarkSubmitEvent.body` is
+  // `minItems: 1` — so "no types selected" must OMIT body, not send `[]`.
+  // Sending `[]` 400s at /bus/emit, and `mark.submit` is fire-and-forget, so
+  // the failure is silent: the button looks inert. Found live 2026-08-24.
+  describe('Create Reference payload', () => {
+    const pendingLinking = {
+      motivation: 'linking' as const,
+      selector: { type: 'TextQuoteSelector' as const, exact: 'thylakoid' },
+    };
+
+    const submitPayloads = (tracker: ReturnType<typeof createEventTracker>) =>
+      tracker.events.filter(e => e.event === 'mark:submit').map(e => e.payload);
+
+    // The panel's own entity-type chips, not AssistSection's identically
+    // labelled ones.
+    const renderPrompt = (tracker: ReturnType<typeof createEventTracker>) => {
+      const { container } = renderWithEventBus(
+        <ReferencesPanel {...panelProps()} pendingAnnotation={pendingLinking} />,
+        tracker,
+      );
+      return within(container.querySelector('.semiont-annotation-prompt') as HTMLElement);
+    };
+
+    it('omits body entirely when no entity type is selected', async () => {
+      const tracker = createEventTracker();
+      const prompt = renderPrompt(tracker);
+
+      await userEvent.click(prompt.getByRole('button', { name: /create reference/i }));
+
+      const [payload] = submitPayloads(tracker);
+      expect(payload).toBeDefined();
+      expect(payload).not.toHaveProperty('body');
+    });
+
+    it('sends a one-item body when an entity type is selected', async () => {
+      const tracker = createEventTracker();
+      const prompt = renderPrompt(tracker);
+
+      await userEvent.click(prompt.getByRole('button', { name: 'Person' }));
+      await userEvent.click(prompt.getByRole('button', { name: /create reference/i }));
+
+      const [payload] = submitPayloads(tracker);
+      expect(payload.body).toEqual([
+        { type: 'TextualBody', value: 'Person', purpose: 'tagging' },
+      ]);
+    });
+  });
+
   describe('Entity Type Selection', () => {
     it('should toggle entity type selection on click', async () => {
       renderWithEventBus(<ReferencesPanel {...panelProps()} />);

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

@@ -73,7 +73,7 @@ function createEventTracker() {
       eventBus.get('yield:clone').subscribe((payload: any) => {
         events.push({ event: 'yield:clone', payload });
       });
-      // `mark:archive` / `mark:unarchive` are backend-routed via `actor.emit`;
+      // `mark:archive` / `mark:unarchive` are gateway-routed via `actor.emit`;
       // spy on the namespace methods instead of subscribing to a local bus.
       const origArchive = client.mark.archive.bind(client.mark);
       const origUnarchive = client.mark.unarchive.bind(client.mark);