@semiont/react-ui 0.5.24 → 0.5.25

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

@@ -1,10 +1,10 @@
 'use client';
 
 import React, { useRef, useState, useCallback, useEffect, useMemo } from 'react';
-import type { Annotation, AnchorRect } from '@semiont/core';
+import type { Annotation, AnchorRect, AnchoredText } from '@semiont/core';
 import { resourceId as toResourceId } from '@semiont/core';
 import { toViewportAnchorRect } from '../../lib/anchor-rect';
-import { createFragmentSelector } from '@semiont/core';
+import { createFragmentSelector, anchorRuns, isTextRun, textUnder } from '@semiont/core';
 import { rectsForPage } from './rects-for-page';
 import { createHoverHandlers, type SemiontSession } from '@semiont/sdk';
 import type { SelectionMotivation } from '../annotation/AnnotateToolbar';
@@ -61,7 +61,7 @@ interface PdfAnnotationCanvasProps {
  * PDF annotation canvas with page navigation and rectangle drawing
  *
  * @emits browse:click - Annotation clicked on PDF. Payload: { annotationId: string, motivation: Motivation }
- * @emits mark:requested - New annotation drawn on PDF. Payload: { selector: FragmentSelector, motivation: SelectionMotivation }
+ * @emits mark:requested - New annotation drawn on PDF. Payload: { selector: [FragmentSelector, TextQuoteSelector?], motivation: SelectionMotivation } — the quote is the text under the rectangle, omitted when the page has no text layer
  * @emits beckon:hover - Annotation hovered or unhovered. Payload: { annotationId: string | null }
  */
 export function PdfAnnotationCanvas({
@@ -83,6 +83,13 @@ export function PdfAnnotationCanvas({
   const [isLoading, setIsLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [pageDimensions, setPageDimensions] = useState<{ width: number; height: number } | null>(null);
+  /**
+   * The current page's text and per-run geometry, read once when the page
+   * loads so a drag can be quoted without a round trip. Null while the page
+   * is loading; `items` is empty on a scanned page, which has no text layer
+   * for the browser to read.
+   */
+  const [pageAnchored, setPageAnchored] = useState<AnchoredText | null>(null);
   const [displayDimensions, setDisplayDimensions] = useState<{ width: number; height: number } | null>(null);
   const [scale] = useState(1.5); // Fixed scale for better quality
 
@@ -125,6 +132,36 @@ export function PdfAnnotationCanvas({
     };
   }, [pdfUrl]);
 
+  /**
+   * The server-derived map, fetched once per document rather than once per
+   * page-load effect (PERSIST-ANCHORS P4). The map is WHOLE-RESOURCE — one
+   * artifact covering every page — so re-reading it from the per-page effect
+   * meant a full refetch and re-decode on every page turn; on a 400-page scan
+   * that is one decode per interaction instead of one per document.
+   *
+   * The cache holds the in-flight promise so concurrent page loads share one
+   * fetch. Answers cache — including "no map" and a stored decline, which are
+   * definitive — but a transport failure clears the entry, so the next page
+   * load retries instead of pinning the whole document to geometry-only.
+   */
+  const resourceAnchoredRef = useRef<{ uri: string; outcome: Promise<AnchoredText | null> } | null>(null);
+  const fetchResourceAnchored = useCallback((): Promise<AnchoredText | null> => {
+    if (!session) return Promise.resolve(null); // no session yet — don't cache its absence
+    const cached = resourceAnchoredRef.current;
+    if (cached && cached.uri === resourceUri) return cached.outcome;
+
+    const uri = resourceUri;
+    const outcome = session.client.browse.resourceAnchoredText(toResourceId(uri)).then(
+      (served) => (served && !('declined' in served) ? served : null),
+      () => {
+        if (resourceAnchoredRef.current?.uri === uri) resourceAnchoredRef.current = null;
+        return null;
+      },
+    );
+    resourceAnchoredRef.current = { uri, outcome };
+    return outcome;
+  }, [session, resourceUri]);
+
   // Load current page when page number changes
   useEffect(() => {
     if (!pdfDoc) return;
@@ -132,6 +169,49 @@ export function PdfAnnotationCanvas({
     let cancelled = false;
     const doc = pdfDoc;
 
+    // Never quote the previous page's text under this page's rectangles.
+    setPageAnchored(null);
+
+    /**
+     * The map a rectangle on this page quotes from, or null when there is
+     * none to be had.
+     *
+     * Never rejects, which is what lets the render run alongside it: quoting
+     * is the optional half of loading a page, so a failure here degrades to
+     * geometry-only rather than reaching the caller's error path. It is also
+     * the only reason `Promise.all` below is safe — a rejection from either
+     * side would leave the other promise dangling, and only the render can
+     * reject.
+     */
+    async function resolveAnchored(page: Awaited<ReturnType<typeof doc.getPage>>): Promise<AnchoredText | null> {
+      try {
+        // The page's text layer, read once here rather than at drag time —
+        // `handleMouseUp` stays synchronous, and a native page costs nothing
+        // extra since pdf.js already parsed it to draw the page.
+        const runs = (await page.getTextContent()).items.filter(isTextRun);
+        if (runs.length > 0) return anchorRuns(runs, pageNumber);
+
+        // No runs means a scanned page: the characters exist only as pixels
+        // and pdf.js has nothing to give. The server derived a map at ingest,
+        // so ask for it rather than leaving the annotation anonymous.
+        // Whole-resource — served once per document via the cache above —
+        // and `textUnder` filters by page: the same shape the native branch
+        // produces, so nothing downstream branches.
+        //
+        // `null` is the ordinary answer for a document that has no map and
+        // never will; a failure is equally non-fatal. Either way the
+        // annotation ships with geometry only, which is what shipped before
+        // this existed. The served record is the full extraction outcome
+        // (PERSIST-ANCHORS D1); a stored decline means extraction ran and
+        // found nothing to anchor — for this canvas the same degradation as
+        // no map at all. A success outcome IS the anchoring shape, plus
+        // provenance this canvas does not read.
+        return await fetchResourceAnchored();
+      } catch {
+        return null;
+      }
+    }
+
     async function loadPage() {
       try {
         const page = await doc.getPage(pageNumber);
@@ -145,11 +225,21 @@ export function PdfAnnotationCanvas({
           height: viewport.height
         });
 
-        // Render page to image
-        const { dataUrl } = await renderPdfPageToDataUrl(page, scale);
+        // Anchoring and rendering are independent, and only one of them the
+        // reader is waiting on. Sequencing them put a network round-trip in
+        // front of the pixels on exactly the documents that need it most: a
+        // scanned page fetches its map from the server, and rendering behind
+        // that await is how "failing to quote it must not fail to show it"
+        // became true of errors but not of latency. Started together, the
+        // page appears on its own schedule.
+        const [anchored, { dataUrl }] = await Promise.all([
+          resolveAnchored(page),
+          renderPdfPageToDataUrl(page, scale),
+        ]);
 
         if (cancelled) return;
 
+        setPageAnchored(anchored);
         setPageImageUrl(dataUrl);
       } catch (err) {
         if (cancelled) return;
@@ -164,7 +254,7 @@ export function PdfAnnotationCanvas({
     return () => {
       cancelled = true;
     };
-  }, [pdfDoc, pageNumber, scale]);
+  }, [pdfDoc, pageNumber, scale, fetchResourceAnchored]);
 
   // Update display dimensions on resize
   useEffect(() => {
@@ -318,15 +408,25 @@ export function PdfAnnotationCanvas({
     // Create FragmentSelector
     const fragmentSelector = createFragmentSelector(pdfCoord);
 
+    // What the box was drawn around. Without it the annotation is a rectangle
+    // with no memory of its own content: the panel entry is blank, search over
+    // annotation text misses it, and an export has nothing to print. Empty on a
+    // scanned page or over an image — emit no quote at all rather than an empty
+    // one, which would assert the box was drawn around nothing.
+    const quoted = pageAnchored ? textUnder(pageAnchored, pdfCoord) : '';
+
     // Emit annotation:requested event with FragmentSelector
     if (selectedMotivation) {
       session.client.mark.request(
         toResourceId(resourceUri),
-        {
-          type: 'FragmentSelector',
-          conformsTo: 'http://tools.ietf.org/rfc/rfc3778',
-          value: fragmentSelector,
-        },
+        [
+          {
+            type: 'FragmentSelector',
+            conformsTo: 'http://tools.ietf.org/rfc/rfc3778',
+            value: fragmentSelector,
+          },
+          ...(quoted ? [{ type: 'TextQuoteSelector' as const, exact: quoted }] : []),
+        ],
         selectedMotivation,
       );
     }
@@ -336,7 +436,7 @@ export function PdfAnnotationCanvas({
     setIsDrawing(false);
     // Note: We keep selection so the preview remains visible
     // It will be cleared when drawingMode changes or user starts new selection
-  }, [isDrawing, selection, pageNumber, pageDimensions, displayDimensions, selectedMotivation, existingAnnotations, session, resourceUri]);
+  }, [isDrawing, selection, pageNumber, pageDimensions, displayDimensions, selectedMotivation, existingAnnotations, session, resourceUri, pageAnchored]);
 
   // Every FragmentSelector rect on the current page — one per line for a
   // multi-line (multi-selector) annotation, exactly one for a manual annotation.

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

@@ -13,9 +13,35 @@ import userEvent from '@testing-library/user-event';
 import { PdfAnnotationCanvas } from '../PdfAnnotationCanvas';
 import { resourceId, annotationId, parseFragmentSelector } from '@semiont/core';
 import { pdfToCanvasCoordinates } from '../../../lib/pdf-coordinates';
+import { loadPdfDocument, renderPdfPageToDataUrl } from '../../../lib/browser-pdfjs';
 
 import type { Annotation } from '@semiont/core';
 
+// The page's text layer, as pdf.js reports it. Geometry is PDF points,
+// bottom-left origin: "Hello world" sits on one line at y=700, "elsewhere" a
+// hundred points below it.
+// vi.hoisted: vi.mock's factory is lifted above these declarations.
+const { MOCK_TEXT_ITEMS } = vi.hoisted(() => ({
+  MOCK_TEXT_ITEMS: [
+    { str: 'Hello', transform: [1, 0, 0, 1, 72, 700], width: 30, height: 12, hasEOL: false },
+    { str: 'world', transform: [1, 0, 0, 1, 106, 700], width: 32, height: 12, hasEOL: true },
+    { str: 'elsewhere', transform: [1, 0, 0, 1, 72, 600], width: 54, height: 12, hasEOL: true },
+  ],
+}));
+
+const mockPage = (textItems: unknown[]) => ({
+  getViewport: vi.fn().mockReturnValue({
+    width: 612,
+    height: 792,
+    scale: 1.0,
+    rotation: 0
+  }),
+  render: vi.fn().mockReturnValue({
+    promise: Promise.resolve()
+  }),
+  getTextContent: vi.fn().mockResolvedValue({ items: textItems })
+});
+
 // Mock browser-pdfjs module
 vi.mock('../../../lib/browser-pdfjs', () => ({
   loadPdfDocument: vi.fn().mockResolvedValue({
@@ -29,7 +55,8 @@ vi.mock('../../../lib/browser-pdfjs', () => ({
       }),
       render: vi.fn().mockReturnValue({
         promise: Promise.resolve()
-      })
+      }),
+      getTextContent: vi.fn().mockResolvedValue({ items: MOCK_TEXT_ITEMS })
     })
   }),
   renderPdfPageToDataUrl: vi.fn().mockResolvedValue({
@@ -313,6 +340,225 @@ describe('PdfAnnotationCanvas', () => {
     });
   });
 
+  /**
+   * Drives the drag → mark.request path far enough to inspect the selector.
+   * `drag` is in canvas pixels; at scale 1 with a 612×792 page these are also
+   * display coordinates, since jsdom's getBoundingClientRect returns zeros.
+   */
+  async function drawRectangle(
+    drag: { fromX: number; fromY: number; toX: number; toY: number },
+  ) {
+    const request = vi.fn();
+    const session = {
+      client: { mark: { request }, beckon: { hover: vi.fn() } },
+    } as unknown as import('@semiont/sdk').SemiontSession;
+
+    render(
+      <PdfAnnotationCanvas resourceUri="res-1"
+        pdfUrl={mockPdfUrl}
+        drawingMode="rectangle"
+        selectedMotivation="highlighting"
+        session={session}
+      />
+    );
+
+    await waitFor(() => {
+      const img = document.querySelector('.semiont-pdf-annotation-canvas__image');
+      expect(img).toBeInTheDocument();
+    });
+
+    const img = document.querySelector('.semiont-pdf-annotation-canvas__image') as HTMLImageElement;
+    Object.defineProperty(img, 'clientWidth', { value: 612, configurable: true });
+    Object.defineProperty(img, 'clientHeight', { value: 792, configurable: true });
+    fireEvent.load(img);
+
+    const container = document.querySelector('.semiont-pdf-annotation-canvas__container')!;
+    fireEvent.mouseDown(container, { clientX: drag.fromX, clientY: drag.fromY });
+    fireEvent.mouseMove(container, { clientX: drag.toX, clientY: drag.toY });
+    fireEvent.mouseUp(container, { clientX: drag.toX, clientY: drag.toY });
+
+    return request;
+  }
+
+  // The manual-annotation capture gap (.plans/PDF-MANUAL-ANNOTATION-TEXT.md):
+  // a hand-drawn rectangle stored geometry and nothing else, so every panel
+  // that quotes an annotation showed it blank.
+  test('a drawn rectangle carries the text it was drawn around', async () => {
+    // The "Hello world" line in canvas space: PDF y=700..712 flips to
+    // canvas y=80..92 on a 792pt page. Drag a box a little larger than it.
+    const line = pdfToCanvasCoordinates(
+      { page: 1, x: 72, y: 700, width: 60, height: 12 }, 792, 1.0,
+    );
+    const request = await drawRectangle({
+      fromX: line.x - 2,
+      fromY: line.y - 2,
+      toX: line.x + line.width + 8,
+      toY: line.y + line.height + 4,
+    });
+
+    await waitFor(() => expect(request).toHaveBeenCalledTimes(1));
+
+    const [source, selector, motivation] = request.mock.calls[0];
+    expect(source).toBe(resourceId('res-1'));
+    expect(motivation).toBe('highlighting');
+    expect(selector).toEqual([
+      {
+        type: 'FragmentSelector',
+        conformsTo: 'http://tools.ietf.org/rfc/rfc3778',
+        value: expect.stringContaining('page=1&viewrect='),
+      },
+      { type: 'TextQuoteSelector', exact: 'Hello world' },
+    ]);
+  });
+
+  test('a rectangle over blank space carries geometry only', async () => {
+    // Between the two lines of text — nothing under the box. An empty-string
+    // quote would assert the box was drawn around nothing, so emit no quote.
+    const request = await drawRectangle({ fromX: 40, fromY: 120, toX: 200, toY: 150 });
+
+    await waitFor(() => expect(request).toHaveBeenCalledTimes(1));
+
+    const selector = request.mock.calls[0][1];
+    expect(selector).toHaveLength(1);
+    expect(selector[0].type).toBe('FragmentSelector');
+  });
+
+  // Phase 2 of .plans/PDF-MANUAL-ANNOTATION-TEXT.md. A scanned page has no text
+  // in the browser, but the server derived one at ingest and serves it through
+  // `browse.resourceAnchoredText`. Same `AnchoredText` shape either way, so
+  // `textUnder` and the drag handler do not branch — only the source does.
+  test('a scanned page quotes from the map the server derived', async () => {
+    vi.mocked(loadPdfDocument).mockResolvedValueOnce({
+      numPages: 3,
+      getPage: vi.fn().mockResolvedValue(mockPage([])),
+    } as unknown as Awaited<ReturnType<typeof loadPdfDocument>>);
+
+    const request = vi.fn();
+    const session = {
+      client: {
+        mark: { request },
+        beckon: { hover: vi.fn() },
+        browse: {
+          resourceAnchoredText: vi.fn().mockResolvedValue({
+            text: 'Hello world again',
+            items: [
+              { start: 0, end: 5, page: 1, x: 72, y: 700, width: 30, height: 12 },
+              { start: 6, end: 11, page: 1, x: 106, y: 700, width: 32, height: 12 },
+            ],
+          }),
+        },
+      },
+    } as unknown as import('@semiont/sdk').SemiontSession;
+
+    render(
+      <PdfAnnotationCanvas resourceUri="res-1"
+        pdfUrl={mockPdfUrl}
+        drawingMode="rectangle"
+        selectedMotivation="highlighting"
+        session={session}
+      />
+    );
+
+    await waitFor(() => {
+      expect(document.querySelector('.semiont-pdf-annotation-canvas__image')).toBeInTheDocument();
+    });
+    const img = document.querySelector('.semiont-pdf-annotation-canvas__image') as HTMLImageElement;
+    Object.defineProperty(img, 'clientWidth', { value: 612, configurable: true });
+    Object.defineProperty(img, 'clientHeight', { value: 792, configurable: true });
+    fireEvent.load(img);
+
+    const line = pdfToCanvasCoordinates({ page: 1, x: 72, y: 700, width: 66, height: 12 }, 792, 1.0);
+    const container = document.querySelector('.semiont-pdf-annotation-canvas__container')!;
+    fireEvent.mouseDown(container, { clientX: line.x - 2, clientY: line.y - 2 });
+    fireEvent.mouseMove(container, { clientX: line.x + line.width + 8, clientY: line.y + line.height + 4 });
+    fireEvent.mouseUp(container, { clientX: line.x + line.width + 8, clientY: line.y + line.height + 4 });
+
+    await waitFor(() => expect(request).toHaveBeenCalledTimes(1));
+    expect(request.mock.calls[0][1]).toEqual([
+      expect.objectContaining({ type: 'FragmentSelector' }),
+      { type: 'TextQuoteSelector', exact: 'Hello world' },
+    ]);
+  });
+
+  // PERSIST-ANCHORS P4. The server map is WHOLE-RESOURCE — one artifact
+  // covering every page — so fetching it from inside the per-page load
+  // effect refetched and re-decoded the entire document's geometry on every
+  // page turn. On a 400-page scan that is the difference between one decode
+  // and one per interaction.
+  test('the whole-resource map is fetched once per document, not once per page-turn', async () => {
+    vi.mocked(loadPdfDocument).mockResolvedValueOnce({
+      numPages: 3,
+      getPage: vi.fn().mockResolvedValue(mockPage([])),
+    } as unknown as Awaited<ReturnType<typeof loadPdfDocument>>);
+
+    const resourceAnchoredText = vi.fn().mockResolvedValue({
+      text: 'Hello world again',
+      items: [
+        { start: 0, end: 5, page: 1, x: 72, y: 700, width: 30, height: 12 },
+        { start: 6, end: 11, page: 2, x: 106, y: 700, width: 32, height: 12 },
+      ],
+    });
+    const session = {
+      client: { beckon: { hover: vi.fn() }, browse: { resourceAnchoredText } },
+    } as unknown as import('@semiont/sdk').SemiontSession;
+
+    render(
+      <PdfAnnotationCanvas resourceUri="res-1"
+        pdfUrl={mockPdfUrl}
+        drawingMode={null}
+        session={session}
+      />
+    );
+
+    const user = userEvent.setup();
+    await waitFor(() => {
+      expect(screen.getByText(/page 1 of 3/i)).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole('button', { name: /next/i }));
+    await waitFor(() => {
+      expect(screen.getByText(/page 2 of 3/i)).toBeInTheDocument();
+    });
+    await user.click(screen.getByRole('button', { name: /next/i }));
+    await waitFor(() => {
+      expect(screen.getByText(/page 3 of 3/i)).toBeInTheDocument();
+    });
+
+    // The render half runs once per page load and starts alongside the
+    // anchoring half (Promise.all), so three render calls prove all three
+    // page-load effects ran to the point of resolving their map.
+    await waitFor(() => {
+      expect(vi.mocked(renderPdfPageToDataUrl)).toHaveBeenCalledTimes(3);
+    });
+
+    expect(resourceAnchoredText).toHaveBeenCalledTimes(1);
+  });
+
+  test('a scanned page with no server map carries geometry only', async () => {
+    // Class B: pdf.js returns no runs, so the browser cannot do the job and
+    // the annotation stays geometry-only pending async enrichment (Phase 2).
+    vi.mocked(loadPdfDocument).mockResolvedValueOnce({
+      numPages: 3,
+      getPage: vi.fn().mockResolvedValue(mockPage([])),
+    } as unknown as Awaited<ReturnType<typeof loadPdfDocument>>);
+
+    const line = pdfToCanvasCoordinates(
+      { page: 1, x: 72, y: 700, width: 60, height: 12 }, 792, 1.0,
+    );
+    const request = await drawRectangle({
+      fromX: line.x - 2,
+      fromY: line.y - 2,
+      toX: line.x + line.width + 8,
+      toY: line.y + line.height + 4,
+    });
+
+    await waitFor(() => expect(request).toHaveBeenCalledTimes(1));
+
+    const selector = request.mock.calls[0][1];
+    expect(selector).toHaveLength(1);
+    expect(selector[0].type).toBe('FragmentSelector');
+  });
+
   test('accepts a drawing gesture without throwing when drawing mode is active', async () => {
     render(
       <PdfAnnotationCanvas resourceUri="res-1"

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');
+  });
+});