@semiont/react-ui 0.5.18 → 0.5.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/react-ui",
-  "version": "0.5.18",
+  "version": "0.5.20",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -122,9 +122,9 @@
     "directory": "packages/react-ui"
   },
   "dependencies": {
-    "@semiont/core": "0.5.18",
-    "@semiont/http-transport": "0.5.18",
-    "@semiont/sdk": "0.5.18",
+    "@semiont/core": "0.5.20",
+    "@semiont/http-transport": "0.5.20",
+    "@semiont/sdk": "0.5.20",
     "pdfjs-dist": "^6.1.200",
     "react-error-boundary": "^6.1.2",
     "react-markdown": "^10.1.0",

package/src/components/AssistProgress.tsx

@@ -0,0 +1,170 @@
+'use client';
+
+import type { components } from '@semiont/core';
+
+type JobProgress = components['schemas']['JobProgress'];
+
+export interface AssistProgressTranslations {
+  /** Header title (e.g. "Annotating Entity References" / "Generating Resource"). Omit for the headerless inline style. */
+  title?: string;
+  /** Cancel-button title attribute. */
+  cancel?: string;
+  /** Default in-progress status message (used when the job sends no `message`). */
+  inProgress?: string;
+  /** Status copy for the terminal 'complete' stage. */
+  complete?: string;
+  /** Fallback status copy for the terminal 'error' stage. */
+  failed?: string;
+  /** Completed entity-type log line (reference flow). */
+  found?: (count: number) => string;
+  /** Current-work detail line (reference flow). */
+  current?: (label: string) => string;
+  /** Dismiss-button label. */
+  close?: string;
+}
+
+export interface AssistProgressProps {
+  progress: JobProgress;
+  /** CSS `data-type` hook ('highlight' | 'comment' | … | 'reference' | 'tag' | 'generation'). */
+  dataType: string;
+  /** Cancel the underlying job — rendered while running when provided. Caller wires `client.job.cancelRequest(...)`. */
+  onCancel?: () => void;
+  /**
+   * Dismiss the display — rendered whenever provided. WHEN dismissal is
+   * offered is the caller's policy (AssistShell withholds the callback while
+   * the assist is still running). Caller wires `client.mark.dismissProgress()`.
+   */
+  onDismiss?: () => void;
+  /** Render the percentage bar (tag flow's visual; percentage itself comes from `progress`). */
+  showPercentBar?: boolean;
+  translations?: AssistProgressTranslations;
+}
+
+/**
+ * The one job-progress renderer (#7) — unifies the three previous shapes
+ * (AssistSection's inline block, the reference/generation widget, TaggingPanel's
+ * inline block). Presentational and provider-free: no session, no context —
+ * cancel/dismiss arrive as callbacks, so it renders identically on the page and
+ * in embeddable (bring-your-own-session) hosts. Feature blocks are
+ * data-presence-driven: each call site keeps its established visuals by passing
+ * the data and translations it always had.
+ */
+export function AssistProgress({
+  progress,
+  dataType,
+  onCancel,
+  onDismiss,
+  showPercentBar = false,
+  translations: tr = {},
+}: AssistProgressProps) {
+  const terminal = progress.stage === 'complete' || progress.stage === 'error';
+
+  return (
+    <div className="semiont-annotation-progress" data-status={progress.stage} data-type={dataType}>
+      {/* Header (title + cancel) — reference/generation style; omitted inline */}
+      {tr.title && (
+        <div className="semiont-annotation-header">
+          <h3 className="semiont-annotation-title">
+            <span className="semiont-annotation-sparkle">✨</span>
+            {tr.title}
+          </h3>
+          {onCancel && !terminal && (
+            <button
+              onClick={onCancel}
+              className="semiont-annotation-cancel"
+              title={tr.cancel || 'Cancel'}
+              aria-label={tr.cancel || 'Cancel'}
+              type="button"
+            >
+              ✕
+            </button>
+          )}
+        </div>
+      )}
+
+      {/* Request parameters */}
+      {progress.requestParams && progress.requestParams.length > 0 && (
+        <div className="semiont-annotation-progress__params" data-type={dataType}>
+          <div className="semiont-annotation-progress__params-title">Request Parameters:</div>
+          {progress.requestParams.map((param, idx) => (
+            <div key={idx} className="semiont-annotation-progress__param">
+              <span className="semiont-annotation-progress__param-label">{param.label}:</span> <span>{param.value}</span>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {/* Completed entity-type log (reference flow) */}
+      {tr.found && progress.completedEntityTypes && progress.completedEntityTypes.length > 0 && (
+        <div className="semiont-annotation-log">
+          {progress.completedEntityTypes.map((item, index) => (
+            <div key={index} className="semiont-annotation-log-item">
+              <span className="semiont-annotation-check">✓</span>
+              <span className="semiont-annotation-entity-type">{item.entityType}:</span>
+              <span>{tr.found!(item.foundCount)}</span>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {/* Status line with stage branching */}
+      <div className="semiont-annotation-progress__status">
+        {progress.stage === 'complete' ? (
+          <div className="semiont-annotation-progress__message">
+            <span className="semiont-annotation-progress__icon">✅</span>
+            {/* JobProgress.message is required but may be '' — never blank a terminal line. */}
+            <span>{tr.complete || progress.message || 'Complete'}</span>
+          </div>
+        ) : progress.stage === 'error' ? (
+          <div className="semiont-annotation-progress__message">
+            <span className="semiont-annotation-progress__icon">❌</span>
+            <span>{progress.message || tr.failed || 'Failed'}</span>
+          </div>
+        ) : (
+          <div className="semiont-annotation-progress__message">
+            <span className="semiont-annotation-progress__icon">✨</span>
+            <span>
+              {progress.message
+                || (progress.currentEntityType && tr.current ? tr.current(progress.currentEntityType) : tr.inProgress)}
+            </span>
+          </div>
+        )}
+
+        {/* Current-work detail while running */}
+        {!terminal && progress.currentEntityType && (
+          <div className="semiont-annotation-progress__details">
+            {tr.current ? tr.current(progress.currentEntityType) : `Processing: ${progress.currentEntityType}`}
+          </div>
+        )}
+        {!terminal && progress.currentCategory && (
+          <div className="semiont-annotation-progress__details">
+            Processing: {progress.currentCategory}
+            {progress.processedCategories !== undefined && progress.totalCategories !== undefined && (
+              <> ({progress.processedCategories}/{progress.totalCategories})</>
+            )}
+          </div>
+        )}
+
+        {/* Dismiss — rendered whenever the caller offers it */}
+        {onDismiss && (
+          <button
+            onClick={onDismiss}
+            className="semiont-annotation-progress__close"
+            aria-label={tr.close || 'Dismiss'}
+            title={tr.close || 'Dismiss'}
+            type="button"
+          >
+            ×
+          </button>
+        )}
+      </div>
+
+      {/* Percentage bar (tag flow) */}
+      {showPercentBar && progress.percentage !== undefined && (
+        <div className="semiont-progress-bar">
+          <div className="semiont-progress-bar__fill" data-type={dataType} style={{ width: `${progress.percentage}%` }} />
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,164 @@
+/**
+ * AssistProgress (#7) — the ONE job-progress renderer, unifying the three
+ * previous shapes (AssistSection's inline block, AnnotateReferencesProgressWidget,
+ * TaggingPanel's inline block) plus the resource-generate flow.
+ *
+ * Contract: presentational and provider-free — no SemiontProvider, no session;
+ * 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.
+ */
+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';
+
+type JobProgress = components['schemas']['JobProgress'];
+
+const running = (over: Partial<JobProgress> = {}): JobProgress => ({
+  stage: 'analyzing', percentage: 40, message: 'working on it', ...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"
+             />,
+    );
+    expect(screen.getByText('working on it')).toBeInTheDocument();
+    expect(screen.getByText(/Density/)).toBeInTheDocument();
+    expect(screen.getByText('5')).toBeInTheDocument();
+    const root = container.querySelector('.semiont-annotation-progress');
+    expect(root).toHaveAttribute('data-type', 'comment');
+    expect(root).toHaveAttribute('data-status', 'analyzing');
+  });
+
+  it('renders a title header only when given one', () => {
+    const { rerender } = render(
+      <AssistProgress progress={running()} dataType="reference" translations={{ title: 'Annotating Entity References' }} />,
+    );
+    expect(screen.getByText('Annotating Entity References')).toBeInTheDocument();
+    rerender(<AssistProgress progress={running()} dataType="comment" />);
+    expect(screen.queryByText('Annotating Entity References')).not.toBeInTheDocument();
+  });
+
+  it('shows cancel in the header while running, hides it once complete', async () => {
+    // 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 { rerender } = render(
+      <AssistProgress progress={running()} dataType="generation" onCancel={onCancel} translations={tr} />,
+    );
+    await userEvent.click(screen.getByTitle('Cancel Job'));
+    expect(onCancel).toHaveBeenCalledOnce();
+    rerender(
+      <AssistProgress progress={running({ stage: 'complete' })} dataType="generation" onCancel={onCancel} translations={tr} />,
+    );
+    expect(screen.queryByTitle('Cancel Job')).not.toBeInTheDocument();
+    // Error is terminal too — offering cancel on a dead job is misleading and
+    // invites redundant cancel requests.
+    rerender(
+      <AssistProgress progress={running({ stage: 'error', message: 'it broke' })} dataType="generation" onCancel={onCancel} translations={tr} />,
+    );
+    expect(screen.queryByTitle('Cancel Job')).not.toBeInTheDocument();
+  });
+
+  it('stage branching: complete shows ✅ + complete copy, error shows ❌ + message', () => {
+    const { rerender } = render(
+      <AssistProgress progress={running({ stage: 'complete' })} dataType="reference" translations={{ complete: 'All done!' }} />,
+    );
+    expect(screen.getByText('All done!')).toBeInTheDocument();
+    rerender(
+      <AssistProgress progress={running({ stage: 'error', message: 'it broke' })} dataType="reference" translations={{ failed: 'Failed' }} />,
+    );
+    expect(screen.getByText('it broke')).toBeInTheDocument();
+  });
+
+  it('renders the completed entity-type log when data + formatter are present', () => {
+    render(
+      <AssistProgress
+        progress={running({ completedEntityTypes: [{ entityType: 'Person', foundCount: 3 }] })}
+        dataType="reference" translations={{ found: (n) => `Found ${n}` }}
+      />,
+    );
+    expect(screen.getByText('Person:')).toBeInTheDocument();
+    expect(screen.getByText('Found 3')).toBeInTheDocument();
+  });
+
+  it('renders the current-work detail line: entity type via formatter, category with counts', () => {
+    const { rerender } = render(
+      <AssistProgress
+        progress={running({ currentEntityType: 'Location' })}
+        dataType="reference" translations={{ current: (l) => `Processing: ${l}` }}
+      />,
+    );
+    expect(screen.getByText('Processing: Location')).toBeInTheDocument();
+    rerender(
+      <AssistProgress
+        progress={running({ currentCategory: 'Rule', processedCategories: 2, totalCategories: 5 })}
+        dataType="tag"      />,
+    );
+    expect(screen.getByText(/Rule/)).toBeInTheDocument();
+    expect(screen.getByText(/2\/5/)).toBeInTheDocument();
+  });
+
+  it('renders the percentage bar only when opted in', () => {
+    const { container, rerender } = render(
+      <AssistProgress progress={running({ percentage: 40 })} dataType="tag" showPercentBar />,
+    );
+    const fill = container.querySelector('.semiont-progress-bar__fill');
+    expect(fill).toBeInTheDocument();
+    expect(fill).toHaveStyle({ width: '40%' });
+    rerender(
+      <AssistProgress progress={running({ percentage: 40 })} dataType="reference" />,
+    );
+    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.
+    render(
+      <AssistProgress progress={running()} dataType="generation"
+        onCancel={vi.fn()} onDismiss={vi.fn()}
+        translations={{ title: 'Generating' }} />,
+    );
+    expect(screen.getByLabelText('Cancel')).toBeInTheDocument();
+    expect(screen.getByLabelText('Dismiss')).toBeInTheDocument();
+  });
+
+  it('terminal stages never render a blank status line', () => {
+    // JobProgress.message is required but can be '' — a terminal display with
+    // no text at all is worse than a generic word.
+    const { rerender } = render(
+      <AssistProgress progress={running({ stage: 'complete', message: '' })} dataType="reference" />,
+    );
+    expect(screen.getByText('Complete')).toBeInTheDocument();
+    rerender(
+      <AssistProgress progress={running({ stage: 'error', message: '' })} dataType="reference" />,
+    );
+    expect(screen.getByText('Failed')).toBeInTheDocument();
+  });
+
+  it('renders dismiss whenever the caller offers it (WHEN is the caller\'s policy)', async () => {
+    // AssistShell withholds onDismiss while the assist is running — that
+    // gate is pinned in AssistShell.test; here the contract is just
+    // "callback present → affordance rendered".
+    const onDismiss = vi.fn();
+    const { rerender } = render(
+      <AssistProgress progress={running()} dataType="highlight" translations={{ close: 'Close' }} />,
+    );
+    expect(screen.queryByLabelText('Close')).not.toBeInTheDocument();
+    rerender(
+      <AssistProgress progress={running()} dataType="highlight"
+        onDismiss={onDismiss} translations={{ close: 'Close' }} />,
+    );
+    await userEvent.click(screen.getByLabelText('Close'));
+    expect(onDismiss).toHaveBeenCalledOnce();
+  });
+});

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

@@ -4,12 +4,8 @@ import React, { useRef, useState, useCallback, useEffect, useMemo } from 'react'
 import type { Annotation, AnchorRect } from '@semiont/core';
 import { resourceId as toResourceId } from '@semiont/core';
 import { toViewportAnchorRect } from '../../lib/anchor-rect';
-import {
-  getTargetSelector,
-  createFragmentSelector,
-  parseFragmentSelector,
-  getPageFromFragment,
-} from '@semiont/core';
+import { createFragmentSelector } from '@semiont/core';
+import { rectsForPage } from './rects-for-page';
 import { createHoverHandlers, type SemiontSession } from '@semiont/sdk';
 import type { SelectionMotivation } from '../annotation/AnnotateToolbar';
 import {
@@ -260,14 +256,8 @@ export function PdfAnnotationCanvas({
         // The hit-test owns the coordinate transform — capture the hit
         // annotation's viewport rect for the emission below (A1 anchor).
         let hitRect: AnchorRect | undefined;
-        const clickedAnnotation = pageAnnotations.find(ann => {
-          const fragmentSel = getFragmentSelector(ann.target);
-          if (!fragmentSel) return false;
-
-          const pdfCoord = parseFragmentSelector(fragmentSel.value);
-          if (!pdfCoord) return false;
-
-          const rect = pdfToCanvasCoordinates(pdfCoord, pageDimensions.height, 1.0);
+        const hit = rectsForPage(existingAnnotations, pageNumber).find(r => {
+          const rect = pdfToCanvasCoordinates(r.coord, pageDimensions.height, 1.0);
 
           // Scale to display coordinates
           const scaleX = displayDimensions.width / pageDimensions.width;
@@ -278,20 +268,20 @@ export function PdfAnnotationCanvas({
           const displayWidth = rect.width * scaleX;
           const displayHeight = rect.height * scaleY;
 
-          const hit = (
+          const inside = (
             selection.endX >= displayX &&
             selection.endX <= displayX + displayWidth &&
             selection.endY >= displayY &&
             selection.endY <= displayY + displayHeight
           );
-          if (hit && imageRef.current) {
+          if (inside && imageRef.current) {
             hitRect = toViewportAnchorRect(imageRef.current.getBoundingClientRect(), displayX, displayY, displayWidth, displayHeight);
           }
-          return hit;
+          return inside;
         });
 
-        if (clickedAnnotation) {
-          session?.client.browse.click(clickedAnnotation.id, clickedAnnotation.motivation, hitRect);
+        if (hit) {
+          session?.client.browse.click(hit.annId, hit.annotation.motivation, hitRect);
           setIsDrawing(false);
           setSelection(null);
           return;
@@ -346,26 +336,11 @@ 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]);
-
-  // Helper to get FragmentSelector from annotation target
-  const getFragmentSelector = (target: Annotation['target']) => {
-    const selector = getTargetSelector(target);
-    if (!selector) return null;
-    const selectors = Array.isArray(selector) ? selector : [selector];
-
-    const found = selectors.find(s => s.type === 'FragmentSelector');
-    if (!found || found.type !== 'FragmentSelector') return null;
-    return found as { type: 'FragmentSelector'; value: string; conformsTo?: string };
-  };
-
-  // Filter annotations for current page
-  const pageAnnotations = existingAnnotations.filter(ann => {
-    const fragmentSel = getFragmentSelector(ann.target);
-    if (!fragmentSel) return false;
-    const page = getPageFromFragment(fragmentSel.value);
-    return page === pageNumber;
-  });
+  }, [isDrawing, selection, pageNumber, pageDimensions, displayDimensions, selectedMotivation, existingAnnotations, session, resourceUri]);
+
+  // Every FragmentSelector rect on the current page — one per line for a
+  // multi-line (multi-selector) annotation, exactly one for a manual annotation.
+  const pageRects = rectsForPage(existingAnnotations, pageNumber);
 
   // Hover handlers with currentHover guard and dwell delay
   const { handleMouseEnter, handleMouseLeave } = useMemo(
@@ -434,29 +409,23 @@ export function PdfAnnotationCanvas({
                 height={displayDimensions.height}
               >
                 {/* Render existing annotations for this page */}
-                {pageAnnotations.map(ann => {
-                  const fragmentSel = getFragmentSelector(ann.target);
-                  if (!fragmentSel) return null;
-
-                  const pdfCoord = parseFragmentSelector(fragmentSel.value);
-                  if (!pdfCoord) return null;
-
-                  const rect = pdfToCanvasCoordinates(pdfCoord, pageDimensions.height, 1.0);
+                {pageRects.map(r => {
+                  const rect = pdfToCanvasCoordinates(r.coord, pageDimensions.height, 1.0);
 
                   // Scale to display coordinates
                   const scaleX = displayDimensions.width / pageDimensions.width;
                   const scaleY = displayDimensions.height / pageDimensions.height;
 
-                  const isHovered = ann.id === hoveredAnnotationId;
-                  const isSelected = ann.id === selectedAnnotationId;
+                  const isHovered = r.annId === hoveredAnnotationId;
+                  const isSelected = r.annId === selectedAnnotationId;
 
-                  // Get color for this annotation's motivation (not the selected motivation)
-                  const annMotivation = ann.motivation as SelectionMotivation | null;
+                  // Colour by the annotation's own motivation (not the toolbar's).
+                  const annMotivation = r.annotation.motivation as SelectionMotivation | null;
                   const { stroke: annStroke, fill: annFill } = getMotivationColor(annMotivation);
 
                   return (
                     <rect
-                      key={ann.id}
+                      key={`${r.annId}:${r.selectorIndex}`}
                       x={rect.x * scaleX}
                       y={rect.y * scaleY}
                       width={rect.width * scaleX}
@@ -469,8 +438,8 @@ export function PdfAnnotationCanvas({
                         cursor: 'pointer',
                         opacity: isSelected ? 1 : isHovered ? 0.9 : 0.7
                       }}
-                      onClick={(e) => session?.client.browse.click(ann.id, ann.motivation, e.currentTarget.getBoundingClientRect())}
-                      onMouseEnter={() => handleMouseEnter(ann.id)}
+                      onClick={(e) => session?.client.browse.click(r.annId, r.annotation.motivation, e.currentTarget.getBoundingClientRect())}
+                      onMouseEnter={() => handleMouseEnter(r.annId)}
                       onMouseLeave={handleMouseLeave}
                     />
                   );

package/src/components/pdf-annotation/__tests__/rects-for-page.test.ts

@@ -0,0 +1,96 @@
+/**
+ * rectsForPage axioms (#735) — the pure partition that distributes an annotation's
+ * FragmentSelectors into per-page rects. Geometry (each coord → canvas pixels) is
+ * covered separately by the pdf-coordinates transform axioms + the core codec axioms.
+ *
+ * The only producer of multi-selector PDF annotations is AI detection (#736), which
+ * doesn't exist yet — so these synthetic fixtures stand in for it.
+ */
+import { describe, it, expect } from 'vitest';
+import * as fc from 'fast-check';
+import { annotationId, resourceId, type Annotation } from '@semiont/core';
+import { rectsForPage } from '../rects-for-page';
+
+const PAGES = 5;
+
+type Sel = { page: number; x: number; y: number; w: number; h: number };
+
+const selArb: fc.Arbitrary<Sel> = fc.record({
+  page: fc.integer({ min: 1, max: PAGES }),
+  x: fc.integer({ min: 0, max: 800 }),
+  y: fc.integer({ min: 0, max: 800 }),
+  w: fc.integer({ min: 1, max: 200 }),
+  h: fc.integer({ min: 1, max: 60 }),
+});
+// A "document" is a list of annotations, each a list of 0..4 selectors.
+const docArb = fc.array(fc.array(selArb, { maxLength: 4 }), { maxLength: 6 });
+
+function build(doc: ReadonlyArray<ReadonlyArray<Sel>>): Annotation[] {
+  return doc.map((sels, i): Annotation => ({
+    '@context': 'http://www.w3.org/ns/anno.jsonld',
+    type: 'Annotation',
+    id: annotationId(`ann-${i}`),
+    target: {
+      source: resourceId('res-1'),
+      selector: sels.map(s => ({
+        type: 'FragmentSelector' as const,
+        value: `page=${s.page}&viewrect=${s.x},${s.y},${s.w},${s.h}`,
+        conformsTo: 'http://tools.ietf.org/rfc/rfc3778',
+      })),
+    },
+    motivation: 'highlighting',
+    created: '2026-01-01T00:00:00.000Z',
+  }));
+}
+
+const keysOn = (anns: Annotation[], page: number): string[] =>
+  rectsForPage(anns, page).map(r => `${r.annId}:${r.selectorIndex}`);
+
+describe('rectsForPage (#735 multi-rect partition)', () => {
+  it('completeness: every FragmentSelector renders exactly once across all pages', () => {
+    fc.assert(fc.property(docArb, doc => {
+      const anns = build(doc);
+      const total = doc.reduce((n, sels) => n + sels.length, 0);
+      let rendered = 0;
+      for (let p = 1; p <= PAGES; p++) rendered += rectsForPage(anns, p).length;
+      expect(rendered).toBe(total);
+    }));
+  });
+
+  it('page-locality: every rect on page p came from a selector with page === p', () => {
+    fc.assert(fc.property(docArb, fc.integer({ min: 1, max: PAGES }), (doc, p) => {
+      for (const r of rectsForPage(build(doc), p)) expect(r.coord.page).toBe(p);
+    }));
+  });
+
+  it('key uniqueness: `${annId}:${selectorIndex}` is pairwise unique on any page', () => {
+    fc.assert(fc.property(docArb, fc.integer({ min: 1, max: PAGES }), (doc, p) => {
+      const keys = keysOn(build(doc), p);
+      expect(new Set(keys).size).toBe(keys.length);
+    }));
+  });
+
+  it('order independence: reversing the annotation list preserves the rendered set per page', () => {
+    fc.assert(fc.property(docArb, fc.integer({ min: 1, max: PAGES }), (doc, p) => {
+      const anns = build(doc);
+      expect([...keysOn([...anns].reverse(), p)].sort()).toEqual([...keysOn(anns, p)].sort());
+    }));
+  });
+
+  it('single-selector invariance: a manual (one-selector) annotation → exactly one rect on its page', () => {
+    const anns = build([[{ page: 2, x: 72, y: 720, w: 150, h: 12 }]]);
+    const onPage2 = rectsForPage(anns, 2);
+    expect(onPage2).toHaveLength(1);
+    expect(onPage2[0].selectorIndex).toBe(0);
+    expect(rectsForPage(anns, 1)).toHaveLength(0);
+  });
+
+  it('multi-line: a 3-selector annotation on one page → 3 distinctly-keyed rects', () => {
+    const anns = build([[
+      { page: 2, x: 72, y: 720, w: 150, h: 12 },
+      { page: 2, x: 72, y: 700, w: 140, h: 12 },
+      { page: 2, x: 72, y: 680, w: 90, h: 12 },
+    ]]);
+    expect(keysOn(anns, 2)).toEqual(['ann-0:0', 'ann-0:1', 'ann-0:2']);
+  });
+});

package/src/components/pdf-annotation/rects-for-page.ts

@@ -0,0 +1,47 @@
+import type { Annotation, PdfCoordinate } from '@semiont/core';
+import { getTargetSelector, parseFragmentSelector } from '@semiont/core';
+
+/** One FragmentSelector rectangle to paint on a PDF page. */
+export interface PageRect {
+  /** Owning annotation id — shared by every rect of a multi-line annotation (hover/click routing). */
+  annId: Annotation['id'];
+  /** Index within the annotation's FragmentSelectors — the stable half of the React key. */
+  selectorIndex: number;
+  /** PDF-point geometry for this rect. */
+  coord: PdfCoordinate;
+  /** Owning annotation (motivation colour, etc.). */
+  annotation: Annotation;
+}
+
+/** Every FragmentSelector on a target, in order (`target.selector` may be one or an array). */
+function fragmentSelectors(target: Annotation['target']): { value: string }[] {
+  const selector = getTargetSelector(target);
+  if (!selector) return [];
+  const selectors = Array.isArray(selector) ? selector : [selector];
+  return selectors
+    .filter(s => s.type === 'FragmentSelector')
+    .map(s => s as { type: 'FragmentSelector'; value: string });
+}
+
+/**
+ * The rectangles to paint on `pageNumber`: one entry per FragmentSelector whose
+ * viewrect page matches. A multi-line (multi-selector) annotation therefore yields
+ * one rect per line; a single-selector (manual) annotation yields exactly one.
+ *
+ * Pure — no React/DOM. `PdfAnnotationCanvas` maps this to `<rect>` keyed
+ * `${annId}:${selectorIndex}`, and the rects-for-page axioms exercise it directly.
+ * Geometry stays deferred: each `coord` still goes through `pdfToCanvasCoordinates`
+ * at paint time (itself covered by the coordinate-transform axioms).
+ */
+export function rectsForPage(annotations: Annotation[], pageNumber: number): PageRect[] {
+  const rects: PageRect[] = [];
+  for (const annotation of annotations) {
+    fragmentSelectors(annotation.target).forEach((sel, selectorIndex) => {
+      const coord = parseFragmentSelector(sel.value);
+      if (coord && coord.page === pageNumber) {
+        rects.push({ annId: annotation.id, selectorIndex, coord, annotation });
+      }
+    });
+  }
+  return rects;
+}