@semiont/react-ui 0.5.26 → 0.5.28

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

@@ -23,200 +23,327 @@ import { AssistProgress, type AssistProgressTranslations } from '../AssistProgre
 
 type JobProgress = components['schemas']['JobProgress'];
 
-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', () => {
+  // Trimmed by P3 (2026-08-12). Five tests were DELETED rather than adapted
+  // because they pinned surfaces this phase removes, and each has a successor
+  // in the P3 block below:
+  //   • paramsTitle copy          → H1 (the label is gone; the line is conditional)
+  //   • "title header only when given one" → A2 (the section header is the title)
+  //   • "cancel in the header / hidden once complete" → A3 ×2 (one control)
+  //   • "stage branching"          → A8 + A3-ended (D7: no producer emits a
+  //                                  terminal stage; terminality is a prop)
+  //   • "percentage bar only when opted in" → A4 (a bar follows the data, not a flag)
+  // What survives here is what P3 does NOT change.
+
+  it('renders provider-free — no session, no context, no providers', () => {
+    // The embeddable contract: this must render standalone. If it ever reaches
+    // for a provider, this throws rather than silently degrading.
     const { container } = render(
-      <AssistProgress
-        progress={running({ requestParams: [{ label: 'Density', value: '5' }] })}
-        dataType="comment"
-        translations={T()}
+      <AssistProgress ended={false} progress={detecting()} dataType="reference" translations={T3()} />,
+    );
+    expect(container.querySelector('.semiont-assist-progress')).toBeInTheDocument();
+    expect(container.querySelector('[data-type="reference"]')).toBeInTheDocument();
+  });
+
+  it('renders the completed entity-type log when data + formatter are present', () => {
+    render(
+      <AssistProgress ended={false}
+        progress={detecting({
+          completedItems: [{ value: 'Person', foundCount: 3 }],
+        })}
+        dataType="reference"
+        translations={T3()}
       />,
     );
-    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');
+    expect(screen.getByText('Person:')).toBeInTheDocument();
+    expect(screen.getByText('tr.found(3)')).toBeInTheDocument();
   });
 
-  it('renders the request-parameters title from translations, never a literal', () => {
+  it('omits the entity-type log when the formatter is absent (non-reference flows)', () => {
+    const tr = T3();
+    delete (tr as Partial<AssistProgressTranslations>).found;
     render(
       <AssistProgress
-        progress={running({ requestParams: [{ label: 'Density', value: '5' }] })}
+        progress={detecting({ completedItems: [{ value: 'Person', foundCount: 3 }] })}
         dataType="comment"
-        translations={T()}
+        ended={false}
+        translations={tr}
       />,
     );
-    expect(screen.getByText('tr.paramsTitle')).toBeInTheDocument();
-    expect(screen.queryByText('Request Parameters:')).not.toBeInTheDocument();
+    expect(screen.queryByText('Person:')).toBeNull();
   });
 
-  it('renders a title header only when given one', () => {
+  it('the control takes its accessible name from translations, per lifecycle', () => {
     const { rerender } = render(
-      <AssistProgress progress={running()} dataType="reference" translations={T({ title: 'Annotating Entity References' })} />,
+      <AssistProgress ended={false}
+        progress={detecting()} dataType="reference"
+        onCancel={vi.fn()} onDismiss={vi.fn()} translations={T3()}
+      />,
     );
-    expect(screen.getByText('Annotating Entity References')).toBeInTheDocument();
-    rerender(<AssistProgress progress={running()} dataType="comment" translations={T()} />);
-    expect(screen.queryByText('Annotating Entity References')).not.toBeInTheDocument();
-  });
+    expect(screen.getByLabelText('tr.cancel')).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 = T({ 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} />,
+      <AssistProgress
+        progress={detecting()} dataType="reference" ended
+        onCancel={vi.fn()} onDismiss={vi.fn()} translations={T3()}
+      />,
     );
-    expect(screen.queryByTitle('Cancel Job')).not.toBeInTheDocument();
+    expect(screen.getByLabelText('tr.close')).toBeInTheDocument();
   });
 
-  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={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!' })} />,
+  it('offers no control at all when the caller wires neither callback', () => {
+    render(<AssistProgress ended={false} progress={detecting()} dataType="reference" translations={T3()} />);
+    expect(screen.queryByTestId('semiont-assist-control')).toBeNull();
+  });
+
+  it('falls back to the generic in-progress copy when no code has arrived', () => {
+    // `JobProgress.message` is optional: a pure liveness heartbeat carries none.
+    const noCode = { percentage: 5 } as JobProgress;
+    render(<AssistProgress ended={false} progress={noCode} dataType="comment" translations={T3()} />);
+    expect(screen.getByTestId('semiont-assist-status').textContent).toBe('tr.inProgress');
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ASSIST-PROGRESS-CONSOLIDATION P3 — the RED wave (A1-A5, A8).
+//
+// These assert STRUCTURE, never copy: H3 set the wording ("Marking…", subject
+// beneath) and it will be revised from use. A test pinned to a sentence rots on
+// the first edit and teaches the next reader to weaken it.
+// ─────────────────────────────────────────────────────────────────────────────
+const STATUS = 'semiont-assist-status';
+const SUBJECT = 'semiont-assist-subject';
+const CONTROL = 'semiont-assist-control';
+const BAR = 'semiont-assist-bar';
+const PARAMS = 'semiont-assist-params';
+
+/** Post-P3 translations: one function for the coded copy, plus structure keys. */
+const T3 = (over: Partial<AssistProgressTranslations> = {}): AssistProgressTranslations =>
+  ({
+    cancel: 'tr.cancel',
+    close: 'tr.close',
+    inProgress: 'tr.inProgress',
+    message: (m: any) => `tr.code(${m.code})`,
+    subject: (current: { kind: string; value: string }, done?: number, total?: number) =>
+      done === undefined
+        ? `tr.subject(${current.kind}:${current.value})`
+        : `tr.subject(${current.kind}:${current.value}|${done}/${total})`,
+    paramLabel: (code: string) => `tr.param(${code})`,
+    found: (n: number) => `tr.found(${n})`,
+    ...over,
+  }) as AssistProgressTranslations;
+
+const detecting = (over: Partial<JobProgress> = {}): JobProgress =>
+  ({
+    percentage: 40,
+    message: { code: 'detecting-entities', entityType: 'Person' },
+    current: { kind: 'entity-type', value: 'Person' },
+    processed: 1,
+    total: 3,
+    ...over,
+  }) as JobProgress;
+
+describe('AssistProgress — P3 consolidation', () => {
+  it('A1: renders the subject exactly once for one progress event', () => {
+    // Defect 1: the status line and the detail line both called
+    // `currentLabel(currentEntityType)`. Post-P1 they produce the IDENTICAL
+    // string, which is why two tests here had to use getAllByText. Singular
+    // `getByText` throws on multiple matches — that IS the assertion.
+    render(<AssistProgress progress={detecting()} dataType="reference" ended={false} translations={T3()} />);
+
+    expect(screen.getByText(/tr\.subject\(entity-type:Person/)).toBeInTheDocument();
+    // And the status line is the CODE's copy, not a second copy of the subject.
+    expect(screen.getByTestId(STATUS).textContent).toContain('tr.code(detecting-entities)');
+    expect(screen.getByTestId(STATUS).textContent).not.toContain('tr.subject');
+  });
+
+  it('A2: renders no heading of its own — the section header is the title', () => {
+    const { container } = render(
+      <AssistProgress ended={false} progress={detecting()} dataType="reference" translations={T3()} />,
     );
-    expect(screen.getByText('All done!')).toBeInTheDocument();
-    rerender(
-      <AssistProgress progress={running({ stage: 'error', message: 'it broke' })} dataType="reference" translations={T({ failed: 'Failed' })} />,
+    expect(container.querySelector('h1,h2,h3,h4,h5,h6')).toBeNull();
+  });
+
+  it('A3: offers exactly one control, and it means cancel while running', async () => {
+    const onCancel = vi.fn();
+    const onDismiss = vi.fn();
+    render(
+      <AssistProgress ended={false}
+        progress={detecting()} dataType="reference"
+        onCancel={onCancel} onDismiss={onDismiss} translations={T3()}
+      />,
     );
-    expect(screen.getByText('it broke')).toBeInTheDocument();
+    const controls = screen.getAllByTestId(CONTROL);
+    expect(controls).toHaveLength(1);
+
+    await userEvent.click(controls[0]!);
+    expect(onCancel).toHaveBeenCalledTimes(1);
+    expect(onDismiss).not.toHaveBeenCalled();
   });
 
-  it('renders the completed entity-type log when data + formatter are present', () => {
+  it('A3: the same single control means dismiss once the run has ENDED', async () => {
+    // D7: terminality is the owner's fact, arriving as a prop. The component
+    // never reads `progress.stage` — no producer emits a terminal stage.
+    const onCancel = vi.fn();
+    const onDismiss = vi.fn();
     render(
       <AssistProgress
-        progress={running({ completedEntityTypes: [{ entityType: 'Person', foundCount: 3 }] })}
-        dataType="reference" translations={T({ found: (n) => `Found ${n}` })}
+        progress={detecting({ message: { code: 'complete-created', count: 7, kind: 'reference' } } as any)}
+        dataType="reference" ended
+        onCancel={onCancel} onDismiss={onDismiss} translations={T3()}
       />,
     );
-    expect(screen.getByText('Person:')).toBeInTheDocument();
-    expect(screen.getByText('Found 3')).toBeInTheDocument();
+    const controls = screen.getAllByTestId(CONTROL);
+    expect(controls).toHaveLength(1);
+
+    await userEvent.click(controls[0]!);
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+    expect(onCancel).not.toHaveBeenCalled();
   });
 
-  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={T({ current: (l) => `Current: ${l}` })}
+  it('A4: the REFERENCE flow renders a fraction and a bar — data it already receives', () => {
+    render(<AssistProgress ended={false} progress={detecting()} dataType="reference" translations={T3()} />);
+
+    expect(screen.getByTestId(SUBJECT).textContent).toBe('tr.subject(entity-type:Person|1/3)');
+    expect(screen.getByTestId(BAR)).toBeInTheDocument();
+  });
+
+  it('A4: the TAG flow gets a bar from percentage alone — it sends no fraction', () => {
+    // The REAL tag shape. `processTagJob` emits percentage and nothing else:
+    // no currentCategory, no processed, no total. An
+    // earlier version of this test invented those fields and so "passed" while
+    // the tag flow had silently lost its bar (PR #1179 review).
+    render(
+      <AssistProgress ended={false}
+        progress={{
+          percentage: 60,
+          message: { code: 'creating-tag-annotations', count: 4 },
+        } as JobProgress}
+        dataType="tag" translations={T3()}
       />,
     );
-    expect(screen.getByText('Current: Location')).toBeInTheDocument();
-    rerender(
-      <AssistProgress
-        progress={running({ currentCategory: 'Rule', processedCategories: 2, totalCategories: 5 })}
-        dataType="tag" translations={T()}
+    expect(screen.getByTestId(BAR)).toBeInTheDocument();
+    // No fraction to show, so no subject line — and that is correct, not a gap.
+    expect(screen.queryByTestId(SUBJECT)).toBeNull();
+  });
+
+  it('A4: the bar is unconditional — percentage is required on every event', () => {
+    // Replaces a test that asserted "no bar when nothing fills it". That state
+    // is unreachable: `percentage` is a REQUIRED field on JobProgress, so there
+    // is always something to fill a bar with. Asserting an impossible case is
+    // how the tag regression hid.
+    render(
+      <AssistProgress ended={false}
+        progress={{ percentage: 10, message: { code: 'loading' } } as JobProgress}
+        dataType="comment" translations={T3()}
       />,
     );
-    expect(screen.getByText(/Rule/)).toBeInTheDocument();
-    expect(screen.getByText(/2\/5/)).toBeInTheDocument();
+    expect(screen.getByTestId(BAR)).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()} />,
+  it('A5: every rendered string is traceable to translations', () => {
+    const { container } = render(
+      <AssistProgress ended={false} progress={detecting()} dataType="reference" translations={T3()} />,
     );
-    expect(screen.getByText('tr.processing(Location)')).toBeInTheDocument();
-    rerender(
-      <AssistProgress progress={running({ currentCategory: 'Rule' })} dataType="tag" translations={T()} />,
+    // Key-echo strings mean any text NOT starting `tr.` came from the component.
+    const stray = Array.from(container.querySelectorAll('*'))
+      .filter((el) => el.children.length === 0)
+      .map((el) => el.textContent?.trim() ?? '')
+      .filter((t) => t.length > 0 && !t.startsWith('tr.') && !/^[\s✨✅✓×✕()0-9/of]+$/.test(t));
+    expect(stray).toEqual([]);
+  });
+
+  it('A8: renders no failure UI of its own — job:fail owns that surface', () => {
+    // Revised by D7. `stage: 'error'` has no producer anywhere in the repo;
+    // failure reaches the user through useOutcomeToasts' job:fail handler.
+    // The widget must not resurrect a branch for a state it never sees.
+    render(
+      <AssistProgress ended={false}
+        progress={detecting({ stage: 'error' } as Partial<JobProgress>)}
+        dataType="reference" translations={T3()}
+      />,
     );
-    expect(screen.getByText(/tr\.processing\(Rule\)/)).toBeInTheDocument();
-    expect(screen.queryByText(/^Processing: /)).not.toBeInTheDocument();
+    // Still the ordinary running render — no special-cased error text.
+    expect(screen.getByTestId(STATUS).textContent).toContain('tr.code(detecting-entities)');
   });
 
-  it('renders the percentage bar only when opted in', () => {
-    const { container, rerender } = render(
-      <AssistProgress progress={running({ percentage: 40 })} dataType="tag" showPercentBar translations={T()} />,
+  it('the outcome link renders only in the ended frame (GENERATE-FROM-RESOURCE P2, D8)', async () => {
+    // The label is the resource's name — user content, deliberately NOT a
+    // translation. While the run is live there is no outcome to offer, even if
+    // a caller wires the prop early.
+    const onOpen = vi.fn();
+    const outcome = { label: 'Summary of PB', onOpen };
+    const { rerender } = render(
+      <AssistProgress ended={false} progress={detecting()} dataType="generation"
+        outcome={outcome} translations={T3()} />,
     );
-    const fill = container.querySelector('.semiont-progress-bar__fill');
-    expect(fill).toBeInTheDocument();
-    expect(fill).toHaveStyle({ width: '40%' });
+    expect(screen.queryByText('Summary of PB')).toBeNull();
+
     rerender(
-      <AssistProgress progress={running({ percentage: 40 })} dataType="reference" translations={T()} />,
+      <AssistProgress ended progress={detecting()} dataType="generation"
+        outcome={outcome} translations={T3()} />,
     );
-    expect(container.querySelector('.semiont-progress-bar__fill')).not.toBeInTheDocument();
+    await userEvent.click(screen.getByRole('button', { name: 'Summary of PB' }));
+    expect(onOpen).toHaveBeenCalledTimes(1);
   });
 
-  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={T({ title: 'Generating' })} />,
+  it('H1: the params line appears only when it adds information', () => {
+    // The discriminator is the COUNT, not the copy — splitting a localized
+    // string on commas to decide whether to show it would be its own defect.
+    const oneType = detecting({
+      requestParams: [{ label: 'entity-types', value: 'Person' }],
+      total: 1,
+    });
+    const { unmount } = render(
+      <AssistProgress ended={false} progress={oneType} dataType="reference" translations={T3()} />,
     );
-    expect(screen.getByLabelText('tr.cancel')).toBeInTheDocument();
-    expect(screen.getByLabelText('tr.close')).toBeInTheDocument();
-    expect(screen.queryByLabelText('Cancel')).not.toBeInTheDocument();
-    expect(screen.queryByLabelText('Dismiss')).not.toBeInTheDocument();
+    expect(screen.queryByTestId(PARAMS)).toBeNull();
+    unmount();
+
+    const many = detecting({
+      requestParams: [{ label: 'entity-types', value: 'Person, Organization, Location' }],
+      total: 3,
+    });
+    render(<AssistProgress ended={false} progress={many} dataType="reference" translations={T3()} />);
+    expect(screen.getByTestId(PARAMS)).toBeInTheDocument();
   });
+});
 
-  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, but that word must be the
-    // caller's translated one.
-    const { rerender } = render(
-      <AssistProgress progress={running({ stage: 'complete', message: '' })} dataType="reference" translations={T()} />,
+// ─────────────────────────────────────────────────────────────────────────────
+// GENERATION-ARRIVAL P1 — the honest ended frame. The producer's terminal
+// 100% frame races job:complete and can lose (its emit is a fire-and-forget
+// heartbeat); terminality is the OWNER's fact (D7), so the ended rendering
+// stops trusting the last payload: full bar, and the owner's terminal
+// sentence when it supplies one.
+// ─────────────────────────────────────────────────────────────────────────────
+describe('AssistProgress — the honest ended frame (GENERATION-ARRIVAL P1)', () => {
+  it('A1: an ended frame renders a FULL bar whatever the last payload said', () => {
+    const { container } = render(
+      <AssistProgress ended progress={detecting({ percentage: 95 })} dataType="generation" translations={T3()} />,
     );
-    expect(screen.getByText('tr.complete')).toBeInTheDocument();
-    rerender(
-      <AssistProgress progress={running({ stage: 'error', message: '' })} dataType="reference" translations={T()} />,
+    const fill = container.querySelector('.semiont-progress-bar__fill') as HTMLElement;
+    expect(fill.style.width).toBe('100%');
+  });
+
+  it('a live frame keeps the payload percentage', () => {
+    const { container } = render(
+      <AssistProgress ended={false} progress={detecting({ percentage: 95 })} dataType="generation" translations={T3()} />,
     );
-    expect(screen.getByText('tr.failed')).toBeInTheDocument();
+    const fill = container.querySelector('.semiont-progress-bar__fill') as HTMLElement;
+    expect(fill.style.width).toBe('95%');
   });
 
-  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={T({ close: 'Close' })} />,
+  it('endedMessage replaces the stale payload copy once ended', () => {
+    render(
+      <AssistProgress ended endedMessage="tr.ended" progress={detecting({ percentage: 95 })} dataType="generation" translations={T3()} />,
     );
-    expect(screen.queryByLabelText('Close')).not.toBeInTheDocument();
-    rerender(
-      <AssistProgress progress={running()} dataType="highlight"
-        onDismiss={onDismiss} translations={T({ close: 'Close' })} />,
+    expect(screen.getByTestId(STATUS).textContent).toBe('tr.ended');
+  });
+
+  it('endedMessage is inert while the run is live', () => {
+    render(
+      <AssistProgress ended={false} endedMessage="tr.ended" progress={detecting()} dataType="generation" translations={T3()} />,
     );
-    await userEvent.click(screen.getByLabelText('Close'));
-    expect(onDismiss).toHaveBeenCalledOnce();
+    expect(screen.getByTestId(STATUS).textContent).toBe('tr.code(detecting-entities)');
   });
 });

package/src/components/annotation/annotation-entries.css

@@ -133,10 +133,6 @@
   color: var(--semiont-text-tertiary);
 }
 
-[data-theme="dark"] .semiont-annotation-entry__char-count {
-  color: var(--semiont-text-tertiary);
-}
-
 /* Tags within entries */
 .semiont-annotation-entry__tags {
   display: flex;

package/src/components/annotation/references.css

@@ -105,10 +105,6 @@
   background-color: var(--semiont-bg-tertiary);
 }
 
-[data-theme="dark"] .semiont-chip--selectable[data-selected="false"]:hover {
-  background-color: var(--semiont-bg-tertiary);
-}
-
 .semiont-chip--selectable[data-selected="true"] {
   background-color: rgba(59, 130, 246, 0.1);
   color: var(--semiont-color-blue-700);

package/src/components/image-annotation/AnnotationOverlay.tsx

@@ -128,7 +128,7 @@ export function AnnotationOverlay({
                   className="semiont-annotation-overlay__shape"
                   data-hovered={isHovered ? 'true' : 'false'}
                   data-selected={isSelected ? 'true' : 'false'}
-                  onClick={(e) => session?.client.browse.click(annotation.id, annotation.motivation, e.currentTarget.getBoundingClientRect())}
+                  onClick={(e) => session?.client.browse.click(annotation.id, e.currentTarget.getBoundingClientRect())}
                   onMouseEnter={() => handleMouseEnter(annotation.id)}
                   onMouseLeave={handleMouseLeave}
                 />
@@ -141,7 +141,7 @@ export function AnnotationOverlay({
                     style={{ userSelect: 'none' }}
                     onClick={(e) => {
                       e.stopPropagation();
-                      session?.client.browse.click(annotation.id, annotation.motivation, e.currentTarget.getBoundingClientRect());
+                      session?.client.browse.click(annotation.id, e.currentTarget.getBoundingClientRect());
                     }}
                     onMouseEnter={() => handleMouseEnter(annotation.id)}
                     onMouseLeave={handleMouseLeave}
@@ -175,7 +175,7 @@ export function AnnotationOverlay({
                   className="semiont-annotation-overlay__shape"
                   data-hovered={isHovered ? 'true' : 'false'}
                   data-selected={isSelected ? 'true' : 'false'}
-                  onClick={(e) => session?.client.browse.click(annotation.id, annotation.motivation, e.currentTarget.getBoundingClientRect())}
+                  onClick={(e) => session?.client.browse.click(annotation.id, e.currentTarget.getBoundingClientRect())}
                   onMouseEnter={() => handleMouseEnter(annotation.id)}
                   onMouseLeave={handleMouseLeave}
                 />
@@ -188,7 +188,7 @@ export function AnnotationOverlay({
                     style={{ userSelect: 'none' }}
                     onClick={(e) => {
                       e.stopPropagation();
-                      session?.client.browse.click(annotation.id, annotation.motivation, e.currentTarget.getBoundingClientRect());
+                      session?.client.browse.click(annotation.id, e.currentTarget.getBoundingClientRect());
                     }}
                     onMouseEnter={() => handleMouseEnter(annotation.id)}
                     onMouseLeave={handleMouseLeave}
@@ -235,7 +235,7 @@ export function AnnotationOverlay({
                   className="semiont-annotation-overlay__shape"
                   data-hovered={isHovered ? 'true' : 'false'}
                   data-selected={isSelected ? 'true' : 'false'}
-                  onClick={(e) => session?.client.browse.click(annotation.id, annotation.motivation, e.currentTarget.getBoundingClientRect())}
+                  onClick={(e) => session?.client.browse.click(annotation.id, e.currentTarget.getBoundingClientRect())}
                   onMouseEnter={() => handleMouseEnter(annotation.id)}
                   onMouseLeave={handleMouseLeave}
                 />
@@ -248,7 +248,7 @@ export function AnnotationOverlay({
                     style={{ userSelect: 'none' }}
                     onClick={(e) => {
                       e.stopPropagation();
-                      session?.client.browse.click(annotation.id, annotation.motivation, e.currentTarget.getBoundingClientRect());
+                      session?.client.browse.click(annotation.id, e.currentTarget.getBoundingClientRect());
                     }}
                     onMouseEnter={() => handleMouseEnter(annotation.id)}
                     onMouseLeave={handleMouseLeave}

package/src/components/image-annotation/SvgDrawingCanvas.tsx

@@ -221,7 +221,7 @@ export function SvgDrawingCanvas({
         });
 
         if (clickedAnnotation) {
-          session?.client.browse.click(clickedAnnotation.id, clickedAnnotation.motivation, hitRect);
+          session?.client.browse.click(clickedAnnotation.id, hitRect);
           setIsDrawing(false);
           setStartPoint(null);
           setCurrentPoint(null);

package/src/components/image-annotation/__tests__/AnnotationOverlay.click.test.tsx

@@ -2,7 +2,7 @@
  * A1 anchor thread (HEADLESS-ANNOTATION-PANELS Phase 3) — image overlay pin.
  *
  * The overlay's shape elements own their on-screen geometry: a click passes
- * the element's viewport rect as browse.click's third argument so hosts can
+ * the element's viewport rect as browse.click's second argument so hosts can
  * anchor popovers. Runtime-only view geometry; no schema involvement.
  */
 import { describe, it, expect, vi } from 'vitest';
@@ -43,7 +43,7 @@ function sessionDouble() {
 }
 
 describe('AnnotationOverlay — anchorRect on click', () => {
-  it('passes the shape element rect as browse.click third argument', () => {
+  it('passes the shape element rect as browse.click second argument', () => {
     const { session, click } = sessionDouble();
 
     const { container } = render(
@@ -65,8 +65,7 @@ describe('AnnotationOverlay — anchorRect on click', () => {
 
     expect(click).toHaveBeenCalledTimes(1);
     expect(click.mock.calls[0]?.[0]).toBe('img-ann-1');
-    expect(click.mock.calls[0]?.[1]).toBe('highlighting');
-    const anchorRect = click.mock.calls[0]?.[2];
+    const anchorRect = click.mock.calls[0]?.[1];
     expect(anchorRect).toBeDefined();
     expect(typeof anchorRect.width).toBe('number');
     expect(typeof anchorRect.left).toBe('number');
@@ -77,7 +76,7 @@ describe('AnnotationOverlay — anchorRect on click', () => {
   it.each([
     ['circle', svgAnnotation('img-circle-1', 'commenting', '<svg><circle cx="30" cy="30" r="10"/></svg>')],
     ['polygon', svgAnnotation('img-polygon-1', 'assessing', '<svg><polygon points="10,10 30,10 20,30"/></svg>')],
-  ] as const)('passes the %s element rect as browse.click third argument', (_kind, annotation) => {
+  ] as const)('passes the %s element rect as browse.click second argument', (_kind, annotation) => {
     const { session, click } = sessionDouble();
 
     const { container } = render(
@@ -99,12 +98,12 @@ describe('AnnotationOverlay — anchorRect on click', () => {
 
     expect(click).toHaveBeenCalledTimes(1);
     expect(click.mock.calls[0]?.[0]).toBe(annotation.id);
-    const anchorRect = click.mock.calls[0]?.[2];
+    const anchorRect = click.mock.calls[0]?.[1];
     expect(anchorRect).toBeDefined();
     expect(typeof anchorRect.width).toBe('number');
   });
 
-  it('passes the status-indicator element rect as browse.click third argument', () => {
+  it('passes the status-indicator element rect as browse.click second argument', () => {
     // Only references render a status indicator (🔗/❓).
     const reference = svgAnnotation('img-ref-1', 'linking', '<svg><rect x="10" y="10" width="20" height="20"/></svg>');
     const { session, click } = sessionDouble();
@@ -129,8 +128,7 @@ describe('AnnotationOverlay — anchorRect on click', () => {
     // stopPropagation: the indicator's own handler emits, exactly once.
     expect(click).toHaveBeenCalledTimes(1);
     expect(click.mock.calls[0]?.[0]).toBe('img-ref-1');
-    expect(click.mock.calls[0]?.[1]).toBe('linking');
-    const anchorRect = click.mock.calls[0]?.[2];
+    const anchorRect = click.mock.calls[0]?.[1];
     expect(anchorRect).toBeDefined();
     expect(typeof anchorRect.width).toBe('number');
   });

package/src/components/image-annotation/__tests__/SvgDrawingCanvas.click.test.tsx

@@ -100,8 +100,7 @@ describe('SvgDrawingCanvas — drawing-path hit-test anchorRect', () => {
 
     expect(click).toHaveBeenCalledTimes(1);
     expect(click.mock.calls[0]?.[0]).toBe('canvas-ann-1');
-    expect(click.mock.calls[0]?.[1]).toBe('highlighting');
-    expect(click.mock.calls[0]?.[2]).toEqual({
+    expect(click.mock.calls[0]?.[1]).toEqual({
       x: 20, y: 20, left: 20, top: 20, width: 40, height: 40, right: 60, bottom: 60,
     });
   });