@semiont/react-ui 0.5.27 → 0.5.29

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

@@ -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;
@@ -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');
@@ -55,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;
@@ -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) {
@@ -276,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([]);
     }
@@ -483,6 +490,7 @@ export function ReferencesPanel({
                   onOpenResource={onOpenResource}
                   annotateMode={annotateMode}
                   isGenerating={reference.id === generatingReferenceId}
+                  sparkle={sparkleAnnotationIds?.has(reference.id) ?? false}
                   ref={(el) => setEntryRef(reference.id, el)}
                 />
               ))

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

@@ -1,13 +1,17 @@
 'use client';
 
 import { useTranslations } from '../../../contexts/TranslationContext';
-import type { SemiontSession } from '@semiont/sdk';
+import { readyValue, type SemiontSession, type YieldOutcome } from '@semiont/sdk';
 import { formatLocaleDisplay } from '@semiont/core';
 import { resourceId as makeResourceId, type components } from '@semiont/core';
+import { useObservable } from '../../../hooks/useObservable';
 import { renderAgentLabel } from './agent-label';
+import { AssistShell } from './AssistShell';
+import { assistProgressTranslations } from '../../../lib/assist-progress-copy';
 import './ResourceInfoPanel.css';
 
 type Agent = components['schemas']['Agent'];
+type JobProgress = components['schemas']['JobProgress'];
 
 interface Props {
   /** Session carrying the client and event bus; null renders inert. */
@@ -30,6 +34,17 @@ interface Props {
    * to a verb). Omit to hide the Generate action.
    */
   onGenerate?: () => void;
+  /**
+   * Generation lifecycle, page-held (`yield.isGenerating$` / `yield.progress$`
+   * / `yield.outcome$`): this panel is generation's progress surface
+   * (GENERATE-FROM-RESOURCE D7) — the run reports where it was started.
+   */
+  isGenerating?: boolean;
+  generationProgress?: JobProgress | null;
+  /** The finished run's result; the ended frame links it by name (D8). */
+  generationOutcome?: YieldOutcome | null;
+  /** Clear the finished display — wires `yield.dismissProgress()`. */
+  onDismissProgress?: () => void;
 }
 
 /**
@@ -54,8 +69,13 @@ export function ResourceInfoPanel({
   wasDerivedFrom,
   generator,
   onGenerate,
+  isGenerating = false,
+  generationProgress = null,
+  generationOutcome = null,
+  onDismissProgress,
 }: Props) {
   const t = useTranslations('ResourceInfoPanel');
+  const ta = useTranslations('AssistProgress');
 
   // Single attribution surface. `wasAttributedTo` is the canonical list
   // of responsible parties; if a producer set only `generator` we
@@ -152,13 +172,7 @@ export function ResourceInfoPanel({
                 <span className="semiont-resource-info-panel__label">{t('derivedFrom')}</span>
                 <span className="semiont-resource-info-panel__value">
                   {(Array.isArray(wasDerivedFrom) ? wasDerivedFrom : [wasDerivedFrom]).map((id, i) => (
-                    <button
-                      key={id}
-                      className="semiont-resource-info-panel__link"
-                      onClick={() => session?.client.browse.openResource(makeResourceId(id))}
-                    >
-                      {i > 0 && ', '}{id}
-                    </button>
+                    <DerivedFromLink key={id} session={session} id={id} first={i === 0} />
                   ))}
                 </span>
               </div>
@@ -185,19 +199,47 @@ export function ResourceInfoPanel({
         </div>
       )}
 
-      {/* Generate Action — opens the resource-generate flow (UI-only) */}
+      {/* Generate — the run reports where it was started (GENERATE-FROM-RESOURCE
+          D7): the same AssistShell every assist uses, its form the Generate
+          control, the progress frame in its place while a generation runs. */}
       {onGenerate && (
-        <div className="semiont-resource-info-panel__action-section">
-          <button
-            onClick={onGenerate}
-            className="semiont-resource-button semiont-resource-button--secondary"
-          >
-            ✨ {t('generate')}
-          </button>
-          <p className="semiont-resource-info-panel__description">
-            {t('generateDescription')}
-          </p>
-        </div>
+        <AssistShell
+          assistType="generation"
+          title={t('generate')}
+          isAssisting={isGenerating}
+          progress={generationProgress}
+          progressProps={{
+            onCancel: () => session?.client.job.cancelRequest('generation'),
+            ...(onDismissProgress ? { onDismiss: onDismissProgress } : {}),
+            ...(generationOutcome ? {
+              outcome: {
+                label: generationOutcome.resourceName,
+                onOpen: () => session?.client.browse.openResource(generationOutcome.resourceId),
+              },
+              // The terminal sentence derives from the OUTCOME, not the final
+              // progress frame — whose fire-and-forget emit can lose the race
+              // with job:complete and leave "creating…" beside a ✅
+              // (GENERATION-ARRIVAL D4/D5).
+              endedMessage: generationOutcome.truncated
+                ? ta('codeCompleteGeneratedTruncated')
+                : ta('codeCompleteGenerated'),
+            } : {}),
+            translations: assistProgressTranslations(ta),
+          }}
+          form={
+            <>
+              <button
+                onClick={onGenerate}
+                className="semiont-resource-button semiont-resource-button--secondary"
+              >
+                ✨ {t('generate')}
+              </button>
+              <p className="semiont-resource-info-panel__description">
+                {t('generateDescription')}
+              </p>
+            </>
+          }
+        />
       )}
 
       {/* Clone Action */}
@@ -244,3 +286,30 @@ export function ResourceInfoPanel({
     </div>
   );
 }
+
+/**
+ * One derived-from entry: linked by id (wire identity), labeled by the source
+ * resource's NAME once `browse.resource` serves its descriptor. The raw id is
+ * the honest label until then — and stays if the descriptor never resolves
+ * (deleted source, no session). Own component because the id list maps in a
+ * loop and the subscription is a hook.
+ */
+function DerivedFromLink({ session, id, first }: {
+  session: SemiontSession | null;
+  id: string;
+  first: boolean;
+}) {
+  // `browse.resource` is stable per id (cache + scope wrappers memoize), so
+  // subscribing straight off the render read is safe; `failed` is an emission,
+  // never a stream error, so `readyValue` covers every unresolved state.
+  const descriptor = useObservable(session ? session.client.browse.resource(makeResourceId(id)) : null);
+  const name = descriptor ? readyValue(descriptor)?.name : undefined;
+  return (
+    <button
+      className="semiont-resource-info-panel__link"
+      onClick={() => session?.client.browse.openResource(makeResourceId(id))}
+    >
+      {!first && ', '}{name ?? id}
+    </button>
+  );
+}

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

@@ -6,7 +6,7 @@ import type { components, Selector } from '@semiont/core';
 type JobProgress = components['schemas']['JobProgress'];
 import type { RouteBuilder, LinkComponentProps } from '../../../contexts/RoutingContext';
 import type { SemiontSession } from '@semiont/sdk';
-import { annotatorKeyForMotivation, type Annotator } from '../../../lib/annotation-registry';
+import { annotatorKeyForMotivation, type Annotator, type AnnotatorKey } from '../../../lib/annotation-registry';
 import { StatisticsPanel } from './StatisticsPanel';
 import { HighlightPanel } from './HighlightPanel';
 import { ReferencesPanel } from './ReferencesPanel';
@@ -17,7 +17,9 @@ import './UnifiedAnnotationsPanel.css';
 
 import type { Annotation } from '@semiont/core';
 type Motivation = components['schemas']['Motivation'];
-type TabKey = 'statistics' | 'reference' | 'highlight' | 'assessment' | 'comment' | 'tag';
+// Derived from the annotator registry (the single motivation↔annotator
+// source) — a hand-written union here could drift from it.
+type TabKey = 'statistics' | AnnotatorKey;
 
 // Unified pending annotation type
 interface PendingAnnotation {
@@ -76,6 +78,8 @@ interface UnifiedAnnotationsPanelProps {
   entityTypesError?: Error | null;
   referencedByError?: Error | null;
   onRetryReferencedBy?: () => void;
+  /** Annotations currently sparkling (recently created or resolved) — RESOLUTION-SPARKLE D6. */
+  sparkleAnnotationIds?: Set<string>;
 
   // Resource context — threaded to every per-motivation panel, which stamps it
   // as `source` on mark:submit (multi-viewer routing).
@@ -328,6 +332,7 @@ export function UnifiedAnnotationsPanel(props: UnifiedAnnotationsPanelProps) {
                 referencedByLoading={props.referencedByLoading}
                 referencedByError={props.referencedByError}
                 onRetryReferencedBy={props.onRetryReferencedBy}
+                sparkleAnnotationIds={props.sparkleAnnotationIds}
                 Link={props.Link}
                 routes={props.routes}
               />

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

@@ -94,6 +94,24 @@ describe('ReferenceEntry', () => {
     mockGetEntityTypes.mockReturnValue([]);
   });
 
+  // RESOLUTION-SPARKLE D6: a just-resolved reference announces itself on the
+  // panel entry's icon with the same `.annotation-sparkle` glow the document
+  // span uses. The host decides WHEN (membership in the sparkle set); the
+  // entry only renders the boolean.
+  describe('Resolution sparkle', () => {
+    it('carries the sparkle animation on the icon when sparkle is set', () => {
+      const { container } = renderEntry({ sparkle: true });
+
+      expect(container.querySelector('.semiont-reference-icon')).toHaveClass('annotation-sparkle');
+    });
+
+    it('does not sparkle by default', () => {
+      const { container } = renderEntry();
+
+      expect(container.querySelector('.semiont-reference-icon')).not.toHaveClass('annotation-sparkle');
+    });
+  });
+
   describe('Rendering', () => {
     it('should render the selected text in quotes', () => {
       renderEntry();
@@ -172,6 +190,29 @@ describe('ReferenceEntry', () => {
 
       expect(screen.getByText(/My Linked Document/)).toBeInTheDocument();
     });
+
+    it('a resource-level derivation headlines Derived, never the generic type label', () => {
+      // The provenance edge minted by resource-focus generation: no selector
+      // (nothing to quote), resolved body naming the derived resource. The
+      // generic "Annotation" label said nothing — the qualifier says what
+      // the entry IS; the link line below says what it points at. Inference
+      // is from shape (the wire vocabulary deliberately has no 'deriving'
+      // purpose); the unresolved case keeps the plain type label.
+      mockGetAnnotationExactText.mockReturnValue('');
+      mockIsBodyResolved.mockReturnValue(true);
+      mockGetBodySource.mockReturnValue('gen-doc');
+
+      const provenanceRef = {
+        ...createMockReference({ target: { source: 'resource-1' } }),
+        _resolvedDocumentName: 'generated from Cedar County, Iowa',
+      };
+
+      renderEntry({ reference: provenanceRef as Annotation });
+
+      expect(screen.getByText('ReferencesPanel.derived')).toBeInTheDocument();
+      expect(screen.queryByText('Annotation')).not.toBeInTheDocument();
+      expect(screen.getByText(/generated from Cedar County, Iowa/)).toBeInTheDocument();
+    });
   });
 
   describe('Entity types', () => {

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,10 +1,10 @@
 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';
-import type { EventBus } from '@semiont/core';
+import type { Annotation, AnnotationId, EventBus } from '@semiont/core';
 import type { SemiontSession } from '@semiont/sdk';
 import { createTestSemiontWrapper } from '../../../../test-utils';
 
@@ -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.
@@ -118,6 +119,38 @@ describe('ReferencesPanel Component', () => {
     vi.restoreAllMocks();
   });
 
+  // RESOLUTION-SPARKLE D6: the panel threads the host's sparkle set down to
+  // the entries — exactly the ids in the set glow, nothing else.
+  describe('Resolution sparkle threading', () => {
+    const linkingReference = (id: string): Annotation => ({
+      '@context': 'http://www.w3.org/ns/anno.jsonld',
+      id: id as AnnotationId,
+      type: 'Annotation',
+      motivation: 'linking',
+      created: '2026-08-21T12:00:00Z',
+      modified: '2026-08-21T12:00:00Z',
+      target: {
+        source: 'res-1',
+        selector: { type: 'TextQuoteSelector', exact: `text of ${id}` },
+      },
+      body: { type: 'SpecificResource', source: 'linked-doc', purpose: 'linking' },
+    });
+
+    it('sparkles exactly the entries named by sparkleAnnotationIds', () => {
+      const { container } = renderWithEventBus(
+        <ReferencesPanel
+          {...panelProps()}
+          annotations={[linkingReference('ann-dark'), linkingReference('ann-lit')]}
+          sparkleAnnotationIds={new Set(['ann-lit'])}
+        />,
+      );
+
+      const sparkling = container.querySelectorAll('.semiont-reference-icon.annotation-sparkle');
+      expect(sparkling).toHaveLength(1);
+      expect(sparkling[0]!.closest('.semiont-annotation-entry')).toHaveTextContent('text of ann-lit');
+    });
+  });
+
   describe('Rendering', () => {
     it('should render panel with title', () => {
       renderWithEventBus(<ReferencesPanel {...panelProps()} />);
@@ -147,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()} />);