@semiont/react-ui 0.5.27 → 0.5.28

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

@@ -16,6 +16,8 @@ import { WizardFooter } from '../WizardFooter';
 import { ConfigureSearchStep } from '../ConfigureSearchStep';
 import { ConfigureGenerationStep } from '../ConfigureGenerationStep';
 import { SearchResultsStep } from '../SearchResultsStep';
+import { ConfigureGatherStep } from '../ConfigureGatherStep';
+import { GatherContextStep } from '../GatherContextStep';
 import type { GatheredContext } from '@semiont/core';
 
 /** Anything that reads as "get me out of here" belongs in the corner, not the footer. */
@@ -78,6 +80,25 @@ describe('WizardFooter', () => {
     await userEvent.click(screen.getByText(/Back/));
     expect(onBack).not.toHaveBeenCalled();
   });
+
+  it('a disabled primary is not clickable, but Back stays live', async () => {
+    // `disabled` is the action's PRECONDITION loading (review step waiting on
+    // gather) — distinct from `pending`, which is the action itself running and
+    // rightly freezes retreat too. While a precondition loads, retreat must work.
+    const onBack = vi.fn();
+    const onAdvance = vi.fn();
+    render(
+      <WizardFooter
+        backLabel="Back"
+        onBack={onBack}
+        primary={{ label: 'Next', type: 'button', onClick: onAdvance, disabled: true }}
+      />,
+    );
+    await userEvent.click(screen.getByText(/Next/));
+    expect(onAdvance).not.toHaveBeenCalled();
+    await userEvent.click(screen.getByText(/Back/));
+    expect(onBack).toHaveBeenCalledTimes(1);
+  });
 });
 
 // ─────────────────────────────────────────────────────────────────────
@@ -87,10 +108,11 @@ describe('WizardFooter', () => {
 const SEARCH_T = {
   maxResults: 'Max Results', semanticScoring: 'Semantic Scoring',
   semanticScoringHelp: 'help', back: 'Back', search: 'Search', searching: 'Searching…',
+  searchFailed: 'Search failed',
 };
 
 const GEN_T = {
-  resourceTitle: 'Title', resourceTitlePlaceholder: '', additionalInstructions: 'Instructions',
+  resourceTitle: 'Title', resourceTitlePlaceholder: '', saveLocation: 'Save location', additionalInstructions: 'Instructions',
   additionalInstructionsPlaceholder: '', language: 'Language', languageHelp: '',
   creativity: 'Creativity', creativityFocused: 'Focused', creativityCreative: 'Creative',
   maxLength: 'Max Length', maxLengthHelp: '', maxLengthCeiling: 'Limited to {{max}} by {{model}}.',
@@ -99,13 +121,18 @@ const GEN_T = {
 
 const CONTEXT_T = {
   sourceContextLabel: 'Source', connectionsLabel: 'Connections', citedByLabel: 'Cited by',
-  userHintLabel: 'Hint', userHintPlaceholder: '',
+  graphPaneTitle: 'In the graph', graphEmpty: 'No links yet.', resourceLinkLabel: 'Resource link',
+};
+
+const GATHER_T = {
+  intro: 'Choose what to include.', includeContent: 'Content', includeSummary: 'Summary',
+  depth: 'Depth', maxResources: 'Max', gather: 'Gather',
 };
 
 const RESULTS_T = { noResults: 'None', score: 'Score', link: 'Link', back: 'Back', ...CONTEXT_T };
 
 const CONTEXT = {
-  focus: { kind: 'annotation', annotation: { id: 'a1' }, sourceResource: { id: 'r1', name: 'Src' } },
+  focus: { kind: 'annotation', annotation: { id: 'a1' }, sourceResource: { '@id': 'r1', name: 'Src' } },
   // `graph` is not optional in practice: ContextSummary hands it straight to
   // `deriveViews`, which dereferences `.nodes`.
   graph: { nodes: [], edges: [] },
@@ -130,7 +157,6 @@ describe('every step footer follows the grammar (A1, A2)', () => {
   it('SearchResultsStep — footer is retreat only; Link lives on the rows', () => {
     const { container } = render(
       <SearchResultsStep
-        context={CONTEXT}
         results={[{ id: 'r1', name: 'Black Sea', score: 54.22 } as never]}
         onBack={vi.fn()}
         onLink={vi.fn()}
@@ -161,6 +187,89 @@ describe('every step footer follows the grammar (A1, A2)', () => {
     expect(labels).toHaveLength(2);
     expect(labels.filter((l) => DISMISSAL.test(l))).toEqual([]);
   });
+
+  it('ConfigureGatherStep — first step of the resource-generate flow: advance only (GFR A5)', () => {
+    const { container } = render(
+      <ConfigureGatherStep onGather={vi.fn()} translations={GATHER_T} />,
+    );
+    const labels = buttonsIn(footerOf(container)!).map((b) => b.textContent ?? '');
+    expect(labels).toHaveLength(1); // nowhere to go back to, and dismissal is the corner's job
+    expect(labels.filter((l) => DISMISSAL.test(l))).toEqual([]);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// The THIRD footer species: the resolution CHOOSER. The one deliberate
+// exception to the WizardFooter grammar — a three-way fork the
+// one-retreat-plus-one-advance component cannot express. Its grammar is
+// its own, and this pin is what keeps it a species instead of drift.
+// ─────────────────────────────────────────────────────────────────────
+describe('the resolution chooser (GatherContextStep) — the named exception', () => {
+  const ANNOTATE = {
+    userHint: '',
+    onUserHintChange: vi.fn(),
+    onBind: vi.fn(),
+    onGenerate: vi.fn(),
+    onCompose: vi.fn(),
+    translations: {
+      search: 'Search', generate: 'Generate', compose: 'Compose',
+      resolutionStrategyLabel: 'Strategy', userHintLabel: 'Hint',
+      userHintEffect: 'steers Search and Generate', userHintPlaceholder: '',
+    },
+  };
+  const DISPLAY_T = {
+    loadingContext: 'Loading…', failedContext: 'Failed', ...CONTEXT_T,
+    corpusPaneTitle: 'In the corpus', corpusEmpty: 'Nothing similar.',
+    excludedReceipt: '{{types}} excluded', machineRead: 'OCR', score: 'Score',
+  };
+
+  const chooserButtons = (container: HTMLElement) =>
+    Array.from(container.querySelectorAll('.semiont-gather__actions button'));
+
+  it('three equal-width peers, one of them quiet, none of them dismissal', () => {
+    const { container } = render(
+      <GatherContextStep
+        context={CONTEXT} contextLoading={false} contextError={null}
+        annotate={ANNOTATE} translations={DISPLAY_T}
+      />,
+    );
+    const buttons = chooserButtons(container);
+    expect(buttons).toHaveLength(3);
+    // Equal width is HONEST here — these are actual peers. This is the same
+    // `--flex` the shared footer bans for making retreat read as advance's peer.
+    for (const b of buttons) expect(b.className).toContain('semiont-button--flex');
+    // The AI paths are primary; the manual path's demotion to secondary is the
+    // recorded convention, not drift.
+    const secondary = buttons.filter((b) => b.className.includes('semiont-button--secondary'));
+    expect(secondary).toHaveLength(1);
+    expect(secondary[0]!.textContent).toContain('Compose');
+    // Dismissal stays in the corner, as on every footer.
+    expect(buttons.map((b) => b.textContent ?? '').filter((l) => DISMISSAL.test(l))).toEqual([]);
+  });
+
+  it('ellipses mark step-vs-act: the step-leading choices carry one, the acting one does not', () => {
+    // The "…" is component-owned markup, not translated copy: Search and
+    // Generate lead to another step; Compose acts immediately (navigates away).
+    const { container } = render(
+      <GatherContextStep
+        context={CONTEXT} contextLoading={false} contextError={null}
+        annotate={ANNOTATE} translations={DISPLAY_T}
+      />,
+    );
+    const labels = chooserButtons(container).map((b) => (b.textContent ?? '').trim());
+    expect(labels.filter((l) => l.endsWith('…'))).toHaveLength(2);
+    expect(labels.find((l) => l.includes('Compose'))!.endsWith('…')).toBe(false);
+  });
+
+  it('every choice waits for context', () => {
+    const { container } = render(
+      <GatherContextStep
+        context={CONTEXT} contextLoading contextError={null}
+        annotate={ANNOTATE} translations={DISPLAY_T}
+      />,
+    );
+    for (const b of chooserButtons(container)) expect(b).toBeDisabled();
+  });
 });
 
 // ─────────────────────────────────────────────────────────────────────

package/src/components/pdf-annotation/PdfAnnotationCanvas.tsx

@@ -685,7 +685,7 @@ export function PdfAnnotationCanvas({
 
     const uri = resourceUri;
     const outcome = session.client.browse.resourceAnchoredText(toResourceId(uri)).then(
-      (served) => (served && !('declined' in served) ? served : null),
+      (served) => (served && served.kind === 'extracted' ? served : null),
       () => {
         if (resourceAnchoredRef.current?.uri === uri) resourceAnchoredRef.current = null;
         return null;
@@ -861,6 +861,39 @@ export function PdfAnnotationCanvas({
 
   const stripRef = useRef<HTMLDivElement>(null);
 
+  // The strip's CSS scrollport ceiling is 100vh — right when the nearest
+  // scroller is the window, a lie inside an inner-scrolled panel: the sticky
+  // strip then extends below the panel's clip, and `nearest` (below) considers
+  // a tick in that hidden band already in view, so the active page vanished
+  // whenever it crossed the strip's bottom (never the top, whose edges
+  // coincide). Size the scrollport to the scroller that actually clips it;
+  // with no such scroller the CSS ceiling stands.
+  useEffect(() => {
+    const strip = stripRef.current;
+    if (pageLayout !== 'scroll' || !strip) return;
+    let scroller: HTMLElement | null = strip.parentElement;
+    while (scroller) {
+      const overflowY = getComputedStyle(scroller).overflowY;
+      if (overflowY === 'auto' || overflowY === 'scroll') break;
+      scroller = scroller.parentElement;
+    }
+    if (!scroller) return;
+    const clip = scroller;
+    const size = () => { strip.style.maxHeight = `${clip.clientHeight}px`; };
+    size();
+    let observer: ResizeObserver | null = null;
+    try {
+      observer = new ResizeObserver(size);
+      observer.observe(clip);
+    } catch {
+      window.addEventListener('resize', size);
+    }
+    return () => {
+      if (observer) observer.disconnect();
+      else window.removeEventListener('resize', size);
+    };
+  }, [pageLayout, numPages, pageShape]);
+
   useEffect(() => {
     // `nearest` so following the reader never yanks the strip around; it
     // scrolls only when the current rectangle would otherwise leave view.

package/src/components/pdf-annotation/__tests__/PdfAnnotationCanvas.test.tsx

@@ -508,6 +508,7 @@ describe('PdfAnnotationCanvas', () => {
         beckon: { hover: vi.fn() },
         browse: {
           resourceAnchoredText: vi.fn().mockResolvedValue({
+            kind: 'extracted',
             text: 'Hello world again',
             items: [
               { start: 0, end: 5, page: 1, x: 72, y: 700, width: 30, height: 12 },
@@ -560,6 +561,7 @@ describe('PdfAnnotationCanvas', () => {
     } as unknown as Awaited<ReturnType<typeof loadPdfDocument>>);
 
     const resourceAnchoredText = vi.fn().mockResolvedValue({
+      kind: 'extracted',
       text: 'Hello world again',
       items: [
         { start: 0, end: 5, page: 1, x: 72, y: 700, width: 30, height: 12 },
@@ -727,6 +729,7 @@ describe('PdfAnnotationCanvas', () => {
       scannedDoc();
 
       const resourceAnchoredText = vi.fn().mockResolvedValue({
+        kind: 'extracted',
         text: 'Hello world again',
         items: [{ start: 0, end: 5, page: 1, x: 72, y: 700, width: 30, height: 12 }],
       });
@@ -889,6 +892,40 @@ describe('PdfAnnotationCanvas', () => {
       });
     });
 
+    test('the strip sizes its scrollport to the panel that clips it — not the window', async () => {
+      // The strip is sticky with a CSS ceiling of 100vh — right when the
+      // nearest scroller is the window, a lie inside an inner-scrolled panel:
+      // there the strip's scrollport extends below the panel's clip, and
+      // `scrollIntoView({block:'nearest'})` considers a tick in that hidden
+      // band already in view — the active page vanished when it crossed the
+      // strip's bottom (never the top, whose edges coincide). Measured live:
+      // strip scrollport 126→846 vs panel 126→639. The fix sizes the
+      // scrollport to the scroller that actually clips it.
+      const io = stubIntersectionObserver();
+      scannedDoc();
+
+      const scroller = document.createElement('div');
+      scroller.style.overflowY = 'auto';
+      Object.defineProperty(scroller, 'clientHeight', { value: 513, configurable: true });
+      document.body.appendChild(scroller);
+
+      render(
+        <PdfAnnotationCanvas resourceUri="res-1"
+          pdfUrl={mockPdfUrl}
+          drawingMode={null}
+          pageLayout="scroll"
+        />,
+        { container: scroller },
+      );
+      await waitFor(() => {
+        expect(document.querySelectorAll('.semiont-pdf-annotation-canvas__strip-page')).toHaveLength(5);
+      });
+      io.fire([1]);
+
+      const strip = document.querySelector('.semiont-pdf-annotation-canvas__strip') as HTMLElement;
+      await waitFor(() => expect(strip.style.maxHeight).toBe('513px'));
+    });
+
     test('clicking a strip rectangle jumps to that page', async () => {
       const io = stubIntersectionObserver();
       scannedDoc();
@@ -1244,7 +1281,7 @@ describe('PdfAnnotationCanvas', () => {
 
       const resourceAnchoredText = vi.fn()
         .mockRejectedValueOnce(new Error('transport down'))
-        .mockResolvedValue({ text: 'later', items: [] });
+        .mockResolvedValue({ kind: 'extracted', text: 'later', items: [] });
       const session = {
         client: { beckon: { hover: vi.fn() }, browse: { resourceAnchoredText } },
       } as unknown as import('@semiont/sdk').SemiontSession;

package/src/components/resource/AnnotateView.tsx

@@ -39,7 +39,7 @@ interface Props {
   /** Session for the shown resource — its client emits mark:* / mark.request; its bus feeds toolbar + beckon events. */
   session: SemiontSession | null;
   /** Recently-created annotation ids to sparkle (host-provided; was ResourceAnnotationsContext). */
-  newAnnotationIds?: Set<string>;
+  sparkleAnnotationIds?: Set<string>;
   /** The bar's Mode control reports the chosen mode here (the owner applies it). */
   onModeChange?: (mode: boolean) => void;
   /** Render the built-in bar (default). false → no bar; selection capture and drawing stay live. */
@@ -69,7 +69,7 @@ export function AnnotateView({
   hoverDelayMs = 150,
   annotateMode,
   session,
-  newAnnotationIds,
+  sparkleAnnotationIds,
   onModeChange,
   showToolbar = true,
   renderers,
@@ -267,7 +267,7 @@ export function AnnotateView({
           selectedMotivation={selectedMotivation}
           hoveredAnnotationId={hoveredAnnotationId}
           hoverDelayMs={hoverDelayMs}
-          newAnnotationIds={newAnnotationIds}
+          sparkleAnnotationIds={sparkleAnnotationIds}
           scrollToAnnotationId={scrollToAnnotationId}
           showLineNumbers={showLineNumbers}
           enableWidgets={enableWidgets}

package/src/components/resource/BrowseView.tsx

@@ -35,7 +35,7 @@ interface Props {
   /** Session for the shown resource — emits browse:click / beckon:hover; its bus feeds beckon events. */
   session: SemiontSession | null;
   /** Recently-created annotation ids to sparkle (host-provided; was ResourceAnnotationsContext). */
-  newAnnotationIds?: Set<string>;
+  sparkleAnnotationIds?: Set<string>;
   /** Override the read-only media renderers (render mode → renderer); merged over the defaults. */
   renderers?: BrowseMediaRenderers;
   /** A content link (`<a href>` in the rendered content) was clicked. The viewer preventDefaults and
@@ -87,7 +87,7 @@ export const BrowseView = memo(function BrowseView({
   annotateMode,
   hoverDelayMs = 150,
   session,
-  newAnnotationIds,
+  sparkleAnnotationIds,
   renderers,
   onLinkClick,
   onReferenceHover,
@@ -227,11 +227,11 @@ export const BrowseView = memo(function BrowseView({
     };
 
     // Apply animation classes to new annotations
-    if (newAnnotationIds) {
+    if (sparkleAnnotationIds) {
       const annotationSpans = container.querySelectorAll('[data-annotation-id]');
       annotationSpans.forEach((span) => {
         const annotationId = span.getAttribute('data-annotation-id');
-        if (annotationId && newAnnotationIds.has(annotationId)) {
+        if (annotationId && sparkleAnnotationIds.has(annotationId)) {
           span.classList.add('annotation-sparkle');
         }
       });
@@ -248,7 +248,7 @@ export const BrowseView = memo(function BrowseView({
       cleanupHover();
       referentSub?.unsubscribe(); // in-flight referent load dies with the effect
     };
-  }, [content, allAnnotations, newAnnotationIds, hoverDelayMs, session, onReferenceHover]);
+  }, [content, allAnnotations, sparkleAnnotationIds, hoverDelayMs, session, onReferenceHover]);
 
   // Helper to scroll annotation into view with pulse effect
   const scrollToAnnotation = useCallback((annotationId: string | null, removePulse = false) => {

package/src/components/resource/ResourceViewer.tsx

@@ -50,7 +50,7 @@ interface Props {
   /** Inline display variant: auto-height, no inner scroll, no pane chrome (browse path). Default: fill-the-pane. */
   inline?: boolean;
   /** Recently-created annotation ids to sparkle (threaded to the browse/annotate subtree). */
-  newAnnotationIds?: Set<string>;
+  sparkleAnnotationIds?: Set<string>;
   generatingReferenceId?: string | null;
   showLineNumbers?: boolean;
   hoverDelayMs?: number;
@@ -116,7 +116,7 @@ export function ResourceViewer({
   onLinkClick,
   onReferenceHover,
   inline = false,
-  newAnnotationIds,
+  sparkleAnnotationIds,
   generatingReferenceId,
   showLineNumbers = false,
   hoverDelayMs,
@@ -356,7 +356,7 @@ export function ResourceViewer({
           onModeChange={changeAnnotateMode}
           showToolbar={showToolbar}
           session={session}
-          newAnnotationIds={newAnnotationIds}
+          sparkleAnnotationIds={sparkleAnnotationIds}
           {...(annotateRenderers && { renderers: annotateRenderers })}
         />
       ) : (
@@ -372,7 +372,7 @@ export function ResourceViewer({
           onClickActionChange={changeClickAction}
           showToolbar={showToolbar}
           session={session}
-          newAnnotationIds={newAnnotationIds}
+          sparkleAnnotationIds={sparkleAnnotationIds}
           onLinkClick={onLinkClick}
           onReferenceHover={onReferenceHover}
           inline={inline}

package/src/components/resource/__tests__/AnnotateView.embeddable.test.tsx

@@ -1,7 +1,7 @@
 /**
  * EMBEDDABLE-RESOURCE-VIEWER step 1b — AnnotateView + AnnotateToolbar provider-free.
  *
- * AnnotateView takes `session` + `newAnnotationIds` as props; the REAL
+ * AnnotateView takes `session` + `sparkleAnnotationIds` as props; the REAL
  * AnnotateToolbar (not mocked — its decoupling is the crux of 1b) takes `session`
  * as a prop. CodeMirrorRenderer is mocked (heavy; already prop-based).
  *

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

@@ -1,7 +1,7 @@
 /**
  * EMBEDDABLE-RESOURCE-VIEWER step 1a — BrowseView renders provider-free.
  *
- * BrowseView takes its `session` + `newAnnotationIds` as props (not
+ * BrowseView takes its `session` + `sparkleAnnotationIds` as props (not
  * `useSemiont()` / `useResourceAnnotations()`), and subscribes to session-scoped
  * beckon events via `session.subscribe`. `AnnotateToolbar` is mocked here — its
  * own provider decoupling is step 1b — so this spec isolates BrowseView's body.

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

@@ -8,7 +8,7 @@ import { createTestSemiontWrapper } from '../../../test-utils';
 
 import type { Annotation, AnnotationId } from '@semiont/core';
 
-// BrowseView takes its `session` + `newAnnotationIds` as props now (step 1a) — no
+// BrowseView takes its `session` + `sparkleAnnotationIds` as props now (step 1a) — no
 // ResourceAnnotationsContext / SemiontProvider reach-in. `makeSession` (below)
 // wraps the fake client so browse:click / beckon:hover land on the bus the
 // trackers listen on, and session.subscribe registers beckon:* on that bus.
@@ -125,14 +125,14 @@ function makeSession(client: SemiontClient): SemiontSession {
 
 const renderWithProviders = (
   component: React.ReactElement<React.ComponentProps<typeof BrowseView>>,
-  options: { newAnnotationIds?: Set<string> } = {}
+  options: { sparkleAnnotationIds?: Set<string> } = {}
 ) => {
   const { SemiontWrapper, client } = createTestSemiontWrapper();
   const Wrapper = ({ children }: { children: React.ReactNode }) => (
     <SemiontWrapper>{children}</SemiontWrapper>
   );
   return render(
-    React.cloneElement(component, { session: makeSession(client), newAnnotationIds: options.newAnnotationIds }),
+    React.cloneElement(component, { session: makeSession(client), sparkleAnnotationIds: options.sparkleAnnotationIds }),
     { wrapper: Wrapper },
   );
 };
@@ -140,7 +140,7 @@ const renderWithProviders = (
 const renderWithEventTracking = (
   component: React.ReactElement<React.ComponentProps<typeof BrowseView>>,
   tracker: ReturnType<typeof createEventTracker>,
-  options: { newAnnotationIds?: Set<string> } = {}
+  options: { sparkleAnnotationIds?: Set<string> } = {}
 ) => {
   const { SemiontWrapper, eventBus, client } = createTestSemiontWrapper();
   tracker._attach(eventBus);
@@ -148,7 +148,7 @@ const renderWithEventTracking = (
     <SemiontWrapper>{children}</SemiontWrapper>
   );
   return render(
-    React.cloneElement(component, { session: makeSession(client), newAnnotationIds: options.newAnnotationIds }),
+    React.cloneElement(component, { session: makeSession(client), sparkleAnnotationIds: options.sparkleAnnotationIds }),
     { wrapper: Wrapper },
   );
 };
@@ -545,7 +545,7 @@ describe('BrowseView Component', () => {
 
   describe('Annotation Animation Classes', () => {
     it('should apply sparkle class to new annotations', () => {
-      const newAnnotationIds = new Set(['new-annotation-1']);
+      const sparkleAnnotationIds = new Set(['new-annotation-1']);
 
       const annotations = {
         ...defaultProps.annotations,
@@ -553,12 +553,12 @@ describe('BrowseView Component', () => {
       };
 
       renderWithProviders(<BrowseView {...defaultProps} annotations={annotations} />, {
-        newAnnotationIds
+        sparkleAnnotationIds
       });
 
-      // Verify the newAnnotationIds set contains the expected annotation
+      // Verify the sparkleAnnotationIds set contains the expected annotation
       // In the actual component, this triggers the sparkle class application
-      expect(newAnnotationIds.has('new-annotation-1')).toBe(true);
+      expect(sparkleAnnotationIds.has('new-annotation-1')).toBe(true);
     });
   });
 

package/src/components/resource/annotate-renderers.tsx

@@ -51,7 +51,7 @@ export interface AnnotateMediaRendererProps {
   // Text-path extras. Optional on the shared interface: a custom image or PDF
   // renderer simply ignores them, the same way `MediaRendererProps.session` is
   // documented to be ignorable.
-  newAnnotationIds?: Set<string>;
+  sparkleAnnotationIds?: Set<string>;
   scrollToAnnotationId?: string | null;
   showLineNumbers?: boolean;
   enableWidgets?: boolean;
@@ -66,7 +66,7 @@ export function TextAnnotateRenderer({
   content,
   annotations,
   session,
-  newAnnotationIds,
+  sparkleAnnotationIds,
   hoveredAnnotationId,
   scrollToAnnotationId,
   showLineNumbers = false,
@@ -84,7 +84,7 @@ export function TextAnnotateRenderer({
       content={content}
       segments={segments}
       editable={false}
-      newAnnotationIds={newAnnotationIds}
+      sparkleAnnotationIds={sparkleAnnotationIds}
       {...(hoveredAnnotationId !== undefined && { hoveredAnnotationId })}
       {...(scrollToAnnotationId !== undefined && { scrollToAnnotationId })}
       sourceView={true}

package/src/components/resource/panels/AssistSection.css

@@ -173,6 +173,41 @@
   font-variant-numeric: tabular-nums;
 }
 
+/* D8: the finished run's artifact, offered as a link. */
+/* The finished run's artifact — the ended frame's primary affordance
+   (GENERATION-ARRIVAL P1, D3's fallback): a button-shaped invitation to open
+   what was made, not an underlined footnote beside the bar. */
+.semiont-assist-progress__outcome {
+  align-self: stretch;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--semiont-color-primary-300);
+  border-radius: 0.5rem;
+  background: var(--semiont-color-primary-50);
+  cursor: pointer;
+  font-size: var(--semiont-text-sm);
+  font-weight: var(--semiont-font-medium);
+  color: var(--semiont-color-primary-700);
+  text-align: left;
+}
+
+.semiont-assist-progress__outcome:hover {
+  border-color: var(--semiont-color-primary-400);
+  background: var(--semiont-color-primary-100);
+  color: var(--semiont-color-primary-800);
+}
+
+[data-theme="dark"] .semiont-assist-progress__outcome {
+  border-color: var(--semiont-color-primary-700);
+  background: var(--semiont-color-primary-900);
+  color: var(--semiont-color-primary-300);
+}
+
+[data-theme="dark"] .semiont-assist-progress__outcome:hover {
+  border-color: var(--semiont-color-primary-600);
+  background: var(--semiont-color-primary-800);
+  color: var(--semiont-color-primary-200);
+}
+
 .semiont-assist-progress__params {
   display: flex;
   flex-wrap: wrap;

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

@@ -27,6 +27,8 @@ interface ReferenceEntryProps {
   onOpenResource?: (resourceId: string) => void;
   annotateMode?: boolean;
   isGenerating?: boolean;
+  /** The reference just got attention-worthy (created or resolved) — glow the icon (RESOLUTION-SPARKLE D6). */
+  sparkle?: boolean;
   ref?: Ref<HTMLDivElement>;
 }
 
@@ -38,6 +40,7 @@ export function ReferenceEntry({
   onOpenResource,
   annotateMode = true,
   isGenerating = false,
+  sparkle = false,
   ref,
 }: ReferenceEntryProps) {
   const t = useTranslations('ReferencesPanel');
@@ -125,7 +128,7 @@ export function ReferenceEntry({
       <div className="semiont-annotation-entry__header">
         <div className="semiont-reference-icon-group">
           <button
-            className={`semiont-reference-icon${iconIsClickable ? ' semiont-reference-icon--clickable' : ''}`}
+            className={`semiont-reference-icon${iconIsClickable ? ' semiont-reference-icon--clickable' : ''}${sparkle ? ' annotation-sparkle' : ''}`}
             title={isResolved ? t('open') : annotateMode ? t('resolve') : t('stub')}
             onClick={iconIsClickable ? handleIconClick : undefined}
             data-generating={!isResolved && isGenerating ? 'true' : 'false'}
@@ -151,7 +154,11 @@ export function ReferenceEntry({
           )}
           {!selectedText && (
             <div className="semiont-annotation-entry__meta">
-              {annotationType}
+              {/* A resource-level annotation with a resolved, named target is
+                  a derivation (the shape generation mints — the vocabulary
+                  deliberately has no 'deriving' purpose): qualify the link
+                  line below instead of showing the generic type label. */}
+              {!selector && resolvedDocumentName ? t('derived') : annotationType}
             </div>
           )}
           {resolvedDocumentName && (

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

@@ -83,6 +83,8 @@ interface Props {
   scrollToAnnotationId?: string | null;
   onScrollCompleted?: () => void;
   hoveredAnnotationId?: string | null;
+  /** Annotations currently sparkling (recently created or resolved) — entries in the set glow their icon (RESOLUTION-SPARKLE D6). */
+  sparkleAnnotationIds?: Set<string>;
 
   /** User UI locale — stamped on the unresolved-reference body's `language` field. */
   locale?: string;
@@ -119,6 +121,7 @@ export function ReferencesPanel({
   scrollToAnnotationId,
   onScrollCompleted,
   hoveredAnnotationId,
+  sparkleAnnotationIds,
   locale,
   sourceLanguage,
 }: Props) {
@@ -483,6 +486,7 @@ export function ReferencesPanel({
                   onOpenResource={onOpenResource}
                   annotateMode={annotateMode}
                   isGenerating={reference.id === generatingReferenceId}
+                  sparkle={sparkleAnnotationIds?.has(reference.id) ?? false}
                   ref={(el) => setEntryRef(reference.id, el)}
                 />
               ))