@semiont/react-ui 0.5.24 → 0.5.26

package/src/components/pdf-annotation/__tests__/estimate-slot-height.test.ts

@@ -0,0 +1,53 @@
+/**
+ * PDF-CONTINUOUS-SCROLL S1b.
+ *
+ * The scroll column reserves space for unmounted pages. If the reservation is
+ * wrong, every mount and unmount changes the column's height and the scrollbar
+ * jumps — which is what S1 shipped, by reserving the raster height rather than
+ * the displayed one.
+ *
+ * These pins hold the estimate to the CSS the image is actually under:
+ * `max-width: 100%; height: auto`.
+ */
+import { describe, it, expect } from 'vitest';
+import { estimateSlotHeight } from '../estimate-slot-height';
+
+// US Letter at scale 1.5: 918 × 1188 raster, aspect 792/612.
+const ASPECT = 792 / 612;
+const RASTER_W = 918;
+
+describe('estimateSlotHeight', () => {
+  it('scales to the column when the column is narrower than the raster', () => {
+    // The common case: `max-width: 100%` shrinks the image to the column.
+    expect(estimateSlotHeight(600, RASTER_W, ASPECT)).toBe(Math.round(600 * ASPECT));
+  });
+
+  it('never upscales past the raster — max-width shrinks only', () => {
+    // A column wider than the raster leaves the image at natural size, so the
+    // height stops growing. Reserving columnWidth * aspect here would over-
+    // reserve and leave a gap under every page.
+    expect(estimateSlotHeight(1600, RASTER_W, ASPECT)).toBe(Math.round(RASTER_W * ASPECT));
+  });
+
+  it('is exactly the raster height when the column matches the raster', () => {
+    expect(estimateSlotHeight(RASTER_W, RASTER_W, ASPECT)).toBe(Math.round(RASTER_W * ASPECT));
+  });
+
+  it('does NOT use the raster height as a width-independent constant', () => {
+    // The S1 defect, stated as a pin: the raster is 1188px tall, but in a
+    // 600px column the page occupies ~776px. Reserving 1188 is what made the
+    // column's height lurch on every mount.
+    const rasterHeight = Math.round(RASTER_W * ASPECT); // 1188
+    expect(estimateSlotHeight(600, RASTER_W, ASPECT)).not.toBe(rasterHeight);
+    expect(estimateSlotHeight(600, RASTER_W, ASPECT)).toBeLessThan(rasterHeight);
+  });
+
+  it('answers null until every measurement is in, rather than guessing', () => {
+    // A wrong reservation is worse than none: an unsized slot is stable, a
+    // mis-sized one moves when the page lands.
+    expect(estimateSlotHeight(null, RASTER_W, ASPECT)).toBeNull();
+    expect(estimateSlotHeight(600, null, ASPECT)).toBeNull();
+    expect(estimateSlotHeight(600, RASTER_W, null)).toBeNull();
+    expect(estimateSlotHeight(0, RASTER_W, ASPECT)).toBeNull();
+  });
+});

package/src/components/pdf-annotation/estimate-slot-height.ts

@@ -0,0 +1,31 @@
+/**
+ * The height a page will occupy once rendered, computed BEFORE rendering it.
+ *
+ * The scrolling column reserves space for pages it has not mounted. If the
+ * reserved height differs from the height the page actually takes, every mount
+ * and unmount changes the column's total height and the scrollbar jumps under
+ * the reader's cursor — the defect S1 shipped by reserving the *raster* height
+ * (`getViewport({ scale }).height`) instead of the *displayed* one.
+ *
+ * This models the CSS the image is under exactly:
+ *
+ *   .semiont-pdf-annotation-canvas__image { max-width: 100%; height: auto; }
+ *
+ * `max-width` shrinks but never upscales, so the displayed width is
+ * `min(columnWidth, rasterWidth)` and the height follows the page's aspect
+ * ratio. Aspect is scale-invariant, so it can come from any viewport.
+ *
+ * @param columnWidth  Measured inner width of the scroll column, in CSS px.
+ * @param rasterWidth  Width of the rendered raster, in px (`viewport(scale).width`).
+ * @param aspect       Page height ÷ width, from any viewport scale.
+ * @returns Reserved height in CSS px, or null when a measurement is not in yet.
+ */
+export function estimateSlotHeight(
+  columnWidth: number | null,
+  rasterWidth: number | null,
+  aspect: number | null,
+): number | null {
+  if (!columnWidth || !rasterWidth || !aspect) return null;
+  if (columnWidth <= 0 || rasterWidth <= 0 || aspect <= 0) return null;
+  return Math.round(Math.min(columnWidth, rasterWidth) * aspect);
+}

package/src/components/resource/AnnotateView.tsx

@@ -5,9 +5,11 @@ import { capabilitiesOf, resourceId as toResourceId } from '@semiont/core';
 import { ANNOTATORS } from '../../lib/annotation-registry';
 import { buildTextSelectors, fallbackTextPosition } from '../../lib/text-selection-handler';
 import { defaultAnnotateRenderers, type AnnotateMediaRenderers } from './annotate-renderers';
+import { DownloadFileLink } from './DownloadFileLink';
 import type { EditorView } from '@codemirror/view';
 import type { SemiontSession } from '@semiont/sdk';
 import { useSessionEventSubscriptions } from '../../hooks/useSessionEventSubscriptions';
+import { scrollAnnotationIntoView } from '../../lib/scroll-utils';
 
 // Type augmentation for custom DOM properties
 interface EnrichedHTMLElement extends HTMLElement {
@@ -51,6 +53,7 @@ interface Props {
  *
  * @emits mark:requested - User requested to create annotation. Payload: { selector: Selector | Selector[], motivation: SelectionMotivation }
  * @subscribes beckon:hover - Annotation hovered. Payload: { annotationId: string | null }
+ * @subscribes beckon:focus - Scroll to and highlight annotation. Payload: { annotationId: string }
  */
 export function AnnotateView({
   content,
@@ -104,10 +107,20 @@ export function AnnotateView({
     onUIStateChangeRef.current?.({ hoveredAnnotationId: annotationId });
   }, []);
 
+  // "Scroll to and highlight this annotation" — the same contract BrowseView
+  // serves, so the behaviour no longer depends on which view mode is active.
+  // The `scrollToAnnotationId` prop path (uiState → renderer) stays as the
+  // host-facing capability it is; this is the in-app producer's route.
+  const handleAnnotationFocus = useCallback(({ annotationId }: { annotationId?: string | null }) => {
+    if (!containerRef.current) return;
+    scrollAnnotationIntoView(annotationId ?? null, containerRef.current, { pulse: true });
+  }, []);
+
   // Annotation hover (session-scoped). Toolbar preference changes flow through
   // props/callbacks, not the bus (TOOLBAR-PREFS-AS-PROPS).
   useSessionEventSubscriptions(session, {
     'beckon:hover': handleAnnotationHover,
+    'beckon:focus': handleAnnotationFocus,
   });
 
   // Handle text annotation with sparkle or immediate creation
@@ -210,13 +223,7 @@ export function AnnotateView({
           <p className="semiont-annotate-view__empty-message">
             Annotation not supported for {mimeType}
           </p>
-          <a
-            href={`/api/resources/${resourceUri}`}
-            download
-            className="semiont-button semiont-button--primary"
-          >
-            Download File
-          </a>
+          <DownloadFileLink resourceUri={resourceUri} session={session} />
         </div>
       </div>
     );

package/src/components/resource/BrowseView.tsx

@@ -21,6 +21,7 @@ import {
 import type { SemiontSession } from '@semiont/sdk';
 import { useSessionEventSubscriptions } from '../../hooks/useSessionEventSubscriptions';
 import { defaultBrowseRenderers, type BrowseMediaRenderers } from './browse-renderers';
+import { DownloadFileLink } from './DownloadFileLink';
 
 interface Props {
   content: string;
@@ -295,13 +296,7 @@ export const BrowseView = memo(function BrowseView({
           <p className="semiont-browse-view__empty-message">
             Preview not available for {mimeType}
           </p>
-          <a
-            href={`/api/resources/${resourceUri}`}
-            download
-            className="semiont-button semiont-button--primary"
-          >
-            Download File
-          </a>
+          <DownloadFileLink resourceUri={resourceUri} session={session} />
         </div>
       </div>
     );

package/src/components/resource/DownloadFileLink.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import { resourceId as toResourceId } from '@semiont/core';
+import type { SemiontSession } from '@semiont/sdk';
+import { useMediaToken } from '../../hooks/useMediaToken';
+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: SemiontSession | null;
+}
+
+/**
+ * The "Download File" affordance on the unsupported-media fallback, shared by
+ * the browse and annotate views.
+ *
+ * Its own component rather than inline markup for two reasons. The token is a
+ * hook, and this fallback is a branch — mounting the component only in that
+ * branch keeps every text/image/PDF view from minting a media token it will
+ * never use. And the URL rule (absolute + `?token=`) lives in `mediaUrl`,
+ * where both views and the viewer page read the same one.
+ *
+ * Before the token lands the anchor renders as a disabled button: a tokenless
+ * URL is a guaranteed 401, and a link that silently fails is worse than one
+ * visibly not ready yet. A client with no `auth` namespace (a host on a bare
+ * transport) stays in that state permanently, which is the honest answer —
+ * it cannot mint tokens at all.
+ */
+export function DownloadFileLink({ resourceUri, session }: Props) {
+  const client = session?.client ?? null;
+  const { token } = useMediaToken(client, toResourceId(resourceUri));
+  const href = mediaUrl(client, toResourceId(resourceUri), token);
+
+  if (!href) {
+    return (
+      <button type="button" disabled className="semiont-button semiont-button--primary semiont-button--disabled">
+        Download File
+      </button>
+    );
+  }
+
+  return (
+    <a href={href} download className="semiont-button semiont-button--primary">
+      Download File
+    </a>
+  );
+}

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

@@ -0,0 +1,58 @@
+/**
+ * ASSIST-SURFACE-WARTS Lane D — in-content scroll on `beckon:focus`.
+ *
+ * `beckon:focus` is the established "scroll to and highlight this annotation"
+ * contract; BrowseView has subscribed to it all along. AnnotateView did not,
+ * so the same event scrolled the content in browse mode and did nothing in
+ * annotate mode. With the history panel now producing the event, that asymmetry
+ * becomes user-visible: the same click works or doesn't depending on the mode.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import type { AnnotationUIState } from '../../../types/annotation-props';
+import { createTestSemiontWrapper } from '../../../test-utils';
+
+const scrollSpy = vi.hoisted(() => vi.fn());
+vi.mock('../../../lib/scroll-utils', () => ({
+  scrollAnnotationIntoView: scrollSpy,
+}));
+vi.mock('../../CodeMirrorRenderer', () => ({
+  CodeMirrorRenderer: () => <div data-annotation-id="ann-7">cm-mock</div>,
+}));
+
+import { AnnotateView } from '../AnnotateView';
+
+const emptyAnnotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+const uiState: AnnotationUIState = {
+  selectedMotivation: 'linking',
+  selectedClick: 'detail',
+  selectedShape: 'rectangle',
+  hoveredAnnotationId: null,
+  scrollToAnnotationId: null,
+};
+
+describe('AnnotateView — beckon:focus scrolls the content', () => {
+  beforeEach(() => { scrollSpy.mockClear(); });
+
+  it('scrolls to the annotation when the session emits beckon:focus', () => {
+    const { session, client } = createTestSemiontWrapper();
+
+    render(
+      <AnnotateView
+        content="hello world"
+        mimeType="text/plain"
+        resourceUri="res-1"
+        annotations={emptyAnnotations}
+        uiState={uiState}
+        session={session}
+        annotateMode
+      />,
+    );
+
+    client.bus.get('beckon:focus').next({ annotationId: 'ann-7' });
+
+    expect(scrollSpy).toHaveBeenCalledTimes(1);
+    expect(scrollSpy.mock.calls[0]?.[0]).toBe('ann-7');
+  });
+});

package/src/components/resource/__tests__/browse-renderers.dispatch.test.tsx

@@ -109,5 +109,38 @@ describe('browse-renderers — annotation + session forwarding (dispatch contrac
     expect(props.existingAnnotations).toEqual([shapeAnnotation()]); // pinned — worked before
     expect(props.drawingMode).toBeNull();
     expect(props.session).toBe(session);                            // NEW — was a session-less no-op
+    // PDF-CONTINUOUS-SCROLL S1: browse asks for the scrolling column.
+    expect(props.pageLayout).toBe('scroll');
+  });
+
+  // S2. Annotate is the mode people actually work in
+  // (.plans/PDF-CONTINUOUS-SCROLL.md D3, second correction), so it gets the
+  // column too — leaving it on Previous/Next made the feature invisible to
+  // its primary audience.
+  it('the annotate registry asks for the column as well, with the live tool', async () => {
+    const session = fakeSession();
+    const { AnnotateView } = await import('../AnnotateView');
+    const { container } = render(
+      <AnnotateView
+        content="blob:pdf-url"
+        mimeType="application/pdf"
+        resourceUri="res-1"
+        annotations={emptyAnnotations}
+        uiState={{
+          selectedMotivation: 'highlighting',
+          selectedClick: 'detail',
+          selectedShape: 'rectangle',
+          hoveredAnnotationId: null,
+          scrollToAnnotationId: null,
+        }}
+        annotateMode
+        session={session}
+      />,
+    );
+
+    await within(container).findByText('pdf-canvas-mock');
+    const props = captured.pdf.at(-1)!;
+    expect(props.pageLayout).toBe('scroll');
+    expect(props.drawingMode).toBe('rectangle'); // the tool still reaches the pages
   });
 });

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

@@ -0,0 +1,129 @@
+/**
+ * The "Download File" affordance on the unsupported-media fallback, in BOTH
+ * resource views.
+ *
+ * `GET /api/resources/:id` is the browser-facing alias of the pipe, and it
+ * exists only as an auth affordance for `<img>`, PDF.js and download links: a
+ * plain `<a download href>` sends neither an Authorization header nor a cookie,
+ * 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.
+ *
+ * Started RED (both hrefs were `/api/resources/res-1`).
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import type { SemiontSession } from '@semiont/sdk';
+import type { AnnotationUIState } from '../../../types/annotation-props';
+import { AnnotateView } from '../AnnotateView';
+import { BrowseView } from '../BrowseView';
+
+vi.mock('../../annotation/AnnotateToolbar', () => ({ AnnotateToolbar: () => null }));
+vi.mock('../../CodeMirrorRenderer', () => ({ CodeMirrorRenderer: () => null }));
+vi.mock('../../image-annotation/SvgDrawingCanvas', () => ({ SvgDrawingCanvas: () => null }));
+vi.mock('react-markdown', () => ({ default: ({ children }: { children: string }) => <div>{children}</div> }));
+vi.mock('remark-gfm', () => ({ default: () => ({}) }));
+
+const BACKEND = 'http://backend.test:4000';
+const UNSUPPORTED = 'application/octet-stream';
+
+const emptyAnnotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+const uiState: AnnotationUIState = {
+  selectedMotivation: null,
+  selectedClick: 'detail',
+  selectedShape: 'rectangle',
+  hoveredAnnotationId: null,
+  scrollToAnnotationId: null,
+};
+
+/** A session whose client mints `token` — the batteries-included case. */
+function sessionMinting(token: string): SemiontSession {
+  return fakeSession({ auth: { mediaToken: vi.fn(async () => ({ token })) } });
+}
+
+/** A session whose token request never settles — the in-flight case. */
+function sessionPending(): SemiontSession {
+  return fakeSession({ auth: { mediaToken: vi.fn(() => new Promise<never>(() => {})) } });
+}
+
+/**
+ * A transport-only client: `SemiontClient.auth` is `AuthNamespace | undefined`,
+ * and a host wiring a bare transport (no `IBackendOperations`) has no `auth`.
+ */
+function sessionWithoutAuth(): SemiontSession {
+  return fakeSession({});
+}
+
+function fakeSession(clientExtras: Record<string, unknown>): SemiontSession {
+  return {
+    client: {
+      baseUrl: BACKEND,
+      mark: { request: vi.fn() },
+      browse: { click: vi.fn() },
+      beckon: { hover: vi.fn() },
+      ...clientExtras,
+    },
+    subscribe: () => () => {},
+  } as unknown as SemiontSession;
+}
+
+const annotateProps = (session: SemiontSession) => ({
+  content: '',
+  mimeType: UNSUPPORTED,
+  resourceUri: 'res-1',
+  annotations: emptyAnnotations,
+  uiState,
+  annotateMode: false,
+  session,
+});
+
+const browseProps = (session: SemiontSession) => ({
+  content: '',
+  mimeType: UNSUPPORTED,
+  resourceUri: 'res-1',
+  annotations: emptyAnnotations,
+  annotateMode: false,
+  session,
+});
+
+const VIEWS = [
+  { name: 'AnnotateView', render: (s: SemiontSession) => render(<AnnotateView {...annotateProps(s)} />) },
+  { name: 'BrowseView', render: (s: SemiontSession) => render(<BrowseView {...browseProps(s)} />) },
+] as const;
+
+describe.each(VIEWS)('$name — unsupported-media download link', ({ render: renderView }) => {
+  it('points at the backend 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('download');
+  });
+
+  it('renders no href while the token is still in flight', async () => {
+    renderView(sessionPending());
+
+    // The affordance stays on screen — it is just not yet actionable. What it
+    // must NOT do is offer a URL already known to fail.
+    expect(await screen.findByText('Download File')).toBeInTheDocument();
+    expect(screen.queryByRole('link', { name: 'Download File' })).not.toBeInTheDocument();
+  });
+
+  it('renders no href when the client has no auth namespace', async () => {
+    renderView(sessionWithoutAuth());
+
+    expect(await screen.findByText('Download File')).toBeInTheDocument();
+    await waitFor(() => {
+      expect(screen.queryByRole('link', { name: 'Download File' })).not.toBeInTheDocument();
+    });
+  });
+
+  it('never builds a host-relative URL', async () => {
+    renderView(sessionMinting('tok-abc'));
+
+    const link = await screen.findByRole('link', { name: 'Download File' });
+    expect(link.getAttribute('href')).not.toMatch(/^\//);
+  });
+});

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

@@ -7,10 +7,18 @@ import { SvgDrawingCanvas } from '../image-annotation/SvgDrawingCanvas';
 import { CodeMirrorRenderer } from '../CodeMirrorRenderer';
 import { segmentTextWithAnnotations } from '../../lib/text-segmentation';
 import type { SelectionMotivation, ShapeType } from '../annotation/AnnotateToolbar';
+import { useTranslations } from '../../contexts/TranslationContext';
 
 // Lazy-load the PDF component to avoid SSR issues with browser PDF.js loading.
 // Kept lazy here deliberately: hoisting it to a static import would make it
 // eager again and reintroduce the SSR problem this indirection exists for.
+/** The lazy chunk's fallback needs its own component: a hook cannot run
+ *  inside a `fallback` prop expression. */
+function PdfViewerLoading() {
+  const t = useTranslations('PdfViewer');
+  return <>{t('viewerLoading')}</>;
+}
+
 const PdfAnnotationCanvas = lazy(() =>
   import('../pdf-annotation/PdfAnnotationCanvas.client').then((mod) => ({ default: mod.PdfAnnotationCanvas })),
 );
@@ -127,7 +135,7 @@ export function PdfAnnotateRenderer({
 }: AnnotateMediaRendererProps) {
   if (!content) return null;
   return (
-    <Suspense fallback={<div className="semiont-annotate-view__loading">Loading PDF viewer...</div>}>
+    <Suspense fallback={<div className="semiont-annotate-view__loading"><PdfViewerLoading /></div>}>
       <PdfAnnotationCanvas
         pdfUrl={content}
         resourceUri={resourceUri}
@@ -137,6 +145,7 @@ export function PdfAnnotateRenderer({
         session={session}
         hoveredAnnotationId={hoveredAnnotationId || null}
         hoverDelayMs={hoverDelayMs}
+        pageLayout="scroll"
       />
     </Suspense>
   );

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

@@ -6,8 +6,16 @@ import remarkGfm from 'remark-gfm';
 import type { Annotation } from '@semiont/core';
 import type { SemiontSession } from '@semiont/sdk';
 import { SvgDrawingCanvas } from '../image-annotation/SvgDrawingCanvas';
+import { useTranslations } from '../../contexts/TranslationContext';
 
 // Lazy-load the PDF component to avoid SSR issues with browser PDF.js loading.
+/** The lazy chunk's fallback needs its own component: a hook cannot run
+ *  inside a `fallback` prop expression. */
+function PdfViewerLoading() {
+  const t = useTranslations('PdfViewer');
+  return <>{t('viewerLoading')}</>;
+}
+
 const PdfAnnotationCanvas = lazy(() => import('../pdf-annotation/PdfAnnotationCanvas.client').then(mod => ({ default: mod.PdfAnnotationCanvas })));
 
 /**
@@ -60,7 +68,7 @@ export function ImageBrowseRenderer({ content, resourceUri, annotations, session
 
 export function PdfBrowseRenderer({ content, resourceUri, annotations, session }: MediaRendererProps) {
   return (
-    <Suspense fallback={<div className="semiont-browse-view__loading">Loading PDF viewer...</div>}>
+    <Suspense fallback={<div className="semiont-browse-view__loading"><PdfViewerLoading /></div>}>
       <PdfAnnotationCanvas
         pdfUrl={content}
         resourceUri={resourceUri}
@@ -68,6 +76,7 @@ export function PdfBrowseRenderer({ content, resourceUri, annotations, session }
         drawingMode={null}
         selectedMotivation={null}
         session={session}
+        pageLayout="scroll"
       />
     </Suspense>
   );

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

@@ -126,49 +126,6 @@
    Detection Log (Completed Results)
    ============================================ */
 
-.semiont-assist-widget__log {
-  background-color: var(--semiont-bg-primary);
-  border-radius: 0.5rem;
-  box-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06);
-  padding: 1rem;
-  display: flex;
-  flex-direction: column;
-  gap: 0.75rem;
-}
-
-[data-theme="dark"] .semiont-assist-widget__log {
-  background-color: var(--semiont-color-gray-800);
-}
-
-.semiont-assist-widget__log-items {
-  display: flex;
-  flex-direction: column;
-  gap: 0.25rem;
-}
-
-.semiont-assist-widget__log-item {
-  font-size: 0.75rem;
-  color: var(--semiont-color-gray-600);
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-}
-
-[data-theme="dark"] .semiont-assist-widget__log-item {
-  color: var(--semiont-color-gray-400);
-}
-
-.semiont-assist-widget__log-check {
-  color: var(--semiont-color-green-600);
-}
-
-[data-theme="dark"] .semiont-assist-widget__log-check {
-  color: var(--semiont-color-green-400);
-}
-
-.semiont-assist-widget__log-type {
-  font-weight: 500;
-}
 
 /* ============================================
    Detection Progress Display

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

@@ -43,6 +43,7 @@ export function AssistSection({
                      annotationType === 'assessment' ? 'AssessmentPanel' :
                      'CommentsPanel';
   const t = useTranslations(panelName);
+  const ta = useTranslations('AssistProgress');
   const [instructions, setInstructions] = useState('');
   type ToneValue = 'scholarly' | 'explanatory' | 'conversational' | 'technical' | 'analytical' | 'critical' | 'balanced' | 'constructive' | '';
   const [tone, setTone] = useState<ToneValue>('');
@@ -89,7 +90,15 @@ export function AssistSection({
       progress={progress}
       progressProps={{
         onDismiss: handleDismissProgress,
-        translations: { close: t('closeProgress') },
+        translations: {
+          cancel: t('cancel'),
+          inProgress: t('annotating'),
+          complete: t('complete'),
+          failed: t('failed'),
+          paramsTitle: ta('paramsTitle'),
+          processing: (label) => ta('processing', { label }),
+          close: ta('close'),
+        },
       }}
       form={
         <>
@@ -157,7 +166,7 @@ export function AssistSection({
                 <span>{t('densityLabel')}</span>
               </label>
               {useDensity && (
-                <span className="semiont-form-field__info">{density} per 2000 words</span>
+                <span className="semiont-form-field__info">{t('densityPerWords', { density })}</span>
               )}
             </div>
 

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

@@ -19,8 +19,12 @@ export interface AssistShellProps {
    * Pass-through config for the progress renderer (cancel/dismiss wiring,
    * translations, percent bar). Dismiss policy lives HERE: the shell forwards
    * `onDismiss` only once the assist is no longer running.
+   *
+   * Required because `translations` is: the shell renders the progress display
+   * itself, so a caller that omitted this would render untranslated chrome —
+   * the failure Lane A exists to make impossible.
    */
-  progressProps?: Omit<AssistProgressProps, 'progress' | 'dataType'>;
+  progressProps: Omit<AssistProgressProps, 'progress' | 'dataType'>;
 }
 
 /**

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

@@ -6,6 +6,7 @@ import type { SemiontSession } from '@semiont/sdk';
 import { useSessionEventSubscriptions } from '../../../hooks/useSessionEventSubscriptions';
 import type { RouteBuilder, LinkComponentProps } from '../../../contexts/RoutingContext';
 import { AssistShell } from './AssistShell';
+import { EntityFoundLog } from '../../EntityFoundLog';
 import { ReferenceEntry } from './ReferenceEntry';
 import type { components, Selector } from '@semiont/core';
 import { getTextPositionSelector, getTargetSelector } from '@semiont/core';
@@ -121,6 +122,9 @@ export function ReferencesPanel({
   sourceLanguage,
 }: Props) {
   const t = useTranslations('ReferencesPanel');
+  // Chrome shared by every assist surface (heading, current-work line, dismiss)
+  // lives in one namespace so the same words aren't re-translated per panel.
+  const ta = useTranslations('AssistProgress');
   const [selectedEntityTypes, setSelectedEntityTypes] = useState<string[]>([]);
   const [lastAnnotationLog, setLastDetectionLog] = useState<Array<{ entityType: string; foundCount: number }> | null>(null);
   const [pendingEntityTypes, setPendingEntityTypes] = useState<string[]>([]);
@@ -375,24 +379,19 @@ export function ReferencesPanel({
                 failed: t('failed'),
                 found: (count) => t('found', { count }),
                 current: (entityType) => t('current', { entityType }),
-                close: t('closeProgress'),
+                paramsTitle: ta('paramsTitle'),
+                processing: (label) => ta('processing', { label }),
+                close: ta('close'),
               },
             }}
             form={
               <>
                 {/* Completed annotation log - shown after completion */}
-                {lastAnnotationLog && lastAnnotationLog.length > 0 && (
-                  <div className="semiont-assist-widget__log">
-                    <div className="semiont-assist-widget__log-items">
-                      {lastAnnotationLog.map((item, index) => (
-                        <div key={index} className="semiont-assist-widget__log-item">
-                          <span className="semiont-assist-widget__log-check">✓</span>
-                          <span className="semiont-assist-widget__log-type">{item.entityType}:</span>
-                          <span>{t('found', { count: item.foundCount })}</span>
-                        </div>
-                      ))}
-                    </div>
-                  </div>
+                {lastAnnotationLog && (
+                  <EntityFoundLog
+                    entries={lastAnnotationLog}
+                    formatFound={(count) => t('found', { count })}
+                  />
                 )}
 
                 {/* Entity Types Selection */}