@semiont/react-ui 0.5.27 → 0.5.29

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

@@ -0,0 +1,152 @@
+/**
+ * COMPOSE-IN-MODAL P1 — the compose strategy's form, as a pure step.
+ *
+ * The from-reference slice of the compose page, lifted: name, save location,
+ * entity types (read-only tags when the reference fixed them, picker
+ * otherwise), language, and the editor. Deliberately NONE of the page's
+ * upload/format/encoding machinery — the fences reference mode already
+ * proved are here as absence pins. The draft is CONTROLLED by the host
+ * (WIZARD-NAVIGATION D3: stepping Back must not discard typed work), and
+ * the evidence display is the host's job (plan A3: no context redux here).
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { ComposeStep, type ComposeDraft } from '../ComposeStep';
+
+// Mock CodeMirrorRenderer to avoid CodeMirror dependencies (same mock the
+// compose page's own tests use).
+vi.mock('../../CodeMirrorRenderer', () => ({
+  CodeMirrorRenderer: ({ content, onChange, editable }: any) => (
+    <textarea
+      data-testid="code-editor"
+      value={content}
+      disabled={!editable}
+      onChange={(e) => onChange?.(e.target.value)}
+    />
+  ),
+}));
+
+const T = {
+  resourceTitle: 'New resource title',
+  resourceTitlePlaceholder: 'Title…',
+  saveLocation: 'Save location',
+  entityTypes: 'Entity types',
+  language: 'Language',
+  contentLabel: 'Content',
+  back: 'Back',
+  createAndLink: 'Create & Link',
+  creatingAndLinking: 'Creating…',
+};
+
+const DRAFT: ComposeDraft = {
+  name: 'Black Hawk',
+  storagePath: 'people/black-hawk.md',
+  content: 'Sauk leader.',
+  entityTypes: [],
+  language: 'en',
+};
+
+function renderStep(over: Partial<React.ComponentProps<typeof ComposeStep>> = {}) {
+  const onDraftChange = vi.fn();
+  const onBack = vi.fn();
+  const onCompose = vi.fn<(p: unknown) => Promise<void>>().mockResolvedValue(undefined);
+  const utils = render(
+    <ComposeStep
+      draft={DRAFT}
+      onDraftChange={onDraftChange}
+      referenceEntityTypes={['Person']}
+      entityTypeOptions={['Person', 'Topic', 'Location']}
+      showLineNumbers={false}
+      hoverDelayMs={300}
+      onBack={onBack}
+      onCompose={onCompose}
+      translations={T}
+      {...over}
+    />,
+  );
+  return { ...utils, onDraftChange, onBack, onCompose };
+}
+
+describe('ComposeStep — the from-reference slice, and nothing else', () => {
+  it('renders the draft: name, save location, content, language', () => {
+    renderStep();
+    expect(screen.getByLabelText(T.resourceTitle)).toHaveValue('Black Hawk');
+    expect(screen.getByLabelText(T.saveLocation)).toHaveValue('people/black-hawk.md');
+    expect(screen.getByTestId('code-editor')).toHaveValue('Sauk leader.');
+    expect(screen.getByLabelText(T.language)).toBeInTheDocument();
+  });
+
+  it('edits flow through onDraftChange — the host owns the draft (D3)', () => {
+    const { onDraftChange } = renderStep();
+    fireEvent.change(screen.getByLabelText(T.resourceTitle), { target: { value: 'Black Hawk (Sauk)' } });
+    expect(onDraftChange).toHaveBeenCalledWith({ name: 'Black Hawk (Sauk)' });
+    fireEvent.change(screen.getByTestId('code-editor'), { target: { value: 'A Sauk leader.' } });
+    expect(onDraftChange).toHaveBeenCalledWith({ content: 'A Sauk leader.' });
+  });
+
+  it('reference-fixed entity types render as read-only tags, not a picker (D6)', () => {
+    renderStep(); // referenceEntityTypes: ['Person']
+    expect(screen.getByText('Person')).toBeInTheDocument();
+    // No toggling: the types were chosen when the reference was created.
+    expect(screen.queryByRole('button', { name: /Person/ })).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: /Topic/ })).not.toBeInTheDocument();
+  });
+
+  it('an empty reference set falls back to the picker over the owner-supplied options (D6)', () => {
+    const { onDraftChange } = renderStep({ referenceEntityTypes: [] });
+    const topic = screen.getByRole('button', { name: /Topic/ });
+    fireEvent.click(topic);
+    expect(onDraftChange).toHaveBeenCalledWith({ entityTypes: ['Topic'] });
+  });
+
+  it('carries NONE of the page-only machinery: no upload, no format, no encoding', () => {
+    const { container } = renderStep();
+    expect(container.querySelector('.semiont-form__upload-dropzone')).toBeNull();
+    expect(container.querySelector('.semiont-form__content-source-toggle')).toBeNull();
+    expect(container.querySelector('#format-select')).toBeNull();
+    expect(container.querySelector('#charset-select')).toBeNull();
+  });
+
+  it('renders no context of its own — the evidence is host-stacked (A3)', () => {
+    const { container } = renderStep();
+    expect(container.querySelector('.semiont-gather-pane')).toBeNull();
+    expect(container.querySelector('.semiont-gather__outer')).toBeNull();
+  });
+
+  it('submit emits the full params with the file:// prefix applied at the seam', async () => {
+    const { onCompose } = renderStep({ referenceEntityTypes: ['Person'] });
+    fireEvent.click(screen.getByRole('button', { name: T.createAndLink }));
+    await waitFor(() => expect(onCompose).toHaveBeenCalledTimes(1));
+    expect(onCompose).toHaveBeenCalledWith({
+      name: 'Black Hawk',
+      storagePath: 'file://people/black-hawk.md',
+      content: 'Sauk leader.',
+      entityTypes: ['Person'],
+      language: 'en',
+    });
+  });
+
+  it('the footer is a wizard footer: Back + Create, pending while in flight, re-enabled on rejection (A4)', async () => {
+    let reject!: (e: Error) => void;
+    const onCompose = vi.fn(() => new Promise<void>((_, r) => { reject = r; }));
+    const { container } = renderStep({ onCompose });
+
+    expect(container.querySelector('.semiont-modal__actions--wizard')).not.toBeNull();
+    fireEvent.click(screen.getByRole('button', { name: T.createAndLink }));
+    expect(await screen.findByRole('button', { name: T.creatingAndLinking })).toBeDisabled();
+
+    reject(new Error('boom'));
+    expect(await screen.findByRole('button', { name: T.createAndLink })).toBeEnabled();
+  });
+
+  it('Back is the only retreat and dismissal never lives in the footer (A4)', () => {
+    const { container, onBack } = renderStep();
+    const footerButtons = Array.from(
+      container.querySelectorAll('.semiont-modal__actions button'),
+    ).map((b) => b.textContent ?? '');
+    expect(footerButtons.filter((l) => /cancel|✕/i.test(l))).toEqual([]);
+    fireEvent.click(screen.getByRole('button', { name: `◀ ${T.back}` }));
+    expect(onBack).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -16,13 +16,12 @@ const t = {
   includeSummary: 'Include summary',
   depth: 'Depth',
   maxResources: 'Max resources',
-  cancel: 'Cancel',
   gather: 'Gather',
 };
 
 describe('ConfigureGatherStep', () => {
   it('renders the intro and the default option values', () => {
-    render(<ConfigureGatherStep onGather={vi.fn()} onCancel={vi.fn()} translations={t} />);
+    render(<ConfigureGatherStep onGather={vi.fn()} translations={t} />);
     expect(screen.getByText('Choose what to include.')).toBeInTheDocument();
     expect(screen.getByLabelText('Include content')).toBeChecked();
     expect(screen.getByLabelText('Include summary')).toBeChecked();
@@ -32,14 +31,14 @@ describe('ConfigureGatherStep', () => {
 
   it('emits the default config on submit', () => {
     const onGather = vi.fn();
-    render(<ConfigureGatherStep onGather={onGather} onCancel={vi.fn()} translations={t} />);
+    render(<ConfigureGatherStep onGather={onGather} translations={t} />);
     fireEvent.click(screen.getByRole('button', { name: /Gather/ }));
     expect(onGather).toHaveBeenCalledWith({ includeContent: true, includeSummary: true, depth: 2, maxResources: 10 });
   });
 
   it('reflects edits in the emitted config', () => {
     const onGather = vi.fn();
-    render(<ConfigureGatherStep onGather={onGather} onCancel={vi.fn()} translations={t} />);
+    render(<ConfigureGatherStep onGather={onGather} translations={t} />);
     fireEvent.click(screen.getByLabelText('Include content')); // uncheck
     fireEvent.click(screen.getByLabelText('Include summary')); // uncheck
     fireEvent.change(screen.getByLabelText('Depth'), { target: { value: '4' } });
@@ -48,32 +47,21 @@ describe('ConfigureGatherStep', () => {
     expect(onGather).toHaveBeenCalledWith({ includeContent: false, includeSummary: false, depth: 4, maxResources: 25 });
   });
 
-  it('honors the defaults prop', () => {
-    const onGather = vi.fn();
-    render(
-      <ConfigureGatherStep
-        defaults={{ includeSummary: false, depth: 1, maxResources: 5 }}
-        onGather={onGather}
-        onCancel={vi.fn()}
-        translations={t}
-      />,
-    );
-    expect(screen.getByLabelText('Include summary')).not.toBeChecked();
-    expect(screen.getByLabelText('Depth')).toHaveValue(1);
-    fireEvent.click(screen.getByRole('button', { name: /Gather/ }));
-    expect(onGather).toHaveBeenCalledWith({ includeContent: true, includeSummary: false, depth: 1, maxResources: 5 });
-  });
-
-  it('calls onCancel from the cancel button', () => {
-    const onCancel = vi.fn();
-    render(<ConfigureGatherStep onGather={vi.fn()} onCancel={onCancel} translations={t} />);
-    fireEvent.click(screen.getByRole('button', { name: /Cancel/ }));
-    expect(onCancel).toHaveBeenCalledTimes(1);
+  it('the footer is the wizard footer: advance only, no dismissal, no flex (GFR A5)', () => {
+    // Dismissal lives on the modal's corner ✕/Esc/backdrop, never in a step
+    // footer (WIZARD-NAVIGATION D1); this is the first step, so no retreat either.
+    const { container } = render(<ConfigureGatherStep onGather={vi.fn()} translations={t} />);
+    const footer = container.querySelector('.semiont-modal__actions--wizard');
+    expect(footer).not.toBeNull();
+    const buttons = Array.from(footer!.querySelectorAll('button'));
+    expect(buttons).toHaveLength(1);
+    expect(buttons[0]!.textContent).not.toMatch(/cancel|✕/i);
+    expect(buttons[0]!.className).not.toContain('semiont-button--flex');
   });
 
   it('renders the children slot (exclusion picker)', () => {
     render(
-      <ConfigureGatherStep onGather={vi.fn()} onCancel={vi.fn()} translations={t}>
+      <ConfigureGatherStep onGather={vi.fn()} translations={t}>
         <div>EXCLUDE-SLOT</div>
       </ConfigureGatherStep>,
     );

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

@@ -12,11 +12,14 @@ 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',
   resourceTitlePlaceholder: 'Title…',
+  saveLocation: 'Save location',
   additionalInstructions: 'Instructions',
   additionalInstructionsPlaceholder: 'Instructions…',
   language: 'Language',
@@ -28,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',
 };
@@ -35,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 =>
   ({
@@ -58,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}
@@ -75,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 } };
 }
@@ -96,6 +104,17 @@ describe('ConfigureGenerationStep — ceiling awareness', () => {
     expect(screen.getByText(/Limited to 64000 tokens by claude-sonnet-5\./)).toBeInTheDocument();
   });
 
+  it('the ceiling sentence is a row-level footnote, never a column child', () => {
+    // A full sentence inside the 5.5rem Max Length column wraps one word per
+    // line and its height taxes the whole flex row — the void under the other
+    // controls IS this caption. It renders full-width under the row instead.
+    renderStep(agentWithCeiling(64_000));
+
+    const help = screen.getByText(/Limited to 64000 tokens/);
+    expect(help).toHaveClass('semiont-form__help--row');
+    expect(help.closest('.semiont-form__field--narrow')).toBeNull();
+  });
+
   it('will not commit a value above the ceiling', () => {
     // `max` on a number input does not prevent TYPING an over-value — it only
     // marks the field invalid. D6 says the value cannot be entered, so assert
@@ -253,3 +272,182 @@ describe('ConfigureGenerationStep — the draft is the owner\'s', () => {
     expect(props.onGenerate.mock.calls[0]![0]).not.toHaveProperty('prompt');
   });
 });
+
+// ── 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(
+      <ConfigureGenerationStep
+        context={context} config={DRAFT} onConfigChange={vi.fn()}
+        onBack={vi.fn()} onGenerate={vi.fn()} translations={translations}
+        hintEcho={{ label: 'Hint', value: 'the ancient city, not the modern province' }}
+      />,
+    );
+    const echo = container.querySelector('.semiont-wizard__hint-echo');
+    expect(echo).not.toBeNull();
+    expect(echo!.textContent).toContain('the ancient city, not the modern province');
+
+    rerender(
+      <ConfigureGenerationStep
+        context={context} config={DRAFT} onConfigChange={vi.fn()}
+        onBack={vi.fn()} onGenerate={vi.fn()} translations={translations}
+      />,
+    );
+    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__/ConfigureSearchStep.test.tsx

@@ -16,7 +16,7 @@ import { ConfigureSearchStep, type SearchConfig } from '../ConfigureSearchStep';
 const T = {
   maxResults: 'Max Results', semanticScoring: 'Semantic Scoring',
   semanticScoringHelp: 'Use AI to score results by semantic relevance',
-  back: 'Back', search: 'Search', searching: 'Searching…',
+  back: 'Back', search: 'Search', searching: 'Searching…', searchFailed: 'Search failed',
 };
 
 const CONFIG: SearchConfig = { limit: 10, useSemanticScoring: true };
@@ -50,6 +50,29 @@ describe('ConfigureSearchStep', () => {
     expect(onConfigChange).toHaveBeenCalledWith({ limit: 10, useSemanticScoring: false });
   });
 
+  it('echoes the hint being steered by, and stays silent without one (GEP P1c, D8)', () => {
+    // The thing the hint steers goes invisible behind the step transition —
+    // one quiet line keeps it visible and advertises that the hint did something.
+    const { container, rerender } = render(
+      <ConfigureSearchStep
+        config={CONFIG} onConfigChange={vi.fn()} onBack={vi.fn()} onSearch={vi.fn()}
+        translations={T}
+        hintEcho={{ label: 'Hint', value: 'the ancient city, not the modern province' }}
+      />,
+    );
+    const echo = container.querySelector('.semiont-wizard__hint-echo');
+    expect(echo).not.toBeNull();
+    expect(echo!.textContent).toContain('the ancient city, not the modern province');
+
+    rerender(
+      <ConfigureSearchStep
+        config={CONFIG} onConfigChange={vi.fn()} onBack={vi.fn()} onSearch={vi.fn()}
+        translations={T}
+      />,
+    );
+    expect(container.querySelector('.semiont-wizard__hint-echo')).toBeNull();
+  });
+
   it('submits whatever the owner currently holds, not a default', async () => {
     // The point of controlled state: a step that kept its own copy could submit
     // something the wizard never saw.