@semiont/react-ui 0.5.23 → 0.5.25

package/src/components/__tests__/AssistProgress.test.tsx

@@ -7,13 +7,19 @@
  * cancel/dismiss arrive as callbacks the caller wires (job.cancelRequest /
  * mark.dismissProgress). Feature blocks are data-presence-driven so each call
  * site keeps its current visuals by passing what it always had.
+ *
+ * i18n contract (ASSIST-SURFACE-WARTS Lane A): every string this component
+ * renders comes from `translations`. There are NO English fallbacks — a
+ * missing key must be a type error at the call site, not a silent English
+ * leak in a Japanese UI. Tests use key-echo strings ('tr.complete') so an
+ * assertion failing means "rendered something other than what was passed".
  */
 import { describe, it, expect, vi } from 'vitest';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import '@testing-library/jest-dom';
 import type { components } from '@semiont/core';
-import { AssistProgress } from '../AssistProgress';
+import { AssistProgress, type AssistProgressTranslations } from '../AssistProgress';
 
 type JobProgress = components['schemas']['JobProgress'];
 
@@ -21,13 +27,26 @@ const running = (over: Partial<JobProgress> = {}): JobProgress => ({
   stage: 'analyzing', percentage: 40, message: 'working on it', ...over,
 });
 
+/** Every required key, echoing its own name; override per test. */
+const T = (over: Partial<AssistProgressTranslations> = {}): AssistProgressTranslations => ({
+  cancel: 'tr.cancel',
+  inProgress: 'tr.inProgress',
+  complete: 'tr.complete',
+  failed: 'tr.failed',
+  close: 'tr.close',
+  paramsTitle: 'tr.paramsTitle',
+  processing: (label: string) => `tr.processing(${label})`,
+  ...over,
+});
+
 describe('AssistProgress', () => {
   it('renders provider-free: message, params, and data hooks', () => {
     const { container } = render(
       <AssistProgress
         progress={running({ requestParams: [{ label: 'Density', value: '5' }] })}
         dataType="comment"
-             />,
+        translations={T()}
+      />,
     );
     expect(screen.getByText('working on it')).toBeInTheDocument();
     expect(screen.getByText(/Density/)).toBeInTheDocument();
@@ -37,12 +56,24 @@ describe('AssistProgress', () => {
     expect(root).toHaveAttribute('data-status', 'analyzing');
   });
 
+  it('renders the request-parameters title from translations, never a literal', () => {
+    render(
+      <AssistProgress
+        progress={running({ requestParams: [{ label: 'Density', value: '5' }] })}
+        dataType="comment"
+        translations={T()}
+      />,
+    );
+    expect(screen.getByText('tr.paramsTitle')).toBeInTheDocument();
+    expect(screen.queryByText('Request Parameters:')).not.toBeInTheDocument();
+  });
+
   it('renders a title header only when given one', () => {
     const { rerender } = render(
-      <AssistProgress progress={running()} dataType="reference" translations={{ title: 'Annotating Entity References' }} />,
+      <AssistProgress progress={running()} dataType="reference" translations={T({ title: 'Annotating Entity References' })} />,
     );
     expect(screen.getByText('Annotating Entity References')).toBeInTheDocument();
-    rerender(<AssistProgress progress={running()} dataType="comment" />);
+    rerender(<AssistProgress progress={running()} dataType="comment" translations={T()} />);
     expect(screen.queryByText('Annotating Entity References')).not.toBeInTheDocument();
   });
 
@@ -50,7 +81,7 @@ describe('AssistProgress', () => {
     // Cancel lives in the title header — both flows that offer cancel
     // (reference detection, generation) render the titled profile.
     const onCancel = vi.fn();
-    const tr = { title: 'Generating Resource', cancel: 'Cancel Job' };
+    const tr = T({ title: 'Generating Resource', cancel: 'Cancel Job' });
     const { rerender } = render(
       <AssistProgress progress={running()} dataType="generation" onCancel={onCancel} translations={tr} />,
     );
@@ -68,13 +99,20 @@ describe('AssistProgress', () => {
     expect(screen.queryByTitle('Cancel Job')).not.toBeInTheDocument();
   });
 
-  it('stage branching: complete shows ✅ + complete copy, error shows ❌ + message', () => {
+  it('stage branching: both terminal stages prefer the job message, then the translated copy', () => {
+    // The job composes detail no static string can ("Created 14 highlights"),
+    // so it wins on BOTH terminal stages; the translated copy covers the
+    // required-but-empty message case (pinned below).
     const { rerender } = render(
-      <AssistProgress progress={running({ stage: 'complete' })} dataType="reference" translations={{ complete: 'All done!' }} />,
+      <AssistProgress progress={running({ stage: 'complete' })} dataType="reference" translations={T({ complete: 'All done!' })} />,
+    );
+    expect(screen.getByText('working on it')).toBeInTheDocument();
+    rerender(
+      <AssistProgress progress={running({ stage: 'complete', message: '' })} dataType="reference" translations={T({ complete: 'All done!' })} />,
     );
     expect(screen.getByText('All done!')).toBeInTheDocument();
     rerender(
-      <AssistProgress progress={running({ stage: 'error', message: 'it broke' })} dataType="reference" translations={{ failed: 'Failed' }} />,
+      <AssistProgress progress={running({ stage: 'error', message: 'it broke' })} dataType="reference" translations={T({ failed: 'Failed' })} />,
     );
     expect(screen.getByText('it broke')).toBeInTheDocument();
   });
@@ -83,7 +121,7 @@ describe('AssistProgress', () => {
     render(
       <AssistProgress
         progress={running({ completedEntityTypes: [{ entityType: 'Person', foundCount: 3 }] })}
-        dataType="reference" translations={{ found: (n) => `Found ${n}` }}
+        dataType="reference" translations={T({ found: (n) => `Found ${n}` })}
       />,
     );
     expect(screen.getByText('Person:')).toBeInTheDocument();
@@ -94,55 +132,75 @@ describe('AssistProgress', () => {
     const { rerender } = render(
       <AssistProgress
         progress={running({ currentEntityType: 'Location' })}
-        dataType="reference" translations={{ current: (l) => `Processing: ${l}` }}
+        dataType="reference" translations={T({ current: (l) => `Current: ${l}` })}
       />,
     );
-    expect(screen.getByText('Processing: Location')).toBeInTheDocument();
+    expect(screen.getByText('Current: Location')).toBeInTheDocument();
     rerender(
       <AssistProgress
         progress={running({ currentCategory: 'Rule', processedCategories: 2, totalCategories: 5 })}
-        dataType="tag"      />,
+        dataType="tag" translations={T()}
+      />,
     );
     expect(screen.getByText(/Rule/)).toBeInTheDocument();
     expect(screen.getByText(/2\/5/)).toBeInTheDocument();
   });
 
+  it('falls back to the generic processing formatter — never the English literal', () => {
+    // The reference flow passes its own `current` wording; every other flow
+    // (tag categories, and any flow without one) uses `processing`. Neither
+    // path may render a hardcoded "Processing: ".
+    const { rerender } = render(
+      <AssistProgress progress={running({ currentEntityType: 'Location' })} dataType="reference" translations={T()} />,
+    );
+    expect(screen.getByText('tr.processing(Location)')).toBeInTheDocument();
+    rerender(
+      <AssistProgress progress={running({ currentCategory: 'Rule' })} dataType="tag" translations={T()} />,
+    );
+    expect(screen.getByText(/tr\.processing\(Rule\)/)).toBeInTheDocument();
+    expect(screen.queryByText(/^Processing: /)).not.toBeInTheDocument();
+  });
+
   it('renders the percentage bar only when opted in', () => {
     const { container, rerender } = render(
-      <AssistProgress progress={running({ percentage: 40 })} dataType="tag" showPercentBar />,
+      <AssistProgress progress={running({ percentage: 40 })} dataType="tag" showPercentBar translations={T()} />,
     );
     const fill = container.querySelector('.semiont-progress-bar__fill');
     expect(fill).toBeInTheDocument();
     expect(fill).toHaveStyle({ width: '40%' });
     rerender(
-      <AssistProgress progress={running({ percentage: 40 })} dataType="reference" />,
+      <AssistProgress progress={running({ percentage: 40 })} dataType="reference" translations={T()} />,
     );
     expect(container.querySelector('.semiont-progress-bar__fill')).not.toBeInTheDocument();
   });
 
-  it('cancel and dismiss carry accessible names, with safe fallbacks when untranslated', () => {
-    // ✕ / × glyphs alone are meaningless to screen readers; the controls must
-    // have an accessible name even when a caller forgets the translations.
+  it('cancel and dismiss take their accessible names from translations', () => {
+    // ✕ / × glyphs alone are meaningless to screen readers, and an English
+    // fallback is meaningless to a non-English reader. The labels are
+    // required keys, so there is nothing to fall back TO.
     render(
       <AssistProgress progress={running()} dataType="generation"
         onCancel={vi.fn()} onDismiss={vi.fn()}
-        translations={{ title: 'Generating' }} />,
+        translations={T({ title: 'Generating' })} />,
     );
-    expect(screen.getByLabelText('Cancel')).toBeInTheDocument();
-    expect(screen.getByLabelText('Dismiss')).toBeInTheDocument();
+    expect(screen.getByLabelText('tr.cancel')).toBeInTheDocument();
+    expect(screen.getByLabelText('tr.close')).toBeInTheDocument();
+    expect(screen.queryByLabelText('Cancel')).not.toBeInTheDocument();
+    expect(screen.queryByLabelText('Dismiss')).not.toBeInTheDocument();
   });
 
-  it('terminal stages never render a blank status line', () => {
+  it('terminal stages never render a blank status line, and never an English one', () => {
     // JobProgress.message is required but can be '' — a terminal display with
-    // no text at all is worse than a generic word.
+    // no text at all is worse than a generic word, but that word must be the
+    // caller's translated one.
     const { rerender } = render(
-      <AssistProgress progress={running({ stage: 'complete', message: '' })} dataType="reference" />,
+      <AssistProgress progress={running({ stage: 'complete', message: '' })} dataType="reference" translations={T()} />,
     );
-    expect(screen.getByText('Complete')).toBeInTheDocument();
+    expect(screen.getByText('tr.complete')).toBeInTheDocument();
     rerender(
-      <AssistProgress progress={running({ stage: 'error', message: '' })} dataType="reference" />,
+      <AssistProgress progress={running({ stage: 'error', message: '' })} dataType="reference" translations={T()} />,
     );
-    expect(screen.getByText('Failed')).toBeInTheDocument();
+    expect(screen.getByText('tr.failed')).toBeInTheDocument();
   });
 
   it('renders dismiss whenever the caller offers it (WHEN is the caller\'s policy)', async () => {
@@ -151,12 +209,12 @@ describe('AssistProgress', () => {
     // "callback present → affordance rendered".
     const onDismiss = vi.fn();
     const { rerender } = render(
-      <AssistProgress progress={running()} dataType="highlight" translations={{ close: 'Close' }} />,
+      <AssistProgress progress={running()} dataType="highlight" translations={T({ close: 'Close' })} />,
     );
     expect(screen.queryByLabelText('Close')).not.toBeInTheDocument();
     rerender(
       <AssistProgress progress={running()} dataType="highlight"
-        onDismiss={onDismiss} translations={{ close: 'Close' }} />,
+        onDismiss={onDismiss} translations={T({ close: 'Close' })} />,
     );
     await userEvent.click(screen.getByLabelText('Close'));
     expect(onDismiss).toHaveBeenCalledOnce();

package/src/components/annotation-popups/JsonLdView.tsx

@@ -7,7 +7,7 @@ import { json } from '@codemirror/lang-json';
 import { oneDark } from '@codemirror/theme-one-dark';
 import { syntaxHighlighting } from '@codemirror/language';
 import { jsonLightTheme, jsonLightHighlightStyle } from '../../lib/codemirror-json-theme';
-import { useLineNumbers } from '../../hooks/useLineNumbers';
+import { useLineNumbers } from '../../contexts/LineNumbersContext';
 
 import type { Annotation } from '@semiont/core';
 

package/src/components/annotation-popups/__tests__/JsonLdView.test.tsx

@@ -47,9 +47,15 @@ vi.mock('../../../lib/codemirror-json-theme', () => ({
   jsonLightHighlightStyle: {},
 }));
 
-vi.mock('@/hooks/useLineNumbers');
+vi.mock('@/contexts/LineNumbersContext', async () => {
+  const actual = await vi.importActual('@/contexts/LineNumbersContext');
+  // Mock ONLY the hook: renderWithProviders mounts the real
+  // LineNumbersProvider, which an auto-mock would swallow (rendering
+  // nothing), while these tests want a fixed showLineNumbers value.
+  return { ...actual, useLineNumbers: vi.fn() };
+});
 
-import { useLineNumbers } from '@/hooks/useLineNumbers';
+import { useLineNumbers } from '@/contexts/LineNumbersContext';
 import { renderWithProviders } from '../../../test-utils';
 import { JsonLdView } from '../JsonLdView';
 

package/src/components/modals/ReferenceWizardModal.tsx

@@ -3,6 +3,7 @@
 import { useState, useEffect, useCallback } from 'react';
 import { Dialog, DialogPanel, DialogTitle, Transition, TransitionChild } from '@headlessui/react';
 import type { GatheredContext } from '@semiont/core';
+import { uuidV4 } from '@semiont/core';
 import { useSemiont } from '../../session/SemiontProvider';
 import { useObservable } from '../../hooks/useObservable';
 import { useEventSubscription } from '../../contexts/useEventSubscription';
@@ -144,7 +145,7 @@ export function ReferenceWizardModal({
     setIsSearching(true);
     const contextWithHint = userHint ? { ...context, userHint } : context;
     session?.client.match.requestSearch({
-      correlationId: crypto.randomUUID(),
+      correlationId: uuidV4(),
       resourceId,
       referenceId: annotationId,
       context: contextWithHint,

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.